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 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  * 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[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  * 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[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  * This function 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  * This function 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  * This function 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  * 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[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  * This function 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  * This function 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  * This function 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  * This function 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  * 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[in,out]  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[in,out]  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[in,out]  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[in,out]  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[in,out]  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[in,out]  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 function sets the Code value.
722  *
723  * @param[in,out]  aMessage  A pointer to the CoAP message to initialize.
724  * @param[in]      aCode     CoAP message code.
725  *
726  */
727 void otCoapMessageSetCode(otMessage *aMessage, otCoapCode aCode);
728 
729 /**
730  * This method returns the CoAP Code as human readable string.
731  *
732  * @param[in]   aMessage    A pointer to the CoAP message.
733  *
734  * @ returns The CoAP Code as string.
735  *
736  */
737 const char *otCoapMessageCodeToString(const otMessage *aMessage);
738 
739 /**
740  * This function returns the Message ID value.
741  *
742  * @param[in]  aMessage  A pointer to the CoAP message.
743  *
744  * @returns The Message ID value.
745  *
746  */
747 uint16_t otCoapMessageGetMessageId(const otMessage *aMessage);
748 
749 /**
750  * This function returns the Token length.
751  *
752  * @param[in]  aMessage  A pointer to the CoAP message.
753  *
754  * @returns The Token length.
755  *
756  */
757 uint8_t otCoapMessageGetTokenLength(const otMessage *aMessage);
758 
759 /**
760  * This function returns a pointer to the Token value.
761  *
762  * @param[in]  aMessage  A pointer to the CoAP message.
763  *
764  * @returns A pointer to the Token value.
765  *
766  */
767 const uint8_t *otCoapMessageGetToken(const otMessage *aMessage);
768 
769 /**
770  * This function initialises an iterator for the options in the given message.
771  *
772  * @param[in,out]  aIterator A pointer to the CoAP message option iterator.
773  * @param[in]      aMessage  A pointer to the CoAP message.
774  *
775  * @retval  OT_ERROR_NONE   Successfully initialised.
776  * @retval  OT_ERROR_PARSE  Message state is inconsistent.
777  *
778  */
779 otError otCoapOptionIteratorInit(otCoapOptionIterator *aIterator, const otMessage *aMessage);
780 
781 /**
782  * This function returns a pointer to the first option matching the specified option number.
783  *
784  * @param[in]  aIterator A pointer to the CoAP message option iterator.
785  * @param[in]  aOption   The option number sought.
786  *
787  * @returns A pointer to the first matching option. If no matching option is present NULL pointer is returned.
788  *
789  */
790 const otCoapOption *otCoapOptionIteratorGetFirstOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption);
791 
792 /**
793  * This function returns a pointer to the first option.
794  *
795  * @param[in,out]  aIterator A pointer to the CoAP message option iterator.
796  *
797  * @returns A pointer to the first option. If no option is present NULL pointer is returned.
798  *
799  */
800 const otCoapOption *otCoapOptionIteratorGetFirstOption(otCoapOptionIterator *aIterator);
801 
802 /**
803  * This function returns a pointer to the next option matching the specified option number.
804  *
805  * @param[in]  aIterator A pointer to the CoAP message option iterator.
806  * @param[in]  aOption   The option number sought.
807  *
808  * @returns A pointer to the next matching option. If no further matching option is present NULL pointer is returned.
809  *
810  */
811 const otCoapOption *otCoapOptionIteratorGetNextOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption);
812 
813 /**
814  * This function returns a pointer to the next option.
815  *
816  * @param[in,out]  aIterator A pointer to the CoAP message option iterator.
817  *
818  * @returns A pointer to the next option. If no more options are present NULL pointer is returned.
819  *
820  */
821 const otCoapOption *otCoapOptionIteratorGetNextOption(otCoapOptionIterator *aIterator);
822 
823 /**
824  * This function fills current option value into @p aValue assuming the current value is an unsigned integer encoded
825  * according to https://tools.ietf.org/html/rfc7252#section-3.2
826  *
827  * @param[in,out]   aIterator   A pointer to the CoAP message option iterator.
828  * @param[out]      aValue      A pointer to an unsigned integer to receive the option value.
829  *
830  * @retval  OT_ERROR_NONE       Successfully filled value.
831  * @retval  OT_ERROR_NOT_FOUND  No current option.
832  * @retval  OT_ERROR_NO_BUFS    Value is too long to fit in a uint64_t.
833  *
834  * @see otCoapMessageAppendUintOption
835  */
836 otError otCoapOptionIteratorGetOptionUintValue(otCoapOptionIterator *aIterator, uint64_t *aValue);
837 
838 /**
839  * This function fills current option value into @p aValue.
840  *
841  * @param[in,out]  aIterator A pointer to the CoAP message option iterator.
842  * @param[out]     aValue    A pointer to a buffer to receive the option value.
843  *
844  * @retval  OT_ERROR_NONE       Successfully filled value.
845  * @retval  OT_ERROR_NOT_FOUND  No current option.
846  *
847  */
848 otError otCoapOptionIteratorGetOptionValue(otCoapOptionIterator *aIterator, void *aValue);
849 
850 /**
851  * This function creates a new CoAP message.
852  *
853  * @note If @p aSettings is 'NULL', the link layer security is enabled and the message priority is set to
854  * OT_MESSAGE_PRIORITY_NORMAL by default.
855  *
856  * @param[in]  aInstance  A pointer to an OpenThread instance.
857  * @param[in]  aSettings  A pointer to the message settings or NULL to set default settings.
858  *
859  * @returns A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid.
860  *
861  */
862 otMessage *otCoapNewMessage(otInstance *aInstance, const otMessageSettings *aSettings);
863 
864 /**
865  * This function sends a CoAP request with custom transmission parameters.
866  *
867  * If a response for a request is expected, respective function and context information should be provided.
868  * If no response is expected, these arguments should be NULL pointers.
869  *
870  * @param[in]  aInstance        A pointer to an OpenThread instance.
871  * @param[in]  aMessage         A pointer to the message to send.
872  * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
873  * @param[in]  aHandler         A function pointer that shall be called on response reception or timeout.
874  * @param[in]  aContext         A pointer to arbitrary context information. May be NULL if not used.
875  * @param[in]  aTxParameters    A pointer to transmission parameters for this request. Use NULL for defaults.
876  *                              Otherwise, parameters given must meet the following conditions:
877  *                              1. mMaxRetransmit is no more than OT_COAP_MAX_RETRANSMIT.
878  *                              2. mAckRandomFactorNumerator / mAckRandomFactorDenominator must not be below 1.0.
879  *                              3. The calculated exchange life time must not overflow uint32_t.
880  *
881  * @retval OT_ERROR_INVALID_ARGS    @p aTxParameters is invalid.
882  * @retval OT_ERROR_NONE            Successfully sent CoAP message.
883  * @retval OT_ERROR_NO_BUFS         Failed to allocate retransmission data.
884  *
885  */
886 otError otCoapSendRequestWithParameters(otInstance               *aInstance,
887                                         otMessage                *aMessage,
888                                         const otMessageInfo      *aMessageInfo,
889                                         otCoapResponseHandler     aHandler,
890                                         void                     *aContext,
891                                         const otCoapTxParameters *aTxParameters);
892 
893 /**
894  * This function sends a CoAP request block-wise with custom transmission parameters.
895  *
896  * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
897  * is enabled.
898  *
899  * If a response for a request is expected, respective function and context information should be provided.
900  * If the response is expected to be block-wise, a respective hook function should be provided.
901  * If no response is expected, these arguments should be NULL pointers.
902  *
903  * @param[in]  aInstance        A pointer to an OpenThread instance.
904  * @param[in]  aMessage         A pointer to the message to send.
905  * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
906  * @param[in]  aHandler         A function pointer that shall be called on response reception or timeout.
907  * @param[in]  aContext         A pointer to arbitrary context information. May be NULL if not used.
908  * @param[in]  aTxParameters    A pointer to transmission parameters for this request. Use NULL for defaults.
909  * @param[in]  aTransmitHook    A pointer to a hook function for outgoing block-wise transfer.
910  * @param[in]  aReceiveHook     A pointer to a hook function for incoming block-wise transfer.
911  *
912  * @retval OT_ERROR_NONE    Successfully sent CoAP message.
913  * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
914  *
915  */
916 otError otCoapSendRequestBlockWiseWithParameters(otInstance                 *aInstance,
917                                                  otMessage                  *aMessage,
918                                                  const otMessageInfo        *aMessageInfo,
919                                                  otCoapResponseHandler       aHandler,
920                                                  void                       *aContext,
921                                                  const otCoapTxParameters   *aTxParameters,
922                                                  otCoapBlockwiseTransmitHook aTransmitHook,
923                                                  otCoapBlockwiseReceiveHook  aReceiveHook);
924 
925 /**
926  * This function sends a CoAP request block-wise.
927  *
928  * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
929  * is enabled.
930  *
931  * If a response for a request is expected, respective function and context information should be provided.
932  * If the response is expected to be block-wise, a respective hook function should be provided.
933  * If no response is expected, these arguments should be NULL pointers.
934  *
935  * @param[in]  aInstance     A pointer to an OpenThread instance.
936  * @param[in]  aMessage      A pointer to the message to send.
937  * @param[in]  aMessageInfo  A pointer to the message info associated with @p aMessage.
938  * @param[in]  aHandler      A function pointer that shall be called on response reception or timeout.
939  * @param[in]  aContext      A pointer to arbitrary context information. May be NULL if not used.
940  * @param[in]  aTransmitHook A pointer to a hook function for outgoing block-wise transfer.
941  * @param[in]  aReceiveHook  A pointer to a hook function for incoming block-wise transfer.
942  *
943  * @retval OT_ERROR_NONE    Successfully sent CoAP message.
944  * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
945  *
946  */
otCoapSendRequestBlockWise(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo,otCoapResponseHandler aHandler,void * aContext,otCoapBlockwiseTransmitHook aTransmitHook,otCoapBlockwiseReceiveHook aReceiveHook)947 static inline otError otCoapSendRequestBlockWise(otInstance                 *aInstance,
948                                                  otMessage                  *aMessage,
949                                                  const otMessageInfo        *aMessageInfo,
950                                                  otCoapResponseHandler       aHandler,
951                                                  void                       *aContext,
952                                                  otCoapBlockwiseTransmitHook aTransmitHook,
953                                                  otCoapBlockwiseReceiveHook  aReceiveHook)
954 {
955     // NOLINTNEXTLINE(modernize-use-nullptr)
956     return otCoapSendRequestBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, NULL,
957                                                     aTransmitHook, aReceiveHook);
958 }
959 
960 /**
961  * This function sends a CoAP request.
962  *
963  * If a response for a request is expected, respective function and context information should be provided.
964  * If no response is expected, these arguments should be NULL pointers.
965  *
966  * @param[in]  aInstance     A pointer to an OpenThread instance.
967  * @param[in]  aMessage      A pointer to the message to send.
968  * @param[in]  aMessageInfo  A pointer to the message info associated with @p aMessage.
969  * @param[in]  aHandler      A function pointer that shall be called on response reception or timeout.
970  * @param[in]  aContext      A pointer to arbitrary context information. May be NULL if not used.
971  *
972  * @retval OT_ERROR_NONE    Successfully sent CoAP message.
973  * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
974  *
975  */
otCoapSendRequest(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo,otCoapResponseHandler aHandler,void * aContext)976 static inline otError otCoapSendRequest(otInstance           *aInstance,
977                                         otMessage            *aMessage,
978                                         const otMessageInfo  *aMessageInfo,
979                                         otCoapResponseHandler aHandler,
980                                         void                 *aContext)
981 {
982     // NOLINTNEXTLINE(modernize-use-nullptr)
983     return otCoapSendRequestWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, NULL);
984 }
985 
986 /**
987  * This function starts the CoAP server.
988  *
989  * @param[in]  aInstance  A pointer to an OpenThread instance.
990  * @param[in]  aPort      The local UDP port to bind to.
991  *
992  * @retval OT_ERROR_NONE    Successfully started the CoAP server.
993  * @retval OT_ERROR_FAILED  Failed to start the CoAP server.
994  *
995  */
996 otError otCoapStart(otInstance *aInstance, uint16_t aPort);
997 
998 /**
999  * This function stops the CoAP server.
1000  *
1001  * @param[in]  aInstance  A pointer to an OpenThread instance.
1002  *
1003  * @retval OT_ERROR_NONE  Successfully stopped the CoAP server.
1004  *
1005  */
1006 otError otCoapStop(otInstance *aInstance);
1007 
1008 /**
1009  * This function adds a resource to 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 otCoapAddResource(otInstance *aInstance, otCoapResource *aResource);
1016 
1017 /**
1018  * This function removes a resource from 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 otCoapRemoveResource(otInstance *aInstance, otCoapResource *aResource);
1025 
1026 /**
1027  * This function adds a block-wise resource to 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 otCoapAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource);
1034 
1035 /**
1036  * This function removes a block-wise resource from the CoAP server.
1037  *
1038  * @param[in]  aInstance  A pointer to an OpenThread instance.
1039  * @param[in]  aResource  A pointer to the resource.
1040  *
1041  */
1042 void otCoapRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource);
1043 
1044 /**
1045  * This function sets the default handler for unhandled CoAP requests.
1046  *
1047  * @param[in]  aInstance  A pointer to an OpenThread instance.
1048  * @param[in]  aHandler   A function pointer that shall be called when an unhandled request arrives.
1049  * @param[in]  aContext   A pointer to arbitrary context information. May be NULL if not used.
1050  *
1051  */
1052 void otCoapSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext);
1053 
1054 /**
1055  * This function sends a CoAP response from the server with custom transmission parameters.
1056  *
1057  * @param[in]  aInstance        A pointer to an OpenThread instance.
1058  * @param[in]  aMessage         A pointer to the CoAP response to send.
1059  * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
1060  * @param[in]  aTxParameters    A pointer to transmission parameters for this response. Use NULL for defaults.
1061  *
1062  * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
1063  * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
1064  *
1065  */
1066 otError otCoapSendResponseWithParameters(otInstance               *aInstance,
1067                                          otMessage                *aMessage,
1068                                          const otMessageInfo      *aMessageInfo,
1069                                          const otCoapTxParameters *aTxParameters);
1070 
1071 /**
1072  * This function sends a CoAP response block-wise from the server with custom transmission parameters.
1073  *
1074  * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
1075  * is enabled.
1076  *
1077  * @param[in]  aInstance        A pointer to an OpenThread instance.
1078  * @param[in]  aMessage         A pointer to the CoAP response to send.
1079  * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
1080  * @param[in]  aTxParameters    A pointer to transmission parameters for this response. Use NULL for defaults.
1081  * @param[in]  aContext         A pointer to arbitrary context information. May be NULL if not used.
1082  * @param[in]  aTransmitHook    A pointer to a hook function for outgoing block-wise transfer.
1083  *
1084  * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
1085  * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
1086  *
1087  */
1088 otError otCoapSendResponseBlockWiseWithParameters(otInstance                 *aInstance,
1089                                                   otMessage                  *aMessage,
1090                                                   const otMessageInfo        *aMessageInfo,
1091                                                   const otCoapTxParameters   *aTxParameters,
1092                                                   void                       *aContext,
1093                                                   otCoapBlockwiseTransmitHook aTransmitHook);
1094 
1095 /**
1096  * This function sends a CoAP response block-wise from the server.
1097  *
1098  * This function is available when OPENTHREAD_CONFIG_COAP_BLOCKWISE_TRANSFER_ENABLE configuration
1099  * is enabled.
1100  *
1101  * @param[in]  aInstance     A pointer to an OpenThread instance.
1102  * @param[in]  aMessage      A pointer to the CoAP response to send.
1103  * @param[in]  aMessageInfo  A pointer to the message info associated with @p aMessage.
1104  * @param[in]  aContext      A pointer to arbitrary context information. May be NULL if not used.
1105  * @param[in]  aTransmitHook A pointer to a hook function for outgoing block-wise transfer.
1106  *
1107  * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
1108  * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
1109  *
1110  */
otCoapSendResponseBlockWise(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo,void * aContext,otCoapBlockwiseTransmitHook aTransmitHook)1111 static inline otError otCoapSendResponseBlockWise(otInstance                 *aInstance,
1112                                                   otMessage                  *aMessage,
1113                                                   const otMessageInfo        *aMessageInfo,
1114                                                   void                       *aContext,
1115                                                   otCoapBlockwiseTransmitHook aTransmitHook)
1116 {
1117     // NOLINTNEXTLINE(modernize-use-nullptr)
1118     return otCoapSendResponseBlockWiseWithParameters(aInstance, aMessage, aMessageInfo, NULL, aContext, aTransmitHook);
1119 }
1120 
1121 /**
1122  * This function sends a CoAP response from the server.
1123  *
1124  * @param[in]  aInstance     A pointer to an OpenThread instance.
1125  * @param[in]  aMessage      A pointer to the CoAP response to send.
1126  * @param[in]  aMessageInfo  A pointer to the message info associated with @p aMessage.
1127  *
1128  * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
1129  * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
1130  *
1131  */
otCoapSendResponse(otInstance * aInstance,otMessage * aMessage,const otMessageInfo * aMessageInfo)1132 static inline otError otCoapSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo)
1133 {
1134     // NOLINTNEXTLINE(modernize-use-nullptr)
1135     return otCoapSendResponseWithParameters(aInstance, aMessage, aMessageInfo, NULL);
1136 }
1137 
1138 /**
1139  * @}
1140  *
1141  */
1142 
1143 #ifdef __cplusplus
1144 } // extern "C"
1145 #endif
1146 
1147 #endif /* OPENTHREAD_COAP_H_ */
1148