libcoap  4.3.0rc2
Context Handling

API functions for handling PDUs using CoAP Contexts. More...

Macros

#define coap_join_mcast_group(ctx, groupname)    (coap_join_mcast_group_intf(ctx, groupname, NULL))
 

Typedefs

typedef enum coap_response_t coap_response_t
 
typedef coap_response_t(* coap_response_handler_t) (coap_context_t *context, coap_session_t *session, coap_pdu_t *sent, coap_pdu_t *received, const coap_mid_t id)
 Response handler that is used as callback in coap_context_t. More...
 
typedef void(* coap_nack_handler_t) (coap_context_t *context, coap_session_t *session, coap_pdu_t *sent, coap_nack_reason_t reason, const coap_mid_t id)
 Negative Acknowedge handler that is used as callback in coap_context_t. More...
 
typedef void(* coap_ping_handler_t) (coap_context_t *context, coap_session_t *session, coap_pdu_t *received, const coap_mid_t id)
 Received Ping handler that is used as callback in coap_context_t. More...
 
typedef void(* coap_pong_handler_t) (coap_context_t *context, coap_session_t *session, coap_pdu_t *received, const coap_mid_t id)
 Received Pong handler that is used as callback in coap_context_t. More...
 

Enumerations

enum  coap_response_t { COAP_RESPONSE_FAIL , COAP_RESPONSE_OK }
 

Functions

void coap_register_response_handler (coap_context_t *context, coap_response_handler_t handler)
 Registers a new message handler that is called whenever a response is received. More...
 
void coap_register_nack_handler (coap_context_t *context, coap_nack_handler_t handler)
 Registers a new message handler that is called whenever a confirmable message (request or response) is dropped after all retries have been exhausted, or a rst message was received, or a network or TLS level event was received that indicates delivering the message is not possible. More...
 
void coap_register_ping_handler (coap_context_t *context, coap_ping_handler_t handler)
 Registers a new message handler that is called whenever a CoAP Ping message is received. More...
 
void coap_register_pong_handler (coap_context_t *context, coap_pong_handler_t handler)
 Registers a new message handler that is called whenever a CoAP Pong message is received. More...
 
void coap_register_option (coap_context_t *ctx, uint16_t type)
 Registers the option type type with the given context object ctx. More...
 
coap_context_tcoap_new_context (const coap_address_t *listen_addr)
 Creates a new coap_context_t object that will hold the CoAP stack status. More...
 
int coap_context_set_psk (coap_context_t *context, const char *hint, const uint8_t *key, size_t key_len)
 Set the context's default PSK hint and/or key for a server. More...
 
int coap_context_set_psk2 (coap_context_t *context, coap_dtls_spsk_t *setup_data)
 Set the context's default PSK hint and/or key for a server. More...
 
int coap_context_set_pki (coap_context_t *context, const coap_dtls_pki_t *setup_data)
 Set the context's default PKI information for a server. More...
 
int coap_context_set_pki_root_cas (coap_context_t *context, const char *ca_file, const char *ca_dir)
 Set the context's default Root CA information for a client or server. More...
 
void coap_context_set_keepalive (coap_context_t *context, unsigned int seconds)
 Set the context keepalive timer for sessions. More...
 
int coap_context_get_coap_fd (const coap_context_t *context)
 Get the libcoap internal file descriptor for using in an application's select() or returned as an event in an application's epoll_wait() call. More...
 
void coap_context_set_max_idle_sessions (coap_context_t *context, unsigned int max_idle_sessions)
 Set the maximum idle sessions count. More...
 
unsigned int coap_context_get_max_idle_sessions (const coap_context_t *context)
 Get the maximum idle sessions count. More...
 
void coap_context_set_session_timeout (coap_context_t *context, unsigned int session_timeout)
 Set the session timeout value. More...
 
unsigned int coap_context_get_session_timeout (const coap_context_t *context)
 Get the session timeout value. More...
 
void coap_context_set_csm_timeout (coap_context_t *context, unsigned int csm_tmeout)
 Set the CSM timeout value. More...
 
unsigned int coap_context_get_csm_timeout (const coap_context_t *context)
 Get the CSM timeout value. More...
 
void coap_context_set_max_handshake_sessions (coap_context_t *context, unsigned int max_handshake_sessions)
 Set the maximum number of sessions in (D)TLS handshake value. More...
 
unsigned int coap_context_get_max_handshake_sessions (const coap_context_t *context)
 Get the session timeout value. More...
 
uint16_t coap_new_message_id (coap_session_t *session)
 Returns a new message id and updates session->tx_mid accordingly. More...
 
void coap_free_context (coap_context_t *context)
 CoAP stack context must be released with coap_free_context(). More...
 
void coap_set_app_data (coap_context_t *context, void *data)
 Stores data with the given CoAP context. More...
 
void * coap_get_app_data (const coap_context_t *context)
 Returns any application-specific data that has been stored with context using the function coap_set_app_data(). More...
 
coap_pdu_tcoap_new_error_response (coap_pdu_t *request, unsigned char code, coap_opt_filter_t *opts)
 Creates a new ACK PDU with specified error code. More...
 
coap_mid_t coap_send_error (coap_session_t *session, coap_pdu_t *request, unsigned char code, coap_opt_filter_t *opts)
 Sends an error response with code code for request request to dst. More...
 
coap_mid_t coap_send_message_type (coap_session_t *session, coap_pdu_t *request, unsigned char type)
 Helper function to create and send a message with type (usually ACK or RST). More...
 
coap_mid_t coap_send_ack (coap_session_t *session, coap_pdu_t *request)
 Sends an ACK message with code 0 for the specified request to dst. More...
 
COAP_STATIC_INLINE coap_mid_t coap_send_rst (coap_session_t *session, coap_pdu_t *request)
 Sends an RST message with code 0 for the specified request to dst. More...
 
coap_mid_t coap_send (coap_session_t *session, coap_pdu_t *pdu)
 Sends a CoAP message to given peer. More...
 
coap_mid_t coap_send_large (coap_session_t *session, coap_pdu_t *pdu)
 Sends a CoAP message to given peer. More...
 
int coap_handle_event (coap_context_t *context, coap_event_t event, coap_session_t *session)
 Invokes the event handler of context for the given event and data. More...
 
int coap_can_exit (coap_context_t *context)
 Returns 1 if there are no messages to send or to dispatch in the context's queues. More...
 
void coap_ticks (coap_tick_t *)
 Returns the current value of an internal tick counter. More...
 
int coap_join_mcast_group_intf (coap_context_t *ctx, const char *groupname, const char *ifname)
 Function interface for joining a multicast group for listening for the currently defined endpoints that are UDP. More...
 
int coap_mcast_set_hops (coap_session_t *session, size_t hops)
 Function interface for defining the hop count (ttl) for sending multicast traffic. More...
 

Detailed Description

API functions for handling PDUs using CoAP Contexts.

Macro Definition Documentation

◆ coap_join_mcast_group

#define coap_join_mcast_group (   ctx,
  groupname 
)     (coap_join_mcast_group_intf(ctx, groupname, NULL))

Definition at line 530 of file net.h.

Typedef Documentation

◆ coap_nack_handler_t

typedef void(* coap_nack_handler_t) (coap_context_t *context, coap_session_t *session, coap_pdu_t *sent, coap_nack_reason_t reason, const coap_mid_t id)

Negative Acknowedge handler that is used as callback in coap_context_t.

Parameters
contextCoAP session.
sessionCoAP session.
sentThe PDU that was transmitted.
reasonThe reason for the NACK.
idCoAP message ID.

Definition at line 68 of file net.h.

◆ coap_ping_handler_t

typedef void(* coap_ping_handler_t) (coap_context_t *context, coap_session_t *session, coap_pdu_t *received, const coap_mid_t id)

Received Ping handler that is used as callback in coap_context_t.

Parameters
contextCoAP session.
sessionCoAP session.
receivedThe PDU that was received.
idCoAP message ID.

Definition at line 82 of file net.h.

◆ coap_pong_handler_t

typedef void(* coap_pong_handler_t) (coap_context_t *context, coap_session_t *session, coap_pdu_t *received, const coap_mid_t id)

Received Pong handler that is used as callback in coap_context_t.

Parameters
contextCoAP session.
sessionCoAP session.
receivedThe PDU that was received.
idCoAP message ID.

Definition at line 95 of file net.h.

◆ coap_response_handler_t

typedef coap_response_t(* coap_response_handler_t) (coap_context_t *context, coap_session_t *session, coap_pdu_t *sent, coap_pdu_t *received, const coap_mid_t id)

Response handler that is used as callback in coap_context_t.

Parameters
contextCoAP session.
sessionCoAP session.
sentThe PDU that was transmitted.
receivedThe PDU that was received.
idCoAP transaction ID.
Returns
COAP_RESPONSE_OK if successful, else COAP_RESPONSE_FAIL which triggers sending a RST packet.

Definition at line 53 of file net.h.

◆ coap_response_t

Enumeration Type Documentation

◆ coap_response_t

Enumerator
COAP_RESPONSE_FAIL 

Response not liked - send CoAP RST packet.

COAP_RESPONSE_OK 

Response is fine.

Definition at line 36 of file net.h.

Function Documentation

◆ coap_can_exit()

int coap_can_exit ( coap_context_t context)

Returns 1 if there are no messages to send or to dispatch in the context's queues.

Definition at line 3166 of file net.c.

◆ coap_context_get_coap_fd()

int coap_context_get_coap_fd ( const coap_context_t context)

Get the libcoap internal file descriptor for using in an application's select() or returned as an event in an application's epoll_wait() call.

Parameters
contextThe coap_context_t object.
Returns
The libcoap file descriptor or -1 if epoll is not available.

Definition at line 493 of file net.c.

◆ coap_context_get_csm_timeout()

unsigned int coap_context_get_csm_timeout ( const coap_context_t context)

Get the CSM timeout value.

Parameters
contextThe coap_context_t object.
Returns
The CSM timeout value.

Definition at line 478 of file net.c.

◆ coap_context_get_max_handshake_sessions()

unsigned int coap_context_get_max_handshake_sessions ( const coap_context_t context)

Get the session timeout value.

Parameters
contextThe coap_context_t object.
Returns
The maximim number of sessions in (D)TLS handshake value.

Definition at line 467 of file net.c.

◆ coap_context_get_max_idle_sessions()

unsigned int coap_context_get_max_idle_sessions ( const coap_context_t context)

Get the maximum idle sessions count.

Parameters
contextThe coap_context_t object.
Returns
The count of max idle sessions.

Definition at line 456 of file net.c.

◆ coap_context_get_session_timeout()

unsigned int coap_context_get_session_timeout ( const coap_context_t context)

Get the session timeout value.

Parameters
contextThe coap_context_t object.
Returns
The session timeout value.

Definition at line 489 of file net.c.

◆ coap_context_set_csm_timeout()

void coap_context_set_csm_timeout ( coap_context_t context,
unsigned int  csm_tmeout 
)

Set the CSM timeout value.

The number of seconds to wait for a (TCP) CSM negotiation response from the peer. 0 (the default) means use wait forever.

Parameters
contextThe coap_context_t object.
csm_tmeoutThe CSM timeout value.

Definition at line 472 of file net.c.

◆ coap_context_set_keepalive()

void coap_context_set_keepalive ( coap_context_t context,
unsigned int  seconds 
)

Set the context keepalive timer for sessions.

A keepalive message will be sent after if a session has been inactive, i.e. no packet sent or received, for the given number of seconds. For unreliable protocols, a CoAP Empty message will be sent. If a CoAP RST is not received, the CoAP Empty messages will get resent based on the Confirmable retry parameters until there is a failure timeout, at which point the session will be considered as disconnected. For reliable protocols, a CoAP PING message will be sent. If a CoAP PONG has not been received before the next PING is due to be sent, the session will be considered as disconnected.

Parameters
contextThe coap_context_t object.
secondsNumber of seconds for the inactivity timer, or zero to disable CoAP-level keepalive messages.

Definition at line 445 of file net.c.

◆ coap_context_set_max_handshake_sessions()

void coap_context_set_max_handshake_sessions ( coap_context_t context,
unsigned int  max_handshake_sessions 
)

Set the maximum number of sessions in (D)TLS handshake value.

If this number is exceeded, the least recently used server session in handshake is completely removed. 0 (the default) means that the number is not monitored.

Parameters
contextThe coap_context_t object.
max_handshake_sessionsThe maximum number of sessions in handshake.

Definition at line 461 of file net.c.

◆ coap_context_set_max_idle_sessions()

void coap_context_set_max_idle_sessions ( coap_context_t context,
unsigned int  max_idle_sessions 
)

Set the maximum idle sessions count.

The number of server sessions that are currently not in use. If this number is exceeded, the least recently used server session is completely removed. 0 (the default) means that the number is not monitored.

Parameters
contextThe coap_context_t object.
max_idle_sessionsThe maximum idle session count.

Definition at line 450 of file net.c.

◆ coap_context_set_pki()

int coap_context_set_pki ( coap_context_t context,
const coap_dtls_pki_t setup_data 
)

Set the context's default PKI information for a server.

Parameters
contextThe current coap_context_t object.
setup_dataIf NULL, PKI authentication will fail. Certificate information required.
Returns
1 if successful, else 0.

Definition at line 420 of file net.c.

+ Here is the call graph for this function:

◆ coap_context_set_pki_root_cas()

int coap_context_set_pki_root_cas ( coap_context_t context,
const char *  ca_file,
const char *  ca_dir 
)

Set the context's default Root CA information for a client or server.

Parameters
contextThe current coap_context_t object.
ca_fileIf not NULL, is the full path name of a PEM encoded file containing all the Root CAs to be used.
ca_dirIf not NULL, points to a directory containing PEM encoded files containing all the Root CAs to be used.
Returns
1 if successful, else 0.

Definition at line 435 of file net.c.

+ Here is the call graph for this function:

◆ coap_context_set_psk()

int coap_context_set_psk ( coap_context_t context,
const char *  hint,
const uint8_t *  key,
size_t  key_len 
)

Set the context's default PSK hint and/or key for a server.

Parameters
contextThe current coap_context_t object.
hintThe default PSK server hint sent to a client. If NULL, PSK authentication is disabled. Empty string is a valid hint.
keyThe default PSK key. If NULL, PSK authentication will fail.
key_lenThe default PSK key's length. If 0, PSK authentication will fail.
Returns
1 if successful, else 0.

Definition at line 386 of file net.c.

+ Here is the call graph for this function:

◆ coap_context_set_psk2()

int coap_context_set_psk2 ( coap_context_t context,
coap_dtls_spsk_t setup_data 
)

Set the context's default PSK hint and/or key for a server.

Parameters
contextThe current coap_context_t object.
setup_dataIf NULL, PSK authentication will fail. PSK information required.
Returns
1 if successful, else 0.

Definition at line 406 of file net.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_context_set_session_timeout()

void coap_context_set_session_timeout ( coap_context_t context,
unsigned int  session_timeout 
)

Set the session timeout value.

The number of seconds of inactivity after which an unused server session will be closed. 0 means use default (300 secs).

Parameters
contextThe coap_context_t object.
session_timeoutThe session timeout value.

Definition at line 483 of file net.c.

◆ coap_free_context()

void coap_free_context ( coap_context_t context)

CoAP stack context must be released with coap_free_context().

This function clears all entries from the receive queue and send queue and deletes the resources that have been registered with context, and frees the attached endpoints.

Parameters
contextThe current coap_context_t object to free off.

Definition at line 629 of file net.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_get_app_data()

void* coap_get_app_data ( const coap_context_t context)

Returns any application-specific data that has been stored with context using the function coap_set_app_data().

This function will return NULL if no data has been stored.

Parameters
contextThe CoAP context.
Returns
The data previously stored or NULL if not data stored.

Definition at line 623 of file net.c.

◆ coap_handle_event()

int coap_handle_event ( coap_context_t context,
coap_event_t  event,
coap_session_t session 
)

Invokes the event handler of context for the given event and data.

Parameters
contextThe CoAP context whose event handler is to be called.
eventThe event to deliver.
sessionThe session related to event.
Returns
The result from the associated event handler or 0 if none was registered.

Definition at line 3155 of file net.c.

+ Here is the caller graph for this function:

◆ coap_join_mcast_group_intf()

int coap_join_mcast_group_intf ( coap_context_t ctx,
const char *  groupname,
const char *  ifname 
)

Function interface for joining a multicast group for listening for the currently defined endpoints that are UDP.

Parameters
ctxThe current context.
groupnameThe name of the group that is to be joined for listening.
ifnameNetwork interface to join the group on, or NULL if first appropriate interface is to be chosen by the O/S.
Returns
0 on success, -1 on error

Definition at line 3272 of file net.c.

+ Here is the call graph for this function:

◆ coap_mcast_set_hops()

int coap_mcast_set_hops ( coap_session_t session,
size_t  hops 
)

Function interface for defining the hop count (ttl) for sending multicast traffic.

Parameters
sessionThe current contexsion.
hopsThe number of hops (ttl) to use before the multicast packet expires.
Returns
1 on success, 0 on error

Definition at line 3495 of file net.c.

+ Here is the call graph for this function:

◆ coap_new_context()

coap_context_t* coap_new_context ( const coap_address_t listen_addr)

Creates a new coap_context_t object that will hold the CoAP stack status.

Definition at line 503 of file net.c.

+ Here is the call graph for this function:

◆ coap_new_error_response()

coap_pdu_t* coap_new_error_response ( coap_pdu_t request,
unsigned char  code,
coap_opt_filter_t opts 
)

Creates a new ACK PDU with specified error code.

The options specified by the filter expression opts will be copied from the original request contained in request. Unless SHORT_ERROR_RESPONSE was defined at build time, the textual reason phrase for code will be added as payload, with Content-Type 0. This function returns a pointer to the new response message, or NULL on error. The storage allocated for the new message must be released with coap_free().

Parameters
requestSpecification of the received (confirmable) request.
codeThe error code to set.
optsAn option filter that specifies which options to copy from the original request in node.
Returns
A pointer to the new message or NULL on error.

Definition at line 2057 of file net.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_new_message_id()

uint16_t coap_new_message_id ( coap_session_t session)

Returns a new message id and updates session->tx_mid accordingly.

The message id is returned in network byte order to make it easier to read in tracing tools.

Parameters
sessionThe current coap_session_t object.
Returns
Incremented message id in network byte order.

Definition at line 1159 of file coap_session.c.

+ Here is the caller graph for this function:

◆ coap_register_nack_handler()

void coap_register_nack_handler ( coap_context_t context,
coap_nack_handler_t  handler 
)

Registers a new message handler that is called whenever a confirmable message (request or response) is dropped after all retries have been exhausted, or a rst message was received, or a network or TLS level event was received that indicates delivering the message is not possible.

Parameters
contextThe context to register the handler for.
handlerThe nack handler to register.

Definition at line 3248 of file net.c.

◆ coap_register_option()

void coap_register_option ( coap_context_t ctx,
uint16_t  type 
)

Registers the option type type with the given context object ctx.

Parameters
ctxThe context to use.
typeThe option type to register.

Definition at line 3266 of file net.c.

+ Here is the call graph for this function:

◆ coap_register_ping_handler()

void coap_register_ping_handler ( coap_context_t context,
coap_ping_handler_t  handler 
)

Registers a new message handler that is called whenever a CoAP Ping message is received.

Parameters
contextThe context to register the handler for.
handlerThe ping handler to register.

Definition at line 3254 of file net.c.

◆ coap_register_pong_handler()

void coap_register_pong_handler ( coap_context_t context,
coap_pong_handler_t  handler 
)

Registers a new message handler that is called whenever a CoAP Pong message is received.

Parameters
contextThe context to register the handler for.
handlerThe pong handler to register.

Definition at line 3260 of file net.c.

◆ coap_register_response_handler()

void coap_register_response_handler ( coap_context_t context,
coap_response_handler_t  handler 
)

Registers a new message handler that is called whenever a response is received.

Parameters
contextThe context to register the handler for.
handlerThe response handler to register.

Definition at line 3242 of file net.c.

◆ coap_send()

coap_mid_t coap_send ( coap_session_t session,
coap_pdu_t pdu 
)

Sends a CoAP message to given peer.

The memory that is allocated for the pdu will be released by coap_send(). The caller must not use the pdu after calling coap_send().

Parameters
sessionThe CoAP session.
pduThe CoAP PDU to send.
Returns
The message id of the sent message or COAP_INVALID_MID on error.

Definition at line 1154 of file net.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_send_ack()

coap_mid_t coap_send_ack ( coap_session_t session,
coap_pdu_t request 
)

Sends an ACK message with code 0 for the specified request to dst.

This function returns the corresponding message id if the message was sent or COAP_INVALID_MID on error.

Parameters
sessionThe CoAP session.
requestThe request to be acknowledged.
Returns
The message id if ACK was sent or COAP_INVALID_MID on error.

Definition at line 750 of file net.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_send_error()

coap_mid_t coap_send_error ( coap_session_t session,
coap_pdu_t request,
unsigned char  code,
coap_opt_filter_t opts 
)

Sends an error response with code code for request request to dst.

opts will be passed to coap_new_error_response() to copy marked options from the request. This function returns the message id if the message was sent, or COAP_INVALID_MID otherwise.

Parameters
sessionThe CoAP session.
requestThe original request to respond to.
codeThe response code.
optsA filter that specifies the options to copy from the request.
Returns
The message id if the message was sent, or COAP_INVALID_MID otherwise.

Definition at line 900 of file net.c.

+ Here is the call graph for this function:

◆ coap_send_large()

coap_mid_t coap_send_large ( coap_session_t session,
coap_pdu_t pdu 
)

Sends a CoAP message to given peer.

The memory that is allocated for the pdu will be released by coap_send_large(). The caller must not use the pdu after calling coap_send_large().

If the response body is split into multiple payloads using blocks, libcoap will handle asking for the subsequent blocks and any necessary recovery needed.

Parameters
sessionThe CoAP session.
pduThe CoAP PDU to send.
Returns
The message id of the sent message or COAP_INVALID_MID on error.

Definition at line 1054 of file net.c.

+ Here is the call graph for this function:

◆ coap_send_message_type()

coap_mid_t coap_send_message_type ( coap_session_t session,
coap_pdu_t request,
unsigned char  type 
)

Helper function to create and send a message with type (usually ACK or RST).

This function returns COAP_INVALID_MID when the message was not sent, a valid transaction id otherwise.

Parameters
sessionThe CoAP session.
requestThe request that should be responded to.
typeWhich type to set.
Returns
message id on success or COAP_INVALID_MID otherwise.

Definition at line 918 of file net.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_send_rst()

COAP_STATIC_INLINE coap_mid_t coap_send_rst ( coap_session_t session,
coap_pdu_t request 
)

Sends an RST message with code 0 for the specified request to dst.

This function returns the corresponding message id if the message was sent or COAP_INVALID_MID on error.

Parameters
sessionThe CoAP session.
requestThe request to be reset.
Returns
The message id if RST was sent or COAP_INVALID_MID on error.

Definition at line 457 of file net.h.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_set_app_data()

void coap_set_app_data ( coap_context_t context,
void *  data 
)

Stores data with the given CoAP context.

This function overwrites any value that has previously been stored with context.

Parameters
contextThe CoAP context.
dataThe data to store with wih the context. Note that this data must be valid during the lifetime of context.

Definition at line 617 of file net.c.

◆ coap_ticks()

void coap_ticks ( coap_tick_t )

Returns the current value of an internal tick counter.

The counter counts COAP_TICKS_PER_SECOND ticks every second.