resource.c File Reference
`#include "coap_internal.h"`
`#include <stdio.h>`
Include dependency graph for resource.c:

Go to the source code of this file.

## Macros

#define | COAP_MALLOC_TYPE(Type) ((coap_##Type##_t *)coap_malloc(sizeof(coap_##Type##_t)))
#define | COAP_FREE_TYPE(Type, Object) coap_free(Object)
#define | COAP_PRINT_STATUS_MAX (~COAP_PRINT_STATUS_MASK)
#define | min(a, b) ((a) < (b) ? (a) : (b))
#define | PRINT_WITH_OFFSET(Buf, Offset, Char)
| Adds Char to Buf if Offset is zero. More...
#define | PRINT_COND_WITH_OFFSET(Buf, Bufend, Offset, Char, Result)
| Adds Char to Buf if Offset is zero and Buf is less than Bufend. More...
#define | COPY_COND_WITH_OFFSET(Buf, Bufend, Offset, Str, Length, Result)
| Copies at most Length characters of Str to Buf. More...
#define | MATCH_URI 0x01
#define | MATCH_PREFIX 0x02
#define | MATCH_SUBSTRING 0x04
#define | INET6_ADDRSTRLEN 40

## Functions

static int | match (const coap_str_const_t *text, const coap_str_const_t *pattern, int match_prefix, int match_substring)
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`. More...
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_attr_t * | coap_add_attr (coap_resource_t *resource, coap_str_const_t *name, coap_str_const_t *val, 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...
static void | coap_free_resource (coap_resource_t *resource)
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_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_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_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...
static coap_subscription_t * | coap_find_observer_query (coap_resource_t *resource, coap_session_t *session, const coap_string_t *query)
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...
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...
static void | coap_notify_observers (coap_context_t *context, coap_resource_t *r)
int | coap_resource_set_dirty (coap_resource_t *r, const coap_string_t *query)
int | coap_resource_notify_observers (coap_resource_t *r, const coap_string_t *query)
| Initiate the sending of an Observe packet for all observers of `resource`, optionally matching `query` if not NULL. More...
void | coap_check_notify (coap_context_t *context)
| Checks for all known resources, if they are dirty and notifies subscribed observers. More...
static void | coap_remove_failed_observers (coap_context_t *context, coap_resource_t *resource, coap_session_t *session, const coap_binary_t *token)
| Checks the failure counter for (peer, token) and removes peer from the list of observers for the given resource when COAP_OBS_MAX_FAIL is reached. More...
void | coap_handle_failed_notify (coap_context_t *context, coap_session_t *session, const coap_binary_t *token)

## Variables

static coap_str_const_t | null_path_value = {0, (const uint8_t*)""}
static coap_str_const_t * | null_path = &null_path_value
static const uint8_t | coap_unknown_resource_uri []

## Macro Definition Documentation

## COAP_FREE_TYPE

#define COAP_FREE_TYPE | ( |  | Type,
|  |  | Object
| ) |  | coap_free(Object)

Definition at line 52 of file resource.c.

## COAP_MALLOC_TYPE

#define COAP_MALLOC_TYPE | ( |  | Type | ) | ((coap_##Type##_t *)coap_malloc(sizeof(coap_##Type##_t)))

Definition at line 50 of file resource.c.

## COAP_PRINT_STATUS_MAX

#define COAP_PRINT_STATUS_MAX (~COAP_PRINT_STATUS_MASK)

Definition at line 55 of file resource.c.

## COPY_COND_WITH_OFFSET

#define COPY_COND_WITH_OFFSET | ( |  | Buf,
|  |  | Bufend,
|  |  | Offset,
|  |  | Str,
|  |  | Length,
|  |  | Result
| ) |  |

Value:
{ \
size_t i; \
for (i = 0; i < (Length); i++) { \
PRINT_COND_WITH_OFFSET((Buf), (Bufend), (Offset), (Str)[i], (Result)); \
} \
}

Copies at most Length characters of Str to Buf.

The first Offset characters are skipped. Output may be truncated to Bufend - Buf characters.

Definition at line 91 of file resource.c.

## INET6_ADDRSTRLEN

#define INET6_ADDRSTRLEN 40

## MATCH_PREFIX

#define MATCH_PREFIX 0x02

## MATCH_SUBSTRING

#define MATCH_SUBSTRING 0x04

## MATCH_URI

#define MATCH_URI 0x01

## min

#define min | ( |  | a,
|  |  | b
| ) |  | ((a) < (b) ? (a) : (b))

Definition at line 58 of file resource.c.

## PRINT_COND_WITH_OFFSET

#define PRINT_COND_WITH_OFFSET | ( |  | Buf,
|  |  | Bufend,
|  |  | Offset,
|  |  | Char,
|  |  | Result
| ) |  |

Value:
{ \
if ((Buf) < (Bufend)) { \
PRINT_WITH_OFFSET(Buf,Offset,Char); \
} \
(Result)++; \
}

Adds Char to Buf if Offset is zero and Buf is less than Bufend.

Definition at line 79 of file resource.c.

## PRINT_WITH_OFFSET

#define PRINT_WITH_OFFSET | ( |  | Buf,
|  |  | Offset,
|  |  | Char
| ) |  |

Value:
if ((Offset) == 0) { \
(*(Buf)++) = (Char); \
} else { \
(Offset)--; \
} \

Adds Char to Buf if Offset is zero.

Otherwise, Char is not written and Offset is decremented.

Definition at line 69 of file resource.c.

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

Here is the call graph for this function:

## coap_add_observer()

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.

Parameters

  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.

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

Definition at line 618 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() 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 447 of file resource.c.

Here is the call 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 864 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 489 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.

Note: This is for internal use only, as it is not deleted from its chain.

Parameters

  attr | Pointer to a previously created attribute.

Definition at line 401 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,
|  | 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.

Parameters

  resource | The observed resource.
  session | The observer's session.
  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 698 of file resource.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_delete_observers()

void coap_delete_observers | ( | coap_context_t * | context,
|  | coap_session_t * | session
| ) |  |

Removes any subscription for `session` and releases the allocated storage.

Parameters

  context | The CoAP context to use.
  session | The observer's session.

Definition at line 724 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_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 469 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 384 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,
|  | coap_session_t * | session,
|  | const coap_binary_t * | token
| ) |  |

Returns a subscription object for given `peer`.

Parameters

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

Returns
  A valid subscription if exists or `NULL` otherwise.

Definition at line 582 of file resource.c.

Here is the caller graph for this function:

## coap_find_observer_query()

static coap_subscription_t* coap_find_observer_query | ( | coap_resource_t * | resource,
|  | coap_session_t * | session,
|  | const coap_string_t * | query
| ) |  |

static

Definition at line 600 of file resource.c.

Here is the caller graph for this function:

## coap_free_resource()

static void coap_free_resource | ( | coap_resource_t * | resource | ) |

static

Definition at line 418 of file resource.c.

Here is the call graph for this function:
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 510 of file resource.c.

Here is the caller graph for this function:

## coap_handle_failed_notify()

void coap_handle_failed_notify | ( | coap_context_t * | context,
|  | coap_session_t * | session,
|  | const coap_binary_t * | token
| ) |  |

Definition at line 924 of file resource.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_notify_observers()

static void coap_notify_observers | ( | coap_context_t * | context,
|  | coap_resource_t * | r
| ) |  |

static

Definition at line 740 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 519 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 163 of file resource.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_register_handler()

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

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

Here is the caller graph for this function:

## coap_remove_failed_observers()

static void coap_remove_failed_observers | ( | coap_context_t * | context,
|  | coap_resource_t * | resource,
|  | coap_session_t * | session,
|  | const coap_binary_t * | token
| ) |  |

static

Checks the failure counter for (peer, token) and removes peer from the list of observers for the given resource when COAP_OBS_MAX_FAIL is reached.

Parameters

  context | The CoAP context to use
  resource | The resource to check for (peer, token)
  session | The observer's session
  token | The token that has been used for subscription.

Definition at line 882 of file resource.c.

Here is the call graph for this function:
Here is the caller graph for this function:

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

Here is the call graph for this function:

## coap_resource_notify_observers()

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.

Parameters

  resource | The CoAP resource to use.
  query | The Query to match against or NULL

Returns
  `1` if the Observe has been triggered, `0` otherwise.

Definition at line 832 of file resource.c.

Here is the caller graph for this function:

## coap_resource_set_dirty()

int coap_resource_set_dirty | ( | coap_resource_t * | r,
|  | const coap_string_t * | query
| ) |  |

Deprecated:
  use coap_resource_notify_observers() instead.

Definition at line 827 of file resource.c.

Here is the call graph for this function:

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

Here is the call graph for this function:

## coap_touch_observer()

void coap_touch_observer | ( | coap_context_t * | context,
|  | coap_session_t * | session,
|  | const coap_binary_t * | token
| ) |  |

Marks an observer as alive.

Parameters

  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.

Here is the call graph for this function:
Here is the caller graph for this function:

## match()

static int match | ( | const coap_str_const_t * | text,
|  | const coap_str_const_t * | pattern,
|  | int | match_prefix,
|  | int | match_substring
| ) |  |

static

Definition at line 99 of file resource.c.

Here is the caller graph for this function:

## Variable Documentation

## coap_unknown_resource_uri

const uint8_t coap_unknown_resource_uri[]

static

Initial value:
=
"- Unknown -"

Definition at line 325 of file resource.c.

## null_path

coap_str_const_t* null_path = &null_path_value

static

Definition at line 292 of file resource.c.

## null_path_value

coap_str_const_t null_path_value = {0, (const uint8_t*)""}

static

Definition at line 291 of file resource.c.