coap_add_attr(3)

1COAP_ATTRIBUTE(3)               libcoap Manual               COAP_ATTRIBUTE(3)
2
3
4

NAME

6       coap_attribute, coap_add_attr, coap_find_attr, coap_attr_get_value -
7       Work with CoAP attributes
8

SYNOPSIS

10       #include <coap3/coap.h>
11
12       coap_attr_t *coap_add_attr(coap_resource_t *resource, coap_str_const_t
13       *name, coap_str_const_t *value, int flags);
14
15       coap_attr_t *coap_find_attr(coap_resource_t *resource, coap_str_const_t
16       *name);
17
18       coap_str_const_t *coap_attr_get_value(coap_attr_t *attribute);
19
20       For specific (D)TLS library support, link with -lcoap-3-notls,
21       -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
22       -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
23       (D)TLS library support.
24

DESCRIPTION

26       CoAP Resources on a CoAP Server need to be created, updated etc. The
27       URI in the request packet defines the resource to work with, with
28       possibly the Query referring to a sub-resource.
29
30       When resources are configured on the CoAP server, the URI to match
31       against is specified. Callback Handlers are then added to the resource
32       to handle the different request methods.
33
34       Adding Attributes allows textual information to be added to the
35       resource which can then be reported back to any client doing a Resource
36       Discovery using a "GET /.well-known/core" request with an optional
37       query. See https://tools.ietf.org/html/rfc6690#section-5 for some
38       examples of resource discovery usage. Common attribute names are rt,
39       if, sz, ct, obs, rel, anchor, rev, hreflang, media, title and type.
40       href cannot be an attribute name.
41
42       Attributes are automatically deleted when a Resource is deleted.
43
44       The coap_add_attr() function registers a new attribute called name for
45       the resource. The value of the attribute is value which can be NULL.
46
47       flags can be one or more of the following, which, if set, defines what
48       is to be internally freed off when the attribute is deleted with
49       coap_delete_resource().
50
51
52       COAP_ATTR_FLAGS_RELEASE_NAME    Free off name when
53                                       attribute is deleted with
54                                       coap_delete_resource().
55
56       COAP_ATTR_FLAGS_RELEASE_VALUE   Free off value when
57                                       attribute is deleted with
58                                       coap_delete_resource().
59
60
61       The coap_find_attr() function returns the attribute with the name, if
62       found, associated with resource.
63
64       The coap_attr_get_value() function returns the value associated with
65       the specified attribute.
66

RETURN VALUES

68       coap_add_attr() function returns a pointer to the attribute that was
69       created or NULL if there is a malloc failure.
70
71       coap_find_attr() function returns a pointer to the first matching
72       attribute or NULL if the name was not found.
73
74       coap_attr_get_value() function returns a pointer to the value held
75       within the attribute. The pointer can be NULL if the value id NULL, or
76       NULL if attribute does not exist.
77

EXAMPLE

79       Initialize Resources
80
81           #include <coap3/coap.h>
82
83           static void
84           init_resources(coap_context_t *ctx) {
85
86             coap_resource_t *r;
87
88             /* Create a resource to return general information */
89             r = coap_resource_init(NULL, 0);
90             coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get_index);
91
92             /* Document resource for '.well-known/core' request */
93             coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
94             coap_add_attr(r, coap_make_str_const("title"),
95                           coap_make_str_const("\"General Info\""), 0);
96
97             coap_add_resource(ctx, r);
98
99             /* Create a resource to return return or update time */
100             r = coap_resource_init(coap_make_str_const("time"),
101                                    COAP_RESOURCE_FLAGS_NOTIFY_CON);
102             coap_resource_set_get_observable(r, 1);
103             coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get_time);
104             coap_register_request_handler(r, COAP_REQUEST_PUT, hnd_put_time);
105             coap_register_request_handler(r, COAP_REQUEST_DELETE, hnd_delete_time);
106
107             /* Document resource for 'time' request */
108             coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
109             coap_add_attr(r, coap_make_str_const("title"),
110                           coap_make_str_const("\"Internal Clock\""), 0);
111             coap_add_attr(r, coap_make_str_const("rt"), coap_make_str_const("\"secs\""),
112                           0);
113             coap_add_attr(r, coap_make_str_const("if"), coap_make_str_const("\"clock\""),
114                           0);
115
116             coap_add_resource(ctx, r);
117
118           }
119

FURTHER INFORMATION

124       See
125
126       "RFC7252: The Constrained Application Protocol (CoAP)"
127
128       "RFC6690: Constrained RESTful Environments (CoRE) Link Format"
129
130       for further information.
131

BUGS

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

AUTHORS

138       The libcoap project <libcoap-developers@lists.sourceforge.net>
139
140
141
142coap_attribute 4.3.1              01/19/2023                 COAP_ATTRIBUTE(3)