Resource Configuraton

API functions for setting up resources. More...

## Macros

#define | COAP_ATTR_FLAGS_RELEASE_NAME 0x1
#define | COAP_ATTR_FLAGS_RELEASE_VALUE 0x2
#define | COAP_RESOURCE_FLAGS_RELEASE_URI 0x1
| The URI passed to coap_resource_init() is free'd by coap_delete_resource(). More...
#define | COAP_RESOURCE_FLAGS_NOTIFY_NON 0x0
| Notifications will be sent non-confirmable by default. More...
#define | COAP_RESOURCE_FLAGS_NOTIFY_CON 0x2
| Notifications will be sent confirmable. More...
#define | COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS 0x4
| Notifications will always be sent non-confirmable. More...
#define | COAP_PRINT_STATUS_MASK 0xF0000000u
#define | COAP_PRINT_OUTPUT_LENGTH(v) ((v) & ~COAP_PRINT_STATUS_MASK)
#define | COAP_PRINT_STATUS_ERROR 0x80000000u
#define | COAP_PRINT_STATUS_TRUNC 0x40000000u

## Typedefs

typedef void(* | coap_method_handler_t) (coap_resource_t *, coap_session_t *, const coap_pdu_t *, const coap_string_t *, coap_pdu_t *)
| Definition of message handler function. More...
typedef void(* | coap_resource_release_userdata_handler_t) (void *user_data)
| Definition of release resource user_data callback function. More...
typedef unsigned int | coap_print_status_t
| Status word to encode the result of conditional print or copy operations such as coap_print_link(). More...

## Functions

coap_resource_t * | coap_resource_init (coap_str_const_t *uri_path, int flags)
| Creates a new resource object and initializes the link field to the string `uri_path`. More...
coap_resource_t * | coap_resource_unknown_init (coap_method_handler_t put_handler)
| Creates a new resource object for the unknown resource handler with support for PUT. More...
coap_resource_t * | coap_resource_proxy_uri_init (coap_method_handler_t handler, size_t host_name_count, const char *host_name_list[])
| Creates a new resource object for handling proxy URIs. More...
coap_resource_t * | coap_get_resource_from_uri_path (coap_context_t *context, coap_str_const_t *uri_path)
| Returns the resource identified by the unique string `uri_path`. More...
coap_str_const_t * | coap_resource_get_uri_path (coap_resource_t *resource)
| Get the uri_path from a `resource`. More...
void | coap_resource_set_mode (coap_resource_t *resource, int mode)
| Sets the notification message type of resource `resource` to given `mode`. More...
void | coap_resource_set_userdata (coap_resource_t *resource, void *data)
| Sets the user_data. More...
void * | coap_resource_get_userdata (coap_resource_t *resource)
| Gets the user_data. More...
void | coap_resource_release_userdata_handler (coap_context_t *context, coap_resource_release_userdata_handler_t callback)
| Defines the context wide callback to use to when the resource is deleted to release the data held in the resource's user_data. More...
void | coap_add_resource (coap_context_t *context, coap_resource_t *resource)
| Registers the given `resource` for `context`. More...
int | coap_delete_resource (coap_context_t *context, coap_resource_t *resource)
| Deletes a resource identified by `resource`. More...
void | coap_register_handler (coap_resource_t *resource, coap_request_t method, coap_method_handler_t handler)
| Registers the specified `handler` as message handler for the request type `method`. More...
coap_attr_t * | coap_add_attr (coap_resource_t *resource, coap_str_const_t *name, coap_str_const_t *value, int flags)
| Registers a new attribute with the given `resource`. More...
coap_attr_t * | coap_find_attr (coap_resource_t *resource, coap_str_const_t *name)
| Returns `resource's` coap_attr_t object with given `name` if found, `NULL` otherwise. More...
coap_str_const_t * | coap_attr_get_value (coap_attr_t *attribute)
| Returns `attribute's` value. More...
coap_print_status_t | coap_print_link (const coap_resource_t *resource, unsigned char *buf, size_t *len, size_t *offset)
| Writes a description of this resource in link-format to given text buffer. More...

## Detailed Description

API functions for setting up resources.

## Macro Definition Documentation

## COAP_ATTR_FLAGS_RELEASE_NAME

#define COAP_ATTR_FLAGS_RELEASE_NAME 0x1

Definition at line 48 of file resource.h.

## COAP_ATTR_FLAGS_RELEASE_VALUE

#define COAP_ATTR_FLAGS_RELEASE_VALUE 0x2

Definition at line 49 of file resource.h.

## COAP_PRINT_OUTPUT_LENGTH

#define COAP_PRINT_OUTPUT_LENGTH | ( |  | v | ) | ((v) & ~COAP_PRINT_STATUS_MASK)

Definition at line 327 of file resource.h.

## COAP_PRINT_STATUS_ERROR

#define COAP_PRINT_STATUS_ERROR 0x80000000u

Definition at line 328 of file resource.h.

## COAP_PRINT_STATUS_MASK

#define COAP_PRINT_STATUS_MASK 0xF0000000u

Definition at line 326 of file resource.h.

## COAP_PRINT_STATUS_TRUNC

#define COAP_PRINT_STATUS_TRUNC 0x40000000u

Definition at line 329 of file resource.h.

## COAP_RESOURCE_FLAGS_NOTIFY_CON

#define COAP_RESOURCE_FLAGS_NOTIFY_CON 0x2

Notifications will be sent confirmable.

RFC 7641 Section 4.5 https://tools.ietf.org/html/rfc7641#section-4.5

Definition at line 65 of file resource.h.

## COAP_RESOURCE_FLAGS_NOTIFY_NON

#define COAP_RESOURCE_FLAGS_NOTIFY_NON 0x0

Notifications will be sent non-confirmable by default.

RFC 7641 Section 4.5 https://tools.ietf.org/html/rfc7641#section-4.5 Libcoap will always send every fifth packet as confirmable.

Definition at line 59 of file resource.h.

## COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS

#define COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS 0x4

Notifications will always be sent non-confirmable.

This is in violation of RFC 7641 Section 4.5 https://tools.ietf.org/html/rfc7641#section-4.5 but required by the DOTS signal channel protocol which needs to operate in lossy DDoS attack environments. https://tools.ietf.org/html/rfc8782#section-4.4.2.1

Definition at line 75 of file resource.h.

## COAP_RESOURCE_FLAGS_RELEASE_URI

#define COAP_RESOURCE_FLAGS_RELEASE_URI 0x1

The URI passed to coap_resource_init() is free'd by coap_delete_resource().

Definition at line 52 of file resource.h.

## Typedef Documentation

## coap_method_handler_t

typedef void(* coap_method_handler_t) (coap_resource_t *, coap_session_t *, const coap_pdu_t *, const coap_string_t *, coap_pdu_t *)

Definition of message handler function.

Definition at line 41 of file resource.h.

## coap_print_status_t

typedef unsigned int coap_print_status_t

Status word to encode the result of conditional print or copy operations such as coap_print_link().

The lower 28 bits of coap_print_status_t are used to encode the number of characters that has actually been printed, bits 28 to 31 encode the status. When COAP_PRINT_STATUS_ERROR is set, an error occurred during output. In this case, the other bits are undefined. COAP_PRINT_STATUS_TRUNC indicates that the output is truncated, i.e. the printing would have exceeded the current buffer.

Definition at line 324 of file resource.h.

## coap_resource_release_userdata_handler_t

typedef void(* coap_resource_release_userdata_handler_t) (void *user_data)

Definition of release resource user_data callback function.

Definition at line 212 of file resource.h.

## Function Documentation

## coap_add_attr()

coap_attr_t* coap_add_attr | ( | coap_resource_t * | resource,
|  | coap_str_const_t * | name,
|  | coap_str_const_t * | value,
|  | int | flags
| ) |  |

Registers a new attribute with the given `resource`.

As the attribute's coap_str_const_ fields will point to `name` and `value` the caller must ensure that these pointers are valid during the attribute's lifetime.

If the `name` and/or `value` string is going to be freed off at attribute removal time by the setting of COAP_ATTR_FLAGS_RELEASE_NAME or COAP_ATTR_FLAGS_RELEASE_VALUE in `flags`, then either the 's' variable of coap_str_const_t has to point to constant text, or point to data within the allocated coap_str_const_t parameter.

Parameters

  resource | The resource to register the attribute with.
  name | The attribute's name as a string.
  value | The attribute's value as a string or `NULL` if none.
  flags | Flags for memory management (in particular release of memory). Possible values: COAP_ATTR_FLAGS_RELEASE_NAME If this flag is set, the name passed to coap_add_attr_release() is free'd when the attribute is deleted COAP_ATTR_FLAGS_RELEASE_VALUE If this flag is set, the value passed to coap_add_attr_release() is free'd when the attribute is deleted

Returns
  A pointer to the new attribute or `NULL` on error.

Definition at line 407 of file resource.c.

Here is the call graph for this function:

## coap_add_resource()

void coap_add_resource | ( | coap_context_t * | context,
|  | coap_resource_t * | resource
| ) |  |

Registers the given `resource` for `context`.

The resource must have been created by coap_resource_init() or coap_resource_unknown_init(), the storage allocated for the resource will be released by coap_delete_resource().

Parameters

  context | The context to use.
  resource | The resource to store.

Definition at line 536 of file resource.c.

Here is the call graph for this function:

## coap_attr_get_value()

coap_str_const_t* coap_attr_get_value | ( | coap_attr_t * | attribute | ) |

Returns `attribute's` value.

Parameters

  attribute | Pointer to attribute.

Returns
  Attribute's value or `NULL`.

Definition at line 461 of file resource.c.

## coap_delete_resource()

int coap_delete_resource | ( | coap_context_t * | context,
|  | coap_resource_t * | resource
| ) |  |

Deletes a resource identified by `resource`.

The storage allocated for that resource is freed, and removed from the context.

Parameters

  context | The context where the resources are stored.
  resource | The resource to delete.

Returns
  `1` if the resource was found (and destroyed), `0` otherwise.

Definition at line 565 of file resource.c.

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

## coap_find_attr()

coap_attr_t* coap_find_attr | ( | coap_resource_t * | resource,
|  | coap_str_const_t * | name
| ) |  |

Returns `resource's` coap_attr_t object with given `name` if found, `NULL` otherwise.

Parameters

  resource | The resource to search for attribute `name`.
  name | Name of the requested attribute as a string.

Returns
  The first attribute with specified `name` or `NULL` if none was found.

Definition at line 444 of file resource.c.

Here is the caller graph for this function:

## coap_get_resource_from_uri_path()

coap_resource_t* coap_get_resource_from_uri_path | ( | coap_context_t * | context,
|  | coap_str_const_t * | uri_path
| ) |  |

Returns the resource identified by the unique string `uri_path`.

If no resource was found, this function returns `NULL`.

Parameters

  context | The context to look for this resource.
  uri_path | The unique string uri of the resource.

Returns
  A pointer to the resource or `NULL` if not found.

Definition at line 615 of file resource.c.

Here is the caller graph for this function:

## coap_print_link()

coap_print_status_t coap_print_link | ( | const coap_resource_t * | resource,
|  | unsigned char * | buf,
|  | size_t * | len,
|  | size_t * | offset
| ) |  |

Writes a description of this resource in link-format to given text buffer.

`len` must be initialized to the maximum length of `buf` and will be set to the number of characters actually written if successful. This function returns `1` on success or `0` on error.

Parameters

  resource | The resource to describe.
  buf | The output buffer to write the description to.
  len | Must be initialized to the length of `buf` and will be set to the length of the printed link description.
  offset | The offset within the resource description where to start writing into `buf`. This is useful for dealing with the Block2 option. `offset` is updated during output as it is consumed.

Returns
  If COAP_PRINT_STATUS_ERROR is set, an error occured. Otherwise, the lower 28 bits will indicate the number of characters that have actually been output into `buffer`. The flag COAP_PRINT_STATUS_TRUNC indicates that the output has been truncated.

Definition at line 624 of file resource.c.

Here is the caller graph for this function:

## coap_register_handler()

void coap_register_handler | ( | coap_resource_t * | resource,
|  | coap_request_t | method,
|  | coap_method_handler_t | handler
| ) |  |

Registers the specified `handler` as message handler for the request type `method`.

Parameters

  resource | The resource for which the handler shall be registered.
  method | The CoAP request method to handle.
  handler | The handler to register with `resource`.

Definition at line 677 of file resource.c.

Here is the caller graph for this function:

## coap_resource_get_uri_path()

coap_str_const_t* coap_resource_get_uri_path | ( | coap_resource_t * | resource | ) |

Get the uri_path from a `resource`.

Parameters

  resource | The CoAP resource to check.

Returns
  The uri_path if it exists or `NULL` otherwise.

Definition at line 1055 of file resource.c.

## coap_resource_get_userdata()

void* coap_resource_get_userdata | ( | coap_resource_t * | resource | ) |

Gets the user_data.

The user_data is exclusively used by the library-user and can be used as context in the handler functions.

Parameters

  resource | Resource to retrieve the user_data from

Returns
  The user_data pointer

Definition at line 1039 of file resource.c.

## coap_resource_init()

coap_resource_t* coap_resource_init | ( | coap_str_const_t * | uri_path,
|  | int | flags
| ) |  |

Creates a new resource object and initializes the link field to the string `uri_path`.

This function returns the new coap_resource_t object.

If the string is going to be freed off by coap_delete_resource() when COAP_RESOURCE_FLAGS_RELEASE_URI is set in `flags`, then either the 's' variable of coap_str_const_t has to point to constant text, or point to data within the allocated coap_str_const_t parameter.

Parameters

  uri_path | The string URI path of the new resource.

  flags

  Flags for memory management (in particular release of memory). Possible values:
  COAP_RESOURCE_FLAGS_RELEASE_URI If this flag is set, the URI passed to coap_resource_init() is free'd by coap_delete_resource()
  COAP_RESOURCE_FLAGS_NOTIFY_CON If this flag is set, coap-observe notifications will be sent confirmable by default.
  COAP_RESOURCE_FLAGS_NOTIFY_NON (default) If this flag is set, coap-observe notifications will be sent non-confirmable by default.
  If flags is set to 0 then the COAP_RESOURCE_FLAGS_NOTIFY_NON is considered.

Returns
  A pointer to the new object or `NULL` on error.

Definition at line 303 of file resource.c.

Here is the call graph for this function:

## coap_resource_proxy_uri_init()

coap_resource_t* coap_resource_proxy_uri_init | ( | coap_method_handler_t | handler,
|  | size_t | host_name_count,
|  | const char * | host_name_list[]
| ) |  |

Creates a new resource object for handling proxy URIs.

This function returns the new coap_resource_t object.

Note: There can only be one proxy resource handler per context - attaching a new one overrides the previous definition.

Parameters

  handler | The PUT/POST/GET etc. handler that handles all request types.
  host_name_count | The number of provided host_name_list entries. A minimum of 1 must be provided.
  host_name_list | Array of depth host_name_count names that this proxy is known by.

Returns
  A pointer to the new object or `NULL` on error.

Definition at line 358 of file resource.c.

Here is the call graph for this function:

## coap_resource_release_userdata_handler()

void coap_resource_release_userdata_handler | ( | coap_context_t * | context,
|  | coap_resource_release_userdata_handler_t | callback
| ) |  |

Defines the context wide callback to use to when the resource is deleted to release the data held in the resource's user_data.

Parameters

  context | The context to associate the release callback with
  callback | The callback to invoke when the resource is deleted or NULL

Definition at line 1044 of file resource.c.

## coap_resource_set_mode()

void coap_resource_set_mode | ( | coap_resource_t * | resource,
|  | int | mode
| ) |  |

Sets the notification message type of resource `resource` to given `mode`.

Parameters

  resource | The resource to update.
  mode | Must be one of `COAP_RESOURCE_FLAGS_NOTIFY_NON` or `COAP_RESOURCE_FLAGS_NOTIFY_CON`.

Definition at line 1027 of file resource.c.

## coap_resource_set_userdata()

void coap_resource_set_userdata | ( | coap_resource_t * | resource,
|  | void * | data
| ) |  |

Sets the user_data.

The user_data is exclusively used by the library-user and can be used as user defined context in the handler functions.

Parameters

  resource | Resource to attach the data to
  data | Data to attach to the user_data field. This pointer is only used for storage, the data remains under user control

Definition at line 1034 of file resource.c.

## coap_resource_unknown_init()

coap_resource_t* coap_resource_unknown_init | ( | coap_method_handler_t | put_handler | ) |

Creates a new resource object for the unknown resource handler with support for PUT.

In the same way that additional handlers can be added to the resource created by coap_resource_init() by using coap_register_handler(), POST, GET, DELETE etc. handlers can be added to this resource. It is the responsibility of the application to manage the unknown resources by either creating new resources with coap_resource_init() (which should have a DELETE handler specified for the resource removal) or by maintaining an active resource list.

Note: There can only be one unknown resource handler per context - attaching a new one overrides the previous definition.

Note: It is not possible to observe the unknown resource with a GET request

- a separate resource needs to be reated by the PUT (or POST) handler, and make that resource observable.

This function returns the new coap_resource_t object.

Parameters

  put_handler | The PUT handler to register with `resource` for unknown Uri-Path.

Returns
  A pointer to the new object or `NULL` on error.

Definition at line 337 of file resource.c.

Here is the call graph for this function: