---
name: "coap_context"
section: "3"
platform: "linux"
package: "libcoap3t64"
version: "4.3.4-1.1+deb13u3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/coap_context"
---

# coap\_context(3)

Work with CoAP contexts

## NAME

coap\_context, coap\_new\_context, coap\_free\_context, coap\_context\_set\_max\_idle\_sessions, coap\_context\_get\_max\_idle\_sessions, coap\_context\_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, coap\_context\_get\_csm\_timeout, coap\_context\_set\_max\_token\_size - Work with CoAP contexts

## 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 \****context***);**

**void coap\_context\_set\_max\_handshake\_sessions(coap\_context\_t \****context***, unsigned 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 \****context***);**

**void coap\_context\_set\_csm\_timeout(coap\_context\_t \****context***, unsigned int** *csm\_timeout***);**

**unsigned int coap\_context\_get\_csm\_timeout(const coap\_context\_t \****context***);**

**void coap\_context\_set\_max\_token\_size(coap\_context\_t \****context***, size\_t** *max\_token\_size***);**

For specific (D)TLS library support, link with **-lcoap-3-notls**, **-lcoap-3-gnutls**, **-lcoap-3-openssl**, **-lcoap-3-mbedtls** 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 information 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 optional *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.

**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 monitored.

**Function: coap\_context\_get\_max\_idle\_sessions()**

The **coap\_context\_get\_max\_idle\_sessions**() function returns the maximum number 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\_handshake\_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()**

The **coap\_context\_set\_csm\_timeout**() function sets the number of seconds to wait for a (TCP) CSM negotiation response from the peer to *csm\_timeout* for *context*. 0 (the default) means wait forever.

**Function: coap\_context\_get\_csm\_timeout()**

The **coap\_context\_get\_csm\_timeout**() function returns the seconds 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 previously set).

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

## 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 timing out an idle server session.

**coap\_context\_get\_csm\_timeout**() returns the seconds to wait for a (TCP) CSM negotiation response from the peer.

## SEE ALSO

[**coap\_session**(3)](/coap_session/3.md)

## FURTHER INFORMATION

See

"RFC7252: The Constrained Application Protocol (CoAP)"

"RFC8974: Extended Tokens and Stateless Clients in the Constrained Application Protocol (CoAP)"

for further information.

## BUGS

Please report bugs on the mailing list for libcoap: libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at https://github.com/obgm/libcoap/issues

## AUTHORS

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