coap_resource(3)

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

NAME

6       coap_resource, coap_resource_init, coap_resource_unknown_init,
7       coap_add_resource, coap_delete_resource, coap_delete_all_resources,
8       coap_resource_set_mode - Work with CoAP resources
9

SYNOPSIS

11       #include <coap2/coap.h>
12
13       coap_resource_t *coap_resource_init(coap_str_const_t *uri_path, int
14       flags);
15
16       coap_resource_t *coap_resource_unknown_init(coap_method_handler_t
17       put_handler);
18
19       void coap_add_resource(coap_context_t *context, coap_resource_t
20       *resource);
21
22       int coap_delete_resource(coap_context_t context, coap_resource_t
23       resource);
24
25       void coap_delete_all_resources(coap_context_t *context);
26
27       void coap_resource_set_mode(coap_resource_t *resource, int mode);
28
29       Link with -lcoap-2, -lcoap-2-gnutls, -lcoap-2-openssl or
30       -lcoap-2-tinydtls depending on your (D)TLS library type.
31

DESCRIPTION

33       CoAP Resources on a CoAP Server need to be created and updated etc. The
34       URI in the request packet defines the resource to work with, with
35       possibly the Query referring to a sub-resource.
36
37       When resources are configured on the CoAP server, the URI to match
38       against in the request packet is specified.
39
40       Callback Handlers are then added to the resource to handle the
41       different request methods.
42
43       Adding Attributes allows textual information to be added to the
44       resource which can then be reported back to any client doing a "GET
45       .well-known/core" request.
46
47       If an incoming packet request matches a resource’s URI and Method, then
48       the appropriate callback resource handler is invoked to process the
49       packet which then should update a suitable response packet for sending
50       back to the requester.
51
52       There is support for handling incoming packets where the URI is
53       unknown. This could, for example, happen when a PUT request is trying
54       to create a new resource. It is the responsibility of the unknown
55       resource callback handler to either create a new resource for the URI
56       or just manage things separately.
57
58       CoAP Observe (RFC 7641) is not supported for unknown resources, so a
59       new resource with GET handler must be created by the unknown resource
60       callback handle matching the URI which then can be Observable.
61
62       The coap_resource_init() function returns a newly created resource of
63       type coap_resource_t * . uri_path specifies the uri string path to
64       match against. flags is used to define whether the resource is of type
65       Confirmable Message or Non-Confirmable Message for any "observe"
66       responses. See coap_observe(3). flags can be one of the following
67       definitions or’ed together.
68
69
70       COAP_RESOURCE_FLAGS_NOTIFY_NON    Set the notification
71                                         message type to
72                                         non-confirmable for any
73                                         trigggered "observe"
74                                         responses.
75
76       COAP_RESOURCE_FLAGS_NOTIFY_CON    Set the notification
77                                         message type to
78                                         confirmable for any
79                                         trigggered "observe"
80                                         responses.
81
82       COAP_RESOURCE_FLAGS_RELEASE_URI   Free off the
83                                         coap_str_const_t for
84                                         uri_path when the resource
85                                         is deleted.
86
87
88       NOTE: uri_path, if not 7 bit readable ASCII, binary bytes must be hex
89       encoded according to the rules defined in RFC3968 Section 2.1.
90
91       The coap_resource_unknown_init() returns a newly created resource of
92       type coap_resource_t *. put_handler is automatically added to the
93       resource to handle PUT requests to resources that are unknown.
94       Additional handlers can be added to this resource if required.
95
96       The coap_add_resource() function registers the given resource with the
97       context. The resource must have been created by coap_resource_init(),
98       or coap_resource_unknown_init(). The storage allocated for the resource
99       will be released by coap_delete_resource().
100
101       As the uri_path of the resource has to be unique across all of the
102       resources associated with a context, coap_add_resource() (or
103       coap_add_resource_release()) will delete any previous resource with the
104       same uri_path before adding in the new resource.
105
106       The coap_delete_resource() function deletes a resource identified by
107       resource from context. The storage allocated for that resource is
108       freed, along with any attrigutes associated with the resource.
109
110       The coap_delete_all_resources() function deletes all resources from
111       context and frees their storage.
112
113       The coap_resource_set_mode() changes the notification message type of
114       resource to the given mode which must be one of
115       COAP_RESOURCE_FLAGS_NOTIFY_NON or COAP_RESOURCE_FLAGS_NOTIFY_CON.
116

RETURN VALUES

118       The coap_resource_init() and coap_resource_unknown_init() functions
119       return a newly created resource or NULL if there is a malloc failure.
120
121       The coap_delete_resource() function return 0 on failure (resource not
122       found), 1 on success.
123

EXAMPLES

125       Fixed Resources Set Up
126
127           #include <coap2/coap.h>
128
129           #define INDEX "This is an example server using libcoap\n"
130
131           void
132           hnd_get_index(coap_context_t *ctx, coap_resource_t *resource,
133           coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
134           coap_string_t *query, coap_pdu_t *response) {
135             unsigned char buf[3];
136
137             response->code = COAP_RESPONSE_CODE(205);
138
139             coap_add_option(response,
140                             COAP_OPTION_CONTENT_TYPE,
141                             coap_encode_var_safe(buf, sizeof(buf),
142                                                  COAP_MEDIATYPE_TEXT_PLAIN),
143                             buf);
144
145             coap_add_option(response,
146                             COAP_OPTION_MAXAGE,
147                             coap_encode_var_safe(buf, sizeof(buf), 0x2ffff), buf);
148
149             coap_add_data(response, strlen(INDEX), (const uint8_t *)INDEX);
150
151           }
152
153           void
154           hnd_delete_time(coap_context_t *ctx, coap_resource_t *resource,
155           coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
156           coap_string_t *query, coap_pdu_t *response) {
157
158             /* .. code .. */
159
160           }
161
162           void
163           hnd_get_time(coap_context_t *ctx, coap_resource_t *resource,
164           coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
165           coap_string_t *query, coap_pdu_t *response) {
166
167             /* .. code .. */
168
169           }
170
171           void
172           hnd_put_time(coap_context_t *ctx, coap_resource_t *resource,
173           coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
174           coap_string_t *query, coap_pdu_t *response) {
175
176             /* .. code .. */
177
178           }
179
180           static void
181           init_resources(coap_context_t *ctx) {
182
183             coap_resource_t *r;
184
185             /* Create a resource to return general information */
186             r = coap_resource_init(NULL, 0);
187             coap_register_handler(r, COAP_REQUEST_GET, hnd_get_index);
188
189             /* Document resource for .well-known/core request */
190             coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
191             coap_add_attr(r, coap_make_str_const("title"),
192                           coap_make_str_const("\"General Info\""), 0);
193
194             coap_add_resource(ctx, r);
195
196             /* Create a resource to return return or update time */
197             r = coap_resource_init(coap_make_str_const("time"),
198                                    COAP_RESOURCE_FLAGS_NOTIFY_CON);
199             coap_resource_set_get_observable(r, 1);
200             coap_register_handler(r, COAP_REQUEST_GET, hnd_get_time);
201             coap_register_handler(r, COAP_REQUEST_PUT, hnd_put_time);
202             coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete_time);
203
204             /* Document resource for .well-known/core request */
205             coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
206             coap_add_attr(r, coap_make_str_const("title"),
207                           coap_make_str_const("\"Internal Clock\""), 0);
208             coap_add_attr(r, coap_make_str_const("rt"), coap_make_str_const("\"secs\""),
209                           0);
210             coap_add_attr(r, coap_make_str_const("if"), coap_make_str_const("\"clock\""),
211                           0);
212
213             coap_add_resource(ctx, r);
214
215           }
216
217       Dynamic Resources Set Up
218
219           #include <coap2/coap.h>
220
221           /* Regular DELETE handler - used by resources created by the
222            * Unknown Resource PUT handler */
223
224           void
225           hnd_delete(coap_context_t *ctx, coap_resource_t *resource,
226           coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
227           coap_string_t *query, coap_pdu_t *response) {
228
229             /* .. code .. */
230
231             /* Dynamic resource no longer required - delete it */
232             coap_delete_resource(ctx, resource);
233
234           }
235
236           /* Regular GET handler - used by resources created by the
237            * Unknown Resource PUT handler */
238
239           void
240           hnd_get(coap_context_t *ctx, coap_resource_t *resource,
241           coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
242           coap_string_t *query, coap_pdu_t *response) {
243
244             coap_str_const_t *get_uri_path;
245             coap_string_t *get_query;
246             coap_opt_iterator_t opt_iter;
247             coap_opt_filter_t filter;
248             coap_opt_t *option;
249             int len;
250
251             /*
252              * request will be NULL if an Observe triggered request, so the uri_path,
253              * if needed, must be abstracted from the resource.
254              * The uri_path string is a const pointer
255              */
256
257             get_uri_path = coap_resource_get_uri_path(resource);
258             get_query = query;
259
260             /* .. code .. */
261
262           }
263
264           /* Regular PUT handler - used by resources created by the
265            * Unknown Resource PUT handler */
266
267           void
268           hnd_put(coap_context_t *ctx, coap_resource_t *resource,
269           coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
270           coap_string_t *query, coap_pdu_t *response) {
271
272             coap_string_t *put_uri_path;
273
274             /* get the uri_path */
275             put_uri_path = coap_get_uri_path(request);
276             if (!put_uri_path) {
277               response->code = COAP_RESPONSE_CODE(404);
278               return;
279             }
280
281             /* .. code .. */
282
283             /* Need to do this as coap_get_uri_path() created it */
284             coap_delete_string(put_uri_path);
285
286           }
287
288           /* Unknown Resource PUT handler */
289
290           void
291           hnd_unknown_put(coap_context_t *ctx, coap_resource_t *resource,
292           coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
293           coap_string_t *query, coap_pdu_t *response) {
294
295             coap_resource_t *r;
296             int len;
297             coap_string_t *uri_path;
298
299             /* get the uri_path - which will get used by coap_resource_init() */
300             uri_path = coap_get_uri_path(request);
301             if (!uri_path) {
302               response->code = COAP_RESPONSE_CODE(404);
303               return;
304             }
305
306             /* Check if new URI Path is valid */
307             if (!check_url_fn (uri_path, request->code)) {
308               response->code = COAP_RESPONSE_CODE(404);
309               coap_delete_string(uri_path);
310               return;
311             }
312
313             /*
314              * Create a resource to handle the new URI
315              * uri_path will get deleted when the resource is removed
316              */
317             r = coap_resource_init((coap_str_const_t*)uri_path,
318                   COAP_RESOURCE_FLAGS_RELEASE_URI | COAP_RESOURCE_FLAGS_NOTIFY_NON);
319             coap_register_handler(r, COAP_REQUEST_PUT, hnd_put);
320             coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete);
321             /* We possibly want to Observe the GETs */
322             coap_resource_set_get_observable(r, 1);
323             coap_register_handler(r, COAP_REQUEST_GET, hnd_get);
324             coap_add_resource(ctx, r);
325
326             /* Do the PUT for this first call */
327             hnd_put(ctx, r, session, request, token, query, response);
328
329             return;
330
331           }
332
333           /* Initialize single Unknown Resource PUT handler */
334
335           static void
336           init_resources(coap_context_t *ctx) {
337
338             coap_resource_t *r;
339
340             /* Create a resource to handle PUTs to unknown URIs */
341             r = coap_resource_unknown_init(hnd_unknown_put);
342             /*
343              * Additional handlers can be added - for example
344              *  coap_register_handler(r, COAP_REQUEST_POST, hnd_post_unknown);
345              *  coap_register_handler(r, COAP_REQUEST_GET, hnd_get_unknown);
346              *  coap_register_handler(r, COAP_REQUEST_DELETE, hnd_delete_unknown);
347              */
348             coap_add_resource(ctx, r);
349
350           }
351

FURTHER INFORMATION

356       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
357       information.
358

BUGS

360       Please report bugs on the mailing list for libcoap:
361       libcoap-developers@lists.sourceforge.net
362

AUTHORS

364       The libcoap project <libcoap-developers@lists.sourceforge.net>
365
366
367
368coap_resource 4.2.1               02/24/2020                  COAP_RESOURCE(3)