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  * This structure 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  * This structure 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  * This function 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  * This function 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  * This function pointer is called when a CoAP message with an block-wise transfer option is received.
361  *
362  * This function 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 transfered 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  * This function pointer is called before the next block in a block-wise transfer is sent.
387  *
388  * This function 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[inout]    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[inout]    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  * This structure 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  * This structure 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  * This structure 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  * This function initializes the CoAP header.
487  *
488  * @param[inout] 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  * This function initializes a response message.
497  *
498  * @note Both message ID and token are set according to @p aRequest.
499  *
500  * @param[inout] 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  * This function sets the Token value and length in a header.
513  *
514  * @param[inout]  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  * This function sets the Token length and randomizes its value.
526  *
527  * @param[inout]  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  * This function 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[inout]  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  * This function appends a CoAP option in a header.
556  *
557  * @param[inout]  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  * This function appends an unsigned integer CoAP option as specified in
571  * https://tools.ietf.org/html/rfc7252#section-3.2
572  *
573  * @param[inout]  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  * This function appends an Observe option.
587  *
588  * @param[inout]  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  * This function appends a Uri-Path option.
600  *
601  * @param[inout]  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  * This function converts a CoAP Block option SZX field to the actual block size
613  *
614  * @param[in]     aSize     Block size exponent.
615  *
616  * @returns The actual size exponent value.
617  *
618  */
619 uint16_t otCoapBlockSizeFromExponent(otCoapBlockSzx aSize);
620 
621 /**
622  * This function appends a Block2 option
623  *
624  * @param[inout]  aMessage  A pointer to the CoAP message.
625  * @param[in]     aNum      Current block number.
626  * @param[in]     aMore     Boolean to indicate more blocks are to be sent.
627  * @param[in]     aSize     Block Size Exponent.
628  *
629  * @retval OT_ERROR_NONE          Successfully appended the option.
630  * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
631  * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
632  *
633  */
634 otError otCoapMessageAppendBlock2Option(otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSzx aSize);
635 
636 /**
637  * This function appends a Block1 option
638  *
639  * @param[inout]  aMessage  A pointer to the CoAP message.
640  * @param[in]     aNum      Current block number.
641  * @param[in]     aMore     Boolean to indicate more blocks are to be sent.
642  * @param[in]     aSize     Block Size Exponent.
643  *
644  * @retval OT_ERROR_NONE          Successfully appended the option.
645  * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
646  * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
647  *
648  */
649 otError otCoapMessageAppendBlock1Option(otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSzx aSize);
650 
651 /**
652  * This function appends a Proxy-Uri option.
653  *
654  * @param[inout]  aMessage  A pointer to the CoAP message.
655  * @param[in]     aUriPath  A pointer to a NULL-terminated string.
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 otCoapMessageAppendProxyUriOption(otMessage *aMessage, const char *aUriPath);
663 
664 /**
665  * This function appends a Max-Age option.
666  *
667  * @param[inout]  aMessage  A pointer to the CoAP message.
668  * @param[in]     aMaxAge   The Max-Age value.
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 otCoapMessageAppendMaxAgeOption(otMessage *aMessage, uint32_t aMaxAge);
676 
677 /**
678  * This function appends a single Uri-Query option.
679  *
680  * @param[inout]  aMessage  A pointer to the CoAP message.
681  * @param[in]     aUriQuery A pointer to NULL-terminated string, which should contain a single key=value pair.
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 otError otCoapMessageAppendUriQueryOption(otMessage *aMessage, const char *aUriQuery);
688 
689 /**
690  * This function adds Payload Marker indicating beginning of the payload to the CoAP header.
691  *
692  * @param[inout]  aMessage  A pointer to the CoAP message.
693  *
694  * @retval OT_ERROR_NONE     Payload Marker successfully added.
695  * @retval OT_ERROR_NO_BUFS  Header Payload Marker exceeds the buffer size.
696  *
697  */
698 otError otCoapMessageSetPayloadMarker(otMessage *aMessage);
699 
700 /**
701  * This function returns the Type value.
702  *
703  * @param[in]  aMessage  A pointer to the CoAP message.
704  *
705  * @returns The Type value.
706  *
707  */
708 otCoapType otCoapMessageGetType(const otMessage *aMessage);
709 
710 /**
711  * This function returns the Code value.
712  *
713  * @param[in]  aMessage  A pointer to the CoAP message.
714  *
715  * @returns The Code value.
716  *
717  */
718 otCoapCode otCoapMessageGetCode(const otMessage *aMessage);
719 
720 /**
721  * This method returns the CoAP Code as human readable string.
722  *
723  * @param[in]   aMessage    A pointer to the CoAP message.
724  *
725  * @ returns The CoAP Code as string.
726  *
727  */
728 const char *otCoapMessageCodeToString(const otMessage *aMessage);
729 
730 /**
731  * This function returns the Message ID value.
732  *
733  * @param[in]  aMessage  A pointer to the CoAP message.
734  *
735  * @returns The Message ID value.
736  *
737  */
738 uint16_t otCoapMessageGetMessageId(const otMessage *aMessage);
739 
740 /**
741  * This function returns the Token length.
742  *
743  * @param[in]  aMessage  A pointer to the CoAP message.
744  *
745  * @returns The Token length.
746  *
747  */
748 uint8_t otCoapMessageGetTokenLength(const otMessage *aMessage);
749 
750 /**
751  * This function returns a pointer to the Token value.
752  *
753  * @param[in]  aMessage  A pointer to the CoAP message.
754  *
755  * @returns A pointer to the Token value.
756  *
757  */
758 const uint8_t *otCoapMessageGetToken(const otMessage *aMessage);
759 
760 /**
761  * This function initialises an iterator for the options in the given message.
762  *
763  * @param[inout]  aIterator A pointer to the CoAP message option iterator.
764  * @param[in]     aMessage  A pointer to the CoAP message.
765  *
766  * @retval  OT_ERROR_NONE   Successfully initialised.
767  * @retval  OT_ERROR_PARSE  Message state is inconsistent.
768  *
769  */
770 otError otCoapOptionIteratorInit(otCoapOptionIterator *aIterator, const otMessage *aMessage);
771 
772 /**
773  * This function returns a pointer to the first option matching the specified option number.
774  *
775  * @param[in]  aIterator A pointer to the CoAP message option iterator.
776  * @param[in]  aOption   The option number sought.
777  *
778  * @returns A pointer to the first matching option. If no matching option is present NULL pointer is returned.
779  *
780  */
781 const otCoapOption *otCoapOptionIteratorGetFirstOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption);
782 
783 /**
784  * This function returns a pointer to the first option.
785  *
786  * @param[inout]  aIterator A pointer to the CoAP message option iterator.
787  *
788  * @returns A pointer to the first option. If no option is present NULL pointer is returned.
789  *
790  */
791 const otCoapOption *otCoapOptionIteratorGetFirstOption(otCoapOptionIterator *aIterator);
792 
793 /**
794  * This function returns a pointer to the next option matching the specified option number.
795  *
796  * @param[in]  aIterator A pointer to the CoAP message option iterator.
797  * @param[in]  aOption   The option number sought.
798  *
799  * @returns A pointer to the next matching option. If no further matching option is present NULL pointer is returned.
800  *
801  */
802 const otCoapOption *otCoapOptionIteratorGetNextOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption);
803 
804 /**
805  * This function returns a pointer to the next option.
806  *
807  * @param[inout]  aIterator A pointer to the CoAP message option iterator.
808  *
809  * @returns A pointer to the next option. If no more options are present NULL pointer is returned.
810  *
811  */
812 const otCoapOption *otCoapOptionIteratorGetNextOption(otCoapOptionIterator *aIterator);
813 
814 /**
815  * This function fills current option value into @p aValue assuming the current value is an unsigned integer encoded
816  * according to https://tools.ietf.org/html/rfc7252#section-3.2
817  *
818  * @param[inout]    aIterator   A pointer to the CoAP message option iterator.
819  * @param[out]      aValue      A pointer to an unsigned integer to receive the option value.
820  *
821  * @retval  OT_ERROR_NONE       Successfully filled value.
822  * @retval  OT_ERROR_NOT_FOUND  No current option.
823  * @retval  OT_ERROR_NO_BUFS    Value is too long to fit in a uint64_t.
824  *
825  * @see otCoapMessageAppendUintOption
826  */
827 otError otCoapOptionIteratorGetOptionUintValue(otCoapOptionIterator *aIterator, uint64_t *aValue);
828 
829 /**
830  * This function fills current option value into @p aValue.
831  *
832  * @param[inout]  aIterator A pointer to the CoAP message option iterator.
833  * @param[out]    aValue    A pointer to a buffer to receive the option value.
834  *
835  * @retval  OT_ERROR_NONE       Successfully filled value.
836  * @retval  OT_ERROR_NOT_FOUND  No current option.
837  *
838  */
839 otError otCoapOptionIteratorGetOptionValue(otCoapOptionIterator *aIterator, void *aValue);
840 
841 /**
842  * This function creates a new CoAP message.
843  *
844  * @note If @p aSettings is 'NULL', the link layer security is enabled and the message priority is set to
845  * OT_MESSAGE_PRIORITY_NORMAL by default.
846  *
847  * @param[in]  aInstance  A pointer to an OpenThread instance.
848  * @param[in]  aSettings  A pointer to the message settings or NULL to set default settings.
849  *
850  * @returns A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid.
851  *
852  */
853 otMessage *otCoapNewMessage(otInstance *aInstance, const otMessageSettings *aSettings);
854 
855 /**
856  * This function sends a CoAP request with custom transmission parameters.
857  *
858  * If a response for a request is expected, respective function and context information should be provided.
859  * If no response is expected, these arguments should be NULL pointers.
860  *
861  * @param[in]  aInstance        A pointer to an OpenThread instance.
862  * @param[in]  aMessage         A pointer to the message to send.
863  * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
864  * @param[in]  aHandler         A function pointer that shall be called on response reception or timeout.
865  * @param[in]  aContext         A pointer to arbitrary context information. May be NULL if not used.
866  * @param[in]  aTxParameters    A pointer to transmission parameters for this request. Use NULL for defaults.
867  *                              Otherwise, parameters given must meet the following conditions:
868  *                              1. mMaxRetransmit is no more than OT_COAP_MAX_RETRANSMIT.
869  *                              2. mAckRandomFactorNumerator / mAckRandomFactorDenominator must not be below 1.0.
870  *                              3. The calculated exchange life time must not overflow uint32_t.
871  *
872  * @retval OT_ERROR_INVALID_ARGS    @p aTxParameters is invalid.
873  * @retval OT_ERROR_NONE            Successfully sent CoAP message.
874  * @retval OT_ERROR_NO_BUFS         Failed to allocate retransmission data.
875  *
876  */
877 otError otCoapSendRequestWithParameters(otInstance *              aInstance,
878                                         otMessage *               aMessage,
879                                         const otMessageInfo *     aMessageInfo,
880                                         otCoapResponseHandler     aHandler,
881                                         void *                    aContext,
882                                         const otCoapTxParameters *aTxParameters);
883 
884 /**
885  * This function sends a CoAP request block-wise with custom transmission parameters.
886  *
887  * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
888  * is enabled.
889  *
890  * If a response for a request is expected, respective function and context information should be provided.
891  * If the response is expected to be block-wise, a respective hook function should be provided.
892  * If no response is expected, these arguments should be NULL pointers.
893  *
894  * @param[in]  aInstance        A pointer to an OpenThread instance.
895  * @param[in]  aMessage         A pointer to the message to send.
896  * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
897  * @param[in]  aHandler         A function pointer that shall be called on response reception or timeout.
898  * @param[in]  aContext         A pointer to arbitrary context information. May be NULL if not used.
899  * @param[in]  aTxParameters    A pointer to transmission parameters for this request. Use NULL for defaults.
900  * @param[in]  aTransmitHook    A pointer to a hook function for outgoing block-wise transfer.
901  * @param[in]  aReceiveHook     A pointer to a hook function for incoming block-wise transfer.
902  *
903  * @retval OT_ERROR_NONE    Successfully sent CoAP message.
904  * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
905  *
906  */
907 otError otCoapSendRequestBlockWiseWithParameters(otInstance *                aInstance,
908                                                  otMessage *                 aMessage,
909                                                  const otMessageInfo *       aMessageInfo,
910                                                  otCoapResponseHandler       aHandler,
911                                                  void *                      aContext,
912                                                  const otCoapTxParameters *  aTxParameters,
913                                                  otCoapBlockwiseTransmitHook aTransmitHook,
914                                                  otCoapBlockwiseReceiveHook  aReceiveHook);
915 
916 /**
917  * This function sends a CoAP request block-wise.
918  *
919  * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
920  * is enabled.
921  *
922  * If a response for a request is expected, respective function and context information should be provided.
923  * If the response is expected to be block-wise, a respective hook function should be provided.
924  * If no response is expected, these arguments should be NULL pointers.
925  *
926  * @param[in]  aInstance     A pointer to an OpenThread instance.
927  * @param[in]  aMessage      A pointer to the message to send.
928  * @param[in]  aMessageInfo  A pointer to the message info associated with @p aMessage.
929  * @param[in]  aHandler      A function pointer that shall be called on response reception or timeout.
930  * @param[in]  aContext      A pointer to arbitrary context information. May be NULL if not used.
931  * @param[in]  aTransmitHook A pointer to a hook function for outgoing block-wise transfer.
932  * @param[in]  aReceiveHook  A pointer to a hook function for incoming block-wise transfer.
933  *
934  * @retval OT_ERROR_NONE    Successfully sent CoAP message.
935  * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
936  *
937  */
otCoapSendRequestBlockWise(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo,otCoapResponseHandler aHandler,void * aContext,otCoapBlockwiseTransmitHook aTransmitHook,otCoapBlockwiseReceiveHook aReceiveHook)938 static inline otError otCoapSendRequestBlockWise(otInstance *                aInstance,
939                                                  otMessage *                 aMessage,
940                                                  const otMessageInfo *       aMessageInfo,
941                                                  otCoapResponseHandler       aHandler,
942                                                  void *                      aContext,
943                                                  otCoapBlockwiseTransmitHook aTransmitHook,
944                                                  otCoapBlockwiseReceiveHook  aReceiveHook)
945 {
946     // NOLINTNEXTLINE(modernize-use-nullptr)
947     return otCoapSendRequestBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, NULL,
948                                                     aTransmitHook, aReceiveHook);
949 }
950 
951 /**
952  * This function sends a CoAP request.
953  *
954  * If a response for a request is expected, respective function and context information should be provided.
955  * If no response is expected, these arguments should be NULL pointers.
956  *
957  * @param[in]  aInstance     A pointer to an OpenThread instance.
958  * @param[in]  aMessage      A pointer to the message to send.
959  * @param[in]  aMessageInfo  A pointer to the message info associated with @p aMessage.
960  * @param[in]  aHandler      A function pointer that shall be called on response reception or timeout.
961  * @param[in]  aContext      A pointer to arbitrary context information. May be NULL if not used.
962  *
963  * @retval OT_ERROR_NONE    Successfully sent CoAP message.
964  * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
965  *
966  */
otCoapSendRequest(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo,otCoapResponseHandler aHandler,void * aContext)967 static inline otError otCoapSendRequest(otInstance *          aInstance,
968                                         otMessage *           aMessage,
969                                         const otMessageInfo * aMessageInfo,
970                                         otCoapResponseHandler aHandler,
971                                         void *                aContext)
972 {
973     // NOLINTNEXTLINE(modernize-use-nullptr)
974     return otCoapSendRequestWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, NULL);
975 }
976 
977 /**
978  * This function starts the CoAP server.
979  *
980  * @param[in]  aInstance  A pointer to an OpenThread instance.
981  * @param[in]  aPort      The local UDP port to bind to.
982  *
983  * @retval OT_ERROR_NONE    Successfully started the CoAP server.
984  * @retval OT_ERROR_FAILED  Failed to start the CoAP server.
985  *
986  */
987 otError otCoapStart(otInstance *aInstance, uint16_t aPort);
988 
989 /**
990  * This function stops the CoAP server.
991  *
992  * @param[in]  aInstance  A pointer to an OpenThread instance.
993  *
994  * @retval OT_ERROR_NONE  Successfully stopped the CoAP server.
995  *
996  */
997 otError otCoapStop(otInstance *aInstance);
998 
999 /**
1000  * This function adds a resource to the CoAP server.
1001  *
1002  * @param[in]  aInstance  A pointer to an OpenThread instance.
1003  * @param[in]  aResource  A pointer to the resource.
1004  *
1005  */
1006 void otCoapAddResource(otInstance *aInstance, otCoapResource *aResource);
1007 
1008 /**
1009  * This function removes a resource from the CoAP server.
1010  *
1011  * @param[in]  aInstance  A pointer to an OpenThread instance.
1012  * @param[in]  aResource  A pointer to the resource.
1013  *
1014  */
1015 void otCoapRemoveResource(otInstance *aInstance, otCoapResource *aResource);
1016 
1017 /**
1018  * This function adds a block-wise resource to the CoAP server.
1019  *
1020  * @param[in]  aInstance  A pointer to an OpenThread instance.
1021  * @param[in]  aResource  A pointer to the resource.
1022  *
1023  */
1024 void otCoapAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource);
1025 
1026 /**
1027  * This function removes a block-wise resource from the CoAP server.
1028  *
1029  * @param[in]  aInstance  A pointer to an OpenThread instance.
1030  * @param[in]  aResource  A pointer to the resource.
1031  *
1032  */
1033 void otCoapRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource);
1034 
1035 /**
1036  * This function sets the default handler for unhandled CoAP requests.
1037  *
1038  * @param[in]  aInstance  A pointer to an OpenThread instance.
1039  * @param[in]  aHandler   A function pointer that shall be called when an unhandled request arrives.
1040  * @param[in]  aContext   A pointer to arbitrary context information. May be NULL if not used.
1041  *
1042  */
1043 void otCoapSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext);
1044 
1045 /**
1046  * This function sends a CoAP response from the server with custom transmission parameters.
1047  *
1048  * @param[in]  aInstance        A pointer to an OpenThread instance.
1049  * @param[in]  aMessage         A pointer to the CoAP response to send.
1050  * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
1051  * @param[in]  aTxParameters    A pointer to transmission parameters for this response. Use NULL for defaults.
1052  *
1053  * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
1054  * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
1055  *
1056  */
1057 otError otCoapSendResponseWithParameters(otInstance *              aInstance,
1058                                          otMessage *               aMessage,
1059                                          const otMessageInfo *     aMessageInfo,
1060                                          const otCoapTxParameters *aTxParameters);
1061 
1062 /**
1063  * This function sends a CoAP response block-wise from the server with custom transmission parameters.
1064  *
1065  * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
1066  * is enabled.
1067  *
1068  * @param[in]  aInstance        A pointer to an OpenThread instance.
1069  * @param[in]  aMessage         A pointer to the CoAP response to send.
1070  * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
1071  * @param[in]  aTxParameters    A pointer to transmission parameters for this response. Use NULL for defaults.
1072  * @param[in]  aContext         A pointer to arbitrary context information. May be NULL if not used.
1073  * @param[in]  aTransmitHook    A pointer to a hook function for outgoing block-wise transfer.
1074  *
1075  * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
1076  * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
1077  *
1078  */
1079 otError otCoapSendResponseBlockWiseWithParameters(otInstance *                aInstance,
1080                                                   otMessage *                 aMessage,
1081                                                   const otMessageInfo *       aMessageInfo,
1082                                                   const otCoapTxParameters *  aTxParameters,
1083                                                   void *                      aContext,
1084                                                   otCoapBlockwiseTransmitHook aTransmitHook);
1085 
1086 /**
1087  * This function sends a CoAP response block-wise from the server.
1088  *
1089  * This function 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]  aContext      A pointer to arbitrary context information. May be NULL if not used.
1096  * @param[in]  aTransmitHook A pointer to a hook function for outgoing block-wise transfer.
1097  *
1098  * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
1099  * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
1100  *
1101  */
otCoapSendResponseBlockWise(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo,void * aContext,otCoapBlockwiseTransmitHook aTransmitHook)1102 static inline otError otCoapSendResponseBlockWise(otInstance *                aInstance,
1103                                                   otMessage *                 aMessage,
1104                                                   const otMessageInfo *       aMessageInfo,
1105                                                   void *                      aContext,
1106                                                   otCoapBlockwiseTransmitHook aTransmitHook)
1107 {
1108     // NOLINTNEXTLINE(modernize-use-nullptr)
1109     return otCoapSendResponseBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, NULL, aContext, aTransmitHook);
1110 }
1111 
1112 /**
1113  * This function sends a CoAP response from the server.
1114  *
1115  * @param[in]  aInstance     A pointer to an OpenThread instance.
1116  * @param[in]  aMessage      A pointer to the CoAP response to send.
1117  * @param[in]  aMessageInfo  A pointer to the message info associated with @p aMessage.
1118  *
1119  * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
1120  * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
1121  *
1122  */
otCoapSendResponse(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo)1123 static inline otError otCoapSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo)
1124 {
1125     // NOLINTNEXTLINE(modernize-use-nullptr)
1126     return otCoapSendResponseWithParameters(aInstance, aMessage, aMessageInfo, NULL);
1127 }
1128 
1129 /**
1130  * @}
1131  *
1132  */
1133 
1134 #ifdef __cplusplus
1135 } // extern "C"
1136 #endif
1137 
1138 #endif /* OPENTHREAD_COAP_H_ */
1139