NAME

SYNOPSIS

coap_attr_t *coap_add_attr(coap_resource_t *resource, coap_str_const_t *name, coap_str_const_t *value, int flags);

coap_attr_t *coap_find_attr(coap_resource_t *resource, coap_str_const_t *name);

coap_str_const_t *coap_attr_get_value(coap_attr_t *attribute);

For specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default (D)TLS library support.

DESCRIPTION

When resources are configured on the CoAP server, the URI to match against is specified. Callback Handlers are then added to the resource to handle the different request methods.

Adding Attributes allows textual information to be added to the resource which can then be reported back to any client doing a Resource Discovery using a "GET /.well-known/core" request with an optional query. See https://tools.ietf.org/html/rfc6690#section-5 for some examples of resource discovery usage. Common attribute names are rt, if, sz, ct, obs, rel, anchor, rev, hreflang, media, title and type. href cannot be an attribute name.

Attributes are automatically deleted when a Resource is deleted.

The coap_add_attr() function registers a new attribute called name for the resource. The value of the attribute is value which can be NULL.

flags can be one or more of the following, which, if set, defines what is to be internally freed off when the attribute is deleted with coap_delete_resource().

The coap_find_attr() function returns the attribute with the name, if found, associated with resource.

The coap_attr_get_value() function returns the value associated with the specified attribute.

RETURN VALUES

coap_find_attr() function returns a pointer to the first matching attribute or NULL if the name was not found.

coap_attr_get_value() function returns a pointer to the value held within the attribute. The pointer can be NULL if the value id NULL, or NULL if attribute does not exist.

EXAMPLE

#include <coap3/coap.h>
static void
init_resources(coap_context_t *ctx) {
  coap_resource_t *r;
  /* Create a resource to return general information */
  r = coap_resource_init(NULL, 0);
  coap_register_handler(r, COAP_REQUEST_GET, hnd_get_index);
  /* Document resource for '.well-known/core' request */
  coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
  coap_add_attr(r, coap_make_str_const("title"),
                coap_make_str_const("\"General Info\""), 0);
  coap_add_resource(ctx, r);
  /* Create a resource to return return or update time */
  r = coap_resource_init(coap_make_str_const("time"),
                         COAP_RESOURCE_FLAGS_NOTIFY_CON);
  coap_resource_set_get_observable(r, 1);
  coap_register_handler(r, COAP_REQUEST_GET, hnd_get_time);
  coap_register_handler(r, COAP_REQUEST_PUT, hnd_put_time);
  coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete_time);
  /* Document resource for 'time' request */
  coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
  coap_add_attr(r, coap_make_str_const("title"),
                coap_make_str_const("\"Internal Clock\""), 0);
  coap_add_attr(r, coap_make_str_const("rt"), coap_make_str_const("\"secs\""),
                0);
  coap_add_attr(r, coap_make_str_const("if"), coap_make_str_const("\"clock\""),
                0);
  coap_add_resource(ctx, r);
}

SEE ALSO

FURTHER INFORMATION

"RFC7252: The Constrained Application Protocol (CoAP)"

"RFC6690: Constrained RESTful Environments (CoRE) Link Format"

for further information.

BUGS

AUTHORS