resource.h File Reference

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)); \
}
coap_key_t
unsigned char coap_key_t[4]
Definition: hashkey.h:20

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

inline static

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

inline static

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: