Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
COAP_CONTEXT(3) 		 libcoap Manual 		 COAP_CONTEXT(3)

NAME
     coap_context,	coap_new_context,      coap_free_context,      coap_con-
     text_set_max_idle_sessions,  coap_context_get_max_idle_sessions,  coap_con-
     text_set_max_handshake_sessions,	coap_context_get_max_handshake_sessions,
     coap_context_set_session_timeout,	       coap_context_get_session_timeout,
     coap_context_set_csm_timeout_ms, coap_context_get_csm_timeout_ms, coap_con-
     text_set_max_token_size,	     coap_context_set_app_data,        coap_con-
     text_get_app_data, coap_context_set_cid_tuple_change - Work with CoAP  con-
     texts

SYNOPSIS
     #include <coap3/coap.h>

     coap_context_t *coap_new_context(const coap_address_t *listen_addr);

     void coap_free_context(coap_context_t *context);

     void  coap_context_set_max_idle_sessions(coap_context_t  *context, unsigned
     int max_idle_sessions);

     unsigned int coap_context_get_max_idle_sessions( const coap_context_t *con-
     text);

     void coap_context_set_max_handshake_sessions(coap_context_t  *context,  un-
     signed int max_handshake_sessions);

     unsigned  int coap_context_get_max_handshake_sessions( const coap_context_t
     *context);

     void coap_context_set_session_timeout(coap_context_t *context, unsigned int
     session_timeout);

     unsigned int coap_context_get_session_timeout( const  coap_context_t  *con-
     text);

     void  coap_context_set_csm_timeout_ms(coap_context_t *context, unsigned int
     csm_timeout_ms);

     unsigned  int  coap_context_get_csm_timeout_ms(const  coap_context_t  *con-
     text);

     void    coap_context_set_max_token_size(coap_context_t   *context,   size_t
     max_token_size);

     void coap_context_set_app_data(coap_context_t *context, void *app_data);

     void *coap_context_get_app_data(const coap_context_t *context);

     int   coap_context_set_cid_tuple_change(coap_context_t    *context_context,
     uint8_t _every);

     For   specific   (D)TLS   library	 support,   link   with  -lcoap-3-notls,
     -lcoap-3-gnutls, -lcoap-3-openssl,  -lcoap-3-mbedtls,  -lcoap-3-wolfssl  or
     -lcoap-3-tinydtls.  Otherwise, link with -lcoap-3 to get the default (D)TLS
     library support.

DESCRIPTION
     This man page focuses on the CoAP Context and how to update or get informa-
     tion from the opaque coap_context_t structure.

     The CoAP stack's global state is stored in a coap_context_t Context object.
     Resources, Endpoints and Sessions are associated with this context  object.
     There  can be more than one coap_context_t object per application, it is up
     to the application to manage each one accordingly.

FUNCTIONS
     Function: coap_new_context()

     The coap_new_context() function creates a new Context that is then used  to
     keep  all	the  CoAP Resources, Endpoints and Sessions information. The op-
     tional listen_addr parameter, if set for a CoAP server, creates an Endpoint
     that is added to the context that is listening for un-encrypted traffic  on
     the IP address and port number defined by listen_addr.

     Function: coap_free_context()

     The  coap_free_context()  function  must  be used to release the CoAP stack
     context. It clears all entries from the receive queue and	send  queue  and
     deletes the Resources that have been registered with context, and frees the
     attached Sessions and Endpoints.

     WARNING: It is unsafe to call coap_free_context() in an atexit() handler as
     other  libraries  may  also call atexit() and clear down some CoAP required
     functionality.

     WARNING: It is unsafe to call coap_free_context() in any  libcoap	callback
     handlers as set up in coap_handler(3).

     WARNING:  In  a  multi-thread,  libcoap  thread-safe  environment, if other
     threads are using context, it is not  recommended	to  call  coap_free_con-
     text()  as various libcoap APIs will unexpectedly fail. It is best to clear
     down those other threads first before calling coap_free_context().

     Function: coap_context_set_max_idle_sessions()

     The coap_context_set_max_idle_sessions() function sets the  maximum  number
     of idle server sessions to max_idle_sessions for context. If this number is
     exceeded,	the  least recently used server session is completely removed. 0
     (the initial default) means that the number of idle sessions is  not  moni-
     tored.

     Function: coap_context_get_max_idle_sessions()

     The  coap_context_get_max_idle_sessions() function returns the maximum num-
     ber of idle server sessions for context.

     Function: coap_context_set_max_handshake_sessions()

     The coap_context_set_max_handshake_sessions()  function  sets  the  maximum
     number  of  outstanding  server  sessions	in (D)TLS handshake to max_hand-
     shake_sessions for context. If this number is exceeded, the least	recently
     used  server  session  in	handshake is completely removed. 0 (the default)
     means that the number of handshakes is not monitored.

     Function: coap_context_get_max_handshake_sessions()

     The coap_context_get_max_handshake_sessions() function returns the  maximum
     number of outstanding server sessions in (D)TLS handshake for context.

     Function: coap_context_set_session_timeout()

     The  coap_context_set_session_timeout() function sets the number of seconds
     of inactivity to session_timeout for context before an idle server  session
     is removed. 0 (the default) means wait for the default of 300 seconds.

     Function: coap_context_get_session_timeout()

     The coap_context_get_session_timeout() function returns the seconds to wait
     before timing out an idle server session for context.

     Function: coap_context_set_csm_timeout_ms()

     The coap_context_set_csm_timeout_ms() function sets the number of millisec-
     onds  to  wait  for  a  (TCP)  CSM  negotiation  response	from the peer to
     csm_timeout_ms for context before timing out and assuming	CoAP  server  is
     broken.  The  default is 1000 milliseconds. The minimum value for csm_time-
     out_ms is set to 10 milliseconds and the maximum value  for  csm_timeout_ms
     is set to 10000 milliseconds.

     Function: coap_context_get_csm_timeout_ms()

     The  coap_context_get_csm_timeout_ms() function returns the milliseconds to
     wait for a (TCP) CSM negotiation response from the peer for context,

     Function: coap_context_set_max_token_size()

     The coap_context_set_max_token_size() function sets the max_token_size  for
     context.  max_token_size  must  be  greater  than 8 to indicate support for
     RFC8974 up to max_token_size bytes, else 8 to disable  RFC8974  (if  previ-
     ously set).

     NOTE:  For  the client, it will send an initial PDU to test the server sup-
     ports the requested extended token size as per "RFC8794 Section 2.2.2"

     Function: coap_context_set_app_data()

     The coap_context_set_app_data() function  is  used  to  define  a	app_data
     pointer for the context which can then be retrieved at a later date.

     Function: coap_context_get_app_data()

     The  coap_context_get_app_data()  function is used to retrieve the app_data
     pointer previously defined by coap_context_set_app_data().

     Function: coap_context_set_cid_tuple_change()

     The coap_context_set_cid_tuple_change() function is used  to  define  to  a
     client  to  force the client's port to change every packets sent, providing
     the ability to test a CID (RFC9146) enabled server. Only supported by  DTLS
     libraries that support CID.

RETURN VALUES
     coap_new_context()  returns  a  newly created context or NULL if there is a
     creation failure.

     coap_context_get_max_idle_sessions() returns the  maximum	number	of  idle
     server sessions.

     coap_context_get_max_handshake_sessions()	returns  the  maximum  number of
     outstanding server sessions in (D)TLS handshake.

     coap_context_get_session_timeout() returns the seconds to wait before  tim-
     ing out an idle server session.

     coap_context_get_csm_timeout_ms()	returns  the  milliseconds to wait for a
     (TCP) CSM negotiation response from the peer.

     coap_context_get_app_data() returns a previously defined pointer.

     coap_context_set_cid_tuple_change() returns 1 on success, else 0;

SEE ALSO
     coap_session(3)

FURTHER INFORMATION
     See

     "RFC7252: The Constrained Application Protocol (CoAP)"

     "RFC8974: Extended Tokens and Stateless Clients in the Constrained Applica-
     tion Protocol (CoAP)"

     for further information.

BUGS
     Please raise an issue on GitHub  at  https://github.com/obgm/libcoap/issues
     to report any bugs.

     Please  raise  a  Pull Request at https://github.com/obgm/libcoap/pulls for
     any fixes.

AUTHORS
     The libcoap project <libcoap-developers@lists.sourceforge.net>

coap_context 4.3.5		   08/02/2026			 COAP_CONTEXT(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=coap_context_set_cid_tuple_change&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help