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