libcoap
4.2.1
|
Generic resource handling. More...
#include "uthash.h"
#include "async.h"
#include "block.h"
#include "str.h"
#include "pdu.h"
#include "net.h"
#include "subscribe.h"
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), uri_path->s[0], (obj)->uri_path->length, (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 *, coap_session_t *, coap_pdu_t *, coap_binary_t *, coap_string_t *, 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 (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_STATIC_INLINE void | coap_resource_set_mode (coap_resource_t *resource, int mode) |
Sets the notification message type of resource resource to given mode . More... | |
COAP_STATIC_INLINE void | coap_resource_set_userdata (coap_resource_t *r, void *data) |
Sets the user_data. More... | |
COAP_STATIC_INLINE void * | coap_resource_get_userdata (coap_resource_t *r) |
Gets the 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_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, 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... | |
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... | |
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_uri_path (coap_context_t *context, coap_str_const_t *uri_path) |
Returns the resource identified by the unique string uri_path . More... | |
coap_subscription_t * | coap_add_observer (coap_resource_t *resource, coap_session_t *session, const coap_binary_t *token, coap_string_t *query, int has_block2, coap_block_t block2) |
Adds the specified peer as observer for resource . More... | |
coap_subscription_t * | coap_find_observer (coap_resource_t *resource, coap_session_t *session, const coap_binary_t *token) |
Returns a subscription object for given peer . More... | |
void | coap_touch_observer (coap_context_t *context, coap_session_t *session, const coap_binary_t *token) |
Marks an observer as alive. More... | |
int | coap_delete_observer (coap_resource_t *resource, coap_session_t *session, const coap_binary_t *token) |
Removes any subscription for observer from resource and releases the allocated storage. More... | |
void | coap_delete_observers (coap_context_t *context, coap_session_t *session) |
Removes any subscription for session 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 *, coap_session_t *, const coap_binary_t *) |
COAP_STATIC_INLINE void | coap_resource_set_get_observable (coap_resource_t *resource, int mode) |
Set whether a resource is observable. More... | |
int | coap_resource_notify_observers (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. More... | |
COAP_STATIC_INLINE coap_str_const_t * | coap_resource_get_uri_path (coap_resource_t *resource) |
Get the UriPath from a resource . More... | |
COAP_DEPRECATED int | coap_resource_set_dirty (coap_resource_t *r, const coap_string_t *query) |
Generic resource handling.
Definition in file resource.h.
#define COAP_ATTR_FLAGS_RELEASE_NAME 0x1 |
Definition at line 43 of file resource.h.
#define COAP_ATTR_FLAGS_RELEASE_VALUE 0x2 |
Definition at line 44 of file resource.h.
#define COAP_PRINT_OUTPUT_LENGTH | ( | v | ) | ((v) & ~COAP_PRINT_STATUS_MASK) |
Definition at line 313 of file resource.h.
#define COAP_PRINT_STATUS_ERROR 0x80000000u |
Definition at line 314 of file resource.h.
#define COAP_PRINT_STATUS_MASK 0xF0000000u |
Definition at line 312 of file resource.h.
#define COAP_PRINT_STATUS_TRUNC 0x40000000u |
Definition at line 315 of file resource.h.
#define COAP_RESOURCE_CHECK_TIME 2 |
The interval in seconds to check if resources have changed.
Definition at line 20 of file resource.h.
#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 66 of file resource.h.
#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 60 of file resource.h.
#define COAP_RESOURCE_FLAGS_RELEASE_URI 0x1 |
The URI passed to coap_resource_init() is free'd by coap_delete_resource().
Definition at line 54 of file resource.h.
#define RESOURCES_ADD | ( | r, | |
obj | |||
) | HASH_ADD(hh, (r), uri_path->s[0], (obj)->uri_path->length, (obj)) |
Definition at line 448 of file resource.h.
#define RESOURCES_DELETE | ( | r, | |
obj | |||
) | HASH_DELETE(hh, (r), (obj)) |
Definition at line 451 of file resource.h.
#define RESOURCES_FIND | ( | r, | |
k, | |||
res | |||
) |
Definition at line 458 of file resource.h.
#define RESOURCES_ITER | ( | r, | |
tmp | |||
) |
Definition at line 454 of file resource.h.
typedef struct coap_attr_t coap_attr_t |
typedef void(* coap_method_handler_t) (coap_context_t *, struct coap_resource_t *, coap_session_t *, coap_pdu_t *, coap_binary_t *, coap_string_t *, coap_pdu_t *) |
Definition of message handler function (.
Definition at line 35 of file resource.h.
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 310 of file resource.h.
typedef struct coap_resource_t coap_resource_t |
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.
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 |
NULL
on error. Definition at line 347 of file resource.c.
coap_subscription_t* coap_add_observer | ( | coap_resource_t * | resource, |
coap_session_t * | session, | ||
const coap_binary_t * | token, | ||
coap_string_t * | query, | ||
int | has_block2, | ||
coap_block_t | block2 | ||
) |
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.
resource | The observed resource. |
session | The observer's session |
token | The token that identifies this subscription. |
query | The query string, if any. subscription will take ownership of the string. |
has_block2 | If Option Block2 defined. |
block2 | Contents of Block2 if Block 2 defined. |
NULL
on error. Definition at line 618 of file resource.c.
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().
context | The context to use. |
resource | The resource to store. |
Definition at line 447 of file resource.c.
void coap_check_notify | ( | coap_context_t * | context | ) |
Checks for all known resources, if they are dirty and notifies subscribed observers.
Definition at line 864 of file resource.c.
void coap_delete_all_resources | ( | coap_context_t * | context | ) |
Deletes all resources from given context
and frees their storage.
context | The CoAP context with the resources to be deleted. |
Definition at line 489 of file resource.c.
void coap_delete_attr | ( | coap_attr_t * | attr | ) |
Deletes an attribute.
Note: This is for internal use only, as it is not deleted from its chain.
attr | Pointer to a previously created attribute. |
Definition at line 401 of file resource.c.
int coap_delete_observer | ( | coap_resource_t * | resource, |
coap_session_t * | session, | ||
const coap_binary_t * | 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.
resource | The observed resource. |
session | The observer's session. |
token | The token that identifies this subscription or NULL for any token. |
1
if the observer has been deleted, 0
otherwise. Definition at line 698 of file resource.c.
void coap_delete_observers | ( | coap_context_t * | context, |
coap_session_t * | session | ||
) |
Removes any subscription for session
and releases the allocated storage.
context | The CoAP context to use. |
session | The observer's session. |
Definition at line 724 of file resource.c.
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.
context | The context where the resources are stored. |
resource | The resource to delete. |
1
if the resource was found (and destroyed), 0
otherwise. Definition at line 469 of file resource.c.
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.
resource | The resource to search for attribute name . |
name | Name of the requested attribute as a string. |
name
or NULL
if none was found. Definition at line 384 of file resource.c.
coap_subscription_t* coap_find_observer | ( | coap_resource_t * | resource, |
coap_session_t * | session, | ||
const coap_binary_t * | token | ||
) |
Returns a subscription object for given peer
.
resource | The observed resource. |
session | The observer's session |
token | The token that identifies this subscription or NULL for any token. |
NULL
otherwise. Definition at line 582 of file resource.c.
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
.
context | The context to look for this resource. |
uri_path | The unique string uri of the resource. |
NULL
if not found. Definition at line 510 of file resource.c.
void coap_handle_failed_notify | ( | coap_context_t * | , |
coap_session_t * | , | ||
const coap_binary_t * | |||
) |
Definition at line 924 of file resource.c.
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.
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. |
buffer
. The flag COAP_PRINT_STATUS_TRUNC indicates that the output has been truncated. Definition at line 519 of file resource.c.
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
.
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 |
buf
. COAP_PRINT_STATUS_TRUNC is set when the output has been truncated. Definition at line 163 of file resource.c.
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
.
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 572 of file resource.c.
COAP_STATIC_INLINE coap_str_const_t* coap_resource_get_uri_path | ( | coap_resource_t * | resource | ) |
Get the UriPath from a resource
.
resource | The CoAP resource to check. |
NULL
otherwise. Definition at line 510 of file resource.h.
COAP_STATIC_INLINE void* coap_resource_get_userdata | ( | coap_resource_t * | r | ) |
Gets the user_data.
The user_data is exclusively used by the library-user and can be used as context in the handler functions.
r | Resource to retrieve the user_darta from |
Definition at line 212 of file resource.h.
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.
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. |
NULL
on error. Definition at line 295 of file resource.c.
int coap_resource_notify_observers | ( | 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.
resource | The CoAP resource to use. |
query | The Query to match against or NULL |
1
if the Observe has been triggered, 0
otherwise. Definition at line 832 of file resource.c.
COAP_DEPRECATED int coap_resource_set_dirty | ( | coap_resource_t * | r, |
const coap_string_t * | query | ||
) |
Definition at line 827 of file resource.c.
COAP_STATIC_INLINE void coap_resource_set_get_observable | ( | coap_resource_t * | resource, |
int | mode | ||
) |
Set whether a resource
is observable.
If the resource is observable and the client has set the COAP_OPTION_OBSERVE in a request packet, then whenever the state of the resource changes (a call to coap_resource_trigger_observe()), an Observer response will get sent.
resource | The CoAP resource to use. |
mode | 1 if Observable is to be set, 0 otherwise. |
Definition at line 485 of file resource.h.
COAP_STATIC_INLINE void coap_resource_set_mode | ( | coap_resource_t * | resource, |
int | mode | ||
) |
Sets the notification message type of resource resource
to given mode
.
resource | The resource to update. |
mode | Must be one of COAP_RESOURCE_FLAGS_NOTIFY_NON or COAP_RESOURCE_FLAGS_NOTIFY_CON . |
Definition at line 184 of file resource.h.
COAP_STATIC_INLINE void coap_resource_set_userdata | ( | coap_resource_t * | r, |
void * | data | ||
) |
Sets the user_data.
The user_data is exclusively used by the library-user and can be used as context in the handler functions.
r | 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 199 of file resource.h.
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
This function returns the new coap_resource_t object.
put_handler | The PUT handler to register with resource for unknown Uri-Path. |
NULL
on error. Definition at line 329 of file resource.c.
void coap_touch_observer | ( | coap_context_t * | context, |
coap_session_t * | session, | ||
const coap_binary_t * | token | ||
) |
Marks an observer as alive.
context | The CoAP context to use. |
session | The observer's session |
token | The corresponding token that has been used for the subscription. |
Definition at line 685 of file resource.c.