Loading...
Searching...
No Matches
Observe Subscription
Libcoap Internal API

Internal API for handling CoAP Observe Subscriptions (RFC7641). More...

Collaboration diagram for Observe Subscription:

## Data Structures

struct | coap_subscription_t
| Number of notifications that may be sent non-confirmable before a confirmable message is sent to detect if observers are alive. More...

## Functions

void | coap_subscription_init (coap_subscription_t *)
void | coap_handle_failed_notify (coap_context_t *context, coap_session_t *session, const coap_bin_const_t *token)
| Handles a failed observe notify.
coap_subscription_t * | coap_add_observer (coap_resource_t *resource, coap_session_t *session, const coap_bin_const_t *token, const coap_pdu_t *pdu)
| Adds the specified peer as observer for `resource`.
coap_subscription_t * | coap_find_observer (coap_resource_t *resource, coap_session_t *session, const coap_bin_const_t *token)
| Returns a subscription object for given `peer`.
void | coap_touch_observer (coap_context_t *context, coap_session_t *session, const coap_bin_const_t *token)
| Flags that data is ready to be sent to observers.
int | coap_delete_observer (coap_resource_t *resource, coap_session_t *session, const coap_bin_const_t *token)
| Removes any subscription for `session` observer from `resource` and releases the allocated storage.
int | coap_delete_observer_request (coap_resource_t *resource, coap_session_t *session, const coap_bin_const_t *token, coap_pdu_t *request)
| Removes any subscription for `session` observer from `resource` and releases the allocated storage.
void | coap_delete_observers (coap_context_t *context, coap_session_t *session)
| Removes any subscription for `session` and releases the allocated storage.
int | coap_resource_notify_observers_lkd (coap_resource_t *resource, const coap_string_t *query)
| Initiate the sending of an Observe packet for all observers of `resource`, optionally matching `query` if not NULL.
void | coap_check_notify_lkd (coap_context_t *context)
| Checks all known resources to see if they are dirty and then notifies subscribed observers.
void | coap_persist_cleanup (coap_context_t *context)
| Close down persist tracking, releasing any memory used.
coap_subscription_t * | coap_persist_observe_add_lkd (coap_context_t *context, coap_proto_t e_proto, const coap_address_t *e_listen_addr, const coap_addr_tuple_t *s_addr_info, const coap_bin_const_t *raw_packet, const coap_bin_const_t *oscore_info)
| Set up an active subscription for an observe that was previously active over a coap-server inadvertant restart.
int | coap_persist_startup_lkd (coap_context_t *context, const char *dyn_resource_save_file, const char *observe_save_file, const char *obs_cnt_save_file, uint32_t save_freq)
| Start up persist tracking using the libcoap module.
void | coap_persist_stop_lkd (coap_context_t *context)
| Stop tracking persist information, leaving the current persist information in the files defined in coap_persist_startup().
int | coap_cancel_observe_lkd (coap_session_t *session, coap_binary_t *token, coap_pdu_type_t message_type)
| Cancel an observe that is being tracked by the client large receive logic.

## Detailed Description

Internal API for handling CoAP Observe Subscriptions (RFC7641).

## Function Documentation

## coap_add_observer()

coap_subscription_t * coap_add_observer | ( | coap_resource_t * | resource,
|  | coap_session_t * | session,
|  | const coap_bin_const_t * | token,
|  | const coap_pdu_t * | pdu )

Adds the specified peer as observer for `resource`.

The subscription is identified by the given `token`. This function returns the registered subscription information if the `observer` has been added, or `NULL` on error.

Parameters

  resource | The observed resource.
  session | The observer's session
  token | The token that identifies this subscription.
  pdu | The requesting pdu.

Returns
  A pointer to the added/updated subscription information or `NULL` on error.

## coap_cancel_observe_lkd()

int coap_cancel_observe_lkd | ( | coap_session_t * | session,
|  | coap_binary_t * | token,
|  | coap_pdu_type_t | message_type )

Cancel an observe that is being tracked by the client large receive logic.

(coap_context_set_block_mode() has to be called) This will trigger the sending of an observe cancel pdu to the server.

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

Parameters

  session | The session that is being used for the observe.
  token | The original token used to initiate the observation.
  message_type | The COAP_MESSAGE_ type (NON or CON) to send the observe cancel pdu as.

Returns
  `1` if observe cancel transmission initiation is successful, else `0`.

Here is the caller graph for this function:

## coap_check_notify_lkd()

void coap_check_notify_lkd | ( | coap_context_t * | context | ) |

Checks all known resources to see if they are dirty and then notifies subscribed observers.

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

Parameters

  context | The context to check for dirty resources.

Here is the caller graph for this function:

## coap_delete_observer()

int coap_delete_observer | ( | coap_resource_t * | resource,
|  | coap_session_t * | session,
|  | const coap_bin_const_t * | token )

Removes any subscription for `session` observer from `resource` and releases the allocated storage.

The result is `1` if an observation relationship with `session` observer and `token` existed, `0` otherwise.

Parameters

  resource | The observed resource.
  session | The observer's session.
  token | The token that identifies this subscription or `NULL` for the first subscription.

Returns
  `1` if the observer has been deleted, `0` otherwise.

Here is the caller graph for this function:

## coap_delete_observer_request()

int coap_delete_observer_request | ( | coap_resource_t * | resource,
|  | coap_session_t * | session,
|  | const coap_bin_const_t * | token,
|  | coap_pdu_t * | request )

Removes any subscription for `session` observer from `resource` and releases the allocated storage.

The result is `1` if an observation relationship with `session` observer and `token` existed, or cache-key derived from `request` matches, `0` otherwise.

Parameters

  resource | The observed resource.
  session | The observer's session.
  token | The token that identifies this subscription or `NULL` for the first subscription.
  request | The requesting PDU.

Returns
  `1` if the observer has been deleted, `0` otherwise.

## coap_delete_observers()

void coap_delete_observers | ( | coap_context_t * | context,
|  | coap_session_t * | session )

Removes any subscription for `session` and releases the allocated storage.

Parameters

  context | The CoAP context to use.
  session | The observer's session.

Here is the caller graph for this function:

## coap_find_observer()

coap_subscription_t * coap_find_observer | ( | coap_resource_t * | resource,
|  | coap_session_t * | session,
|  | const coap_bin_const_t * | token )

Returns a subscription object for given `peer`.

Parameters

  resource | The observed resource.
  session | The observer's session
  token | The token that identifies this subscription or `NULL` for the first subscription.

Returns
  A valid subscription if exists or `NULL` otherwise.

## coap_handle_failed_notify()

void coap_handle_failed_notify | ( | coap_context_t * | context,
|  | coap_session_t * | session,
|  | const coap_bin_const_t * | token )

Handles a failed observe notify.

Parameters

  context | The context holding the resource.
  session | The session that the observe notify failed on.
  token | The token used when the observe notify failed.

Here is the caller graph for this function:

## coap_persist_cleanup()

void coap_persist_cleanup | ( | coap_context_t * | context | ) |

Close down persist tracking, releasing any memory used.

Parameters

  context | The current CoAP context.

Here is the caller graph for this function:

## coap_persist_observe_add_lkd()

coap_subscription_t * coap_persist_observe_add_lkd | ( | coap_context_t * | context,
|  | coap_proto_t | e_proto,
|  | const coap_address_t * | e_listen_addr,
|  | const coap_addr_tuple_t * | s_addr_info,
|  | const coap_bin_const_t * | raw_packet,
|  | const coap_bin_const_t * | oscore_info )

Set up an active subscription for an observe that was previously active over a coap-server inadvertant restart.

Only UDP sessions currently supported.

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

Parameters

  context | The context that the session is to be associated with.
  e_proto | The CoAP protocol in use for the session / endpoint.
  e_listen_addr | The IP/port that the endpoint is listening on.
  s_addr_info | Local / Remote IP addresses. ports etc. of previous session.
  raw_packet | L7 packet as seen on the wire (could be concatenated if Block1 FETCH is being used).
  oscore_info | Has OSCORE information if OSCORE is protecting the session or NULL if OSCORE is not in use.

Returns
  ptr to subscription if success else `NULL`.

## coap_persist_startup_lkd()

int coap_persist_startup_lkd | ( | coap_context_t * | context,
|  | const char * | dyn_resource_save_file,
|  | const char * | observe_save_file,
|  | const char * | obs_cnt_save_file,
|  | uint32_t | save_freq )

Start up persist tracking using the libcoap module.

If the files already exist with saved data, then this information is used in building back up the persist information.

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

Parameters

  context | The current CoAP context.
  dyn_resource_save_file | File where dynamically created resource information is stored or NULL if not required.
  observe_save_file | File where observe information is stored or NULL if not required.
  obs_cnt_save_file | File where resource observe counter information is stored or NULL if not required.
  save_freq | Frequency of change of observe value for calling the save observe counter logic.

Returns
  `1` if success else `0`.

## coap_persist_stop_lkd()

void coap_persist_stop_lkd | ( | coap_context_t * | context | ) |

Stop tracking persist information, leaving the current persist information in the files defined in coap_persist_startup().

It is then safe to call coap_free_context() to close the application down cleanly.

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

Alternatively, if coap_persist_track_funcs() was called, then this will disable all the callbacks, as well as making sure that no 4.04 is sent out for any active observe subscriptions when the resource is deleted after subsequently calling coap_free_context().

Parameters

  context | The context that tracking information is to be stopped on.

## coap_resource_notify_observers_lkd()

int coap_resource_notify_observers_lkd | ( | coap_resource_t * | resource,
|  | const coap_string_t * | query )

Initiate the sending of an Observe packet for all observers of `resource`, optionally matching `query` if not NULL.

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

Parameters

  resource | The CoAP resource to use.
  query | The Query to match against or NULL

Returns
  `1` if the Observe has been triggered, `0` otherwise.

## coap_subscription_init()

void coap_subscription_init | ( | coap_subscription_t * |  | ) |

## coap_touch_observer()

void coap_touch_observer | ( | coap_context_t * | context,
|  | coap_session_t * | session,
|  | const coap_bin_const_t * | token )

Flags that data is ready to be sent to observers.

Parameters

  context | The CoAP context to use.
  session | The observer's session
  token | The corresponding token that has been used for the subscription.

Here is the caller graph for this function: