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

NAME

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

SYNOPSIS

15       #include <coap3/coap.h>
16
17       coap_pdu_t *coap_new_pdu(coap_pdu_type_t type, coap_pdu_code_t code,
18       coap_session_t *session);
19
20       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
23       void coap_session_init_token(coap_session_t *session, size_t length,
24       const uint8_t *token);
25
26       void coap_session_new_token(coap_session_t *session, size_t *length,
27       uint8_t *token);
28
29       int coap_add_token(coap_pdu_t *pdu, size_t length, const uint8_t
30       *data);
31
32       coap_optlist_t *coap_new_optlist(uint16_t number, size_t length, const
33       uint8_t *data);
34
35       int coap_insert_optlist(coap_optlist_t **optlist_chain, coap_optlist_t
36       *optlist);
37
38       void coap_delete_optlist(coap_optlist_t *optlist_chain);
39
40       unsigned int coap_encode_var_safe(uint8_t *buffer, size_t size,
41       unsigned int value);
42
43       unsigned int coap_encode_var_safe8(uint8_t *buffer, size_t size,
44       uint64_t value);
45
46       int coap_add_optlist_pdu(coap_pdu_t *pdu, coap_optlist_t
47       **optlist_chain);
48
49       size_t coap_add_option(coap_pdu_t *pdu, uint16_t number, size_t length,
50       const uint8_t *data);
51
52       int coap_add_data(coap_pdu_t *pdu, size_t length, const uint8_t *data);
53
54       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
58       coap_mid_t coap_send(coap_session_t *session, coap_pdu_t *pdu);
59
60       int coap_split_path(const uint8_t *path, size_t length, uint8_t
61       *buffer, size_t *buflen);
62
63       int coap_split_query(const uint8_t *query, size_t length, uint8_t
64       *buffer, size_t *buflen);
65
66       void coap_pdu_set_mid(coap_pdu_t *pdu, coap_mid_t mid);
67
68       void coap_pdu_set_code(coap_pdu_t *pdu, coap_pdu_code_t code);
69
70       void coap_pdu_set_type(coap_pdu_t *pdu, coap_pdu_type_t type);
71
72       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

DESCRIPTION

78       The CoAP PDU is of the form
79
80       --header--|--optional token--|--optional options--|--optional payload--
81
82       The terminology used is taken mainly from
83       https://tools.ietf.org/html/rfc7252#section-1.2
84
85       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
90       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
94       Typically for clients, when creating a request, the PDU needs to be
95       created before filling it with the appropriate information.
96
97       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
106       For handling situations where the data to be transmitted does not fit
107       into a single packet, see coap_block(3).
108

PDU CREATE AND HEADER

110       Function: coap_new_pdu()
111
112       The coap_new_pdu() function returns a newly created PDU of type
113       coap_pdu_t.
114
115       The type is one of the following
116
117           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
122       The code is one of the following
123
124           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
166       and session is used to set up other default values.
167
168       Function: coap_pdu_init()
169
170       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
174       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
179       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
189       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
192       Function: coap_pdu_set_mid()
193
194       The coap_pdu_set_mid() function is used to set the message id mid in
195       the PDU pdu.
196
197       Function: coap_pdu_set_code()
198
199       The coap_pdu_set_code() function is used to set the code code in the
200       PDU pdu.
201
202       Function: coap_pdu_set_type()
203
204       The coap_pdu_set_type() function is used to set the type of the PDU
205       pdu.
206
207       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

PDU TOKEN

214       Function: coap_session_init_token()
215
216       The coap_session_init_token() function is used to initialize the
217       starting token of length for the session.
218
219       Function: coap_session_new_token()
220
221       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
227       Function: coap_add_token()
228
229       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
235       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
239       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

PDU OPTIONS

246       The following is the current list of options with their numeric value
247
248           /*
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
273           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
299       See FURTHER INFORMATION as to how to get the latest list.
300
301       Function: coap_new_optlist()
302
303       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
309       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
315       Function: coap_insert_optlist()
316
317       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
323       Function: coap_delete_optlist()
324
325       The coap_delete_optlist() function deletes and frees off all the
326       optlist entries in the optlist_chain.
327
328       Function: coap_add_optlist_pdu()
329
330       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
336       Function: coap_add_option()
337
338       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
343       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
349       Function: coap_encode_var_safe()
350
351       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
356       Function: coap_encode_var_safe8()
357
358       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
362       Function: coap_split_path()
363
364       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
372       Function: coap_split_query()
373
374       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

PDU OPTIONS - LIBCOAP HANDLING

383       Most of the options are under the control of the applications, but the
384       following are primarily used internally by libcoap.
385
386       COAP_OPTION_BLOCK1 and COAP_OPTION_BLOCK2
387
388       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
394       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
398       COAP_OPTION_ECHO
399
400       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
407       COAP_OPTION_ETAG
408
409       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
413       COAP_OPTION_HOP_LIMIT
414
415       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
421       COAP_OPTION_RTAG
422
423       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
427       COAP_OPTION_SIZE1 and COAP_OPTION_SIZE2
428
429       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

PDU PAYLOAD DATA

435       Function: coap_add_data()
436
437       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
442       Function: coap_add_data_blocked_response()
443
444       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
459       NOTE: This function has been superseded by
460       coap_add_data_large_response(). See coap_block(3).
461

PDU TRANSMIT

463       Function: coap_send()
464
465       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
469       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

RETURN VALUES

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
477       The coap_new_optlist() function returns a newly created optlist or NULL
478       if there is a malloc failure.
479
480       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
484       The coap_add_optlist() function returns either the length of the option
485       or 0 on failure.
486
487       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
490       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
493       The coap_send() function returns the CoAP message ID on success or
494       COAP_INVALID_MID on failure.
495
496       The coap_split_path() and coap_split_query() functions return the
497       number of components found.
498

EXAMPLES

500       Setup PDU and Transmit
501
502           #include <coap3/coap.h>
503
504           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
509             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
518             /* 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
524             /*
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
534             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
547             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
560             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
570             /* ... Other code / options etc. ... */
571
572             /* Add in all the options (after internal sorting) to the pdu */
573             if (!coap_add_optlist_pdu(pdu, &optlist_chain))
574               goto error;
575
576             if (data && length) {
577               /* Add in the specified data */
578               if (!coap_add_data(pdu, length, data))
579                 goto error;
580             }
581
582             if (coap_send(session, pdu) == COAP_INVALID_MID)
583               goto error;
584             return 1;
585
586           error:
587
588             if (pdu)
589               coap_delete_pdu(pdu);
590             return 0;
591
592           }
593
594       Resource Request Handler Response PDU Update
595
596           #include <coap3/coap.h>
597
598           #include <stdio.h>
599
600           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
604             unsigned char buf[40];
605             size_t len;
606             time_t now;
607
608             /* ... Additional analysis code for resource, request pdu etc.  ... */
609
610             /* After analysis, generate a suitable response */
611
612             now = time(NULL);
613
614             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
651           }
652

SEE ALSO

654       coap_block(3), coap_observe(3), coap_pdu_access(3) and coap_resource(3)
655

FURTHER INFORMATION

657       See
658
659       "RFC7252: The Constrained Application Protocol (CoAP)"
660
661       "RFC7959: Block-Wise Transfers in the Constrained Application Protocol
662       (CoAP)"
663
664       "RFC9175: CoAP: Echo, Request-Tag, and Token Processing"
665
666       for further information.
667
668       See
669       https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#option-numbers
670       for the current set of defined CoAP Options.
671

BUGS

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

AUTHORS

678       The libcoap project <libcoap-developers@lists.sourceforge.net>
679
680
681
682coap_pdu_setup 4.3.1              11/24/2022                 COAP_PDU_SETUP(3)
Impressum