doc: Update coap_session_set_type_client() documentation

obgm · Apr 25, 2024 · 758a341 · 758a341
1 parent 65f2f40
commit 758a341
Show file tree

Hide file tree

Showing 2 changed files with 10 additions and 4 deletions.
diff --git a/include/coap3/coap_session.h b/include/coap3/coap_session.h
@@ -208,10 +208,13 @@ coap_context_t *coap_session_get_context(const coap_session_t *session);
 
 /**
  * Set the session type to client. Typically used in a call-home server.
- * The session needs to be of type COAP_SESSION_TYPE_SERVER.
+ * The session initially needs to be of type COAP_SESSION_TYPE_SERVER,
+ * which is then made COAP_SESSION_TYPE_CLIENT.
  * Note: If this function is successful, the session reference count is
  * incremented and a subsequent coap_session_release() taking the
- * reference count to 0 will cause the session to be freed off.
+ * reference count to 0 will cause the (now client) session to be freed off.
+ * Note: This function will fail for a DTLS server type session if done before
+ * the ClientHello is seen.
  *
  * @param session The CoAP session.
  *

diff --git a/man/coap_session.txt.in b/man/coap_session.txt.in
@@ -127,9 +127,12 @@ get dropped.
 *Function: coap_session_set_type_client()*
 
 The *coap_session_set_type_client*() function is used to convert the _session_
-frrm a session endpoint type of Server to Client.  This typically is used in a
+from a session endpoint type of Server to Client.  This typically is used in a
 Call-Home type environment where the roles have to change following the
-establishment of a session.  The reference count is incremented by 1.
+establishment of a session.  The reference count is incremented by 1 so that
+the now type Client _session_ does not expire until a *coap_session_release*()
+is done. *NOTE:* This function will fail for a DTLS server type session if done
+before the ClientHello is seen.
 
 *Function: coap_session_set_app_data()*