NAME

       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>