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:

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ COAP_ATTR_FLAGS_RELEASE_NAME

◆ COAP_ATTR_FLAGS_RELEASE_VALUE

◆ COAP_PRINT_OUTPUT_LENGTH

◆ COAP_PRINT_STATUS_ERROR

◆ COAP_PRINT_STATUS_MASK

◆ COAP_PRINT_STATUS_TRUNC

◆ COAP_RESOURCE_FLAGS_NOTIFY_CON

◆ COAP_RESOURCE_FLAGS_NOTIFY_NON

◆ COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS

◆ COAP_RESOURCE_FLAGS_RELEASE_URI

Typedef Documentation

◆ coap_method_handler_t

◆ coap_print_status_t

◆ coap_resource_release_userdata_handler_t

Function Documentation

◆ coap_add_attr()

◆ coap_add_resource()

◆ coap_attr_get_value()

◆ coap_delete_resource()

◆ coap_find_attr()

◆ coap_get_resource_from_uri_path()

◆ coap_print_link()

◆ coap_register_handler()

◆ coap_resource_get_uri_path()

◆ coap_resource_get_userdata()

◆ coap_resource_init()

◆ coap_resource_proxy_uri_init()

◆ coap_resource_release_userdata_handler()

◆ coap_resource_set_mode()

◆ coap_resource_set_userdata()

◆ coap_resource_unknown_init()