1COAP_RESOURCE(3) libcoap Manual COAP_RESOURCE(3)
2
3
4
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
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
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
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
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
353 coap_attribute(3), coap_context(3), coap_observe(3) and coap_handler(3)
354
356 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
357 information.
358
360 Please report bugs on the mailing list for libcoap:
361 libcoap-developers@lists.sourceforge.net
362
364 The libcoap project <libcoap-developers@lists.sourceforge.net>
365
366
367
368coap_resource 4.2.1 01/26/2021 COAP_RESOURCE(3)