Generic resource handling. More...

#include <assert.h>
#include "uthash.h"
#include "hashkey.h"
#include "async.h"
#include "str.h"
#include "pdu.h"
#include "net.h"
#include "subscribe.h"

Include dependency graph for resource.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	coap_attr_t

struct	coap_resource_t

Macros
#define	COAP_RESOURCE_CHECK_TIME 2
	The interval in seconds to check if resources have changed. More...

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

#define	RESOURCES_ADD(r, obj) HASH_ADD(hh, (r), key, sizeof(coap_key_t), (obj))

#define	RESOURCES_DELETE(r, obj) HASH_DELETE(hh, (r), (obj))

#define	RESOURCES_ITER(r, tmp)

#define	RESOURCES_FIND(r, k, res)

Typedefs
typedef void(*	coap_method_handler_t) (coap_context_t , struct coap_resource_t , const coap_endpoint_t , coap_address_t , coap_pdu_t , str , coap_pdu_t *)
	Definition of message handler function (. More...

typedef struct coap_attr_t	coap_attr_t

typedef struct coap_resource_t	coap_resource_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(). More...

Functions
coap_resource_t *	coap_resource_init (const unsigned char *uri, size_t len, int flags)
	Creates a new resource object and initializes the link field to the string of length `len`. More...

static void	coap_resource_set_mode (coap_resource_t *r, int mode)
	Sets the notification message type of resource `r` to given `mode` which must be one of `COAP_RESOURCE_FLAGS_NOTIFY_NON` or `COAP_RESOURCE_FLAGS_NOTIFY_CON`. 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_key_t key)
	Deletes a resource identified by `key`. More...

void	coap_delete_all_resources (coap_context_t *context)
	Deletes all resources from given `context` and frees their storage. More...

coap_attr_t *	coap_add_attr (coap_resource_t resource, const unsigned char name, size_t nlen, const unsigned char *val, size_t vlen, int flags)
	Registers a new attribute with the given `resource`. More...

coap_attr_t *	coap_find_attr (coap_resource_t resource, const unsigned char name, size_t nlen)
	Returns `resource's` coap_attr_t object with given `name` if found, `NULL` otherwise. More...

void	coap_delete_attr (coap_attr_t *attr)
	Deletes an attribute. 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...

static void	coap_register_handler (coap_resource_t *resource, unsigned char method, coap_method_handler_t handler)
	Registers the specified `handler` as message handler for the request type `method`. More...

coap_resource_t *	coap_get_resource_from_key (coap_context_t *context, coap_key_t key)
	Returns the resource identified by the unique string `key`. More...

void	coap_hash_request_uri (const coap_pdu_t *request, coap_key_t key)
	Calculates the hash key for the resource requested by the Uri-Options of `request`. More...

coap_subscription_t *	coap_add_observer (coap_resource_t resource, const coap_endpoint_t local_interface, const coap_address_t observer, const str token)
	Adds the specified peer as observer for `resource`. More...

coap_subscription_t *	coap_find_observer (coap_resource_t resource, const coap_address_t peer, const str *token)
	Returns a subscription object for given `peer`. More...

void	coap_touch_observer (coap_context_t context, const coap_address_t observer, const str *token)
	Marks an observer as alive. More...

int	coap_delete_observer (coap_resource_t resource, const coap_address_t observer, const str *token)
	Removes any subscription for `observer` from `resource` and releases the allocated storage. More...

void	coap_check_notify (coap_context_t *context)
	Checks for all known resources, if they are dirty and notifies subscribed observers. More...

coap_print_status_t	coap_print_wellknown (coap_context_t , unsigned char , size_t , size_t, coap_opt_t )
	Prints the names of all known resources to `buf`. More...

void	coap_handle_failed_notify (coap_context_t , const coap_address_t , const str *)

Detailed Description

Generic resource handling.

Definition in file resource.h.

Macro Definition Documentation

§ COAP_ATTR_FLAGS_RELEASE_NAME

#define COAP_ATTR_FLAGS_RELEASE_NAME 0x1

Definition at line 50 of file resource.h.

§ COAP_ATTR_FLAGS_RELEASE_VALUE

#define COAP_ATTR_FLAGS_RELEASE_VALUE 0x2

Definition at line 51 of file resource.h.

§ COAP_PRINT_OUTPUT_LENGTH

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

Definition at line 220 of file resource.h.

§ COAP_PRINT_STATUS_ERROR

#define COAP_PRINT_STATUS_ERROR 0x80000000u

Definition at line 221 of file resource.h.

§ COAP_PRINT_STATUS_MASK

#define COAP_PRINT_STATUS_MASK 0xF0000000u

Definition at line 219 of file resource.h.

§ COAP_PRINT_STATUS_TRUNC

#define COAP_PRINT_STATUS_TRUNC 0x40000000u

Definition at line 222 of file resource.h.

§ COAP_RESOURCE_CHECK_TIME

#define COAP_RESOURCE_CHECK_TIME 2

The interval in seconds to check if resources have changed.

Definition at line 22 of file resource.h.

§ COAP_RESOURCE_FLAGS_NOTIFY_CON

#define COAP_RESOURCE_FLAGS_NOTIFY_CON 0x2

Notifications will be sent confirmable by default.

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

Definition at line 73 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

Definition at line 67 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 61 of file resource.h.

§ RESOURCES_ADD

#define RESOURCES_ADD	(	r,
		obj
	)	HASH_ADD(hh, (r), key, sizeof(coap_key_t), (obj))

Definition at line 381 of file resource.h.

§ RESOURCES_DELETE

#define RESOURCES_DELETE	(	r,
		obj
	)	HASH_DELETE(hh, (r), (obj))

Definition at line 384 of file resource.h.

§ RESOURCES_FIND

#define RESOURCES_FIND	(	r,
		k,
		res
	)

Value:

{                     \
    HASH_FIND(hh, (r), (k), sizeof(coap_key_t), (res)); \
  }

Definition at line 391 of file resource.h.

§ RESOURCES_ITER

#define RESOURCES_ITER	(	r,
		tmp
	)

Value:

coap_resource_t *tmp, *rtmp; \

HASH_ITER(hh, (r), tmp, rtmp)

coap_resource_t

Definition: resource.h:75

Definition at line 387 of file resource.h.

Typedef Documentation

§ coap_attr_t

typedef struct coap_attr_t coap_attr_t

§ coap_method_handler_t

typedef void(* coap_method_handler_t) (coap_context_t *, struct coap_resource_t *, const coap_endpoint_t *, coap_address_t *, coap_pdu_t *, str *, coap_pdu_t *)

Definition of message handler function (.

See also: coap_resource_t).

Definition at line 42 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 217 of file resource.h.

§ coap_resource_t

typedef struct coap_resource_t coap_resource_t

Function Documentation

§ coap_add_attr()

coap_attr_t* coap_add_attr	(	coap_resource_t *	resource,
		const unsigned char *	name,
		size_t	nlen,
		const unsigned char *	val,
		size_t	vlen,
		int	flags
	)

Registers a new attribute with the given resource.

As the attributes str fields will point to name and val the caller must ensure that these pointers are valid during the attribute's lifetime.

Parameters

resource	The resource to register the attribute with.
name	The attribute's name.
nlen	Length of `name`.
val	The attribute's value or `NULL` if none.
vlen	Length of `val` if specified.
flags	Flags for memory management (in particular release of memory).

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

Definition at line 314 of file resource.c.

Here is the call graph for this function:

Here is the caller graph for this function:

§ coap_add_observer()

coap_subscription_t* coap_add_observer	(	coap_resource_t *	resource,
		const coap_endpoint_t *	local_interface,
		const coap_address_t *	observer,
		const str *	token
	)

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.
local_interface	The local network interface where the observer is attached to.
observer	The remote peer that wants to received status updates.
token	The token that identifies this subscription.

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

Definition at line 542 of file resource.c.

Here is the call graph for this function:

Here is the caller 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(), 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 399 of file resource.c.

Here is the caller graph for this function:

§ coap_check_notify()

void coap_check_notify ( coap_context_t * context )

Checks for all known resources, if they are dirty and notifies subscribed observers.

Definition at line 689 of file resource.c.

Here is the call graph for this function:

Here is the caller graph for this function:

§ coap_delete_all_resources()

void coap_delete_all_resources ( coap_context_t * context )

Deletes all resources from given context and frees their storage.

Parameters

context The CoAP context with the resources to be deleted.

Definition at line 449 of file resource.c.

Here is the call graph for this function:

Here is the caller graph for this function:

§ coap_delete_attr()

void coap_delete_attr ( coap_attr_t * attr )

Deletes an attribute.

Parameters

attr	Pointer to a previously created attribute.

Definition at line 366 of file resource.c.

Here is the call graph for this function:

Here is the caller graph for this function:

§ coap_delete_observer()

int coap_delete_observer	(	coap_resource_t *	resource,
		const coap_address_t *	observer,
		const str *	token
	)

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

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

Parameters

resource	The observed resource.
observer	The observer's address.
token	The token that identifies this subscription or `NULL` for any token.

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

Definition at line 593 of file resource.c.

Here is the call graph for this function:

Here is the caller graph for this function:

§ coap_delete_resource()

int coap_delete_resource	(	coap_context_t *	context,
		coap_key_t	key
	)

Deletes a resource identified by key.

The storage allocated for that resource is freed.

Parameters

context	The context where the resources are stored.
key	The unique key for the resource to delete.

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

Definition at line 428 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,
		const unsigned char *	name,
		size_t	nlen
	)

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.
nlen	Actual length of `name`.

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

Definition at line 349 of file resource.c.

Here is the caller graph for this function:

§ coap_find_observer()

coap_subscription_t* coap_find_observer	(	coap_resource_t *	resource,
		const coap_address_t *	peer,
		const str *	token
	)

Returns a subscription object for given peer.

Parameters

resource	The observed resource.
peer	The address to search for.
token	The token that identifies this subscription or `NULL` for any token.

Returns: A valid subscription if exists or NULL otherwise.

Definition at line 524 of file resource.c.

Here is the call graph for this function:

Here is the caller graph for this function:

§ coap_get_resource_from_key()

coap_resource_t* coap_get_resource_from_key	(	coap_context_t *	context,
		coap_key_t	key
	)

Returns the resource identified by the unique string key.

If no resource was found, this function returns NULL.

Parameters

context	The context to look for this resource.
key	The unique key of the resource.

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

Definition at line 469 of file resource.c.

Here is the caller graph for this function:

§ coap_handle_failed_notify()

void coap_handle_failed_notify	(	coap_context_t *	,
		const coap_address_t *	,
		const str *
	)

Definition at line 748 of file resource.c.

Here is the call graph for this function:

Here is the caller graph for this function:

§ coap_hash_request_uri()

void coap_hash_request_uri	(	const coap_pdu_t *	request,
		coap_key_t	key
	)

Calculates the hash key for the resource requested by the Uri-Options of request.

This function calls coap_hash() for every path segment.

Parameters

request	The requesting pdu.
key	The resulting hash is stored in `key`.

Definition at line 383 of file resource.c.

Here is the call graph for this function:

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 478 of file resource.c.

Here is the caller graph for this function:

§ coap_print_wellknown()

coap_print_status_t coap_print_wellknown	(	coap_context_t *	context,
		unsigned char *	buf,
		size_t *	buflen,
		size_t	offset,
		coap_opt_t *	query_filter
	)

Prints the names of all known resources to buf.

This function sets buflen to the number of bytes actually written and returns 1 on succes. On error, the value in buflen is undefined and the return value will be 0.

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.

Definition at line 167 of file resource.c.

Here is the call graph for this function:

Here is the caller graph for this function:

§ coap_register_handler()

static void coap_register_handler	(	coap_resource_t *	resource,
		unsigned char	method,
		coap_method_handler_t	handler
	)

inlinestatic

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 259 of file resource.h.

Here is the call graph for this function:

§ coap_resource_init()

coap_resource_t* coap_resource_init	(	const unsigned char *	uri,
		size_t	len,
		int	flags
	)

Creates a new resource object and initializes the link field to the string of length len.

This function returns the new coap_resource_t object.

Parameters

uri	The URI path of the new resource.
len	The length of `uri`.
flags	Flags for memory management (in particular release of memory).

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

Definition at line 288 of file resource.c.

Here is the call graph for this function:

§ coap_resource_set_mode()

static void coap_resource_set_mode	(	coap_resource_t *	r,
		int	mode
	)

inlinestatic

Sets the notification message type of resource r to given mode which must be one of COAP_RESOURCE_FLAGS_NOTIFY_NON or COAP_RESOURCE_FLAGS_NOTIFY_CON.

Definition at line 130 of file resource.h.

Here is the call graph for this function:

§ coap_touch_observer()

void coap_touch_observer	(	coap_context_t *	context,
		const coap_address_t *	observer,
		const str *	token
	)

Marks an observer as alive.

Parameters

context	The CoAP context to use.
observer	The transport address of the observer.
token	The corresponding token that has been used for the subscription.

Definition at line 580 of file resource.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

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_CHECK_TIME

§ COAP_RESOURCE_FLAGS_NOTIFY_CON

§ COAP_RESOURCE_FLAGS_NOTIFY_NON

§ COAP_RESOURCE_FLAGS_RELEASE_URI

§ RESOURCES_ADD

§ RESOURCES_DELETE

§ RESOURCES_FIND

§ RESOURCES_ITER

Typedef Documentation

§ coap_attr_t

§ coap_method_handler_t

§ coap_print_status_t

§ coap_resource_t

Function Documentation

§ coap_add_attr()

§ coap_add_observer()

§ coap_add_resource()

§ coap_check_notify()

§ coap_delete_all_resources()

§ coap_delete_attr()

§ coap_delete_observer()

§ coap_delete_resource()

§ coap_find_attr()

§ coap_find_observer()

§ coap_get_resource_from_key()

§ coap_handle_failed_notify()

§ coap_hash_request_uri()

§ coap_print_link()

§ coap_print_wellknown()

§ coap_register_handler()

§ coap_resource_init()

§ coap_resource_set_mode()

§ coap_touch_observer()