1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc,tw=0: 3 4coap_attribute(3) 5================= 6:doctype: manpage 7:man source: coap_attribute 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_attribute, 14coap_add_attr, 15coap_find_attr 16- Work with CoAP attributes 17 18SYNOPSIS 19-------- 20*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 21 22*coap_attr_t *coap_add_attr(coap_resource_t *_resource_, 23coap_str_const_t *_name_, coap_str_const_t *_value_, int _flags_);* 24 25*coap_attr_t *coap_find_attr(coap_resource_t *_resource_, 26coap_str_const_t *_name_);* 27 28*coap_str_const_t *coap_attr_get_value(coap_attr_t *_attribute_);* 29 30For specific (D)TLS library support, link with 31*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 32*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 33or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 34*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 35 36DESCRIPTION 37----------- 38CoAP Resources on a CoAP Server need to be created, updated etc. The URI in 39the request packet defines the resource to work with, with possibly the Query 40referring to a sub-resource. 41 42When resources are configured on the CoAP server, the URI to match against 43is specified. 44Callback Handlers are then added to the resource to handle the different 45request methods. 46 47Adding Attributes allows textual information to be added to the resource 48which can then be reported back to any client doing a Resource Discovery using 49a "GET /.well-known/core" request with an optional query. 50See https://tools.ietf.org/html/rfc6690#section-5 for some examples of 51resource discovery usage. Common attribute names are rt, if, sz, ct, obs, rel, 52anchor, rev, hreflang, media, title and type. href cannot be an attribute name. 53 54Attributes are automatically deleted when a Resource is deleted. 55 56The *coap_add_attr*() function 57registers a new attribute called _name_ for the _resource_. 58The value of the attribute is _value_ which can be NULL. 59 60_flags_ can be one or more of the following, which, if set, defines what is 61to be internally freed off when the attribute is deleted with 62*coap_delete_resource*(). 63 64[horizontal] 65*COAP_ATTR_FLAGS_RELEASE_NAME*:: 66Free off _name_ when attribute is deleted with *coap_delete_resource*(). 67 68*COAP_ATTR_FLAGS_RELEASE_VALUE*:: 69Free off _value_ when attribute is deleted with *coap_delete_resource*(). 70 71The *coap_find_attr*() function returns the attribute with the _name_, 72if found, associated with _resource_. 73 74The *coap_attr_get_value*() function returns the _value_ associated with the 75specified _attribute_. 76 77RETURN VALUES 78------------- 79*coap_add_attr*() function returns a pointer to 80the attribute that was created or NULL if there is a malloc failure. 81 82*coap_find_attr*() function returns a pointer to the first matching 83attribute or NULL if the _name_ was not found. 84 85*coap_attr_get_value*() function returns a pointer to the value held within 86the attribute. The pointer can be NULL if the _value_ id NULL, or NULL if 87_attribute_ does not exist. 88 89EXAMPLE 90------- 91*Initialize Resources* 92 93[source, c] 94-- 95#include <coap@LIBCOAP_API_VERSION@/coap.h> 96 97static void 98init_resources(coap_context_t *ctx) { 99 100 coap_resource_t *r; 101 102 /* Create a resource to return general information */ 103 r = coap_resource_init(NULL, 0); 104 coap_register_handler(r, COAP_REQUEST_GET, hnd_get_index); 105 106 /* Document resource for '.well-known/core' request */ 107 coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0); 108 coap_add_attr(r, coap_make_str_const("title"), 109 coap_make_str_const("\"General Info\""), 0); 110 111 coap_add_resource(ctx, r); 112 113 /* Create a resource to return return or update time */ 114 r = coap_resource_init(coap_make_str_const("time"), 115 COAP_RESOURCE_FLAGS_NOTIFY_CON); 116 coap_resource_set_get_observable(r, 1); 117 coap_register_handler(r, COAP_REQUEST_GET, hnd_get_time); 118 coap_register_handler(r, COAP_REQUEST_PUT, hnd_put_time); 119 coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete_time); 120 121 /* Document resource for 'time' request */ 122 coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0); 123 coap_add_attr(r, coap_make_str_const("title"), 124 coap_make_str_const("\"Internal Clock\""), 0); 125 coap_add_attr(r, coap_make_str_const("rt"), coap_make_str_const("\"secs\""), 126 0); 127 coap_add_attr(r, coap_make_str_const("if"), coap_make_str_const("\"clock\""), 128 0); 129 130 coap_add_resource(ctx, r); 131 132} 133-- 134 135SEE ALSO 136-------- 137*coap_resource*(3) and *coap_handler*(3) 138 139FURTHER INFORMATION 140------------------- 141See 142 143"RFC7252: The Constrained Application Protocol (CoAP)" 144 145"RFC6690: Constrained RESTful Environments (CoRE) Link Format" 146 147for further information. 148 149BUGS 150---- 151Please report bugs on the mailing list for libcoap: 152libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 153https://github.com/obgm/libcoap/issues 154 155AUTHORS 156------- 157The libcoap project <libcoap-developers@lists.sourceforge.net> 158