coap_attribute man page

coap_attribute, coap_add_attr, coap_find_attr — Work with CoAP attributes

Synopsis

#include <coap2/coap.h>

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

Link with -lcoap-2, -lcoap-2-gnutls, -lcoap-2-openssl or -lcoap-2-tinydtls depending on your (D)TLS library type.

Description

CoAP Resources on a CoAP Server need to be created, updated etc. The URI in the request packet defines the resource to work with, with possibly the Query referring to a sub-resource. 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 "GET .well-known/core" request.

Attributes are automatically freed 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.

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

COAP_ATTR_FLAGS_RELEASE_NAME Free off name when attribute is deleted with coap_delete_resource().
COAP_ATTR_FLAGS_RELEASE_VALUE Free off value when attribute is deleted with coap_delete_resource().

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

Return Values

coap_add_attr() function return a pointer to the attribute that was created or NULL if there is a malloc failure.

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

Example

Initialize Resources

#include <coap2/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 .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("\"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

coap_resource(3) and coap_handler(3)

Further Information

See RFC7252 ‘The Constrained Application Protocol (CoAP)’ for further information.

Bugs

Please report bugs on the mailing list for libcoap: libcoap-developers@lists.sourceforge.net

Authors

The libcoap project <libcoap-developers@lists.sourceforge.net>

Referenced By

coap(7), coap_observe(3), coap_resource(3).

The man pages coap_add_attr(3) and coap_find_attr(3) are aliases of coap_attribute(3).

07/25/2019 coap_attribute 4.2.0 libcoap Manual