1 /*
2 * Copyright (c) 2016, The OpenThread Authors.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * 3. Neither the name of the copyright holder nor the
13 * names of its contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28
29 /**
30 * @file
31 * @brief
32 * This file defines the top-level functions for the OpenThread CoAP implementation.
33 */
34
35 #ifndef OPENTHREAD_COAP_H_
36 #define OPENTHREAD_COAP_H_
37
38 #include <stdint.h>
39
40 #include <openthread/ip6.h>
41 #include <openthread/message.h>
42
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47 /**
48 * @addtogroup api-coap
49 *
50 * @brief
51 * This module includes functions that control CoAP communication.
52 *
53 * The functions in this module are available when CoAP API feature (`OPENTHREAD_CONFIG_COAP_API_ENABLE`) is enabled.
54 *
55 * @{
56 *
57 */
58
59 #define OT_DEFAULT_COAP_PORT 5683 ///< Default CoAP port, as specified in RFC 7252
60
61 #define OT_COAP_DEFAULT_TOKEN_LENGTH 2 ///< Default token length.
62
63 #define OT_COAP_MAX_TOKEN_LENGTH 8 ///< Max token length as specified (RFC 7252).
64
65 #define OT_COAP_MAX_RETRANSMIT 20 ///< Max retransmit supported by OpenThread.
66
67 #define OT_COAP_MIN_ACK_TIMEOUT 1000 ///< Minimal ACK timeout in milliseconds supported by OpenThread.
68
69 /**
70 * CoAP Type values (2 bit unsigned integer).
71 *
72 */
73 typedef enum otCoapType
74 {
75 OT_COAP_TYPE_CONFIRMABLE = 0, ///< Confirmable
76 OT_COAP_TYPE_NON_CONFIRMABLE = 1, ///< Non-confirmable
77 OT_COAP_TYPE_ACKNOWLEDGMENT = 2, ///< Acknowledgment
78 OT_COAP_TYPE_RESET = 3, ///< Reset
79 } otCoapType;
80
81 /**
82 * Helper macro to define CoAP Code values.
83 *
84 */
85 #define OT_COAP_CODE(c, d) ((((c)&0x7) << 5) | ((d)&0x1f))
86
87 /**
88 * CoAP Code values.
89 *
90 */
91 typedef enum otCoapCode
92 {
93 OT_COAP_CODE_EMPTY = OT_COAP_CODE(0, 0), ///< Empty message code
94 OT_COAP_CODE_GET = OT_COAP_CODE(0, 1), ///< Get
95 OT_COAP_CODE_POST = OT_COAP_CODE(0, 2), ///< Post
96 OT_COAP_CODE_PUT = OT_COAP_CODE(0, 3), ///< Put
97 OT_COAP_CODE_DELETE = OT_COAP_CODE(0, 4), ///< Delete
98
99 OT_COAP_CODE_RESPONSE_MIN = OT_COAP_CODE(2, 0), ///< 2.00
100 OT_COAP_CODE_CREATED = OT_COAP_CODE(2, 1), ///< Created
101 OT_COAP_CODE_DELETED = OT_COAP_CODE(2, 2), ///< Deleted
102 OT_COAP_CODE_VALID = OT_COAP_CODE(2, 3), ///< Valid
103 OT_COAP_CODE_CHANGED = OT_COAP_CODE(2, 4), ///< Changed
104 OT_COAP_CODE_CONTENT = OT_COAP_CODE(2, 5), ///< Content
105 OT_COAP_CODE_CONTINUE = OT_COAP_CODE(2, 31), ///< RFC7959 Continue
106
107 OT_COAP_CODE_BAD_REQUEST = OT_COAP_CODE(4, 0), ///< Bad Request
108 OT_COAP_CODE_UNAUTHORIZED = OT_COAP_CODE(4, 1), ///< Unauthorized
109 OT_COAP_CODE_BAD_OPTION = OT_COAP_CODE(4, 2), ///< Bad Option
110 OT_COAP_CODE_FORBIDDEN = OT_COAP_CODE(4, 3), ///< Forbidden
111 OT_COAP_CODE_NOT_FOUND = OT_COAP_CODE(4, 4), ///< Not Found
112 OT_COAP_CODE_METHOD_NOT_ALLOWED = OT_COAP_CODE(4, 5), ///< Method Not Allowed
113 OT_COAP_CODE_NOT_ACCEPTABLE = OT_COAP_CODE(4, 6), ///< Not Acceptable
114 OT_COAP_CODE_REQUEST_INCOMPLETE = OT_COAP_CODE(4, 8), ///< RFC7959 Request Entity Incomplete
115 OT_COAP_CODE_PRECONDITION_FAILED = OT_COAP_CODE(4, 12), ///< Precondition Failed
116 OT_COAP_CODE_REQUEST_TOO_LARGE = OT_COAP_CODE(4, 13), ///< Request Entity Too Large
117 OT_COAP_CODE_UNSUPPORTED_FORMAT = OT_COAP_CODE(4, 15), ///< Unsupported Content-Format
118
119 OT_COAP_CODE_INTERNAL_ERROR = OT_COAP_CODE(5, 0), ///< Internal Server Error
120 OT_COAP_CODE_NOT_IMPLEMENTED = OT_COAP_CODE(5, 1), ///< Not Implemented
121 OT_COAP_CODE_BAD_GATEWAY = OT_COAP_CODE(5, 2), ///< Bad Gateway
122 OT_COAP_CODE_SERVICE_UNAVAILABLE = OT_COAP_CODE(5, 3), ///< Service Unavailable
123 OT_COAP_CODE_GATEWAY_TIMEOUT = OT_COAP_CODE(5, 4), ///< Gateway Timeout
124 OT_COAP_CODE_PROXY_NOT_SUPPORTED = OT_COAP_CODE(5, 5), ///< Proxying Not Supported
125 } otCoapCode;
126
127 /**
128 * CoAP Option Numbers
129 */
130 typedef enum otCoapOptionType
131 {
132 OT_COAP_OPTION_IF_MATCH = 1, ///< If-Match
133 OT_COAP_OPTION_URI_HOST = 3, ///< Uri-Host
134 OT_COAP_OPTION_E_TAG = 4, ///< ETag
135 OT_COAP_OPTION_IF_NONE_MATCH = 5, ///< If-None-Match
136 OT_COAP_OPTION_OBSERVE = 6, ///< Observe [RFC7641]
137 OT_COAP_OPTION_URI_PORT = 7, ///< Uri-Port
138 OT_COAP_OPTION_LOCATION_PATH = 8, ///< Location-Path
139 OT_COAP_OPTION_URI_PATH = 11, ///< Uri-Path
140 OT_COAP_OPTION_CONTENT_FORMAT = 12, ///< Content-Format
141 OT_COAP_OPTION_MAX_AGE = 14, ///< Max-Age
142 OT_COAP_OPTION_URI_QUERY = 15, ///< Uri-Query
143 OT_COAP_OPTION_ACCEPT = 17, ///< Accept
144 OT_COAP_OPTION_LOCATION_QUERY = 20, ///< Location-Query
145 OT_COAP_OPTION_BLOCK2 = 23, ///< Block2 (RFC7959)
146 OT_COAP_OPTION_BLOCK1 = 27, ///< Block1 (RFC7959)
147 OT_COAP_OPTION_SIZE2 = 28, ///< Size2 (RFC7959)
148 OT_COAP_OPTION_PROXY_URI = 35, ///< Proxy-Uri
149 OT_COAP_OPTION_PROXY_SCHEME = 39, ///< Proxy-Scheme
150 OT_COAP_OPTION_SIZE1 = 60, ///< Size1
151 } otCoapOptionType;
152
153 /**
154 * Represents a CoAP option.
155 *
156 */
157 typedef struct otCoapOption
158 {
159 uint16_t mNumber; ///< Option Number
160 uint16_t mLength; ///< Option Length
161 } otCoapOption;
162
163 /**
164 * Acts as an iterator for CoAP options
165 *
166 */
167 typedef struct otCoapOptionIterator
168 {
169 const otMessage *mMessage; ///< CoAP message
170 otCoapOption mOption; ///< CoAP message option
171 uint16_t mNextOptionOffset; ///< Byte offset of next option
172 } otCoapOptionIterator;
173
174 /**
175 * CoAP Content Format codes. The full list is documented at
176 * https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats
177 */
178 typedef enum otCoapOptionContentFormat
179 {
180 /**
181 * text/plain; charset=utf-8: [RFC2046][RFC3676][RFC5147]
182 */
183 OT_COAP_OPTION_CONTENT_FORMAT_TEXT_PLAIN = 0,
184
185 /**
186 * application/cose; cose-type="cose-encrypt0": [RFC8152]
187 */
188 OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT0 = 16,
189
190 /**
191 * application/cose; cose-type="cose-mac0": [RFC8152]
192 */
193 OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC0 = 17,
194
195 /**
196 * application/cose; cose-type="cose-sign1": [RFC8152]
197 */
198 OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN1 = 18,
199
200 /**
201 * application/link-format: [RFC6690]
202 */
203 OT_COAP_OPTION_CONTENT_FORMAT_LINK_FORMAT = 40,
204
205 /**
206 * application/xml: [RFC3023]
207 */
208 OT_COAP_OPTION_CONTENT_FORMAT_XML = 41,
209
210 /**
211 * application/octet-stream: [RFC2045][RFC2046]
212 */
213 OT_COAP_OPTION_CONTENT_FORMAT_OCTET_STREAM = 42,
214
215 /**
216 * application/exi:
217 * ["Efficient XML Interchange (EXI) Format 1.0 (Second Edition)", February 2014]
218 */
219 OT_COAP_OPTION_CONTENT_FORMAT_EXI = 47,
220
221 /**
222 * application/json: [RFC7159]
223 */
224 OT_COAP_OPTION_CONTENT_FORMAT_JSON = 50,
225
226 /**
227 * application/json-patch+json: [RFC6902]
228 */
229 OT_COAP_OPTION_CONTENT_FORMAT_JSON_PATCH_JSON = 51,
230
231 /**
232 * application/merge-patch+json: [RFC7396]
233 */
234 OT_COAP_OPTION_CONTENT_FORMAT_MERGE_PATCH_JSON = 52,
235
236 /**
237 * application/cbor: [RFC7049]
238 */
239 OT_COAP_OPTION_CONTENT_FORMAT_CBOR = 60,
240
241 /**
242 * application/cwt: [RFC8392]
243 */
244 OT_COAP_OPTION_CONTENT_FORMAT_CWT = 61,
245
246 /**
247 * application/cose; cose-type="cose-encrypt": [RFC8152]
248 */
249 OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT = 96,
250
251 /**
252 * application/cose; cose-type="cose-mac": [RFC8152]
253 */
254 OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC = 97,
255
256 /**
257 * application/cose; cose-type="cose-sign": [RFC8152]
258 */
259 OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN = 98,
260
261 /**
262 * application/cose-key: [RFC8152]
263 */
264 OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY = 101,
265
266 /**
267 * application/cose-key-set: [RFC8152]
268 */
269 OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY_SET = 102,
270
271 /**
272 * application/senml+json: [RFC8428]
273 */
274 OT_COAP_OPTION_CONTENT_FORMAT_SENML_JSON = 110,
275
276 /**
277 * application/sensml+json: [RFC8428]
278 */
279 OT_COAP_OPTION_CONTENT_FORMAT_SENSML_JSON = 111,
280
281 /**
282 * application/senml+cbor: [RFC8428]
283 */
284 OT_COAP_OPTION_CONTENT_FORMAT_SENML_CBOR = 112,
285
286 /**
287 * application/sensml+cbor: [RFC8428]
288 */
289 OT_COAP_OPTION_CONTENT_FORMAT_SENSML_CBOR = 113,
290
291 /**
292 * application/senml-exi: [RFC8428]
293 */
294 OT_COAP_OPTION_CONTENT_FORMAT_SENML_EXI = 114,
295
296 /**
297 * application/sensml-exi: [RFC8428]
298 */
299 OT_COAP_OPTION_CONTENT_FORMAT_SENSML_EXI = 115,
300
301 /**
302 * application/coap-group+json: [RFC7390]
303 */
304 OT_COAP_OPTION_CONTENT_FORMAT_COAP_GROUP_JSON = 256,
305
306 /**
307 * application/senml+xml: [RFC8428]
308 */
309 OT_COAP_OPTION_CONTENT_FORMAT_SENML_XML = 310,
310
311 /**
312 * application/sensml+xml: [RFC8428]
313 */
314 OT_COAP_OPTION_CONTENT_FORMAT_SENSML_XML = 311
315 } otCoapOptionContentFormat;
316
317 /**
318 * CoAP Block Size Exponents
319 */
320 typedef enum otCoapBlockSzx
321 {
322 OT_COAP_OPTION_BLOCK_SZX_16 = 0,
323 OT_COAP_OPTION_BLOCK_SZX_32 = 1,
324 OT_COAP_OPTION_BLOCK_SZX_64 = 2,
325 OT_COAP_OPTION_BLOCK_SZX_128 = 3,
326 OT_COAP_OPTION_BLOCK_SZX_256 = 4,
327 OT_COAP_OPTION_BLOCK_SZX_512 = 5,
328 OT_COAP_OPTION_BLOCK_SZX_1024 = 6
329 } otCoapBlockSzx;
330
331 /**
332 * Pointer is called when a CoAP response is received or on the request timeout.
333 *
334 * @param[in] aContext A pointer to application-specific context.
335 * @param[in] aMessage A pointer to the message buffer containing the response. NULL if no response was received.
336 * @param[in] aMessageInfo A pointer to the message info for @p aMessage. NULL if no response was received.
337 * @param[in] aResult A result of the CoAP transaction.
338 *
339 * @retval OT_ERROR_NONE A response was received successfully.
340 * @retval OT_ERROR_ABORT A CoAP transaction was reset by peer.
341 * @retval OT_ERROR_RESPONSE_TIMEOUT No response or acknowledgment received during timeout period.
342 *
343 */
344 typedef void (*otCoapResponseHandler)(void *aContext,
345 otMessage *aMessage,
346 const otMessageInfo *aMessageInfo,
347 otError aResult);
348
349 /**
350 * Pointer is called when a CoAP request with a given Uri-Path is received.
351 *
352 * @param[in] aContext A pointer to arbitrary context information.
353 * @param[in] aMessage A pointer to the message.
354 * @param[in] aMessageInfo A pointer to the message info for @p aMessage.
355 *
356 */
357 typedef void (*otCoapRequestHandler)(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo);
358
359 /**
360 * Pointer is called when a CoAP message with a block-wise transfer option is received.
361 *
362 * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
363 * is enabled.
364 *
365 * @param[in] aContext A pointer to application-specific context.
366 * @param[in] aBlock A pointer to the block segment.
367 * @param[in] aPosition The position of @p aBlock in a sequence in bytes.
368 * @param[in] aBlockLength The length of the block segment in bytes.
369 * @param[in] aMore Flag if more block segments are following.
370 * @param[in] aTotalLength The total length in bytes of the transferred information (indicated by a Size1 or Size2
371 * option).
372 *
373 * @retval OT_ERROR_NONE Block segment was stored successfully.
374 * @retval OT_ERROR_NO_BUFS No more memory to store blocks.
375 * @retval OT_ERROR_NO_FRAME_RECEIVED Block segment missing.
376 *
377 */
378 typedef otError (*otCoapBlockwiseReceiveHook)(void *aContext,
379 const uint8_t *aBlock,
380 uint32_t aPosition,
381 uint16_t aBlockLength,
382 bool aMore,
383 uint32_t aTotalLength);
384
385 /**
386 * Pointer is called before the next block in a block-wise transfer is sent.
387 *
388 * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
389 * is enabled.
390 *
391 * @param[in] aContext A pointer to application-specific context.
392 * @param[in,out] aBlock A pointer to where the block segment can be written to.
393 * @param[in] aPosition The position in a sequence from which to obtain the block segment.
394 * @param[in,out] aBlockLength On entry, the maximum block segment length in bytes.
395 * @param[out] aMore A pointer to the flag if more block segments will follow.
396 *
397 * @warning By changing the value of aBlockLength, the block size of the whole exchange is
398 * renegotiated. It is recommended to do this after the first block has been received as
399 * later changes could cause problems with other CoAP implementations.
400 *
401 * @retval OT_ERROR_NONE No error occurred.
402 * @retval OT_ERROR_INVALID_ARGS Block at @p aPosition does not exist.
403 *
404 */
405 typedef otError (*otCoapBlockwiseTransmitHook)(void *aContext,
406 uint8_t *aBlock,
407 uint32_t aPosition,
408 uint16_t *aBlockLength,
409 bool *aMore);
410
411 /**
412 * Represents a CoAP resource.
413 *
414 */
415 typedef struct otCoapResource
416 {
417 const char *mUriPath; ///< The URI Path string
418 otCoapRequestHandler mHandler; ///< The callback for handling a received request
419 void *mContext; ///< Application-specific context
420 struct otCoapResource *mNext; ///< The next CoAP resource in the list
421 } otCoapResource;
422
423 /**
424 * Represents a CoAP resource with block-wise transfer.
425 *
426 */
427 typedef struct otCoapBlockwiseResource
428 {
429 const char *mUriPath; ///< The URI Path string
430 otCoapRequestHandler mHandler; ///< The callback for handling a received request
431
432 /** The callback for handling incoming block-wise transfer.
433 * This callback is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE
434 * configuration is enabled.
435 */
436 otCoapBlockwiseReceiveHook mReceiveHook;
437
438 /** The callback for handling outgoing block-wise transfer.
439 * This callback is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE
440 * configuration is enabled.
441 */
442 otCoapBlockwiseTransmitHook mTransmitHook;
443 void *mContext; ///< Application-specific context
444 struct otCoapBlockwiseResource *mNext; ///< The next CoAP resource in the list
445 } otCoapBlockwiseResource;
446
447 /**
448 * Represents the CoAP transmission parameters.
449 *
450 * @note mAckTimeout * ((2 ** (mMaxRetransmit + 1)) - 1) * (mAckRandomFactorNumerator / mAckRandomFactorDenominator)
451 * must not exceed what can be represented by a uint32_t (0xffffffff). This limitation allows OpenThread to
452 * avoid 64-bit arithmetic.
453 *
454 */
455 typedef struct otCoapTxParameters
456 {
457 /**
458 * Minimum spacing before first retransmission when ACK is not received, in milliseconds (RFC7252 default value is
459 * 2000ms).
460 *
461 */
462 uint32_t mAckTimeout;
463
464 /**
465 * Numerator of ACK_RANDOM_FACTOR used to calculate maximum spacing before first retransmission when ACK is not
466 * received (RFC7252 default value of ACK_RANDOM_FACTOR is 1.5; must not be decreased below 1).
467 *
468 */
469 uint8_t mAckRandomFactorNumerator;
470
471 /**
472 * Denominator of ACK_RANDOM_FACTOR used to calculate maximum spacing before first retransmission when ACK is not
473 * received (RFC7252 default value of ACK_RANDOM_FACTOR is 1.5; must not be decreased below 1).
474 *
475 */
476 uint8_t mAckRandomFactorDenominator;
477
478 /**
479 * Maximum number of retransmissions for CoAP Confirmable messages (RFC7252 default value is 4).
480 *
481 */
482 uint8_t mMaxRetransmit;
483 } otCoapTxParameters;
484
485 /**
486 * Initializes the CoAP header.
487 *
488 * @param[in,out] aMessage A pointer to the CoAP message to initialize.
489 * @param[in] aType CoAP message type.
490 * @param[in] aCode CoAP message code.
491 *
492 */
493 void otCoapMessageInit(otMessage *aMessage, otCoapType aType, otCoapCode aCode);
494
495 /**
496 * Initializes a response message.
497 *
498 * @note Both message ID and token are set according to @p aRequest.
499 *
500 * @param[in,out] aResponse A pointer to the CoAP response message.
501 * @param[in] aRequest A pointer to the CoAP request message.
502 * @param[in] aType CoAP message type.
503 * @param[in] aCode CoAP message code.
504 *
505 * @retval OT_ERROR_NONE Successfully initialized the response message.
506 * @retval OT_ERROR_NO_BUFS Insufficient message buffers available to initialize the response message.
507 *
508 */
509 otError otCoapMessageInitResponse(otMessage *aResponse, const otMessage *aRequest, otCoapType aType, otCoapCode aCode);
510
511 /**
512 * Sets the Token value and length in a header.
513 *
514 * @param[in,out] aMessage A pointer to the CoAP message.
515 * @param[in] aToken A pointer to the Token value.
516 * @param[in] aTokenLength The Length of @p aToken.
517 *
518 * @retval OT_ERROR_NONE Successfully set the Token value.
519 * @retval OT_ERROR_NO_BUFS Insufficient buffers to set the Token value.
520 *
521 */
522 otError otCoapMessageSetToken(otMessage *aMessage, const uint8_t *aToken, uint8_t aTokenLength);
523
524 /**
525 * Sets the Token length and randomizes its value.
526 *
527 * @param[in,out] aMessage A pointer to the CoAP message.
528 * @param[in] aTokenLength The Length of a Token to set.
529 *
530 */
531 void otCoapMessageGenerateToken(otMessage *aMessage, uint8_t aTokenLength);
532
533 /**
534 * Appends the Content Format CoAP option as specified in
535 * https://tools.ietf.org/html/rfc7252#page-92. This *must* be called before
536 * setting otCoapMessageSetPayloadMarker if a payload is to be included in the
537 * message.
538 *
539 * The function is a convenience wrapper around otCoapMessageAppendUintOption,
540 * and if the desired format type code isn't listed in otCoapOptionContentFormat,
541 * this base function should be used instead.
542 *
543 * @param[in,out] aMessage A pointer to the CoAP message.
544 * @param[in] aContentFormat One of the content formats listed in
545 * otCoapOptionContentFormat above.
546 *
547 * @retval OT_ERROR_NONE Successfully appended the option.
548 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
549 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
550 *
551 */
552 otError otCoapMessageAppendContentFormatOption(otMessage *aMessage, otCoapOptionContentFormat aContentFormat);
553
554 /**
555 * Appends a CoAP option in a header.
556 *
557 * @param[in,out] aMessage A pointer to the CoAP message.
558 * @param[in] aNumber The CoAP Option number.
559 * @param[in] aLength The CoAP Option length.
560 * @param[in] aValue A pointer to the CoAP value.
561 *
562 * @retval OT_ERROR_NONE Successfully appended the option.
563 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
564 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
565 *
566 */
567 otError otCoapMessageAppendOption(otMessage *aMessage, uint16_t aNumber, uint16_t aLength, const void *aValue);
568
569 /**
570 * Appends an unsigned integer CoAP option as specified in
571 * https://tools.ietf.org/html/rfc7252#section-3.2
572 *
573 * @param[in,out] aMessage A pointer to the CoAP message.
574 * @param[in] aNumber The CoAP Option number.
575 * @param[in] aValue The CoAP Option unsigned integer value.
576 *
577 * @retval OT_ERROR_NONE Successfully appended the option.
578 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
579 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
580 *
581 * @see otCoapMessageGetOptionUintValue
582 */
583 otError otCoapMessageAppendUintOption(otMessage *aMessage, uint16_t aNumber, uint32_t aValue);
584
585 /**
586 * Appends an Observe option.
587 *
588 * @param[in,out] aMessage A pointer to the CoAP message.
589 * @param[in] aObserve Observe field value.
590 *
591 * @retval OT_ERROR_NONE Successfully appended the option.
592 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
593 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
594 *
595 */
596 otError otCoapMessageAppendObserveOption(otMessage *aMessage, uint32_t aObserve);
597
598 /**
599 * Appends a Uri-Path option.
600 *
601 * @param[in,out] aMessage A pointer to the CoAP message.
602 * @param[in] aUriPath A pointer to a NULL-terminated string.
603 *
604 * @retval OT_ERROR_NONE Successfully appended the option.
605 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
606 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
607 *
608 */
609 otError otCoapMessageAppendUriPathOptions(otMessage *aMessage, const char *aUriPath);
610
611 /**
612 * Appends a Uri-Query option.
613 *
614 * @param[in,out] aMessage A pointer to the CoAP message.
615 * @param[in] aUriQuery A pointer to a NULL-terminated string.
616 *
617 * @retval OT_ERROR_NONE Successfully appended the option.
618 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
619 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
620 *
621 */
622 otError otCoapMessageAppendUriQueryOptions(otMessage *aMessage, const char *aUriQuery);
623
624 /**
625 * Converts a CoAP Block option SZX field to the actual block size
626 *
627 * @param[in] aSize Block size exponent.
628 *
629 * @returns The actual size exponent value.
630 *
631 */
632 uint16_t otCoapBlockSizeFromExponent(otCoapBlockSzx aSize);
633
634 /**
635 * Appends a Block2 option
636 *
637 * @param[in,out] aMessage A pointer to the CoAP message.
638 * @param[in] aNum Current block number.
639 * @param[in] aMore Boolean to indicate more blocks are to be sent.
640 * @param[in] aSize Block Size Exponent.
641 *
642 * @retval OT_ERROR_NONE Successfully appended the option.
643 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
644 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
645 *
646 */
647 otError otCoapMessageAppendBlock2Option(otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSzx aSize);
648
649 /**
650 * Appends a Block1 option
651 *
652 * @param[in,out] aMessage A pointer to the CoAP message.
653 * @param[in] aNum Current block number.
654 * @param[in] aMore Boolean to indicate more blocks are to be sent.
655 * @param[in] aSize Block Size Exponent.
656 *
657 * @retval OT_ERROR_NONE Successfully appended the option.
658 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
659 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
660 *
661 */
662 otError otCoapMessageAppendBlock1Option(otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSzx aSize);
663
664 /**
665 * Appends a Proxy-Uri option.
666 *
667 * @param[in,out] aMessage A pointer to the CoAP message.
668 * @param[in] aUriPath A pointer to a NULL-terminated string.
669 *
670 * @retval OT_ERROR_NONE Successfully appended the option.
671 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
672 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
673 *
674 */
675 otError otCoapMessageAppendProxyUriOption(otMessage *aMessage, const char *aUriPath);
676
677 /**
678 * Appends a Max-Age option.
679 *
680 * @param[in,out] aMessage A pointer to the CoAP message.
681 * @param[in] aMaxAge The Max-Age value.
682 *
683 * @retval OT_ERROR_NONE Successfully appended the option.
684 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
685 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
686 *
687 */
688 otError otCoapMessageAppendMaxAgeOption(otMessage *aMessage, uint32_t aMaxAge);
689
690 /**
691 * Appends a single Uri-Query option.
692 *
693 * @param[in,out] aMessage A pointer to the CoAP message.
694 * @param[in] aUriQuery A pointer to NULL-terminated string, which should contain a single key=value pair.
695 *
696 * @retval OT_ERROR_NONE Successfully appended the option.
697 * @retval OT_ERROR_INVALID_ARGS The option type is not equal or greater than the last option type.
698 * @retval OT_ERROR_NO_BUFS The option length exceeds the buffer size.
699 */
700 otError otCoapMessageAppendUriQueryOption(otMessage *aMessage, const char *aUriQuery);
701
702 /**
703 * Adds Payload Marker indicating beginning of the payload to the CoAP header.
704 *
705 * @param[in,out] aMessage A pointer to the CoAP message.
706 *
707 * @retval OT_ERROR_NONE Payload Marker successfully added.
708 * @retval OT_ERROR_NO_BUFS Header Payload Marker exceeds the buffer size.
709 *
710 */
711 otError otCoapMessageSetPayloadMarker(otMessage *aMessage);
712
713 /**
714 * Returns the Type value.
715 *
716 * @param[in] aMessage A pointer to the CoAP message.
717 *
718 * @returns The Type value.
719 *
720 */
721 otCoapType otCoapMessageGetType(const otMessage *aMessage);
722
723 /**
724 * Returns the Code value.
725 *
726 * @param[in] aMessage A pointer to the CoAP message.
727 *
728 * @returns The Code value.
729 *
730 */
731 otCoapCode otCoapMessageGetCode(const otMessage *aMessage);
732
733 /**
734 * Sets the Code value.
735 *
736 * @param[in,out] aMessage A pointer to the CoAP message to initialize.
737 * @param[in] aCode CoAP message code.
738 *
739 */
740 void otCoapMessageSetCode(otMessage *aMessage, otCoapCode aCode);
741
742 /**
743 * Returns the CoAP Code as human readable string.
744 *
745 * @param[in] aMessage A pointer to the CoAP message.
746 *
747 * @ returns The CoAP Code as string.
748 *
749 */
750 const char *otCoapMessageCodeToString(const otMessage *aMessage);
751
752 /**
753 * Returns the Message ID value.
754 *
755 * @param[in] aMessage A pointer to the CoAP message.
756 *
757 * @returns The Message ID value.
758 *
759 */
760 uint16_t otCoapMessageGetMessageId(const otMessage *aMessage);
761
762 /**
763 * Returns the Token length.
764 *
765 * @param[in] aMessage A pointer to the CoAP message.
766 *
767 * @returns The Token length.
768 *
769 */
770 uint8_t otCoapMessageGetTokenLength(const otMessage *aMessage);
771
772 /**
773 * Returns a pointer to the Token value.
774 *
775 * @param[in] aMessage A pointer to the CoAP message.
776 *
777 * @returns A pointer to the Token value.
778 *
779 */
780 const uint8_t *otCoapMessageGetToken(const otMessage *aMessage);
781
782 /**
783 * Initialises an iterator for the options in the given message.
784 *
785 * @param[in,out] aIterator A pointer to the CoAP message option iterator.
786 * @param[in] aMessage A pointer to the CoAP message.
787 *
788 * @retval OT_ERROR_NONE Successfully initialised.
789 * @retval OT_ERROR_PARSE Message state is inconsistent.
790 *
791 */
792 otError otCoapOptionIteratorInit(otCoapOptionIterator *aIterator, const otMessage *aMessage);
793
794 /**
795 * Returns a pointer to the first option matching the specified option number.
796 *
797 * @param[in] aIterator A pointer to the CoAP message option iterator.
798 * @param[in] aOption The option number sought.
799 *
800 * @returns A pointer to the first matching option. If no matching option is present NULL pointer is returned.
801 *
802 */
803 const otCoapOption *otCoapOptionIteratorGetFirstOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption);
804
805 /**
806 * Returns a pointer to the first option.
807 *
808 * @param[in,out] aIterator A pointer to the CoAP message option iterator.
809 *
810 * @returns A pointer to the first option. If no option is present NULL pointer is returned.
811 *
812 */
813 const otCoapOption *otCoapOptionIteratorGetFirstOption(otCoapOptionIterator *aIterator);
814
815 /**
816 * Returns a pointer to the next option matching the specified option number.
817 *
818 * @param[in] aIterator A pointer to the CoAP message option iterator.
819 * @param[in] aOption The option number sought.
820 *
821 * @returns A pointer to the next matching option. If no further matching option is present NULL pointer is returned.
822 *
823 */
824 const otCoapOption *otCoapOptionIteratorGetNextOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption);
825
826 /**
827 * Returns a pointer to the next option.
828 *
829 * @param[in,out] aIterator A pointer to the CoAP message option iterator.
830 *
831 * @returns A pointer to the next option. If no more options are present NULL pointer is returned.
832 *
833 */
834 const otCoapOption *otCoapOptionIteratorGetNextOption(otCoapOptionIterator *aIterator);
835
836 /**
837 * Fills current option value into @p aValue assuming the current value is an unsigned integer encoded
838 * according to https://tools.ietf.org/html/rfc7252#section-3.2
839 *
840 * @param[in,out] aIterator A pointer to the CoAP message option iterator.
841 * @param[out] aValue A pointer to an unsigned integer to receive the option value.
842 *
843 * @retval OT_ERROR_NONE Successfully filled value.
844 * @retval OT_ERROR_NOT_FOUND No current option.
845 * @retval OT_ERROR_NO_BUFS Value is too long to fit in a uint64_t.
846 *
847 * @see otCoapMessageAppendUintOption
848 */
849 otError otCoapOptionIteratorGetOptionUintValue(otCoapOptionIterator *aIterator, uint64_t *aValue);
850
851 /**
852 * Fills current option value into @p aValue.
853 *
854 * @param[in,out] aIterator A pointer to the CoAP message option iterator.
855 * @param[out] aValue A pointer to a buffer to receive the option value.
856 *
857 * @retval OT_ERROR_NONE Successfully filled value.
858 * @retval OT_ERROR_NOT_FOUND No current option.
859 *
860 */
861 otError otCoapOptionIteratorGetOptionValue(otCoapOptionIterator *aIterator, void *aValue);
862
863 /**
864 * Creates a new CoAP message.
865 *
866 * @note If @p aSettings is 'NULL', the link layer security is enabled and the message priority is set to
867 * OT_MESSAGE_PRIORITY_NORMAL by default.
868 *
869 * @param[in] aInstance A pointer to an OpenThread instance.
870 * @param[in] aSettings A pointer to the message settings or NULL to set default settings.
871 *
872 * @returns A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid.
873 *
874 */
875 otMessage *otCoapNewMessage(otInstance *aInstance, const otMessageSettings *aSettings);
876
877 /**
878 * Sends a CoAP request with custom transmission parameters.
879 *
880 * If a response for a request is expected, respective function and context information should be provided.
881 * If no response is expected, these arguments should be NULL pointers.
882 *
883 * @param[in] aInstance A pointer to an OpenThread instance.
884 * @param[in] aMessage A pointer to the message to send.
885 * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage.
886 * @param[in] aHandler A function pointer that shall be called on response reception or timeout.
887 * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used.
888 * @param[in] aTxParameters A pointer to transmission parameters for this request. Use NULL for defaults.
889 * Otherwise, parameters given must meet the following conditions:
890 * 1. mMaxRetransmit is no more than OT_COAP_MAX_RETRANSMIT.
891 * 2. mAckRandomFactorNumerator / mAckRandomFactorDenominator must not be below 1.0.
892 * 3. The calculated exchange life time must not overflow uint32_t.
893 *
894 * @retval OT_ERROR_NONE Successfully sent CoAP message.
895 * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
896 * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given.
897 *
898 */
899 otError otCoapSendRequestWithParameters(otInstance *aInstance,
900 otMessage *aMessage,
901 const otMessageInfo *aMessageInfo,
902 otCoapResponseHandler aHandler,
903 void *aContext,
904 const otCoapTxParameters *aTxParameters);
905
906 /**
907 * Sends a CoAP request block-wise with custom transmission parameters.
908 *
909 * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
910 * is enabled.
911 *
912 * If a response for a request is expected, respective function and context information should be provided.
913 * If the response is expected to be block-wise, a respective hook function should be provided.
914 * If no response is expected, these arguments should be NULL pointers.
915 *
916 * @param[in] aInstance A pointer to an OpenThread instance.
917 * @param[in] aMessage A pointer to the message to send.
918 * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage.
919 * @param[in] aHandler A function pointer that shall be called on response reception or timeout.
920 * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used.
921 * @param[in] aTxParameters A pointer to transmission parameters for this request. Use NULL for defaults.
922 * @param[in] aTransmitHook A pointer to a hook function for outgoing block-wise transfer.
923 * @param[in] aReceiveHook A pointer to a hook function for incoming block-wise transfer.
924 *
925 * @retval OT_ERROR_NONE Successfully sent CoAP message.
926 * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
927 * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given.
928 *
929 */
930 otError otCoapSendRequestBlockWiseWithParameters(otInstance *aInstance,
931 otMessage *aMessage,
932 const otMessageInfo *aMessageInfo,
933 otCoapResponseHandler aHandler,
934 void *aContext,
935 const otCoapTxParameters *aTxParameters,
936 otCoapBlockwiseTransmitHook aTransmitHook,
937 otCoapBlockwiseReceiveHook aReceiveHook);
938
939 /**
940 * Sends a CoAP request block-wise.
941 *
942 * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
943 * is enabled.
944 *
945 * If a response for a request is expected, respective function and context information should be provided.
946 * If the response is expected to be block-wise, a respective hook function should be provided.
947 * If no response is expected, these arguments should be NULL pointers.
948 *
949 * @param[in] aInstance A pointer to an OpenThread instance.
950 * @param[in] aMessage A pointer to the message to send.
951 * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage.
952 * @param[in] aHandler A function pointer that shall be called on response reception or timeout.
953 * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used.
954 * @param[in] aTransmitHook A pointer to a hook function for outgoing block-wise transfer.
955 * @param[in] aReceiveHook A pointer to a hook function for incoming block-wise transfer.
956 *
957 * @retval OT_ERROR_NONE Successfully sent CoAP message.
958 * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
959 *
960 */
otCoapSendRequestBlockWise(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo,otCoapResponseHandler aHandler,void * aContext,otCoapBlockwiseTransmitHook aTransmitHook,otCoapBlockwiseReceiveHook aReceiveHook)961 static inline otError otCoapSendRequestBlockWise(otInstance *aInstance,
962 otMessage *aMessage,
963 const otMessageInfo *aMessageInfo,
964 otCoapResponseHandler aHandler,
965 void *aContext,
966 otCoapBlockwiseTransmitHook aTransmitHook,
967 otCoapBlockwiseReceiveHook aReceiveHook)
968 {
969 // NOLINTNEXTLINE(modernize-use-nullptr)
970 return otCoapSendRequestBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, NULL,
971 aTransmitHook, aReceiveHook);
972 }
973
974 /**
975 * Sends a CoAP request.
976 *
977 * If a response for a request is expected, respective function and context information should be provided.
978 * If no response is expected, these arguments should be NULL pointers.
979 *
980 * @param[in] aInstance A pointer to an OpenThread instance.
981 * @param[in] aMessage A pointer to the message to send.
982 * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage.
983 * @param[in] aHandler A function pointer that shall be called on response reception or timeout.
984 * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used.
985 *
986 * @retval OT_ERROR_NONE Successfully sent CoAP message.
987 * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
988 *
989 */
otCoapSendRequest(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo,otCoapResponseHandler aHandler,void * aContext)990 static inline otError otCoapSendRequest(otInstance *aInstance,
991 otMessage *aMessage,
992 const otMessageInfo *aMessageInfo,
993 otCoapResponseHandler aHandler,
994 void *aContext)
995 {
996 // NOLINTNEXTLINE(modernize-use-nullptr)
997 return otCoapSendRequestWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, NULL);
998 }
999
1000 /**
1001 * Starts the CoAP server.
1002 *
1003 * @param[in] aInstance A pointer to an OpenThread instance.
1004 * @param[in] aPort The local UDP port to bind to.
1005 *
1006 * @retval OT_ERROR_NONE Successfully started the CoAP server.
1007 * @retval OT_ERROR_FAILED Failed to start the CoAP server.
1008 *
1009 */
1010 otError otCoapStart(otInstance *aInstance, uint16_t aPort);
1011
1012 /**
1013 * Stops the CoAP server.
1014 *
1015 * @param[in] aInstance A pointer to an OpenThread instance.
1016 *
1017 * @retval OT_ERROR_NONE Successfully stopped the CoAP server.
1018 *
1019 */
1020 otError otCoapStop(otInstance *aInstance);
1021
1022 /**
1023 * Adds a resource to the CoAP server.
1024 *
1025 * @param[in] aInstance A pointer to an OpenThread instance.
1026 * @param[in] aResource A pointer to the resource.
1027 *
1028 */
1029 void otCoapAddResource(otInstance *aInstance, otCoapResource *aResource);
1030
1031 /**
1032 * Removes a resource from the CoAP server.
1033 *
1034 * @param[in] aInstance A pointer to an OpenThread instance.
1035 * @param[in] aResource A pointer to the resource.
1036 *
1037 */
1038 void otCoapRemoveResource(otInstance *aInstance, otCoapResource *aResource);
1039
1040 /**
1041 * Adds a block-wise resource to the CoAP server.
1042 *
1043 * @param[in] aInstance A pointer to an OpenThread instance.
1044 * @param[in] aResource A pointer to the resource.
1045 *
1046 */
1047 void otCoapAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource);
1048
1049 /**
1050 * Removes a block-wise resource from the CoAP server.
1051 *
1052 * @param[in] aInstance A pointer to an OpenThread instance.
1053 * @param[in] aResource A pointer to the resource.
1054 *
1055 */
1056 void otCoapRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource);
1057
1058 /**
1059 * Sets the default handler for unhandled CoAP requests.
1060 *
1061 * @param[in] aInstance A pointer to an OpenThread instance.
1062 * @param[in] aHandler A function pointer that shall be called when an unhandled request arrives.
1063 * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used.
1064 *
1065 */
1066 void otCoapSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext);
1067
1068 /**
1069 * Sends a CoAP response from the server with custom transmission parameters.
1070 *
1071 * @param[in] aInstance A pointer to an OpenThread instance.
1072 * @param[in] aMessage A pointer to the CoAP response to send.
1073 * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage.
1074 * @param[in] aTxParameters A pointer to transmission parameters for this response. Use NULL for defaults.
1075 *
1076 * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message.
1077 * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response.
1078 * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given.
1079 *
1080 */
1081 otError otCoapSendResponseWithParameters(otInstance *aInstance,
1082 otMessage *aMessage,
1083 const otMessageInfo *aMessageInfo,
1084 const otCoapTxParameters *aTxParameters);
1085
1086 /**
1087 * Sends a CoAP response block-wise from the server with custom transmission parameters.
1088 *
1089 * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
1090 * is enabled.
1091 *
1092 * @param[in] aInstance A pointer to an OpenThread instance.
1093 * @param[in] aMessage A pointer to the CoAP response to send.
1094 * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage.
1095 * @param[in] aTxParameters A pointer to transmission parameters for this response. Use NULL for defaults.
1096 * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used.
1097 * @param[in] aTransmitHook A pointer to a hook function for outgoing block-wise transfer.
1098 *
1099 * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message.
1100 * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response.
1101 * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given.
1102 *
1103 */
1104 otError otCoapSendResponseBlockWiseWithParameters(otInstance *aInstance,
1105 otMessage *aMessage,
1106 const otMessageInfo *aMessageInfo,
1107 const otCoapTxParameters *aTxParameters,
1108 void *aContext,
1109 otCoapBlockwiseTransmitHook aTransmitHook);
1110
1111 /**
1112 * Sends a CoAP response block-wise from the server.
1113 *
1114 * Is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
1115 * is enabled.
1116 *
1117 * @param[in] aInstance A pointer to an OpenThread instance.
1118 * @param[in] aMessage A pointer to the CoAP response to send.
1119 * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage.
1120 * @param[in] aContext A pointer to arbitrary context information. May be NULL if not used.
1121 * @param[in] aTransmitHook A pointer to a hook function for outgoing block-wise transfer.
1122 *
1123 * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message.
1124 * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response.
1125 *
1126 */
otCoapSendResponseBlockWise(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo,void * aContext,otCoapBlockwiseTransmitHook aTransmitHook)1127 static inline otError otCoapSendResponseBlockWise(otInstance *aInstance,
1128 otMessage *aMessage,
1129 const otMessageInfo *aMessageInfo,
1130 void *aContext,
1131 otCoapBlockwiseTransmitHook aTransmitHook)
1132 {
1133 // NOLINTNEXTLINE(modernize-use-nullptr)
1134 return otCoapSendResponseBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, NULL, aContext, aTransmitHook);
1135 }
1136
1137 /**
1138 * Sends a CoAP response from the server.
1139 *
1140 * @param[in] aInstance A pointer to an OpenThread instance.
1141 * @param[in] aMessage A pointer to the CoAP response to send.
1142 * @param[in] aMessageInfo A pointer to the message info associated with @p aMessage.
1143 *
1144 * @retval OT_ERROR_NONE Successfully enqueued the CoAP response message.
1145 * @retval OT_ERROR_NO_BUFS Insufficient buffers available to send the CoAP response.
1146 *
1147 */
otCoapSendResponse(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo)1148 static inline otError otCoapSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo)
1149 {
1150 // NOLINTNEXTLINE(modernize-use-nullptr)
1151 return otCoapSendResponseWithParameters(aInstance, aMessage, aMessageInfo, NULL);
1152 }
1153
1154 /**
1155 * @}
1156 *
1157 */
1158
1159 #ifdef __cplusplus
1160 } // extern "C"
1161 #endif
1162
1163 #endif /* OPENTHREAD_COAP_H_ */
1164