Loading...
Searching...
No Matches
Resource Configuraton
Application API

API for setting up resources. More...

Collaboration diagram for Resource Configuraton:

## 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().
#define | COAP_RESOURCE_FLAGS_NOTIFY_NON 0x0
| Observe Notifications will be sent non-confirmable by default.
#define | COAP_RESOURCE_FLAGS_NOTIFY_CON 0x2
| Observe Notifications will be sent confirmable.
#define | COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS 0x4
| Observe Notifications will always be sent non-confirmable.
#define | COAP_RESOURCE_FLAGS_HAS_MCAST_SUPPORT 0x8
| This resource has support for multicast requests.
#define | COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_DELAYS 0x10
| Disable libcoap library from adding in delays to multicast requests before releasing the response back to the client.
#define | COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_05 0x20
| Enable libcoap library suppression of 205 multicast responses that are empty (overridden by RFC7969 No-Response option) for multicast requests.
#define | COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_XX 0x40
| Enable libcoap library suppressing 2.xx multicast responses (overridden by RFC7969 No-Response option) for multicast requests.
#define | COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_4_XX 0x80
| Disable libcoap library suppressing 4.xx multicast responses (overridden by RFC7969 No-Response option) for multicast requests.
#define | COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_5_XX 0x100
| Disable libcoap library suppressing 5.xx multicast responses (overridden by RFC7969 No-Response option) for multicast requests.
#define | COAP_RESOURCE_FLAGS_MCAST_LIST
#define | COAP_RESOURCE_FLAGS_FORCE_SINGLE_BODY 0x200
| Force all large traffic to this resource to be presented as a single body to the request handler.
#define | COAP_RESOURCE_FLAGS_OSCORE_ONLY 0x400
| Define this resource as an OSCORE enabled access only.
#define | COAP_RESOURCE_HANDLE_WELLKNOWN_CORE 0x800
| Define this when invoking coap_resource_unknown_init2() if .well-known/core is to be passed to the unknown URI handler rather than processed locally.
#define | COAP_PRINT_STATUS_MASK 0xF0000000UL
#define | COAP_PRINT_STATUS_MAX 0x0FFFFFFFUL
#define | COAP_PRINT_OUTPUT_LENGTH(v)
#define | COAP_PRINT_STATUS_ERROR 0x80000000UL
#define | COAP_PRINT_STATUS_TRUNC 0x40000000UL

## Typedefs

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

## 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`.
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.
coap_resource_t * | coap_resource_unknown_init2 (coap_method_handler_t put_handler, int flags)
| Creates a new resource object for the unknown resource handler with support for PUT and configurable control over multicast requests packets.
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.
coap_resource_t * | coap_resource_proxy_uri_init2 (coap_method_handler_t handler, size_t host_name_count, const char *host_name_list[], int flags)
| Creates a new resource object for handling proxy URIs with configurable control over multicast request packets.
coap_resource_t * | coap_resource_reverse_proxy_init (coap_method_handler_t handler, int flags)
| Creates a new resource object for the reverse-proxy resource handler with control over multicast request packets.
COAP_API 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`.
coap_str_const_t * | coap_resource_get_uri_path (coap_resource_t *resource)
| Get the uri_path from a `resource`.
void | coap_resource_set_mode (coap_resource_t *resource, int mode)
| Sets the notification message type of resource `resource` to given `mode`.
void | coap_resource_set_userdata (coap_resource_t *resource, void *data)
| Sets the user_data.
void * | coap_resource_get_userdata (coap_resource_t *resource)
| Gets the user_data.
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.
COAP_API void | coap_add_resource (coap_context_t *context, coap_resource_t *resource)
| Registers the given `resource` for `context`.
COAP_API int | coap_delete_resource (coap_context_t *context, coap_resource_t *resource)
| Deletes a resource identified by `resource`.
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`.
void | coap_register_request_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`.
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`.
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.
coap_str_const_t * | coap_attr_get_value (coap_attr_t *attribute)
| Returns `attribute's` value.
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.
COAP_API coap_print_status_t | coap_print_wellknown (coap_context_t *context, unsigned char *buf, size_t *buflen, size_t offset, const coap_string_t *query_filter)
| Prints the names of all known resources for `context` to `buf`.

## Detailed Description

API for setting up resources.

## Macro Definition Documentation

## COAP_ATTR_FLAGS_RELEASE_NAME

#define COAP_ATTR_FLAGS_RELEASE_NAME 0x1

Definition at line 47 of file coap_resource.h.

## COAP_ATTR_FLAGS_RELEASE_VALUE

#define COAP_ATTR_FLAGS_RELEASE_VALUE 0x2

Definition at line 48 of file coap_resource.h.

## COAP_PRINT_OUTPUT_LENGTH

#define COAP_PRINT_OUTPUT_LENGTH | ( |  | v | ) |

Value:
((v) & COAP_PRINT_STATUS_MAX)
COAP_PRINT_STATUS_MAX
#define COAP_PRINT_STATUS_MAX
Definition coap_resource.h:492

Definition at line 493 of file coap_resource.h.

## COAP_PRINT_STATUS_ERROR

#define COAP_PRINT_STATUS_ERROR 0x80000000UL

Definition at line 494 of file coap_resource.h.

## COAP_PRINT_STATUS_MASK

#define COAP_PRINT_STATUS_MASK 0xF0000000UL

Definition at line 491 of file coap_resource.h.

## COAP_PRINT_STATUS_MAX

#define COAP_PRINT_STATUS_MAX 0x0FFFFFFFUL

Definition at line 492 of file coap_resource.h.

## COAP_PRINT_STATUS_TRUNC

#define COAP_PRINT_STATUS_TRUNC 0x40000000UL

Definition at line 495 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_FORCE_SINGLE_BODY

#define COAP_RESOURCE_FLAGS_FORCE_SINGLE_BODY 0x200

Force all large traffic to this resource to be presented as a single body to the request handler.

Definition at line 146 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_HAS_MCAST_SUPPORT

#define COAP_RESOURCE_FLAGS_HAS_MCAST_SUPPORT 0x8

This resource has support for multicast requests.

https://rfc-editor.org/rfc/rfc7252#section-11.3 https://rfc-editor.org/rfc/rfc7390#section-2.8 https://datatracker.ietf.org/doc/html/draft-ietf-core-groupcomm-bis-06.txt#section-3.6 Note: ".well-known/core" always supports multicast. Note: Only tested if coap_mcast_per_resource() has been called.

Definition at line 85 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_DELAYS

#define COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_DELAYS 0x10

Disable libcoap library from adding in delays to multicast requests before releasing the response back to the client.

It is then the responsibility of the app to delay the responses for multicast requests. https://rfc-editor.org/rfc/rfc7252#section-8.2 https://rfc-editor.org/rfc/rfc7390#section-2.8 https://datatracker.ietf.org/doc/html/draft-ietf-core-groupcomm-bis-06.txt#section-3.6 Note: Only tested if coap_mcast_per_resource() has been called.

Definition at line 96 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_4_XX

#define COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_4_XX 0x80

Disable libcoap library suppressing 4.xx multicast responses (overridden by RFC7969 No-Response option) for multicast requests.

https://rfc-editor.org/rfc/rfc7390#section-2.7 https://datatracker.ietf.org/doc/html/draft-ietf-core-groupcomm-bis-06.txt#section-3.1.2 Note: Only tested if coap_mcast_per_resource() has been called.

Definition at line 123 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_5_XX

#define COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_5_XX 0x100

Disable libcoap library suppressing 5.xx multicast responses (overridden by RFC7969 No-Response option) for multicast requests.

https://rfc-editor.org/rfc/rfc7390#section-2.7 https://datatracker.ietf.org/doc/html/draft-ietf-core-groupcomm-bis-06.txt#section-3.1.2 Note: Only tested if coap_mcast_per_resource() has been called.

Definition at line 132 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_05

#define COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_05 0x20

Enable libcoap library suppression of 205 multicast responses that are empty (overridden by RFC7969 No-Response option) for multicast requests.

https://rfc-editor.org/rfc/rfc7390#section-2.7 https://datatracker.ietf.org/doc/html/draft-ietf-core-groupcomm-bis-06.txt#section-3.1.2 Note: Only tested if coap_mcast_per_resource() has been called.

Definition at line 105 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_XX

#define COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_XX 0x40

Enable libcoap library suppressing 2.xx multicast responses (overridden by RFC7969 No-Response option) for multicast requests.

https://rfc-editor.org/rfc/rfc7390#section-2.7 https://datatracker.ietf.org/doc/html/draft-ietf-core-groupcomm-bis-06.txt#section-3.1.2 Note: Only tested if coap_mcast_per_resource() has been called.

Definition at line 114 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_MCAST_LIST

#define COAP_RESOURCE_FLAGS_MCAST_LIST

Value:
(COAP_RESOURCE_FLAGS_HAS_MCAST_SUPPORT | \
COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_DELAYS | \
COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_05 | \
COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_XX | \
COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_4_XX | \
COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_5_XX)
COAP_RESOURCE_FLAGS_HAS_MCAST_SUPPORT
#define COAP_RESOURCE_FLAGS_HAS_MCAST_SUPPORT
This resource has support for multicast requests.
Definition coap_resource.h:85
COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_4_XX
#define COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_4_XX
Disable libcoap library suppressing 4.xx multicast responses (overridden by RFC7969 No-Response optio...
Definition coap_resource.h:123
COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_DELAYS
#define COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_DELAYS
Disable libcoap library from adding in delays to multicast requests before releasing the response bac...
Definition coap_resource.h:96
COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_5_XX
#define COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_5_XX
Disable libcoap library suppressing 5.xx multicast responses (overridden by RFC7969 No-Response optio...
Definition coap_resource.h:132
COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_05
#define COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_05
Enable libcoap library suppression of 205 multicast responses that are empty (overridden by RFC7969 N...
Definition coap_resource.h:105
COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_XX
#define COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_XX
Enable libcoap library suppressing 2.xx multicast responses (overridden by RFC7969 No-Response option...
Definition coap_resource.h:114

Definition at line 134 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_NOTIFY_CON

#define COAP_RESOURCE_FLAGS_NOTIFY_CON 0x2

Observe Notifications will be sent confirmable.

RFC 7641 Section 4.5 https://rfc-editor.org/rfc/rfc7641#section-4.5

Definition at line 65 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_NOTIFY_NON

#define COAP_RESOURCE_FLAGS_NOTIFY_NON 0x0

Observe Notifications will be sent non-confirmable by default.

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

Definition at line 59 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS

#define COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS 0x4

Observe Notifications will always be sent non-confirmable.

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

Definition at line 75 of file coap_resource.h.

## COAP_RESOURCE_FLAGS_OSCORE_ONLY

#define COAP_RESOURCE_FLAGS_OSCORE_ONLY 0x400

Define this resource as an OSCORE enabled access only.

Definition at line 151 of file coap_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 51 of file coap_resource.h.

## COAP_RESOURCE_HANDLE_WELLKNOWN_CORE

#define COAP_RESOURCE_HANDLE_WELLKNOWN_CORE 0x800

Define this when invoking coap_resource_unknown_init2() if .well-known/core is to be passed to the unknown URI handler rather than processed locally.

Used for easily passing on a request as a reverse-proxy request.

Definition at line 158 of file coap_resource.h.

## Typedef Documentation

## coap_method_handler_t

typedef void(* coap_method_handler_t) (coap_resource_t *resource, coap_session_t *session, const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response)

Definition of message handler function.

Parameters

  resource | The resource being requested.
  session | The CoAP session.
  request | The request PDU.
  query | The query string for the resource.
  response | The pre-populated response PDU.

Definition at line 41 of file coap_resource.h.

## coap_print_status_t

typedef uint32_t 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 489 of file coap_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 362 of file coap_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.

## coap_add_resource()

COAP_API 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.

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

## coap_delete_resource()

COAP_API 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 | This parameter is ignored, but kept for backward compatibility.
  resource | The resource to delete.

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

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

## coap_get_resource_from_uri_path()

COAP_API 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.

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

## coap_print_wellknown()

COAP_API coap_print_status_t coap_print_wellknown | ( | coap_context_t * | context,
|  | unsigned char * | buf,
|  | size_t * | buflen,
|  | size_t | offset,
|  | const coap_string_t * | query_filter )

Prints the names of all known resources for `context` to `buf`.

This function sets `buflen` to the number of bytes actually written and returns `COAP_PRINT_STATUS_ERROR` on error. On error, the value in `buflen` is undefined. Otherwise, the lower 28 bits are set to the number of bytes that have actually been written. COAP_PRINT_STATUS_TRUNC is set when the output has been truncated.

Parameters

  context | The context with the resource map.
  buf | The buffer to write the result.
  buflen | Must be initialized to the maximum length of `buf` and will be set to the length of the well-known response on return.
  offset | The offset in bytes where the output shall start and is shifted accordingly with the characters that have been processed. This parameter is used to support the block option.
  query_filter | A filter query according to Link Format

Returns
  COAP_PRINT_STATUS_ERROR on error. Otherwise, the lower 28 bits are set to the number of bytes that have actually been written to `buf`. COAP_PRINT_STATUS_TRUNC is set when the output has been truncated.

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

Deprecated
  use coap_register_request_handler() instead.

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`.

## coap_register_request_handler()

void coap_register_request_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`.

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

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

## 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. The leading '/' is not normally required - e.g. just "full/path/for/resource".
  flags | Flags for memory management, observe handling and multicast support, comprising of zero or more COAP_RESOURCE_FLAGS_* ored together.

If flags does not have COAP_RESOURCE_FLAGS_NOTIFY_CON set, then COAP_RESOURCE_FLAGS_NOTIFY_NON is assumed and observe notifications will be sent as non-confirmable, except that every 5th notification will be confirmable.

If COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS is set, observe notifications will always be sent non-confirmable.

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

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

## coap_resource_proxy_uri_init2()

coap_resource_t * coap_resource_proxy_uri_init2 | ( | coap_method_handler_t | handler,
|  | size_t | host_name_count,
|  | const char * | host_name_list[],
|  | int | flags )

Creates a new resource object for handling proxy URIs with configurable control over multicast request packets.

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.
  flags | Zero or more COAP_RESOURCE_FLAGS_*MCAST* ored together to indicate what to do with multicast packets.

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

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

## coap_resource_reverse_proxy_init()

coap_resource_t * coap_resource_reverse_proxy_init | ( | coap_method_handler_t | handler,
|  | int | flags )

Creates a new resource object for the reverse-proxy resource handler with control over multicast request packets.

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

This function returns the new coap_resource_t object.

Parameters

  handler | The PUT/POST/GET etc. handler that handles all the reverse-proxy requests including .well-known-core.
  flags | Zero or more COAP_RESOURCE_FLAGS_*MCAST* ored together to indicate what to do with multicast packets.

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

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

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

## 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_request_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 created 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.

## coap_resource_unknown_init2()

coap_resource_t * coap_resource_unknown_init2 | ( | coap_method_handler_t | put_handler,
|  | int | flags )

Creates a new resource object for the unknown resource handler with support for PUT and configurable control over multicast requests packets.

In the same way that additional handlers can be added to the resource created by coap_resource_init() by using coap_register_request_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 or reverse-proxy 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 created 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.
  flags | Zero or more COAP_RESOURCE_FLAGS_*MCAST* ored together to indicate what to do with multicast packets.

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