1COAP_RESOURCE(3) libcoap Manual COAP_RESOURCE(3)
2
6 coap_resource, coap_resource_init, coap_resource_unknown_init,
7 coap_resource_unknown_init2, coap_resource_proxy_uri_init,
8 coap_resource_proxy_uri_init2, coap_add_resource, coap_delete_resource,
9 coap_resource_set_mode, coap_resource_set_userdata,
10 coap_resource_get_userdata, coap_resource_release_userdata_handler,
11 coap_resource_get_uri_path - Work with CoAP resources
12
14 #include <coap3/coap.h>
15 coap_resource_t *coap_resource_init(coap_str_const_t *uri_path, int
17 flags);
18 coap_resource_t *coap_resource_unknown_init(coap_method_handler_t
20 put_handler);
21 coap_resource_t *coap_resource_unknown_init2(coap_method_handler_t
23 put_handler, int flags);
24 coap_resource_t *coap_resource_proxy_uri_init(coap_method_handler_t
26 proxy_handler, size_t host_name_count, const char *host_name_list[]);
27 coap_resource_t *coap_resource_proxy_uri_init2(coap_method_handler_t
29 proxy_handler, size_t host_name_count, const char *host_name_list[],
30 int flags);
31 void coap_add_resource(coap_context_t *context, coap_resource_t
33 *resource);
34 int coap_delete_resource(coap_context_t *context, coap_resource_t
36 *resource);
37 void coap_resource_set_mode(coap_resource_t *resource, int mode);
39 void coap_resource_set_userdata(coap_resource_t *resource, void *data);
41 void *coap_resource_get_userdata(coap_resource_t *resource);
43 void coap_resource_release_userdata_handler(coap_context_t *context,
45 coap_resource_release_userdata_handler_t callback);
46 coap_str_const_t *coap_resource_get_uri_path(coap_resource_t
48 *resource);
49 For specific (D)TLS library support, link with -lcoap-3-notls,
51 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
52 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
53 (D)TLS library support.
54
56 CoAP Resources on a CoAP Server need to be created and updated etc. The
57 URI in the request packet defines the resource to work with, with
58 possibly the Query referring to a sub-resource.
59 When resources are configured on the CoAP server, the URI to match
61 against in the request packet is specified.
62 Callback Handlers are then added to the resource to handle the
64 different request methods. See coap_register_request_handler(3) for
65 further information.
66 Adding Attributes allows textual information to be added to the
68 resource which can then be reported back to any client doing a "GET
69 .well-known/core" request. See coap_add_attr(3) for further
70 information.
71 If an incoming packet request matches a resource’s URI and Method, then
73 the appropriate callback resource handler is invoked to process the
74 packet which should then update a suitable response packet for
75 returning back to the requester.
76 There is support for handling incoming packets where the URI is unknown
78 (no specific resource has been created). This could, for example,
79 happen when a PUT request is trying to create a new resource. It is the
80 responsibility of the unknown resource callback handler to either
81 create a new resource for the URI or just manage things separately.
82 CoAP Observe (RFC 7641) is not supported for unknown resources, so a
84 new resource with GET handler must be created by the unknown resource
85 callback handle matching the URI which then can be Observable.
86 There is support for handling incoming proxy based requests using the
88 Proxy-Uri or Proxy-Scheme options.
89
91 Function: coap_resource_init()
92 The coap_resource_init() function returns a newly created resource of
94 type coap_resource_t * . uri_path specifies the uri string path to
95 match against. Normally there is no need for the leading / - e.g. just
96 "full/path/for/resource". flags is used to define whether the resource
97 is of type Confirmable Message or Non-Confirmable Message for any
98 "observe" responses. See coap_observe(3). flags can be one of the
99 following definitions ored together.
100 COAP_RESOURCE_FLAGS_NOTIFY_NON Set the notification
103 message type to
104 non-confirmable for any
105 trigggered "observe"
106 responses with type set to
107 confirmable every 5
108 packets as required by
109 RFC7641 section-4.5.
110 COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS Set the notification
112 message type to always
113 non-confirmable for any
114 trigggered "observe"
115 responses. This should
116 only be used if a upper
117 layer protocol requires
118 it.
119 COAP_RESOURCE_FLAGS_NOTIFY_CON Set the notification
121 message type to
122 confirmable for any
123 trigggered "observe"
124 responses.
125 COAP_RESOURCE_FLAGS_RELEASE_URI Free off the
127 coap_str_const_t for
128 uri_path when the resource
129 is deleted.
130 NOTE: The following flags are only tested against if
133 coap_mcast_per_resource() has been called. If coap_mcast_per_resource()
134 has not been called, then all resources have multicast support, libcoap
135 adds in random delays to the responses, and 4.xx / 5.xx responses are
136 dropped.
137 COAP_RESOURCE_FLAGS_HAS_MCAST_SUPPORT This resource has support
140 for multicast requests.
141 COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_DELAYS Disable libcoap library
143 from adding in delays to
144 multicast requests before
145 releasing the response
146 back to the client. It is
147 then the responsibility of
148 the app to delay the
149 responses for multicast
150 requests. See
151 https://datatracker.ietf.org/doc/html/rfc7252#section-8.2.
152 However, the pseudo
153 resource for
154 ".well-known/core" always
155 has multicast support
156 enabled.
157 COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_05 Enable libcoap library suppression of 205 multicast
159 responses that are empty (overridden by RFC7969
160 No-Response option) for multicast requests.
161 COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_XX Enable libcoap library suppressing 2.xx multicast
163 responses (overridden by RFC7969 No-Response option) for
164 multicast requests.
165 COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_4_XX Disable libcoap library suppressing 4.xx multicast
167 responses (overridden by RFC7969 No-Response option) for
168 multicast requests.
169 COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_5_XX Disable libcoap library suppressing 5.xx multicast
171 responses (overridden by RFC7969 No-Response option) for
172 multicast requests.
173 NOTE: uri_path, if not 7 bit readable ASCII, binary bytes must be hex
176 encoded according to the rules defined in RFC3968 Section 2.1.
177 Function: coap_resource_unknown_init()
179 The coap_resource_unknown_init() function returns a newly created
181 resource of type coap_resource_t *. put_handler is automatically added
182 to the resource to handle PUT requests to resources that are unknown.
183 Additional handlers can be added to this resource if required.
184 Function: coap_resource_unknown_init2()
186 The coap_resource_unknown_init2() function returns a newly created
188 resource of type coap_resource_t *. put_handler is automatically added
189 to the resource to handle PUT requests to resources that are unknown.
190 Additional handlers can be added to this resource if required. flags
191 can be zero or more COAP_RESOURCE_FLAGS MCAST definitions.
192 Function: coap_resource_proxy_uri_init()
194 The coap_resource_proxy_uri_init() function returns a newly created
196 resource of type coap_resource_t *. proxy_handler is automatically
197 added to the resource to handle PUT/POST/GET etc. requests that use the
198 Proxy-Uri option. There is no need to add explicit request type
199 handlers. One or more names by which the proxy is known by (IP address,
200 DNS name etc.) must be supplied in the array defined by
201 host_name_list[] which has a count of host_name_count. This is used to
202 check whether the current endpoint is the proxy target address, or the
203 request has to be passed on to an upstream server.
204 Function: coap_resource_proxy_uri_init2()
206 The coap_resource_proxy_uri_init2() function returns a newly created
208 resource of type coap_resource_t *. proxy_handler is automatically
209 added to the resource to handle PUT/POST/GET etc. requests that use the
210 Proxy-Uri option. There is no need to add explicit request type
211 handlers. One or more names by which the proxy is known by (IP address,
212 DNS name etc.) must be supplied in the array defined by
213 host_name_list[] which has a count of host_name_count. This is used to
214 check whether the current endpoint is the proxy target address, or the
215 request has to be passed on to an upstream server. flags can be zero or
216 more COAP_RESOURCE_FLAGS MCAST definitions.
217 Function: coap_add_resource()
219 The coap_add_resource() function registers the given resource with the
221 context. The resource must have been created by coap_resource_init(),
222 coap_resource_unknown_init(), coap_resource_unknown_init2(),
223 coap_resource_proxy_uri_init() or coap_resource_proxy_uri_init2(). The
224 storage allocated for the resource will be released by
225 coap_delete_resource().
226 As the uri_path of the resource has to be unique across all of the
228 resources associated with a context, coap_add_resource() will delete
229 any previous resource with the same uri_path before adding in the new
230 resource.
231 Function: coap_delete_resource()
233 The coap_delete_resource() function deletes a resource identified by
235 resource. The context parameter is ignored. The storage allocated for
236 that resource is freed, along with any attributes associated with the
237 resource.
238 Function: coap_resource_set_mode()
240 The coap_resource_set_mode() changes the notification message type of
242 resource to the given mode which must be one of
243 COAP_RESOURCE_FLAGS_NOTIFY_NON, COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS
244 or COAP_RESOURCE_FLAGS_NOTIFY_CON.
245 Function: coap_resource_set_userdata()
247 The coap_resource_set_userdata() function allows a pointer to user data
249 to be associated with a resource that can accessed in any callback that
250 includes resource as a parameter.
251 NOTE: data must point to a static, or allocated, block of memory.
253 Function: coap_resource_get_userdata()
255 The coap_resource_get_userdata() function obtains the user data pointer
257 from the resource that had previously been set up by
258 coap_resource_set_userdata().
259 Function: coap_resource_release_userdata_handler()
261 The coap_resource_release_userdata_handler() function defines the
263 context wide callback handler to call to release the allocated user
264 data that has been added to the resource using
265 coap_resource_set_userdata() when the resource is deleted. callback can
266 be NULL (which is the default) if nothing needs to be freed off.
267 Function: coap_resource_get_uri_path()
269 The coap_resource_get_uri_path() function is used to obtain the UriPath
271 of the resource definion.
272
274 The coap_resource_init(), coap_resource_unknown_init(),
275 coap_resource_unknown_init2(), coap_resource_proxy_uri_init() and
276 coap_resource_proxy_uri_init2() functions return a newly created
277 resource or NULL if there is a malloc failure.
278 The coap_delete_resource() function return 0 on failure (resource not
280 found), 1 on success.
281 The coap_resource_get_userdata() function returns the value previously
283 set by the coap_resource_set_userdata() function or NULL.
284 The coap_resource_get_uri_path() function returns the uri_path or NULL
286 if there was a failure.
287
289 Fixed Resources Set Up
290 #include <coap3/coap.h>
292 #define INDEX "This is an example server using libcoap\n"
294 static void
296 hnd_get_index(coap_resource_t *resource, coap_session_t *session,
297 const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
298 unsigned char buf[3];
299 /* Remove (void) definition if variable is used */
300 (void)resource;
301 (void)session;
302 (void)request;
303 (void)query;
304 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
306 coap_add_option(response,
308 COAP_OPTION_CONTENT_TYPE,
309 coap_encode_var_safe(buf, sizeof(buf),
310 COAP_MEDIATYPE_TEXT_PLAIN),
311 buf);
312 coap_add_option(response,
314 COAP_OPTION_MAXAGE,
315 coap_encode_var_safe(buf, sizeof(buf), 0x2ffff), buf);
316 coap_add_data(response, strlen(INDEX), (const uint8_t *)INDEX);
318 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
320 }
321 static void
323 hnd_delete_time(coap_resource_t *resource, coap_session_t *session,
324 const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
325 /* Remove (void) definition if variable is used */
326 (void)resource;
327 (void)session;
328 (void)request;
329 (void)query;
330 /* .. code .. */
332 coap_pdu_set_code(response, COAP_RESPONSE_CODE_DELETED);
334 }
335 static void
337 hnd_get_time(coap_resource_t *resource, coap_session_t *session,
338 const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
339 /* Remove (void) definition if variable is used */
340 (void)resource;
341 (void)session;
342 (void)request;
343 (void)query;
344 (void)response;
345 /* .. code .. */
347 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
349 }
350 static void
352 hnd_put_time(coap_resource_t *resource, coap_session_t *session,
353 const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
354 /* Remove (void) definition if variable is used */
355 (void)resource;
356 (void)session;
357 (void)request;
358 (void)query;
359 (void)response;
360 /* .. code .. */
362 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CHANGED);
364 }
365 static void
367 init_resources(coap_context_t *ctx) {
368 coap_resource_t *r;
370 /* Create a resource to return general information */
372 r = coap_resource_init(NULL, 0);
373 coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get_index);
374 /* Document resource for '.well-known/core' request */
376 coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
377 coap_add_attr(r, coap_make_str_const("title"),
378 coap_make_str_const("\"General Info\""), 0);
379 coap_add_resource(ctx, r);
381 /* Create a resource to return return or update time */
383 r = coap_resource_init(coap_make_str_const("time"),
384 COAP_RESOURCE_FLAGS_NOTIFY_CON);
385 coap_resource_set_get_observable(r, 1);
386 coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get_time);
387 coap_register_request_handler(r, COAP_REQUEST_PUT, hnd_put_time);
388 coap_register_request_handler(r, COAP_REQUEST_DELETE, hnd_delete_time);
389 /* Document resource for 'time' request */
391 coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
392 coap_add_attr(r, coap_make_str_const("title"),
393 coap_make_str_const("\"Internal Clock\""), 0);
394 coap_add_attr(r, coap_make_str_const("rt"), coap_make_str_const("\"secs\""),
395 0);
396 coap_add_attr(r, coap_make_str_const("if"), coap_make_str_const("\"clock\""),
397 0);
398 coap_add_resource(ctx, r);
400 }
402 Dynamic Resources Set Up
404 #include <coap3/coap.h>
406 /* Regular DELETE handler - used by resources created by the
408 * Unknown Resource PUT handler */
409 static void
411 hnd_delete(coap_resource_t *resource, coap_session_t *session,
412 const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
413 /* Remove (void) definition if variable is used */
414 (void)session;
415 (void)request;
416 (void)query;
417 (void)response;
418 /* .. code .. */
420 /* Dynamic resource no longer required - delete it */
422 coap_delete_resource(NULL, resource);
423 coap_pdu_set_code(response, COAP_RESPONSE_CODE_DELETED);
425 }
426 /* Regular GET handler - used by resources created by the
428 * Unknown Resource PUT handler */
429 static void
431 hnd_get(coap_resource_t *resource, coap_session_t *session,
432 const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
433 coap_str_const_t *get_uri_path;
435 /* Remove (void) definition if variable is used */
437 (void)resource;
438 (void)session;
439 (void)request;
440 (void)query;
441 /*
443 * Get the specific resouce being requested to determine what the response is
444 * The uri_path string is a const pointer
445 */
446 get_uri_path = coap_resource_get_uri_path(resource);
448 /* .. code .. */
450 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
452 }
453 /* Regular PUT handler - used by resources created by the
455 * Unknown Resource PUT handler */
456 static void
458 hnd_put(coap_resource_t *resource, coap_session_t *session,
459 const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
460 /* Remove (void) definition if variable is used */
461 (void)resource;
462 (void)session;
463 (void)query;
464 coap_string_t *put_uri_path;
466 size_t length;
467 const uint8_t *data;
468 size_t offset;
469 size_t total;
470 int new_resource = 0;
471 /* get the uri_path */
473 put_uri_path = coap_get_uri_path(request);
474 if (!put_uri_path) {
475 coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
476 return;
477 }
478 coap_get_data_large(request, &length, &data, &offset, &total);
479 /* .. code .. */
481 /* Need to do this as coap_get_uri_path() created it */
483 coap_delete_string(put_uri_path);
484 if (length + offset < total)
486 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTINUE);
487 else if (new_resource)
488 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CREATED);
489 else
490 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CHANGED);
491 }
492 static int
494 check_url_fn(coap_string_t *uri_path, uint8_t code) {
495 /* Remove (void) definition if variable is used */
496 (void)uri_path;
497 (void)code;
498 /* Code to determine whether the uri is valid or not */
500 return 1;
502 }
503 /* Unknown Resource PUT handler */
505 static void
507 hnd_put_unknown(coap_resource_t *resource, coap_session_t *session,
508 const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
509 /* Remove (void) definition if variable is used */
510 (void)resource;
511 coap_pdu_code_t req_code = coap_pdu_get_code(request);
512 coap_resource_t *r;
514 coap_string_t *uri_path;
515 /* get the uri_path - which will get used by coap_resource_init() */
517 uri_path = coap_get_uri_path(request);
518 if (!uri_path) {
519 coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
520 return;
521 }
522 /* Check if new URI Path is valid */
524 if (!check_url_fn (uri_path, req_code)) {
525 coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
526 coap_delete_string(uri_path);
527 return;
528 }
529 /*
531 * Create a resource to handle the new URI
532 * uri_path will get deleted when the resource is removed
533 */
534 r = coap_resource_init((coap_str_const_t*)uri_path,
535 COAP_RESOURCE_FLAGS_RELEASE_URI | COAP_RESOURCE_FLAGS_NOTIFY_NON);
536 coap_register_request_handler(r, COAP_REQUEST_PUT, hnd_put);
537 coap_register_request_handler(r, COAP_REQUEST_DELETE, hnd_delete);
538 /* We possibly want to Observe the GETs */
539 coap_resource_set_get_observable(r, 1);
540 coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get);
541 coap_add_resource(coap_session_get_context(session), r);
542 /* Do the PUT for this first call */
544 hnd_put(r, session, request, query, response);
545 return;
547 }
549 /* Initialize single Unknown Resource PUT handler */
551 static void
553 init_resources(coap_context_t *ctx) {
554 coap_resource_t *r;
556 /* Create a resource to handle PUTs to unknown URIs */
558 r = coap_resource_unknown_init2(hnd_put_unknown, 0);
559 /*
560 * Additional handlers can be added - for example
561 * coap_register_request_handler(r, COAP_REQUEST_POST, hnd_post_unknown);
562 * coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get_unknown);
563 * coap_register_request_handler(r, COAP_REQUEST_DELETE, hnd_delete_unknown);
564 */
565 coap_add_resource(ctx, r);
566 }
568
570 coap_attribute(3), coap_context(3), coap_handler(3) and coap_observe(3)
571
573 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
574 information.
575
577 Please report bugs on the mailing list for libcoap:
578 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
579 https://github.com/obgm/libcoap/issues
580
582 The libcoap project <libcoap-developers@lists.sourceforge.net>
583coap_resource 4.3.1 01/19/2023 COAP_RESOURCE(3)