libcoap 4.3.2rc2

Data Structures | Functions
Context Handling
Libcoap Internal API

Internal API for Context Handling. More...

## 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`. More...
int | coap_delete_node (coap_queue_t *node)
| Destroys specified `node`. More...
void | coap_delete_all (coap_queue_t *queue)
| Removes all items from given `queue` and frees the allocated storage. More...
coap_queue_t * | coap_new_node (void)
| Creates a new node suitable for adding to the CoAP sendqueue. More...
unsigned int | coap_adjust_basetime (coap_context_t *ctx, coap_tick_t now)
| Set sendqueue_basetime in the given context object `ctx` to `now`. More...
coap_queue_t * | coap_peek_next (coap_context_t *context)
| Returns the next pdu to send without removing from sendqeue. More...
coap_queue_t * | coap_pop_next (coap_context_t *context)
| Returns the next pdu to send and removes it from the sendqeue. More...
coap_mid_t | coap_retransmit (coap_context_t *context, coap_queue_t *node)
| Handles retransmissions of confirmable messages. More...
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`. More...
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. More...
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. More...
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`. More...
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. More...
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. More...
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. More...
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. More...
coap_mid_t | coap_send_internal (coap_session_t *session, coap_pdu_t *pdu)
| Sends a CoAP message to given peer. More...
int | coap_client_delay_first (coap_session_t *session)
| Delay the sending of the first client request until some other negotiation has completed. More...

## 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 129 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 881 of file coap_net.c.

## ◆ 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 2323 of file coap_net.c.

## ◆ 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 2282 of file coap_net.c.

## ◆ 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 986 of file coap_net.c.

## ◆ 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 223 of file coap_net.c.

## ◆ coap_delete_node()

int coap_delete_node | ( | coap_queue_t * | node | ) |

Destroys specified `node`.

Parameters

  node | Node entry to remove.

Returns
  `1` node deleted from queue, `0` failure.

Definition at line 203 of file coap_net.c.

## ◆ 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 3517 of file coap_net.c.

## ◆ 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 2200 of file coap_net.c.

## ◆ 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 166 of file coap_net.c.

## ◆ 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 232 of file coap_net.c.

## ◆ 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:655
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 655 of file coap_net.c.

## ◆ 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 246 of file coap_net.c.

## ◆ 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 254 of file coap_net.c.

## ◆ 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 2237 of file coap_net.c.

## ◆ 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 1610 of file coap_net.c.

## ◆ 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 1381 of file coap_net.c.

## ◆ coap_wait_ack()

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

Definition at line 907 of file coap_net.c.

## ◆ 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.