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_PROXY_URI      = 35, ///< Proxy-Uri
148
    OT_COAP_OPTION_PROXY_SCHEME   = 39, ///< Proxy-Scheme
149
    OT_COAP_OPTION_SIZE1          = 60, ///< Size1
150
} otCoapOptionType;
151

152
/**
153
 * CoAP Block Size Exponents
154
 */
155
typedef enum otCoapBlockSize
156
{
157
    OT_COAP_BLOCK_SIZE_16   = 0,
158
    OT_COAP_BLOCK_SIZE_32   = 1,
159
    OT_COAP_BLOCK_SIZE_64   = 2,
160
    OT_COAP_BLOCK_SIZE_128  = 3,
161
    OT_COAP_BLOCK_SIZE_256  = 4,
162
    OT_COAP_BLOCK_SIZE_512  = 5,
163
    OT_COAP_BLOCK_SIZE_1024 = 6,
164
} otCoapBlockSize;
165

166
/**
167
 * This structure represents a CoAP option.
168
 *
169
 */
170
typedef struct otCoapOption
171
{
172
    uint16_t mNumber; ///< Option Number
173
    uint16_t mLength; ///< Option Length
174
} otCoapOption;
175

176
/**
177
 * This structure acts as an iterator for CoAP options
178
 *
179
 */
180
typedef struct otCoapOptionIterator
181
{
182
    const otMessage *mMessage;          ///< CoAP message
183
    otCoapOption     mOption;           ///< CoAP message option
184
    uint16_t         mNextOptionOffset; ///< Byte offset of next option
185
} otCoapOptionIterator;
186

187
/**
188
 * CoAP Content Format codes.  The full list is documented at
189
 * https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats
190
 */
191
typedef enum otCoapOptionContentFormat
192
{
193
    /**
194
     * text/plain; charset=utf-8: [RFC2046][RFC3676][RFC5147]
195
     */
196
    OT_COAP_OPTION_CONTENT_FORMAT_TEXT_PLAIN = 0,
197

198
    /**
199
     * application/cose; cose-type="cose-encrypt0": [RFC8152]
200
     */
201
    OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT0 = 16,
202

203
    /**
204
     * application/cose; cose-type="cose-mac0": [RFC8152]
205
     */
206
    OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC0 = 17,
207

208
    /**
209
     * application/cose; cose-type="cose-sign1": [RFC8152]
210
     */
211
    OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN1 = 18,
212

213
    /**
214
     * application/link-format: [RFC6690]
215
     */
216
    OT_COAP_OPTION_CONTENT_FORMAT_LINK_FORMAT = 40,
217

218
    /**
219
     * application/xml: [RFC3023]
220
     */
221
    OT_COAP_OPTION_CONTENT_FORMAT_XML = 41,
222

223
    /**
224
     * application/octet-stream: [RFC2045][RFC2046]
225
     */
226
    OT_COAP_OPTION_CONTENT_FORMAT_OCTET_STREAM = 42,
227

228
    /**
229
     * application/exi:
230
     * ["Efficient XML Interchange (EXI) Format 1.0 (Second Edition)", February 2014]
231
     */
232
    OT_COAP_OPTION_CONTENT_FORMAT_EXI = 47,
233

234
    /**
235
     * application/json: [RFC7159]
236
     */
237
    OT_COAP_OPTION_CONTENT_FORMAT_JSON = 50,
238

239
    /**
240
     * application/json-patch+json: [RFC6902]
241
     */
242
    OT_COAP_OPTION_CONTENT_FORMAT_JSON_PATCH_JSON = 51,
243

244
    /**
245
     * application/merge-patch+json: [RFC7396]
246
     */
247
    OT_COAP_OPTION_CONTENT_FORMAT_MERGE_PATCH_JSON = 52,
248

249
    /**
250
     * application/cbor: [RFC7049]
251
     */
252
    OT_COAP_OPTION_CONTENT_FORMAT_CBOR = 60,
253

254
    /**
255
     * application/cwt: [RFC8392]
256
     */
257
    OT_COAP_OPTION_CONTENT_FORMAT_CWT = 61,
258

259
    /**
260
     * application/cose; cose-type="cose-encrypt": [RFC8152]
261
     */
262
    OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT = 96,
263

264
    /**
265
     * application/cose; cose-type="cose-mac": [RFC8152]
266
     */
267
    OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC = 97,
268

269
    /**
270
     * application/cose; cose-type="cose-sign": [RFC8152]
271
     */
272
    OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN = 98,
273

274
    /**
275
     * application/cose-key: [RFC8152]
276
     */
277
    OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY = 101,
278

279
    /**
280
     * application/cose-key-set: [RFC8152]
281
     */
282
    OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY_SET = 102,
283

284
    /**
285
     * application/senml+json: [RFC8428]
286
     */
287
    OT_COAP_OPTION_CONTENT_FORMAT_SENML_JSON = 110,
288

289
    /**
290
     * application/sensml+json: [RFC8428]
291
     */
292
    OT_COAP_OPTION_CONTENT_FORMAT_SENSML_JSON = 111,
293

294
    /**
295
     * application/senml+cbor: [RFC8428]
296
     */
297
    OT_COAP_OPTION_CONTENT_FORMAT_SENML_CBOR = 112,
298

299
    /**
300
     * application/sensml+cbor: [RFC8428]
301
     */
302
    OT_COAP_OPTION_CONTENT_FORMAT_SENSML_CBOR = 113,
303

304
    /**
305
     * application/senml-exi: [RFC8428]
306
     */
307
    OT_COAP_OPTION_CONTENT_FORMAT_SENML_EXI = 114,
308

309
    /**
310
     * application/sensml-exi: [RFC8428]
311
     */
312
    OT_COAP_OPTION_CONTENT_FORMAT_SENSML_EXI = 115,
313

314
    /**
315
     * application/coap-group+json: [RFC7390]
316
     */
317
    OT_COAP_OPTION_CONTENT_FORMAT_COAP_GROUP_JSON = 256,
318

319
    /**
320
     * application/senml+xml: [RFC8428]
321
     */
322
    OT_COAP_OPTION_CONTENT_FORMAT_SENML_XML = 310,
323

324
    /**
325
     * application/sensml+xml: [RFC8428]
326
     */
327
    OT_COAP_OPTION_CONTENT_FORMAT_SENSML_XML = 311
328
} otCoapOptionContentFormat;
329

330
/**
331
 * This function pointer is called when a CoAP response is received or on the request timeout.
332
 *
333
 * @param[in]  aContext      A pointer to application-specific context.
334
 * @param[in]  aMessage      A pointer to the message buffer containing the response. NULL if no response was received.
335
 * @param[in]  aMessageInfo  A pointer to the message info for @p aMessage. NULL if no response was received.
336
 * @param[in]  aResult       A result of the CoAP transaction.
337
 *
338
 * @retval  OT_ERROR_NONE              A response was received successfully.
339
 * @retval  OT_ERROR_ABORT             A CoAP transaction was reset by peer.
340
 * @retval  OT_ERROR_RESPONSE_TIMEOUT  No response or acknowledgment received during timeout period.
341
 *
342
 */
343
typedef void (*otCoapResponseHandler)(void *               aContext,
344
                                      otMessage *          aMessage,
345
                                      const otMessageInfo *aMessageInfo,
346
                                      otError              aResult);
347

348
/**
349
 * This function pointer is called when a CoAP request with a given Uri-Path is received.
350
 *
351
 * @param[in]  aContext      A pointer to arbitrary context information.
352
 * @param[in]  aMessage      A pointer to the message.
353
 * @param[in]  aMessageInfo  A pointer to the message info for @p aMessage.
354
 *
355
 */
356
typedef void (*otCoapRequestHandler)(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo);
357

358
/**
359
 * This structure represents a CoAP resource.
360
 *
361
 */
362
typedef struct otCoapResource
363
{
364
    const char *           mUriPath; ///< The URI Path string
365
    otCoapRequestHandler   mHandler; ///< The callback for handling a received request
366
    void *                 mContext; ///< Application-specific context
367
    struct otCoapResource *mNext;    ///< The next CoAP resource in the list
368
} otCoapResource;
369

370
/**
371
 * This structure represents the CoAP transmission parameters.
372
 *
373
 * @note mAckTimeout * ((2 ** (mMaxRetransmit + 1)) - 1) * (mAckRandomFactorNumerator / mAckRandomFactorDenominator)
374
 *       must not exceed what can be represented by a uint32_t (0xffffffff). This limitation allows OpenThread to
375
 *       avoid 64-bit arithmetic.
376
 *
377
 */
378
typedef struct otCoapTxParameters
379
{
380
    /**
381
     * Minimum spacing before first retransmission when ACK is not received, in milliseconds (RFC7252 default value is
382
     * 2000ms).
383
     *
384
     */
385
    uint32_t mAckTimeout;
386

387
    /**
388
     * Numerator of ACK_RANDOM_FACTOR used to calculate maximum spacing before first retransmission when ACK is not
389
     * received (RFC7252 default value of ACK_RANDOM_FACTOR is 1.5; must not be decreased below 1).
390
     *
391
     */
392
    uint8_t mAckRandomFactorNumerator;
393

394
    /**
395
     * Denominator of ACK_RANDOM_FACTOR used to calculate maximum spacing before first retransmission when ACK is not
396
     * received (RFC7252 default value of ACK_RANDOM_FACTOR is 1.5; must not be decreased below 1).
397
     *
398
     */
399
    uint8_t mAckRandomFactorDenominator;
400

401
    /**
402
     * Maximum number of retransmissions for CoAP Confirmable messages (RFC7252 default value is 4).
403
     *
404
     */
405
    uint8_t mMaxRetransmit;
406
} otCoapTxParameters;
407

408
/**
409
 * This function initializes the CoAP header.
410
 *
411
 * @param[inout] aMessage   A pointer to the CoAP message to initialize.
412
 * @param[in]    aType      CoAP message type.
413
 * @param[in]    aCode      CoAP message code.
414
 *
415
 */
416
void otCoapMessageInit(otMessage *aMessage, otCoapType aType, otCoapCode aCode);
417

418
/**
419
 * This function initializes a response message.
420
 *
421
 * @note Both message ID and token are set according to @p aRequest.
422
 *
423
 * @param[inout] aResponse  A pointer to the CoAP response message.
424
 * @param[in]    aRequest   A pointer to the CoAP request message.
425
 * @param[in]    aType      CoAP message type.
426
 * @param[in]    aCode      CoAP message code.
427
 *
428
 * @retval OT_ERROR_NONE     Successfully initialized the response message.
429
 * @retval OT_ERROR_NO_BUFS  Insufficient message buffers available to initialize the response message.
430
 *
431
 */
432
otError otCoapMessageInitResponse(otMessage *aResponse, const otMessage *aRequest, otCoapType aType, otCoapCode aCode);
433

434
/**
435
 * This function sets the Token value and length in a header.
436
 *
437
 * @param[inout]  aMessage          A pointer to the CoAP message.
438
 * @param[in]     aToken            A pointer to the Token value.
439
 * @param[in]     aTokenLength      The Length of @p aToken.
440
 *
441
 * @retval OT_ERROR_NONE     Successfully set the Token value.
442
 * @retval OT_ERROR_NO_BUFS  Insufficient buffers to set the Token value.
443
 *
444
 */
445
otError otCoapMessageSetToken(otMessage *aMessage, const uint8_t *aToken, uint8_t aTokenLength);
446

447
/**
448
 * This function sets the Token length and randomizes its value.
449
 *
450
 * @param[inout]  aMessage      A pointer to the CoAP message.
451
 * @param[in]     aTokenLength  The Length of a Token to set.
452
 *
453
 */
454
void otCoapMessageGenerateToken(otMessage *aMessage, uint8_t aTokenLength);
455

456
/**
457
 * This function appends the Content Format CoAP option as specified in
458
 * https://tools.ietf.org/html/rfc7252#page-92.  This *must* be called before
459
 * setting otCoapMessageSetPayloadMarker if a payload is to be included in the
460
 * message.
461
 *
462
 * The function is a convenience wrapper around otCoapMessageAppendUintOption,
463
 * and if the desired format type code isn't listed in otCoapOptionContentFormat,
464
 * this base function should be used instead.
465
 *
466
 * @param[inout]  aMessage          A pointer to the CoAP message.
467
 * @param[in]     aContentFormat    One of the content formats listed in
468
 *                                  otCoapOptionContentFormat above.
469
 *
470
 * @retval OT_ERROR_NONE          Successfully appended the option.
471
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
472
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
473
 *
474
 */
475
otError otCoapMessageAppendContentFormatOption(otMessage *aMessage, otCoapOptionContentFormat aContentFormat);
476

477
/**
478
 * This function appends a CoAP option in a header.
479
 *
480
 * @param[inout]  aMessage  A pointer to the CoAP message.
481
 * @param[in]     aNumber   The CoAP Option number.
482
 * @param[in]     aLength   The CoAP Option length.
483
 * @param[in]     aValue    A pointer to the CoAP value.
484
 *
485
 * @retval OT_ERROR_NONE          Successfully appended the option.
486
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
487
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
488
 *
489
 */
490
otError otCoapMessageAppendOption(otMessage *aMessage, uint16_t aNumber, uint16_t aLength, const void *aValue);
491

492
/**
493
 * This function appends an unsigned integer CoAP option as specified in
494
 * https://tools.ietf.org/html/rfc7252#section-3.2
495
 *
496
 * @param[inout]  aMessage A pointer to the CoAP message.
497
 * @param[in]     aNumber  The CoAP Option number.
498
 * @param[in]     aValue   The CoAP Option unsigned integer value.
499
 *
500
 * @retval OT_ERROR_NONE          Successfully appended the option.
501
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
502
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
503
 *
504
 * @see otCoapMessageGetOptionUintValue
505
 */
506
otError otCoapMessageAppendUintOption(otMessage *aMessage, uint16_t aNumber, uint32_t aValue);
507

508
/**
509
 * This function appends an Observe option.
510
 *
511
 * @param[inout]  aMessage  A pointer to the CoAP message.
512
 * @param[in]     aObserve  Observe field value.
513
 *
514
 * @retval OT_ERROR_NONE          Successfully appended the option.
515
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
516
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
517
 *
518
 */
519
otError otCoapMessageAppendObserveOption(otMessage *aMessage, uint32_t aObserve);
520

521
/**
522
 * This function appends a Uri-Path option.
523
 *
524
 * @param[inout]  aMessage  A pointer to the CoAP message.
525
 * @param[in]     aUriPath  A pointer to a NULL-terminated string.
526
 *
527
 * @retval OT_ERROR_NONE          Successfully appended the option.
528
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
529
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
530
 *
531
 */
532
otError otCoapMessageAppendUriPathOptions(otMessage *aMessage, const char *aUriPath);
533

534
/**
535
 * This function converts a CoAP Block option SZX field to the actual block size
536
 *
537
 * @param[in]     aSize     Block size exponent.
538
 *
539
 * @returns The actual size exponent value.
540
 *
541
 */
542
uint16_t otCoapBlockSizeFromExponent(otCoapBlockSize aSize);
543

544
/**
545
 * This function appends a Block2 option
546
 *
547
 * @param[inout]  aMessage  A pointer to the CoAP message.
548
 * @param[in]     aNum      Current block number.
549
 * @param[in]     aMore     Boolean to indicate more blocks are to be sent.
550
 * @param[in]     aSize     Block Size Exponent.
551
 *
552
 * @retval OT_ERROR_NONE          Successfully appended the option.
553
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
554
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
555
 *
556
 */
557
otError otCoapMessageAppendBlock2Option(otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSize aSize);
558

559
/**
560
 * This function appends a Block1 option
561
 *
562
 * @param[inout]  aMessage  A pointer to the CoAP message.
563
 * @param[in]     aNum      Current block number.
564
 * @param[in]     aMore     Boolean to indicate more blocks are to be sent.
565
 * @param[in]     aSize     Block Size Exponent.
566
 *
567
 * @retval OT_ERROR_NONE          Successfully appended the option.
568
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
569
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
570
 *
571
 */
572
otError otCoapMessageAppendBlock1Option(otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSize aSize);
573

574
/**
575
 * This function appends a Proxy-Uri option.
576
 *
577
 * @param[inout]  aMessage  A pointer to the CoAP message.
578
 * @param[in]     aUriPath  A pointer to a NULL-terminated string.
579
 *
580
 * @retval OT_ERROR_NONE          Successfully appended the option.
581
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
582
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
583
 *
584
 */
585
otError otCoapMessageAppendProxyUriOption(otMessage *aMessage, const char *aUriPath);
586

587
/**
588
 * This function appends a Max-Age option.
589
 *
590
 * @param[inout]  aMessage  A pointer to the CoAP message.
591
 * @param[in]     aMaxAge   The Max-Age value.
592
 *
593
 * @retval OT_ERROR_NONE          Successfully appended the option.
594
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
595
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
596
 *
597
 */
598
otError otCoapMessageAppendMaxAgeOption(otMessage *aMessage, uint32_t aMaxAge);
599

600
/**
601
 * This function appends a single Uri-Query option.
602
 *
603
 * @param[inout]  aMessage  A pointer to the CoAP message.
604
 * @param[in]     aUriQuery A pointer to NULL-terminated string, which should contain a single key=value pair.
605
 *
606
 * @retval OT_ERROR_NONE          Successfully appended the option.
607
 * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
608
 * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
609
 */
610
otError otCoapMessageAppendUriQueryOption(otMessage *aMessage, const char *aUriQuery);
611

612
/**
613
 * This function adds Payload Marker indicating beginning of the payload to the CoAP header.
614
 *
615
 * @param[inout]  aMessage  A pointer to the CoAP message.
616
 *
617
 * @retval OT_ERROR_NONE     Payload Marker successfully added.
618
 * @retval OT_ERROR_NO_BUFS  Header Payload Marker exceeds the buffer size.
619
 *
620
 */
621
otError otCoapMessageSetPayloadMarker(otMessage *aMessage);
622

623
/**
624
 * This function returns the Type value.
625
 *
626
 * @param[in]  aMessage  A pointer to the CoAP message.
627
 *
628
 * @returns The Type value.
629
 *
630
 */
631
otCoapType otCoapMessageGetType(const otMessage *aMessage);
632

633
/**
634
 * This function returns the Code value.
635
 *
636
 * @param[in]  aMessage  A pointer to the CoAP message.
637
 *
638
 * @returns The Code value.
639
 *
640
 */
641
otCoapCode otCoapMessageGetCode(const otMessage *aMessage);
642

643
/**
644
 * This method returns the CoAP Code as human readable string.
645
 *
646
 * @param[in]   aMessage    A pointer to the CoAP message.
647
 *
648
 * @ returns The CoAP Code as string.
649
 *
650
 */
651
const char *otCoapMessageCodeToString(const otMessage *aMessage);
652

653
/**
654
 * This function returns the Message ID value.
655
 *
656
 * @param[in]  aMessage  A pointer to the CoAP message.
657
 *
658
 * @returns The Message ID value.
659
 *
660
 */
661
uint16_t otCoapMessageGetMessageId(const otMessage *aMessage);
662

663
/**
664
 * This function returns the Token length.
665
 *
666
 * @param[in]  aMessage  A pointer to the CoAP message.
667
 *
668
 * @returns The Token length.
669
 *
670
 */
671
uint8_t otCoapMessageGetTokenLength(const otMessage *aMessage);
672

673
/**
674
 * This function returns a pointer to the Token value.
675
 *
676
 * @param[in]  aMessage  A pointer to the CoAP message.
677
 *
678
 * @returns A pointer to the Token value.
679
 *
680
 */
681
const uint8_t *otCoapMessageGetToken(const otMessage *aMessage);
682

683
/**
684
 * This function initialises an iterator for the options in the given message.
685
 *
686
 * @param[inout]  aIterator A pointer to the CoAP message option iterator.
687
 * @param[in]     aMessage  A pointer to the CoAP message.
688
 *
689
 * @retval  OT_ERROR_NONE   Successfully initialised.
690
 * @retval  OT_ERROR_PARSE  Message state is inconsistent.
691
 *
692
 */
693
otError otCoapOptionIteratorInit(otCoapOptionIterator *aIterator, const otMessage *aMessage);
694

695
/**
696
 * This function returns a pointer to the first option matching the specified option number.
697
 *
698
 * @param[in]  aIterator A pointer to the CoAP message option iterator.
699
 * @param[in]  aOption   The option number sought.
700
 *
701
 * @returns A pointer to the first matching option. If no matching option is present NULL pointer is returned.
702
 *
703
 */
704
const otCoapOption *otCoapOptionIteratorGetFirstOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption);
705

706
/**
707
 * This function returns a pointer to the first option.
708
 *
709
 * @param[inout]  aIterator A pointer to the CoAP message option iterator.
710
 *
711
 * @returns A pointer to the first option. If no option is present NULL pointer is returned.
712
 *
713
 */
714
const otCoapOption *otCoapOptionIteratorGetFirstOption(otCoapOptionIterator *aIterator);
715

716
/**
717
 * This function returns a pointer to the next option matching the specified option number.
718
 *
719
 * @param[in]  aIterator A pointer to the CoAP message option iterator.
720
 * @param[in]  aOption   The option number sought.
721
 *
722
 * @returns A pointer to the next matching option. If no further matching option is present NULL pointer is returned.
723
 *
724
 */
725
const otCoapOption *otCoapOptionIteratorGetNextOptionMatching(otCoapOptionIterator *aIterator, uint16_t aOption);
726

727
/**
728
 * This function returns a pointer to the next option.
729
 *
730
 * @param[inout]  aIterator A pointer to the CoAP message option iterator.
731
 *
732
 * @returns A pointer to the next option. If no more options are present NULL pointer is returned.
733
 *
734
 */
735
const otCoapOption *otCoapOptionIteratorGetNextOption(otCoapOptionIterator *aIterator);
736

737
/**
738
 * This function fills current option value into @p aValue assuming the current value is an unsigned integer encoded
739
 * according to https://tools.ietf.org/html/rfc7252#section-3.2
740
 *
741
 * @param[inout]    aIterator   A pointer to the CoAP message option iterator.
742
 * @param[out]      aValue      A pointer to an unsigned integer to receive the option value.
743
 *
744
 * @retval  OT_ERROR_NONE       Successfully filled value.
745
 * @retval  OT_ERROR_NOT_FOUND  No current option.
746
 * @retval  OT_ERROR_NO_BUFS    Value is too long to fit in a uint64_t.
747
 *
748
 * @see otCoapMessageAppendUintOption
749
 */
750
otError otCoapOptionIteratorGetOptionUintValue(otCoapOptionIterator *aIterator, uint64_t *const aValue);
751

752
/**
753
 * This function fills current option value into @p aValue.
754
 *
755
 * @param[inout]  aIterator A pointer to the CoAP message option iterator.
756
 * @param[out]    aValue    A pointer to a buffer to receive the option value.
757
 *
758
 * @retval  OT_ERROR_NONE       Successfully filled value.
759
 * @retval  OT_ERROR_NOT_FOUND  No current option.
760
 *
761
 */
762
otError otCoapOptionIteratorGetOptionValue(otCoapOptionIterator *aIterator, void *aValue);
763

764
/**
765
 * This function creates a new CoAP message.
766
 *
767
 * @note If @p aSettings is 'NULL', the link layer security is enabled and the message priority is set to
768
 * OT_MESSAGE_PRIORITY_NORMAL by default.
769
 *
770
 * @param[in]  aInstance  A pointer to an OpenThread instance.
771
 * @param[in]  aSettings  A pointer to the message settings or NULL to set default settings.
772
 *
773
 * @returns A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid.
774
 *
775
 */
776
otMessage *otCoapNewMessage(otInstance *aInstance, const otMessageSettings *aSettings);
777

778
/**
779
 * This function sends a CoAP request with custom transmission parameters.
780
 *
781
 * If a response for a request is expected, respective function and context information should be provided.
782
 * If no response is expected, these arguments should be NULL pointers.
783
 *
784
 * @param[in]  aInstance        A pointer to an OpenThread instance.
785
 * @param[in]  aMessage         A pointer to the message to send.
786
 * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
787
 * @param[in]  aHandler         A function pointer that shall be called on response reception or timeout.
788
 * @param[in]  aContext         A pointer to arbitrary context information. May be NULL if not used.
789
 * @param[in]  aTxParameters    A pointer to transmission parameters for this request. Use NULL for defaults.
790
 *                              Otherwise, parameters given must meet the following conditions:
791
 *                              1. mMaxRetransmit is no more than OT_COAP_MAX_RETRANSMIT.
792
 *                              2. mAckRandomFactorNumerator / mAckRandomFactorDenominator must not be below 1.0.
793
 *                              3. The calculated exchange life time must not overflow uint32_t.
794
 *
795
 * @retval OT_ERROR_INVALID_ARGS    @p aTxParameters is invalid.
796
 * @retval OT_ERROR_NONE            Successfully sent CoAP message.
797
 * @retval OT_ERROR_NO_BUFS         Failed to allocate retransmission data.
798
 *
799
 */
800
otError otCoapSendRequestWithParameters(otInstance *              aInstance,
801
                                        otMessage *               aMessage,
802
                                        const otMessageInfo *     aMessageInfo,
803
                                        otCoapResponseHandler     aHandler,
804
                                        void *                    aContext,
805
                                        const otCoapTxParameters *aTxParameters);
806

807
/**
808
 * This function sends a CoAP request.
809
 *
810
 * If a response for a request is expected, respective function and context information should be provided.
811
 * If no response is expected, these arguments should be NULL pointers.
812
 *
813
 * @param[in]  aInstance     A pointer to an OpenThread instance.
814
 * @param[in]  aMessage      A pointer to the message to send.
815
 * @param[in]  aMessageInfo  A pointer to the message info associated with @p aMessage.
816
 * @param[in]  aHandler      A function pointer that shall be called on response reception or timeout.
817
 * @param[in]  aContext      A pointer to arbitrary context information. May be NULL if not used.
818
 *
819
 * @retval OT_ERROR_NONE    Successfully sent CoAP message.
820
 * @retval OT_ERROR_NO_BUFS Failed to allocate retransmission data.
821
 *
822
 */
823 0
static inline otError otCoapSendRequest(otInstance *          aInstance,
824
                                        otMessage *           aMessage,
825
                                        const otMessageInfo * aMessageInfo,
826
                                        otCoapResponseHandler aHandler,
827
                                        void *                aContext)
828
{
829 0
    return otCoapSendRequestWithParameters(aInstance, aMessage, aMessageInfo, aHandler, aContext, NULL);
830
}
831

832
/**
833
 * This function starts the CoAP server.
834
 *
835
 * @param[in]  aInstance  A pointer to an OpenThread instance.
836
 * @param[in]  aPort      The local UDP port to bind to.
837
 *
838
 * @retval OT_ERROR_NONE    Successfully started the CoAP server.
839
 * @retval OT_ERROR_FAILED  Failed to start the CoAP server.
840
 *
841
 */
842
otError otCoapStart(otInstance *aInstance, uint16_t aPort);
843

844
/**
845
 * This function stops the CoAP server.
846
 *
847
 * @param[in]  aInstance  A pointer to an OpenThread instance.
848
 *
849
 * @retval OT_ERROR_NONE  Successfully stopped the CoAP server.
850
 *
851
 */
852
otError otCoapStop(otInstance *aInstance);
853

854
/**
855
 * This function adds a resource to the CoAP server.
856
 *
857
 * @param[in]  aInstance  A pointer to an OpenThread instance.
858
 * @param[in]  aResource  A pointer to the resource.
859
 *
860
 */
861
void otCoapAddResource(otInstance *aInstance, otCoapResource *aResource);
862

863
/**
864
 * This function removes a resource from the CoAP server.
865
 *
866
 * @param[in]  aInstance  A pointer to an OpenThread instance.
867
 * @param[in]  aResource  A pointer to the resource.
868
 *
869
 */
870
void otCoapRemoveResource(otInstance *aInstance, otCoapResource *aResource);
871

872
/**
873
 * This function sets the default handler for unhandled CoAP requests.
874
 *
875
 * @param[in]  aInstance  A pointer to an OpenThread instance.
876
 * @param[in]  aHandler   A function pointer that shall be called when an unhandled request arrives.
877
 * @param[in]  aContext   A pointer to arbitrary context information. May be NULL if not used.
878
 *
879
 */
880
void otCoapSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext);
881

882
/**
883
 * This function sends a CoAP response from the server with custom transmission parameters.
884
 *
885
 * @param[in]  aInstance        A pointer to an OpenThread instance.
886
 * @param[in]  aMessage         A pointer to the CoAP response to send.
887
 * @param[in]  aMessageInfo     A pointer to the message info associated with @p aMessage.
888
 * @param[in]  aTxParameters    A pointer to transmission parameters for this response. Use NULL for defaults.
889
 *
890
 * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
891
 * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
892
 *
893
 */
894
otError otCoapSendResponseWithParameters(otInstance *              aInstance,
895
                                         otMessage *               aMessage,
896
                                         const otMessageInfo *     aMessageInfo,
897
                                         const otCoapTxParameters *aTxParameters);
898

899
/**
900
 * This function sends a CoAP response from the server.
901
 *
902
 * @param[in]  aInstance     A pointer to an OpenThread instance.
903
 * @param[in]  aMessage      A pointer to the CoAP response to send.
904
 * @param[in]  aMessageInfo  A pointer to the message info associated with @p aMessage.
905
 *
906
 * @retval OT_ERROR_NONE     Successfully enqueued the CoAP response message.
907
 * @retval OT_ERROR_NO_BUFS  Insufficient buffers available to send the CoAP response.
908
 *
909
 */
910
static inline otError otCoapSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo)
911
{
912
    return otCoapSendResponseWithParameters(aInstance, aMessage, aMessageInfo, NULL);
913
}
914

915
/**
916
 * @}
917
 *
918
 */
919

920
#ifdef __cplusplus
921
} // extern "C"
922
#endif
923

924
#endif /* OPENTHREAD_COAP_H_ */

Read our documentation on viewing source code .

Loading