NAME

       coap_attribute, coap_add_attr, coap_find_attr, coap_attr_get_value - Work with CoAP attributes

SYNOPSIS

       #include <coap3/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);

       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

       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 Resource Discovery using a "GET /.well-known/core" request with an optional query.
       See "RFC6690 5. Examples" 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.

FUNCTIONS

       Function: coap_add_attr()

       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 zero or more of the following or’d together, 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().

       Function: coap_find_attr()

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

       Function: coap_attr_get_value()

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

RETURN VALUES

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

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

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

       Initialize Resources

           #include <coap3/coap.h>

           void hnd_get_index(coap_resource_t *resource, coap_session_t *session,
                              const coap_pdu_t *request,
                              const coap_string_t *query,
                              coap_pdu_t *response);

           void hnd_get_time(coap_resource_t *resource, coap_session_t *session,
                             const coap_pdu_t *request,
                             const coap_string_t *query,
                             coap_pdu_t *response);

           void hnd_put_time(coap_resource_t *resource, coap_session_t *session,
                             const coap_pdu_t *request,
                             const coap_string_t *query,
                             coap_pdu_t *response);

           void hnd_delete_time(coap_resource_t *resource, coap_session_t *session,
                                const coap_pdu_t *request,
                                const coap_string_t *query,
                                coap_pdu_t *response);

           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_request_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_request_handler(r, COAP_REQUEST_GET, hnd_get_time);
             coap_register_request_handler(r, COAP_REQUEST_PUT, hnd_put_time);
             coap_register_request_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

       coap_resource(3) and coap_handler(3)

FURTHER INFORMATION

       See

       "RFC7252: The Constrained Application Protocol (CoAP)"

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

       for further information.

BUGS

       Please report bugs on the mailing list for libcoap: libcoap-developers@lists.sourceforge.net or raise an
       issue on GitHub at https://github.com/obgm/libcoap/issues

AUTHORS

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