From 758a3415462143e7e8a21f12cb58ebf77d6b82d7 Mon Sep 17 00:00:00 2001 From: Jon Shallow Date: Thu, 25 Apr 2024 14:08:38 +0100 Subject: [PATCH] doc: Update coap_session_set_type_client() documentation --- include/coap3/coap_session.h | 7 +++++-- man/coap_session.txt.in | 7 +++++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/include/coap3/coap_session.h b/include/coap3/coap_session.h index 0d9ccc166c..da4f023ebb 100644 --- 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 index 4a6908d8bd..88c6a8588c 100644 --- 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()*