Loading...
Searching...
No Matches
Context Handling
Libcoap Internal API

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 4386 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 2616 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 2573 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 3871 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 2483 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 4358 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 1909 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 ...
}
}
}
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.
Definition coap_net.c:846
coap_option_next
coap_opt_t * coap_option_next(coap_opt_iterator_t *oi)
Updates the iterator oi to point to the next option.
Definition coap_option.c:153
coap_option_iterator_init
coap_opt_iterator_t * coap_option_iterator_init(const coap_pdu_t *pdu, coap_opt_iterator_t *oi, const coap_opt_filter_t *filter)
Initializes the given option iterator oi to point to the beginning of the pdu's option list.
Definition coap_option.c:117
coap_opt_filter_t
Definition coap_option.h:101
coap_opt_iterator_t
Iterator to run through PDU options.
Definition coap_option.h:168

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 4548 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 2528 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 1908 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.