mirror of
https://github.com/obgm/libcoap.git
synced 2026-11-19 05:59:05 +03:00
Update examples-code-check.c to cross-check NAME and SYNOPSIS entries. Update examples-code-check.c to cross-check SYNOPSIS and RETURN VALUE entries. Make the formating style of RETURN VALUES consistent.
198 lines
6.9 KiB
Plaintext
198 lines
6.9 KiB
Plaintext
// -*- mode:doc; -*-
|
|
// vim: set syntax=asciidoc tw=0
|
|
|
|
coap_context(3)
|
|
===============
|
|
:doctype: manpage
|
|
:man source: coap_context
|
|
:man version: @PACKAGE_VERSION@
|
|
:man manual: libcoap Manual
|
|
|
|
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 <coap@LIBCOAP_API_VERSION@/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-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
|
|
*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*
|
|
or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with
|
|
*-lcoap-@LIBCOAP_API_VERSION@* 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 https://rfc-editor.org/rfc/rfc8974[RFC8974] up to _max_token_size_
|
|
bytes, else 8 to disable https://rfc-editor.org/rfc/rfc8974[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
|
|
"https://rfc-editor.org/rfc/rfc8974.html#section-2.2.2[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)
|
|
|
|
FURTHER INFORMATION
|
|
-------------------
|
|
See
|
|
|
|
"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]"
|
|
|
|
"https://rfc-editor.org/rfc/rfc8974[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>
|