1COAP_PDU_SETUP(3) libcoap Manual COAP_PDU_SETUP(3)
2
6 coap_pdu_setup, coap_new_pdu, coap_pdu_init, coap_session_init_token,
7 coap_session_new_token, coap_add_token, coap_new_optlist,
8 coap_insert_optlist, coap_delete_optlist, coap_encode_var_safe,
9 coap_encode_var_safe8, coap_add_optlist_pdu, coap_add_option,
10 coap_add_data, coap_add_data_blocked_response, coap_send,
11 coap_split_path, coap_split_query, coap_pdu_set_mid, coap_pdu_set_code,
12 coap_pdu_set_type - Setting up CoAP PDUs
13
15 #include <coap3/coap.h>
16 coap_pdu_t *coap_new_pdu(coap_pdu_type_t type, coap_pdu_code_t code,
18 coap_session_t *session);
19 coap_pdu_t *coap_pdu_init(coap_pdu_type_t type, coap_pdu_code_t code,
21 coap_mid_t message_id, size_t max_size);
22 void coap_session_init_token(coap_session_t *session, size_t length,
24 const uint8_t *token);
25 void coap_session_new_token(coap_session_t *session, size_t *length,
27 uint8_t *token);
28 int coap_add_token(coap_pdu_t *pdu, size_t length, const uint8_t
30 *data);
31 coap_optlist_t *coap_new_optlist(uint16_t number, size_t length, const
33 uint8_t *data);
34 int coap_insert_optlist(coap_optlist_t **optlist_chain, coap_optlist_t
36 *optlist);
37 void coap_delete_optlist(coap_optlist_t *optlist_chain);
39 unsigned int coap_encode_var_safe(uint8_t *buffer, size_t size,
41 unsigned int value);
42 unsigned int coap_encode_var_safe8(uint8_t *buffer, size_t size,
44 uint64_t value);
45 int coap_add_optlist_pdu(coap_pdu_t *pdu, coap_optlist_t
47 **optlist_chain);
48 size_t coap_add_option(coap_pdu_t *pdu, uint16_t number, size_t length,
50 const uint8_t *data);
51 int coap_add_data(coap_pdu_t *pdu, size_t length, const uint8_t *data);
53 void coap_add_data_blocked_response(const coap_pdu_t *request,
55 coap_pdu_t *response, uint16_t media_type, int maxage, size_t length,
56 const uint8_t *data);
57 coap_mid_t coap_send(coap_session_t *session, coap_pdu_t *pdu);
59 int coap_split_path(const uint8_t *path, size_t length, uint8_t
61 *buffer, size_t *buflen);
62 int coap_split_query(const uint8_t *query, size_t length, uint8_t
64 *buffer, size_t *buflen);
65 void coap_pdu_set_mid(coap_pdu_t *pdu, coap_mid_t mid);
67 void coap_pdu_set_code(coap_pdu_t *pdu, coap_pdu_code_t code);
69 void coap_pdu_set_type(coap_pdu_t *pdu, coap_pdu_type_t type);
71 For specific (D)TLS library support, link with -lcoap-3-notls,
73 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
74 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
75 (D)TLS library support.
76
78 The CoAP PDU is of the form
79 --header--|--optional token--|--optional options--|--optional payload--
81 The terminology used is taken mainly from
83 https://tools.ietf.org/html/rfc7252#section-1.2
84 The PDU must be built in the correct order, from left to right. In
86 particular, the options need to be added in the correct numerical
87 option order as they are stored in the PDU using relative numeric
88 offsets from the previous option number.
89 There are option list functions available where options can be added to
91 a chained list of options and then the chain list is sorted and then be
92 added to the PDU.
93 Typically for clients, when creating a request, the PDU needs to be
95 created before filling it with the appropriate information.
96 Typically with a server, the response PDU, with the optional token
98 already added in, will already be created before the response handler
99 is called, and the response PDU will need to be updated as appropriate
100 starting with the optional options. Note that updating the response
101 pdu’s code variable will cause the response pdu to get transmitted. If
102 code does not get updated, and the PDU is of type CONFIRMABLE, then the
103 response PDU is transmitted as an empty ACK packet. The response pdu is
104 always freed off by the underlying library.
105 For handling situations where the data to be transmitted does not fit
107 into a single packet, see coap_block(3).
108
110 Function: coap_new_pdu()
111 The coap_new_pdu() function returns a newly created PDU of type
113 coap_pdu_t.
114 The type is one of the following
116 COAP_MESSAGE_CON Set the _PDU_ to be of type confirmable.
118 COAP_MESSAGE_NON Set the _PDU_ to be of type non-confirmable.
119 COAP_MESSAGE_ACK Set the _PDU_ to be of type acknowledge (for internal use).
120 COAP_MESSAGE_RST Set the _PDU_ to be of type reset.
121 The code is one of the following
123 COAP_EMPTY_CODE 0.00
125 COAP_REQUEST_CODE_GET 0.01
126 COAP_REQUEST_CODE_POST 0.02
127 COAP_REQUEST_CODE_PUT 0.03
128 COAP_REQUEST_CODE_DELETE 0.04
129 COAP_REQUEST_CODE_FETCH 0.05
130 COAP_REQUEST_CODE_PATCH 0.06
131 COAP_REQUEST_CODE_IPATCH 0.07
132 COAP_RESPONSE_CODE_OK 2.00
133 COAP_RESPONSE_CODE_CREATED 2.01
134 COAP_RESPONSE_CODE_DELETED 2.02
135 COAP_RESPONSE_CODE_VALID 2.03
136 COAP_RESPONSE_CODE_CHANGED 2.04
137 COAP_RESPONSE_CODE_CONTENT 2.05
138 COAP_RESPONSE_CODE_CONTINUE 2.31
139 COAP_RESPONSE_CODE_BAD_REQUEST 4.00
140 COAP_RESPONSE_CODE_UNAUTHORIZED 4.01
141 COAP_RESPONSE_CODE_BAD_OPTION 4.02
142 COAP_RESPONSE_CODE_FORBIDDEN 4.03
143 COAP_RESPONSE_CODE_NOT_FOUND 4.04
144 COAP_RESPONSE_CODE_NOT_ALLOWED 4.05
145 COAP_RESPONSE_CODE_NOT_ACCEPTABLE 4.06
146 COAP_RESPONSE_CODE_INCOMPLETE 4.08
147 COAP_RESPONSE_CODE_CONFLICT 4.09
148 COAP_RESPONSE_CODE_PRECONDITION_FAILED 4.12
149 COAP_RESPONSE_CODE_REQUEST_TOO_LARGE 4.13
150 COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT 4.15
151 COAP_RESPONSE_CODE_UNPROCESSABLE 4.22
152 COAP_RESPONSE_CODE_TOO_MANY_REQUESTS 4.29
153 COAP_RESPONSE_CODE_INTERNAL_ERROR 5.00
154 COAP_RESPONSE_CODE_NOT_IMPLEMENTED 5.01
155 COAP_RESPONSE_CODE_BAD_GATEWAY 5.02
156 COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE 5.03
157 COAP_RESPONSE_CODE_GATEWAY_TIMEOUT 5.04
158 COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED 5.05
159 COAP_RESPONSE_CODE_HOP_LIMIT_REACHED 5.08
160 COAP_SIGNALING_CODE_CSM 7.01
161 COAP_SIGNALING_CODE_PING 7.02
162 COAP_SIGNALING_CODE_PONG 7.03
163 COAP_SIGNALING_CODE_RELEASE 7.04
164 COAP_SIGNALING_CODE_ABORT 7.05
165 and session is used to set up other default values.
167 Function: coap_pdu_init()
169 The coap_pdu_init() function does the same work as coap_new_pdu() but
171 gives the additional ability to define the default values for
172 message_id and max_size that coap_new_pdu() creates.
173 The message_id must be unique per request (which is not the same as the
175 token), and must not be reused within EXCHANGE_LIFETIME (usually 247
176 seconds). To automate this, the function coap_new_message_id(session)
177 should be called.
178 At the CoAP protocol level, requests and responses are matched by
180 message_id which is why it needs to be unique. At the application
181 level, for "separate" responses, the initial empty ACK response matches
182 the message_id of the request (handled by libcoap) but the actual
183 response has the same token as the request and this must be used for
184 the match. For "piggybacked" responses the token must still be used as
185 the valid match for request and response. and the message_id just
186 happens to match (but unsafe in case the server is sending back a
187 "separate" response).
188 The max_size parameter defines the maximum size of a PDU and is usually
190 determined by calling coap_session_max_pdu_size(session);
191 Function: coap_pdu_set_mid()
193 The coap_pdu_set_mid() function is used to set the message id mid in
195 the PDU pdu.
196 Function: coap_pdu_set_code()
198 The coap_pdu_set_code() function is used to set the code code in the
200 PDU pdu.
201 Function: coap_pdu_set_type()
203 The coap_pdu_set_type() function is used to set the type of the PDU
205 pdu.
206 NOTE: A PDU does not need to be created by the server application to
208 send back a response. The libcoap server logic creates the initial PDU
209 with COAP_EMPTY_CODE, appropriate message_id, matching token and
210 potentially some other options before calling the appropriate request
211 handler (See coap_register_request_handler(3)).
212
214 Function: coap_session_init_token()
215 The coap_session_init_token() function is used to initialize the
217 starting token of length for the session.
218 Function: coap_session_new_token()
220 The coap_session_new_token() function is used to obtain the next
222 available token of length for the session. Note that the same token
223 must be used for doing an observe cancellation that was used for doing
224 the observe registration. Otherwise tokens should be unique for each
225 request/response so that they can be correctly matched.
226 Function: coap_add_token()
228 The coap_add_token() function adds in the specified token’s data of
230 length length to the PDU pdu. The maximum length of the token is 8
231 bytes. Adding the token must be done before any options or data are
232 added. This function must only be called once per pdu, and must not be
233 called in the appropriate request handler.
234 If a token is not added, then the token in the PDU is zero length, but
236 still a valid token which is used for matching. The exception is an
237 empty ACK packet.
238 NOTE: The token provided by the client application may not be the same
240 as used internally by libcoap - for example when doing data
241 transmission where the body of data is spread over multiple payloads
242 (see coap_block(3)). However, when the data transfers complete, the
243 application will receive the corrected token in the response PDU.
244
246 The following is the current list of options with their numeric value
247 /*
249 * The C, U, and N flags indicate the properties
250 * Critical, Unsafe, and NoCacheKey, respectively.
251 * If U is set, then N has no meaning as per
252 * https://tools.ietf.org/html/rfc7252#section-5.10
253 * and is set to a -.
254 * Separately, R is for the options that can be repeated
255 *
256 * The least significant byte of the option is set as followed
257 * as per https://tools.ietf.org/html/rfc7252#section-5.4.6
258 *
259 * 0 1 2 3 4 5 6 7
260 * --+---+---+---+---+---+---+---+
261 * | NoCacheKey| U | C |
262 * --+---+---+---+---+---+---+---+
263 *
264 * https://tools.ietf.org/html/rfc8613#section-4 goes on to define E, I and U
265 * properties Encrypted and Integrity Protected, Integrity Protected Only and
266 * Unprotected respectively. Integrity Protected Only is not currently used.
267 *
268 * An Option is tagged with CUNREIU with any of the letters replaced with _ if
269 * not set, or - for N if U is set (see above) for aiding understanding of the
270 * Option.
271 */
272 COAP_OPTION_IF_MATCH 1 /* C__RE__, opaque, 0-8 B, RFC7252 */
274 COAP_OPTION_URI_HOST 3 /* CU-___U, String, 1-255 B, RFC7252 */
275 COAP_OPTION_ETAG 4 /* ___RE__, opaque, 1-8 B, RFC7252 */
276 COAP_OPTION_IF_NONE_MATCH 5 /* C___E__, empty, 0 B, RFC7252 */
277 COAP_OPTION_OBSERVE 6 /* _U-_E_U, empty/uint, 0 B/0-3 B, RFC7641 */
278 COAP_OPTION_URI_PORT 7 /* CU-___U, uint, 0-2 B, RFC7252 */
279 COAP_OPTION_LOCATION_PATH 8 /* ___RE__, String, 0-255 B, RFC7252 */
280 COAP_OPTION_OSCORE 9 /* C_____U, *, 0-255 B, RFC8613 */
281 COAP_OPTION_URI_PATH 11 /* CU-RE__, String, 0-255 B, RFC7252 */
282 COAP_OPTION_CONTENT_FORMAT 12 /* ____E__, uint, 0-2 B, RFC7252 */
283 /* COAP_OPTION_MAXAGE default 60 seconds if not set */
284 COAP_OPTION_MAXAGE 14 /* _U-_E_U, uint, 0-4 B, RFC7252 */
285 COAP_OPTION_URI_QUERY 15 /* CU-RE__, String, 1-255 B, RFC7252 */
286 COAP_OPTION_HOP_LIMIT 16 /* ______U, uint, 1 B, RFC8768 */
287 COAP_OPTION_ACCEPT 17 /* C___E__, uint, 0-2 B, RFC7252 */
288 COAP_OPTION_LOCATION_QUERY 20 /* ___RE__, String, 0-255 B, RFC7252 */
289 COAP_OPTION_BLOCK2 23 /* CU-_E_U, uint, 0-3 B, RFC7959 */
290 COAP_OPTION_BLOCK1 27 /* CU-_E_U, uint, 0-3 B, RFC7959 */
291 COAP_OPTION_SIZE2 28 /* __N_E_U, uint, 0-4 B, RFC7959 */
292 COAP_OPTION_PROXY_URI 35 /* CU-___U, String, 1-1034 B, RFC7252 */
293 COAP_OPTION_PROXY_SCHEME 39 /* CU-___U, String, 1-255 B, RFC7252 */
294 COAP_OPTION_SIZE1 60 /* __N_E_U, uint, 0-4 B, RFC7252 */
295 COAP_OPTION_ECHO 252 /* _N__E_U, opaque, 0-40 B, RFC9175 */
296 COAP_OPTION_NORESPONSE 258 /* _U-_E_U, uint, 0-1 B, RFC7967 */
297 COAP_OPTION_RTAG 292 /* ___RE_U, opaque, 0-8 B, RFC9175 */
298 See FURTHER INFORMATION as to how to get the latest list.
300 Function: coap_new_optlist()
302 The coap_new_optlist() function returns a newly created optlist entry
304 of type coap_optlist_t*. The number specifies which CoAP option is to
305 be used, and is one of the COAP_OPTION_* definitions. The length is the
306 length of the data of the option, and data points to the content of the
307 option.
308 NOTE: Where possible, the option data needs to be stripped of leading
310 zeros (big endian) to reduce the amount of data needed in the PDU, as
311 well as in some cases the maximum data size of an option can be
312 exceeded if not stripped and hence be illegal. This is done by using
313 coap_encode_var_safe() or coap_encode_var_safe8().
314 Function: coap_insert_optlist()
316 The coap_insert_optlist() function adds the optlist entry onto the
318 optlist_chain and then sorts the optlist_chain before returning. The
319 initial optlist_chain entry needs to be set to NULL before this
320 function is first called. The coap_delete_optlist() function has to be
321 called to free off all the optlist_chain entries.
322 Function: coap_delete_optlist()
324 The coap_delete_optlist() function deletes and frees off all the
326 optlist entries in the optlist_chain.
327 Function: coap_add_optlist_pdu()
329 The coap_add_optlist_pdu() function sorts all of the entries in
331 optlist_chain into ascending option numeric order and adds all the
332 entries to the pdu. This function does not free off the entries in
333 optlist_chain. This function must be called after adding any token and
334 before adding in the payload data.
335 Function: coap_add_option()
337 The coap_add_option() function adds in the specified option of type
339 number with data of length length to the PDU pdu. It is important that
340 options are added to the pdu with number either being the same or
341 greater than the previous option number that was added.
342 NOTE: Where possible, the option data needs to be stripped of leading
344 zeros (big endian) to reduce the amount of data needed in the PDU, as
345 well as in some cases the maximum data size of an option can be
346 exceeded if not stripped and hence be illegal. This is done by using
347 coap_encode_var_safe() or coap_encode_var_safe8().
348 Function: coap_encode_var_safe()
350 The coap_encode_var_safe() function encodes value into buffer which has
352 a size of size in bytes. Normally, the buffer size should be at least
353 the sizeof(int) bytes unless you definitely know less space is
354 required.
355 Function: coap_encode_var_safe8()
357 The coap_encode_var_safe8() function encodes 8 byte value into buffer
359 which has a size of size in bytes. Normally, the buffer size should be
360 at least 8 bytes unless you definitely know less space is required.
361 Function: coap_split_path()
363 The coap_split_path() function splits up path of length length and
365 places the result in buffer which has a size of buflen with the nul
366 character separating each path component. buflen needs to be preset
367 with the size of buffer before the function call, and then buflen is
368 updated with the actual size of buffer used. The return value indicates
369 the number of components that individual COAP_OPTION_URI_PATH options
370 need to be created for.
371 Function: coap_split_query()
373 The coap_split_query() function splits up query of length length and
375 places the result in buffer which has a size of buflen with the nul
376 character separating each path component. buflen needs to be preset
377 with the size of buffer before the function call, and then buflen is
378 updated with the actual size of buffer used. The return value indicates
379 the number of components that individual COAP_OPTION_URI_QUERY options
380 need to be created for.
381
383 Most of the options are under the control of the applications, but the
384 following are primarily used internally by libcoap.
385 COAP_OPTION_BLOCK1 and COAP_OPTION_BLOCK2
387 These Block options are used when a large body needs to be split up
389 into multiple payloads. Following the introduction of
390 coap_context_set_block_mode(3), libcoap can internally handle the
391 setting of these options (see coap_block(3)). Applications can continue
392 to include these options to set hint block size values.
393 It is recommended that coap_context_set_block_mode(context,
395 COAP_BLOCK_USE_LIBCOAP|COAP_BLOCK_SINGLE_BODY) is used to reduce the
396 programming requirements for block handling within the applications.
397 COAP_OPTION_ECHO
399 This option can be set by the server application to indicate that the
401 state of the client’s freshness is confirmed. The libcoap client logic
402 will detect the use of the Echo option by the server and reflect back
403 the Echo value in the next request without involving the client
404 application. The opaque option Echo may be seen by the client
405 application.
406 COAP_OPTION_ETAG
408 This option is normally set by the server libcoap logic when sending
410 back multiple payloads so that the (libcoap logic) client can
411 re-assemble the correct body.
412 COAP_OPTION_HOP_LIMIT
414 When using proxy logic, the value of the Hop-Limit option is
416 decremented by one for each proxy hop. If the count decrements to zero,
417 then a 5.08 (Hop Limit Reached) error code is returned to the sender.
418 The initial count is 16, unless the client application sets its own
419 limit using the Hop-Limit option.
420 COAP_OPTION_RTAG
422 This option is set by the libcoap client logic when transmitting
424 multiple bodies with multiple payloads so that the (libcoap logic)
425 server can differentiate and re-assemble the correct body.
426 COAP_OPTION_SIZE1 and COAP_OPTION_SIZE2
428 These options are added by the libcoap logic to provide a size (Size1
430 by libcoap client logic, Size2 by libcoap server logic) indication to
431 the recipient of the size of the large body that is to be transferred.
432 See coap_block(3).
433
435 Function: coap_add_data()
436 The coap_add_data() function adds in the specified payload data of
438 length length to the PDU pdu. Adding the payload data must be done
439 after any token or options are added. This function must only be called
440 once per pdu.
441 Function: coap_add_data_blocked_response()
443 The coap_add_data_blocked_response() function adds in the appropriate
445 part of the payload data of length length to the PDU pdu. It should be
446 used as a direct replacement for coap_add_data() if it is possible that
447 the data will not fit into a single pdu. It also adds in the
448 appropriate CoAP options to handle Block-Wise transfer. This function
449 is usually used for a server’s GET / FETCH response. The request and
450 response are the same parameters for the registered GET / FETCH
451 resource handler. The media_type is for the format of the data and
452 maxage defines the lifetime of the response. If set to -1, then the
453 Max-Age option does not get included. This function must only be called
454 once per pdu. It is the responsibility of the client to recognize that
455 it has only received a part of the data and request the next block
456 (with the appropriate Block options) from the server. Returning the
457 next requested block is handled by this function.
458 NOTE: This function has been superseded by
460 coap_add_data_large_response(). See coap_block(3).
461
463 Function: coap_send()
464 The coap_send() function is used to initiate the transmission of the
466 pdu associated with the session. The caller must not access or delete
467 pdu after calling coap_send() - even if there is a return error.
468 NOTE: For request handlers, returning from the request handler will
470 cause the response PDU to be transmitted as appropriate and there is no
471 need to call coap_send() to do this.
472
474 The coap_new_pdu() and coap_pdu_init() function returns a newly created
475 PDU or NULL if there is a malloc or parameter failure.
476 The coap_new_optlist() function returns a newly created optlist or NULL
478 if there is a malloc failure.
479 The coap_add_token(), coap_insert_optlist(), coap_delete_optlist(),
481 coap_add_optlist_pdu() and coap_add_data() functions return 0 on
482 failure, 1 on success.
483 The coap_add_optlist() function returns either the length of the option
485 or 0 on failure.
486 The coap_encode_var_safe() function returns either the length of bytes
488 encoded (which can be 0 when encoding 0) or 0 on failure.
489 The coap_encode_var_safe8() function returns either the length of bytes
491 encoded (which can be 0 when encoding 0) or 0 on failure.
492 The coap_send() function returns the CoAP message ID on success or
494 COAP_INVALID_MID on failure.
495 The coap_split_path() and coap_split_query() functions return the
497 number of components found.
498
500 Setup PDU and Transmit
501 #include <coap3/coap.h>
503 static int
505 build_send_pdu(coap_context_t *context, coap_session_t *session,
506 uint8_t msgtype, uint8_t request_code, const char *uri, const char *query,
507 unsigned char *data, size_t length, int observe) {
508 coap_pdu_t *pdu;
510 uint8_t buf[1024];
511 size_t buflen;
512 uint8_t *sbuf = buf;
513 int res;
514 coap_optlist_t *optlist_chain = NULL;
515 /* Remove (void) definition if variable is used */
516 (void)context;
517 /* Create the pdu with the appropriate options */
519 pdu = coap_pdu_init(msgtype, request_code, coap_new_message_id(session),
520 coap_session_max_pdu_size(session));
521 if (!pdu)
522 return 0;
523 /*
525 * Create unique token for this request for handling unsolicited /
526 * delayed responses
527 */
528 coap_session_new_token(session, &buflen, buf);
529 if (!coap_add_token(pdu, buflen, buf)) {
530 coap_log(LOG_DEBUG, "cannot add token to request\n");
531 goto error;
532 }
533 if (uri) {
535 /* Add in the URI options */
536 buflen = sizeof(buf);
537 res = coap_split_path((const uint8_t*)uri, strlen(uri), sbuf, &buflen);
538 while (res--) {
539 if (!coap_insert_optlist(&optlist_chain,
540 coap_new_optlist(COAP_OPTION_URI_PATH,
541 coap_opt_length(sbuf), coap_opt_value(sbuf))))
542 goto error;
543 sbuf += coap_opt_size(sbuf);
544 }
545 }
546 if (query) {
548 /* Add in the QUERY options */
549 buflen = sizeof(buf);
550 res = coap_split_query((const uint8_t*)query, strlen(query), sbuf, &buflen);
551 while (res--) {
552 if (!coap_insert_optlist(&optlist_chain,
553 coap_new_optlist(COAP_OPTION_URI_QUERY,
554 coap_opt_length(sbuf), coap_opt_value(sbuf))))
555 goto error;
556 sbuf += coap_opt_size(sbuf);
557 }
558 }
559 if (request_code == COAP_REQUEST_GET && observe) {
561 /* Indicate that we want to observe this resource */
562 if (!coap_insert_optlist(&optlist_chain,
563 coap_new_optlist(COAP_OPTION_OBSERVE,
564 coap_encode_var_safe(buf, sizeof(buf),
565 COAP_OBSERVE_ESTABLISH), buf)
566 ))
567 goto error;
568 }
569 /* ... Other code / options etc. ... */
571 /* Add in all the options (after internal sorting) to the pdu */
573 if (!coap_add_optlist_pdu(pdu, &optlist_chain))
574 goto error;
575 if (data && length) {
577 /* Add in the specified data */
578 if (!coap_add_data(pdu, length, data))
579 goto error;
580 }
581 if (coap_send(session, pdu) == COAP_INVALID_MID)
583 goto error;
584 return 1;
585 error:
587 if (pdu)
589 coap_delete_pdu(pdu);
590 return 0;
591 }
593 Resource Request Handler Response PDU Update
595 #include <coap3/coap.h>
597 #include <stdio.h>
599 static void
601 hnd_get_time(coap_resource_t *resource, coap_session_t *session,
602 const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
603 unsigned char buf[40];
605 size_t len;
606 time_t now;
607 /* ... Additional analysis code for resource, request pdu etc. ... */
609 /* After analysis, generate a suitable response */
611 now = time(NULL);
613 if (query != NULL && coap_string_equal(query, coap_make_str_const("secs"))) {
615 /* Output secs since Jan 1 1970 */
616 len = snprintf((char *)buf, sizeof(buf), "%lu", now);
617 }
618 else {
619 /* Output human-readable time */
620 struct tm *tmp;
621 tmp = gmtime(&now);
622 if (!tmp) {
623 /* If 'now' is not valid */
624 coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
625 return;
626 }
627 len = strftime((char *)buf, sizeof(buf), "%b %d %H:%M:%S", tmp);
628 }
629 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
630 /*
631 * Invoke coap_add_data_large_response() to do all the hard work.
632 *
633 * Define the format - COAP_MEDIATYPE_TEXT_PLAIN - to add in
634 * Define how long this response is valid for (secs) - 1 - to add in.
635 * Etag Option added internally with unique value as param set to 0
636 *
637 * Observe Option added internally if needed within the function
638 * Block2 Option added internally if output too large
639 * Size2 Option added internally
640 */
641 coap_add_data_large_response(resource, session, request, response,
642 query, COAP_MEDIATYPE_TEXT_PLAIN, 1, 0,
643 len,
644 buf, NULL, NULL);
645 /*
646 * When request handler returns, the response pdu will get automatically
647 * sent, unless the pdu code is not updated and this is a NON or TCP based
648 * request.
649 */
650 }
652
654 coap_block(3), coap_observe(3), coap_pdu_access(3) and coap_resource(3)
655
657 See
658 "RFC7252: The Constrained Application Protocol (CoAP)"
660 "RFC7959: Block-Wise Transfers in the Constrained Application Protocol
662 (CoAP)"
663 "RFC9175: CoAP: Echo, Request-Tag, and Token Processing"
665 for further information.
667 See
669 https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#option-numbers
670 for the current set of defined CoAP Options.
671
673 Please report bugs on the mailing list for libcoap:
674 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
675 https://github.com/obgm/libcoap/issues
676
678 The libcoap project <libcoap-developers@lists.sourceforge.net>
679coap_pdu_setup 4.3.1 01/19/2023 COAP_PDU_SETUP(3)