Context Handling

Internal API for Context Handling. More...

Collaboration diagram for Context Handling:

Data Structures
struct	coap_queue_t
	Queue entry. More...
struct	coap_context_t
	The CoAP stack's global state is stored in a coap_context_t object. More...

Functions
int	coap_insert_node (coap_queue_t **queue, coap_queue_t *node)
	Adds node to given queue, ordered by variable t in node.
COAP_API int	coap_delete_node (coap_queue_t *node)
	Destroys specified node.
int	coap_delete_node_lkd (coap_queue_t *node)
	Destroys specified node.
void	coap_delete_all (coap_queue_t *queue)
	Removes all items from given queue and frees the allocated storage.
coap_queue_t *	coap_new_node (void)
	Creates a new node suitable for adding to the CoAP sendqueue.
unsigned int	coap_adjust_basetime (coap_context_t *ctx, coap_tick_t now)
	Set sendqueue_basetime in the given context object ctx to now.
coap_queue_t *	coap_peek_next (coap_context_t *context)
	Returns the next pdu to send without removing from sendqeue.
coap_queue_t *	coap_pop_next (coap_context_t *context)
	Returns the next pdu to send and removes it from the sendqeue.
coap_mid_t	coap_retransmit (coap_context_t *context, coap_queue_t *node)
	Handles retransmissions of confirmable messages.
int	coap_handle_dgram (coap_context_t *ctx, coap_session_t *session, uint8_t *data, size_t data_len)
	Parses and interprets a CoAP datagram with context ctx.
int	coap_remove_from_queue (coap_queue_t **queue, coap_session_t *session, coap_mid_t id, coap_queue_t **node)
	This function removes the element with given id from the list given list.
coap_mid_t	coap_wait_ack (coap_context_t *context, coap_session_t *session, coap_queue_t *node)
void	coap_cancel_all_messages (coap_context_t *context, coap_session_t *session, coap_bin_const_t *token)
	Cancels all outstanding messages for session session that have the specified token.
void	coap_cancel_session_messages (coap_context_t *context, coap_session_t *session, coap_nack_reason_t reason)
	Cancels all outstanding messages for session session.
uint16_t	coap_new_message_id_lkd (coap_session_t *session)
	Returns a new message id and updates session->tx_mid accordingly.
void	coap_dispatch (coap_context_t *context, coap_session_t *session, coap_pdu_t *pdu)
	Dispatches the PDUs from the receive queue in given context.
int	coap_option_check_critical (coap_session_t *session, coap_pdu_t *pdu, coap_opt_filter_t *unknown)
	Verifies that pdu contains no unknown critical options.
coap_pdu_t *	coap_wellknown_response (coap_context_t *context, coap_session_t *session, coap_pdu_t *request)
	Creates a new response for given request with the contents of .well-known/core.
unsigned int	coap_calc_timeout (coap_session_t *session, unsigned char r)
	Calculates the initial timeout based on the session CoAP transmission parameters 'ack_timeout', 'ack_random_factor', and COAP_TICKS_PER_SECOND.
int	coap_check_code_class (coap_session_t *session, coap_pdu_t *pdu)
	Check whether the pdu contains a valid code class.
coap_mid_t	coap_send_internal (coap_session_t *session, coap_pdu_t *pdu)
	Sends a CoAP message to given peer.
int	coap_client_delay_first (coap_session_t *session)
	Delay the sending of the first client request until some other negotiation has completed.
void	coap_free_context_lkd (coap_context_t *context)
	CoAP stack context must be released with coap_free_context_lkd().
int	coap_handle_event_lkd (coap_context_t *context, coap_event_t event, coap_session_t *session)
	Invokes the event handler of context for the given event and data.
int	coap_can_exit_lkd (coap_context_t *context)
	Returns 1 if there are no messages to send or to dispatch in the context's queues.
int	coap_join_mcast_group_intf_lkd (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.
void	coap_register_option_lkd (coap_context_t *ctx, uint16_t type)
	Registers the option type type with the given context object ctx.
int	coap_context_set_pki_lkd (coap_context_t *context, const coap_dtls_pki_t *setup_data)
	Set the context's default PKI information for a server.
int	coap_context_set_pki_root_cas_lkd (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.
int	coap_context_set_psk_lkd (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.
int	coap_context_set_psk2_lkd (coap_context_t *context, coap_dtls_spsk_t *setup_data)
	Set the context's default PSK hint and/or key for a server.

Detailed Description

Internal API for Context Handling.

Function Documentation

coap_adjust_basetime()

unsigned int coap_adjust_basetime	(	coap_context_t *	ctx,
		coap_tick_t	now
	)

Set sendqueue_basetime in the given context object ctx to now.

This function returns the number of elements in the queue head that have timed out.

Definition at line 130 of file coap_net.c.

coap_calc_timeout()

unsigned int coap_calc_timeout	(	coap_session_t *	session,
		unsigned char	r
	)

Calculates the initial timeout based on the session CoAP transmission parameters 'ack_timeout', 'ack_random_factor', and COAP_TICKS_PER_SECOND.

The calculation requires 'ack_timeout' and 'ack_random_factor' to be in Qx.FRAC_BITS fixed point notation, whereas the passed parameter r is interpreted as the fractional part of a Q0.MAX_BITS random value.

Parameters

session	session timeout is associated with
r	random value as fractional part of a Q0.MAX_BITS fixed point value

Returns

COAP_TICKS_PER_SECOND * 'ack_timeout' * (1 + ('ack_random_factor' - 1) * r)

Definition at line 1123 of file coap_net.c.

Here is the caller graph for this function:

coap_can_exit_lkd()

int coap_can_exit_lkd

(

coap_context_t *

context

)

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

Note: This function must be called in the locked state.

Parameters

context

The CoAP context to check.

Returns

0 if there are still pending transmits else 1 if nothing queued for transmission. Note that 0 does not mean there has been a response to a transmitted request.

Definition at line 4558 of file coap_net.c.

Here is the caller graph for this function:

coap_cancel_all_messages()

void coap_cancel_all_messages	(	coap_context_t *	context,
		coap_session_t *	session,
		coap_bin_const_t *	token
	)

Cancels all outstanding messages for session session that have the specified token.

Parameters

context	The context in use.
session	Session of the messages to remove.
token	Message token.

Definition at line 2762 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_cancel_session_messages()

void coap_cancel_session_messages	(	coap_context_t *	context,
		coap_session_t *	session,
		coap_nack_reason_t	reason
	)

Cancels all outstanding messages for session session.

Parameters

context	The context in use.
session	Session of the messages to remove.
reason	The reasion for the session cancellation

Definition at line 2723 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_check_code_class()

int coap_check_code_class	(	coap_session_t *	session,
		coap_pdu_t *	pdu
	)

Check whether the pdu contains a valid code class.

Parameters

session	The CoAP session.
pdu	The PDU to check.

Returns

1 valid, 0 invalid.

Definition at line 1294 of file coap_net.c.

Here is the caller graph for this function:

coap_client_delay_first()

int coap_client_delay_first

(

coap_session_t *

session

)

Delay the sending of the first client request until some other negotiation has completed.

Parameters

session

The CoAP session.

Returns

1 if everything was ok, 0 otherwise.

Definition at line 1226 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_context_set_pki_lkd()

int coap_context_set_pki_lkd	(	coap_context_t *	context,
		const coap_dtls_pki_t *	setup_data
	)

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

Note: This function must be called in the locked state.

Parameters

context	The current coap_context_t object.
setup_data	If NULL, PKI authentication will fail. Certificate information required.

Returns

1 if successful, else 0.

coap_context_set_pki_root_cas_lkd()

int coap_context_set_pki_root_cas_lkd	(	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.

Note: This function must be called in the locked state.

Parameters

context	The current coap_context_t object.
ca_file	If not NULL, is the full path name of a PEM encoded file containing all the Root CAs to be used.
ca_dir	If 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 448 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_context_set_psk2_lkd()

int coap_context_set_psk2_lkd	(	coap_context_t *	context,
		coap_dtls_spsk_t *	setup_data
	)

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

Note: This function must be called in the locked state.

Parameters

context	The current coap_context_t object.
setup_data	If NULL, PSK authentication will fail. PSK information required.

Returns

1 if successful, else 0.

coap_context_set_psk_lkd()

int coap_context_set_psk_lkd	(	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.

Deprecated:

Use coap_context_set_psk2() instead.

Note: This function must be called in the locked state.

Parameters

context	The current coap_context_t object.
hint	The default PSK server hint sent to a client. If NULL, PSK authentication is disabled. Empty string is a valid hint.
key	The default PSK key. If NULL, PSK authentication will fail.
key_len	The default PSK key's length. If 0, PSK authentication will fail.

Returns

1 if successful, else 0.

coap_delete_all()

void coap_delete_all

(

coap_queue_t *

queue

)

Removes all items from given queue and frees the allocated storage.

Internal function.

Parameters

queue

The queue to delete.

Definition at line 247 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_delete_node()

COAP_API int coap_delete_node

(

coap_queue_t *

node

)

Destroys specified node.

Note: Not a part of the Public API.

Parameters

node	Node entry to remove.

Returns

1 node deleted from queue, 0 failure.

Definition at line 204 of file coap_net.c.

Here is the call graph for this function:

coap_delete_node_lkd()

int coap_delete_node_lkd

(

coap_queue_t *

node

)

Destroys specified node.

Note: Needs to be called in a locked state if node->session is set.

Parameters

node	Node entry to remove.

Returns

1 node deleted from queue, 0 failure.

Definition at line 227 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_dispatch()

void coap_dispatch	(	coap_context_t *	context,
		coap_session_t *	session,
		coap_pdu_t *	pdu
	)

Dispatches the PDUs from the receive queue in given context.

Definition at line 4024 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_free_context_lkd()

void coap_free_context_lkd

(

coap_context_t *

context

)

CoAP stack context must be released with coap_free_context_lkd().

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.

Note: This function must be called in the locked state.

Parameters

context

The current coap_context_t object to free off.

Definition at line 755 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_handle_dgram()

int coap_handle_dgram	(	coap_context_t *	ctx,
		coap_session_t *	session,
		uint8_t *	data,
		size_t	data_len
	)

Parses and interprets a CoAP datagram with context ctx.

This function returns 0 if the datagram was handled, or a value less than zero on error.

Parameters

ctx	The current CoAP context.
session	The current CoAP session.
data	The received packet'd data.
data_len	The received packet'd data length.

Returns

0 if message was handled successfully, or less than zero on error.

Definition at line 2633 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_handle_event_lkd()

int coap_handle_event_lkd	(	coap_context_t *	context,
		coap_event_t	event,
		coap_session_t *	session
	)

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

Note: This function must be called in the locked state.

Parameters

context	The CoAP context whose event handler is to be called.
event	The event to deliver.
session	The session related to event.

Returns

The result from the associated event handler or 0 if none was registered.

Definition at line 4496 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_insert_node()

int coap_insert_node	(	coap_queue_t **	queue,
		coap_queue_t *	node
	)

Adds node to given queue, ordered by variable t in node.

Parameters

queue	Queue to add to.
node	Node entry to add to Queue.

Returns

1 added to queue, 0 failure.

Definition at line 167 of file coap_net.c.

Here is the caller graph for this function:

coap_join_mcast_group_intf_lkd()

int coap_join_mcast_group_intf_lkd	(	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.

Note: This function must be called in the locked state.

Parameters

ctx	The current context.
groupname	The name of the group that is to be joined for listening.
ifname	Network 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

coap_new_message_id_lkd()

uint16_t coap_new_message_id_lkd

(

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.

Note: This function must be called in the locked state.

Parameters

session

The current coap_session_t object.

Returns

Incremented message id in network byte order.

Definition at line 1933 of file coap_session.c.

Here is the caller graph for this function:

coap_new_node()

coap_queue_t * coap_new_node

(

void

)

Creates a new node suitable for adding to the CoAP sendqueue.

Returns

New node entry, or NULL if failure.

Definition at line 256 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_option_check_critical()

int coap_option_check_critical	(	coap_session_t *	session,
		coap_pdu_t *	pdu,
		coap_opt_filter_t *	unknown
	)

Verifies that pdu contains no unknown critical options.

Options must be registered at ctx, using the function coap_register_option(). A basic set of options is registered automatically by coap_new_context(). This function returns 1 if pdu is ok, 0 otherwise. The given filter object unknown will be updated with the unknown options. As only COAP_MAX_OPT options can be signalled this way, remaining options must be examined manually.

coap_opt_filter_t f = COAP_OPT_NONE;
coap_opt_iterator_t opt_iter;
 
if (coap_option_check_critical(session, pdu, f) == 0) {
  coap_option_iterator_init(pdu, &opt_iter, f);
 
  while (coap_option_next(&opt_iter)) {
    if (opt_iter.type & 0x01) {
      ... handle unknown critical option in opt_iter ...
    }
  }
}

Parameters

session	The current session.
pdu	The PDU to check.
unknown	The output filter that will be updated to indicate the unknown critical options found in pdu.

Returns

1 if everything was ok, 0 otherwise.

Definition at line 846 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_peek_next()

coap_queue_t * coap_peek_next

(

coap_context_t *

context

)

Returns the next pdu to send without removing from sendqeue.

Definition at line 270 of file coap_net.c.

Here is the caller graph for this function:

coap_pop_next()

coap_queue_t * coap_pop_next

(

coap_context_t *

context

)

Returns the next pdu to send and removes it from the sendqeue.

Definition at line 278 of file coap_net.c.

Here is the caller graph for this function:

coap_register_option_lkd()

void coap_register_option_lkd	(	coap_context_t *	ctx,
		uint16_t	type
	)

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

Note: This function must be called in the locked state.

Parameters

ctx	The context to use.
type	The option type to register.

Definition at line 4721 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_remove_from_queue()

int coap_remove_from_queue	(	coap_queue_t **	queue,
		coap_session_t *	session,
		coap_mid_t	id,
		coap_queue_t **	node
	)

This function removes the element with given id from the list given list.

If id was found, node is updated to point to the removed element. Note that the storage allocated by node is not released. The caller must do this manually using coap_delete_node(). This function returns 1 if the element with id id was found, 0 otherwise. For a return value of 0, the contents of node is undefined.

Parameters

queue	The queue to search for id.
session	The session to look for.
id	The message id to look for.
node	If found, node is updated to point to the removed node. You must release the storage pointed to by node manually.

Returns

1 if id was found, 0 otherwise.

Definition at line 2678 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_retransmit()

coap_mid_t coap_retransmit	(	coap_context_t *	context,
		coap_queue_t *	node
	)

Handles retransmissions of confirmable messages.

Parameters

context	The CoAP context.
node	The node to retransmit.

Returns

The message id of the sent message or COAP_INVALID_MID on error.

Definition at line 2055 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_send_internal()

coap_mid_t coap_send_internal	(	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_internal(). The caller must not use the pdu after calling coap_send_internal().

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

session	The CoAP session.
pdu	The CoAP PDU to send.

Returns

The message id of the sent message or COAP_INVALID_MID on error.

Definition at line 1679 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_wait_ack()

coap_mid_t coap_wait_ack	(	coap_context_t *	context,
		coap_session_t *	session,
		coap_queue_t *	node
	)

Definition at line 1149 of file coap_net.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_wellknown_response()

coap_pdu_t * coap_wellknown_response	(	coap_context_t *	context,
		coap_session_t *	session,
		coap_pdu_t *	request
	)

Creates a new response for given request with the contents of .well-known/core.

The result is NULL on error or a newly allocated PDU that must be either sent with coap_sent() or released by coap_delete_pdu().

Parameters

context	The current coap context to use.
session	The CoAP session.
request	The request for .well-known/core .

Returns

A new 2.05 response for .well-known/core or NULL on error.