CoAP

This module includes functions that control CoAP communication.

Classes

struct  otCoapOption
 This structure represents a CoAP option.
 
struct  otCoapOptionIterator
 This structure acts as an iterator for CoAP options.
 
struct  otCoapResource
 This structure represents a CoAP resource.
 
struct  otCoapTxParameters
 This structure represents the CoAP transmission parameters.

Macros

#define OT_DEFAULT_COAP_PORT   5683
 Default CoAP port, as specified in RFC 7252.
 
#define OT_COAP_MAX_TOKEN_LENGTH   8
 Max token length as specified (RFC 7252).
 
#define OT_COAP_MAX_RETRANSMIT   30
 Max retransmit supported by OpenThread.
 
#define OT_COAP_MIN_ACK_TIMEOUT   1000
 Minimal ACK timeout in milliseconds supported by OpenThread.
 
#define OT_COAP_CODE(c, d)   ((((c)&0x7) << 5) | ((d)&0x1f))
 Helper macro to define CoAP Code values.

Typedefs

typedef enum otCoapType otCoapType
 CoAP Type values.
 
typedef enum otCoapCode otCoapCode
 CoAP Code values.
 
typedef enum otCoapOptionType otCoapOptionType
 CoAP Option Numbers.
 
typedef enum otCoapBlockSize otCoapBlockSize
 CoAP Block Size Exponents.
 
typedef struct otCoapOption otCoapOption
 This structure represents a CoAP option.
 
typedef struct otCoapOptionIterator otCoapOptionIterator
 This structure acts as an iterator for CoAP options.
 
typedef enum otCoapOptionContentFormat otCoapOptionContentFormat
 CoAP Content Format codes.
 
typedef void(* otCoapResponseHandler) (void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo, otError aResult)
 This function pointer is called when a CoAP response is received or on the request timeout.
 
typedef void(* otCoapRequestHandler) (void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo)
 This function pointer is called when a CoAP request with a given Uri-Path is received.
 
typedef struct otCoapResource otCoapResource
 This structure represents a CoAP resource.
 
typedef struct otCoapTxParameters otCoapTxParameters
 This structure represents the CoAP transmission parameters.

Enumerations

enum  otCoapType {
  OT_COAP_TYPE_CONFIRMABLE = 0x00,
  OT_COAP_TYPE_NON_CONFIRMABLE = 0x10,
  OT_COAP_TYPE_ACKNOWLEDGMENT = 0x20,
  OT_COAP_TYPE_RESET = 0x30
}
 CoAP Type values.
 
enum  otCoapCode {
  OT_COAP_CODE_EMPTY = OT_COAP_CODE(0, 0),
  OT_COAP_CODE_GET = OT_COAP_CODE(0, 1),
  OT_COAP_CODE_POST = OT_COAP_CODE(0, 2),
  OT_COAP_CODE_PUT = OT_COAP_CODE(0, 3),
  OT_COAP_CODE_DELETE = OT_COAP_CODE(0, 4),
  OT_COAP_CODE_RESPONSE_MIN = OT_COAP_CODE(2, 0),
  OT_COAP_CODE_CREATED = OT_COAP_CODE(2, 1),
  OT_COAP_CODE_DELETED = OT_COAP_CODE(2, 2),
  OT_COAP_CODE_VALID = OT_COAP_CODE(2, 3),
  OT_COAP_CODE_CHANGED = OT_COAP_CODE(2, 4),
  OT_COAP_CODE_CONTENT = OT_COAP_CODE(2, 5),
  OT_COAP_CODE_CONTINUE = OT_COAP_CODE(2, 31),
  OT_COAP_CODE_BAD_REQUEST = OT_COAP_CODE(4, 0),
  OT_COAP_CODE_UNAUTHORIZED = OT_COAP_CODE(4, 1),
  OT_COAP_CODE_BAD_OPTION = OT_COAP_CODE(4, 2),
  OT_COAP_CODE_FORBIDDEN = OT_COAP_CODE(4, 3),
  OT_COAP_CODE_NOT_FOUND = OT_COAP_CODE(4, 4),
  OT_COAP_CODE_METHOD_NOT_ALLOWED = OT_COAP_CODE(4, 5),
  OT_COAP_CODE_NOT_ACCEPTABLE = OT_COAP_CODE(4, 6),
  OT_COAP_CODE_REQUEST_INCOMPLETE = OT_COAP_CODE(4, 8),
  OT_COAP_CODE_PRECONDITION_FAILED = OT_COAP_CODE(4, 12),
  OT_COAP_CODE_REQUEST_TOO_LARGE = OT_COAP_CODE(4, 13),
  OT_COAP_CODE_UNSUPPORTED_FORMAT = OT_COAP_CODE(4, 15),
  OT_COAP_CODE_INTERNAL_ERROR = OT_COAP_CODE(5, 0),
  OT_COAP_CODE_NOT_IMPLEMENTED = OT_COAP_CODE(5, 1),
  OT_COAP_CODE_BAD_GATEWAY = OT_COAP_CODE(5, 2),
  OT_COAP_CODE_SERVICE_UNAVAILABLE = OT_COAP_CODE(5, 3),
  OT_COAP_CODE_GATEWAY_TIMEOUT = OT_COAP_CODE(5, 4),
  OT_COAP_CODE_PROXY_NOT_SUPPORTED = OT_COAP_CODE(5, 5)
}
 CoAP Code values.
 
enum  otCoapOptionType {
  OT_COAP_OPTION_IF_MATCH = 1,
  OT_COAP_OPTION_URI_HOST = 3,
  OT_COAP_OPTION_E_TAG = 4,
  OT_COAP_OPTION_IF_NONE_MATCH = 5,
  OT_COAP_OPTION_OBSERVE = 6,
  OT_COAP_OPTION_URI_PORT = 7,
  OT_COAP_OPTION_LOCATION_PATH = 8,
  OT_COAP_OPTION_URI_PATH = 11,
  OT_COAP_OPTION_CONTENT_FORMAT = 12,
  OT_COAP_OPTION_MAX_AGE = 14,
  OT_COAP_OPTION_URI_QUERY = 15,
  OT_COAP_OPTION_ACCEPT = 17,
  OT_COAP_OPTION_LOCATION_QUERY = 20,
  OT_COAP_OPTION_BLOCK2 = 23,
  OT_COAP_OPTION_BLOCK1 = 27,
  OT_COAP_OPTION_PROXY_URI = 35,
  OT_COAP_OPTION_PROXY_SCHEME = 39,
  OT_COAP_OPTION_SIZE1 = 60
}
 CoAP Option Numbers.
 
enum  otCoapBlockSize {
  OT_COAP_BLOCK_SIZE_16 = 0,
  OT_COAP_BLOCK_SIZE_32 = 1,
  OT_COAP_BLOCK_SIZE_64 = 2,
  OT_COAP_BLOCK_SIZE_128 = 3,
  OT_COAP_BLOCK_SIZE_256 = 4,
  OT_COAP_BLOCK_SIZE_512 = 5,
  OT_COAP_BLOCK_SIZE_1024 = 6
}
 CoAP Block Size Exponents.
 
enum  otCoapOptionContentFormat {
  OT_COAP_OPTION_CONTENT_FORMAT_TEXT_PLAIN = 0,
  OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT0 = 16,
  OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC0 = 17,
  OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN1 = 18,
  OT_COAP_OPTION_CONTENT_FORMAT_LINK_FORMAT = 40,
  OT_COAP_OPTION_CONTENT_FORMAT_XML = 41,
  OT_COAP_OPTION_CONTENT_FORMAT_OCTET_STREAM = 42,
  OT_COAP_OPTION_CONTENT_FORMAT_EXI = 47,
  OT_COAP_OPTION_CONTENT_FORMAT_JSON = 50,
  OT_COAP_OPTION_CONTENT_FORMAT_JSON_PATCH_JSON = 51,
  OT_COAP_OPTION_CONTENT_FORMAT_MERGE_PATCH_JSON = 52,
  OT_COAP_OPTION_CONTENT_FORMAT_CBOR = 60,
  OT_COAP_OPTION_CONTENT_FORMAT_CWT = 61,
  OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT = 96,
  OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC = 97,
  OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN = 98,
  OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY = 101,
  OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY_SET = 102,
  OT_COAP_OPTION_CONTENT_FORMAT_SENML_JSON = 110,
  OT_COAP_OPTION_CONTENT_FORMAT_SENSML_JSON = 111,
  OT_COAP_OPTION_CONTENT_FORMAT_SENML_CBOR = 112,
  OT_COAP_OPTION_CONTENT_FORMAT_SENSML_CBOR = 113,
  OT_COAP_OPTION_CONTENT_FORMAT_SENML_EXI = 114,
  OT_COAP_OPTION_CONTENT_FORMAT_SENSML_EXI = 115,
  OT_COAP_OPTION_CONTENT_FORMAT_COAP_GROUP_JSON = 256,
  OT_COAP_OPTION_CONTENT_FORMAT_SENML_XML = 310,
  OT_COAP_OPTION_CONTENT_FORMAT_SENSML_XML = 311
}
 CoAP Content Format codes.

Functions

void otCoapMessageInit (otMessage *aMessage, otCoapType aType, otCoapCode aCode)
 This function initializes the CoAP header.
 
otError otCoapMessageInitResponse (otMessage *aResponse, const otMessage *aRequest, otCoapType aType, otCoapCode aCode)
 This function initializes a response message.
 
otError otCoapMessageSetToken (otMessage *aMessage, const uint8_t *aToken, uint8_t aTokenLength)
 This function sets the Token value and length in a header.
 
void otCoapMessageGenerateToken (otMessage *aMessage, uint8_t aTokenLength)
 This function sets the Token length and randomizes its value.
 
otError otCoapMessageAppendContentFormatOption (otMessage *aMessage, otCoapOptionContentFormat aContentFormat)
 This function appends the Content Format CoAP option as specified in https://tools.ietf.org/html/rfc7252#page-92.
 
otError otCoapMessageAppendOption (otMessage *aMessage, uint16_t aNumber, uint16_t aLength, const void *aValue)
 This function appends a CoAP option in a header.
 
otError otCoapMessageAppendUintOption (otMessage *aMessage, uint16_t aNumber, uint32_t aValue)
 This function appends an unsigned integer CoAP option as specified in https://tools.ietf.org/html/rfc7252#section-3.2.
 
otError otCoapMessageAppendObserveOption (otMessage *aMessage, uint32_t aObserve)
 This function appends an Observe option.
 
otError otCoapMessageAppendUriPathOptions (otMessage *aMessage, const char *aUriPath)
 This function appends a Uri-Path option.
 
uint16_t otCoapBlockSizeFromExponent (otCoapBlockSize aSize)
 This function converts a CoAP Block option SZX field to the actual block size.
 
otError otCoapMessageAppendBlock2Option (otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSize aSize)
 This function appends a Block2 option.
 
otError otCoapMessageAppendBlock1Option (otMessage *aMessage, uint32_t aNum, bool aMore, otCoapBlockSize aSize)
 This function appends a Block1 option.
 
otError otCoapMessageAppendProxyUriOption (otMessage *aMessage, const char *aUriPath)
 This function appends a Proxy-Uri option.
 
otError otCoapMessageAppendMaxAgeOption (otMessage *aMessage, uint32_t aMaxAge)
 This function appends a Max-Age option.
 
otError otCoapMessageAppendUriQueryOption (otMessage *aMessage, const char *aUriQuery)
 This function appends a single Uri-Query option.
 
otError otCoapMessageSetPayloadMarker (otMessage *aMessage)
 This function adds Payload Marker indicating beginning of the payload to the CoAP header.
 
otCoapType otCoapMessageGetType (const otMessage *aMessage)
 This function returns the Type value.
 
otCoapCode otCoapMessageGetCode (const otMessage *aMessage)
 This function returns the Code value.
 
const char * otCoapMessageCodeToString (const otMessage *aMessage)
 This method returns the CoAP Code as human readable string.
 
uint16_t otCoapMessageGetMessageId (const otMessage *aMessage)
 This function returns the Message ID value.
 
uint8_t otCoapMessageGetTokenLength (const otMessage *aMessage)
 This function returns the Token length.
 
const uint8_t * otCoapMessageGetToken (const otMessage *aMessage)
 This function returns a pointer to the Token value.
 
otError otCoapOptionIteratorInit (otCoapOptionIterator *aIterator, const otMessage *aMessage)
 This function initialises an iterator for the options in the given message.
 
const otCoapOptionotCoapOptionIteratorGetFirstOptionMatching (otCoapOptionIterator *aIterator, uint16_t aOption)
 This function returns a pointer to the first option matching the specified option number.
 
const otCoapOptionotCoapOptionIteratorGetFirstOption (otCoapOptionIterator *aIterator)
 This function returns a pointer to the first option.
 
const otCoapOptionotCoapOptionIteratorGetNextOptionMatching (otCoapOptionIterator *aIterator, uint16_t aOption)
 This function returns a pointer to the next option matching the specified option number.
 
const otCoapOptionotCoapOptionIteratorGetNextOption (otCoapOptionIterator *aIterator)
 This function returns a pointer to the next option.
 
otError otCoapOptionIteratorGetOptionUintValue (otCoapOptionIterator *aIterator, uint64_t *const aValue)
 This function fills current option value into aValue assuming the current value is an unsigned integer encoded according to https://tools.ietf.org/html/rfc7252#section-3.2.
 
otError otCoapOptionIteratorGetOptionValue (otCoapOptionIterator *aIterator, void *aValue)
 This function fills current option value into aValue.
 
otMessageotCoapNewMessage (otInstance *aInstance, const otMessageSettings *aSettings)
 This function creates a new CoAP message.
 
otError otCoapSendRequestWithParameters (otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo, otCoapResponseHandler aHandler, void *aContext, const otCoapTxParameters *aTxParameters)
 This function sends a CoAP request with custom transmission parameters.
 
static otError otCoapSendRequest (otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo, otCoapResponseHandler aHandler, void *aContext)
 This function sends a CoAP request.
 
otError otCoapStart (otInstance *aInstance, uint16_t aPort)
 This function starts the CoAP server.
 
otError otCoapStop (otInstance *aInstance)
 This function stops the CoAP server.
 
otError otCoapAddResource (otInstance *aInstance, otCoapResource *aResource)
 This function adds a resource to the CoAP server.
 
void otCoapRemoveResource (otInstance *aInstance, otCoapResource *aResource)
 This function removes a resource from the CoAP server.
 
void otCoapSetDefaultHandler (otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext)
 This function sets the default handler for unhandled CoAP requests.
 
otError otCoapSendResponseWithParameters (otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo, const otCoapTxParameters *aTxParameters)
 This function sends a CoAP response from the server with custom transmission parameters.
 
static otError otCoapSendResponse (otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo)
 This function sends a CoAP response from the server.

Detailed Description

This module includes functions that control CoAP communication.

The functions in this module are available when CoAP API feature (OPENTHREAD_CONFIG_COAP_API_ENABLE) is enabled.

Typedef Documentation

◆ otCoapOptionContentFormat

◆ otCoapOptionIterator

This structure acts as an iterator for CoAP options.

◆ otCoapRequestHandler

typedef void(* otCoapRequestHandler) (void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo)

This function pointer is called when a CoAP request with a given Uri-Path is received.

Parameters
[in]aContextA pointer to arbitrary context information.
[in]aMessageA pointer to the message.
[in]aMessageInfoA pointer to the message info for aMessage.

◆ otCoapResponseHandler

typedef void(* otCoapResponseHandler) (void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo, otError aResult)

This function pointer is called when a CoAP response is received or on the request timeout.

Parameters
[in]aContextA pointer to application-specific context.
[in]aMessageA pointer to the message buffer containing the response. NULL if no response was received.
[in]aMessageInfoA pointer to the message info for aMessage. NULL if no response was received.
[in]aResultA result of the CoAP transaction.
Return values
OT_ERROR_NONEA response was received successfully.
OT_ERROR_ABORTA CoAP transaction was reset by peer.
OT_ERROR_RESPONSE_TIMEOUTNo response or acknowledgment received during timeout period.

Enumeration Type Documentation

◆ otCoapCode

enum otCoapCode

CoAP Code values.

Enumerator
OT_COAP_CODE_EMPTY 

Empty message code.

OT_COAP_CODE_GET 

Get.

OT_COAP_CODE_POST 

Post.

OT_COAP_CODE_PUT 

Put.

OT_COAP_CODE_DELETE 

Delete.

OT_COAP_CODE_RESPONSE_MIN 

2.00

OT_COAP_CODE_CREATED 

Created.

OT_COAP_CODE_DELETED 

Deleted.

OT_COAP_CODE_VALID 

Valid.

OT_COAP_CODE_CHANGED 

Changed.

OT_COAP_CODE_CONTENT 

Content.

OT_COAP_CODE_CONTINUE 

RFC7959 Continue.

OT_COAP_CODE_BAD_REQUEST 

Bad Request.

OT_COAP_CODE_UNAUTHORIZED 

Unauthorized.

OT_COAP_CODE_BAD_OPTION 

Bad Option.

OT_COAP_CODE_FORBIDDEN 

Forbidden.

OT_COAP_CODE_NOT_FOUND 

Not Found.

OT_COAP_CODE_METHOD_NOT_ALLOWED 

Method Not Allowed.

OT_COAP_CODE_NOT_ACCEPTABLE 

Not Acceptable.

OT_COAP_CODE_REQUEST_INCOMPLETE 

RFC7959 Request Entity Incomplete.

OT_COAP_CODE_PRECONDITION_FAILED 

Precondition Failed.

OT_COAP_CODE_REQUEST_TOO_LARGE 

Request Entity Too Large.

OT_COAP_CODE_UNSUPPORTED_FORMAT 

Unsupported Content-Format.

OT_COAP_CODE_INTERNAL_ERROR 

Internal Server Error.

OT_COAP_CODE_NOT_IMPLEMENTED 

Not Implemented.

OT_COAP_CODE_BAD_GATEWAY 

Bad Gateway.

OT_COAP_CODE_SERVICE_UNAVAILABLE 

Service Unavailable.

OT_COAP_CODE_GATEWAY_TIMEOUT 

Gateway Timeout.

OT_COAP_CODE_PROXY_NOT_SUPPORTED 

Proxying Not Supported.

◆ otCoapOptionContentFormat

CoAP Content Format codes.

The full list is documented at https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats

Enumerator
OT_COAP_OPTION_CONTENT_FORMAT_TEXT_PLAIN 

text/plain; charset=utf-8: [RFC2046][RFC3676][RFC5147]

OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT0 

application/cose; cose-type="cose-encrypt0": [RFC8152]

OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC0 

application/cose; cose-type="cose-mac0": [RFC8152]

OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN1 

application/cose; cose-type="cose-sign1": [RFC8152]

OT_COAP_OPTION_CONTENT_FORMAT_LINK_FORMAT 

application/link-format: [RFC6690]

OT_COAP_OPTION_CONTENT_FORMAT_XML 

application/xml: [RFC3023]

OT_COAP_OPTION_CONTENT_FORMAT_OCTET_STREAM 

application/octet-stream: [RFC2045][RFC2046]

OT_COAP_OPTION_CONTENT_FORMAT_EXI 

application/exi: ["Efficient XML Interchange (EXI) Format 1.0 (Second Edition)", February 2014]

OT_COAP_OPTION_CONTENT_FORMAT_JSON 

application/json: [RFC7159]

OT_COAP_OPTION_CONTENT_FORMAT_JSON_PATCH_JSON 

application/json-patch+json: [RFC6902]

OT_COAP_OPTION_CONTENT_FORMAT_MERGE_PATCH_JSON 

application/merge-patch+json: [RFC7396]

OT_COAP_OPTION_CONTENT_FORMAT_CBOR 

application/cbor: [RFC7049]

OT_COAP_OPTION_CONTENT_FORMAT_CWT 

application/cwt: [RFC8392]

OT_COAP_OPTION_CONTENT_FORMAT_COSE_ENCRYPT 

application/cose; cose-type="cose-encrypt": [RFC8152]

OT_COAP_OPTION_CONTENT_FORMAT_COSE_MAC 

application/cose; cose-type="cose-mac": [RFC8152]

OT_COAP_OPTION_CONTENT_FORMAT_COSE_SIGN 

application/cose; cose-type="cose-sign": [RFC8152]

OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY 

application/cose-key: [RFC8152]

OT_COAP_OPTION_CONTENT_FORMAT_COSE_KEY_SET 

application/cose-key-set: [RFC8152]

OT_COAP_OPTION_CONTENT_FORMAT_SENML_JSON 

application/senml+json: [RFC8428]

OT_COAP_OPTION_CONTENT_FORMAT_SENSML_JSON 

application/sensml+json: [RFC8428]

OT_COAP_OPTION_CONTENT_FORMAT_SENML_CBOR 

application/senml+cbor: [RFC8428]

OT_COAP_OPTION_CONTENT_FORMAT_SENSML_CBOR 

application/sensml+cbor: [RFC8428]

OT_COAP_OPTION_CONTENT_FORMAT_SENML_EXI 

application/senml-exi: [RFC8428]

OT_COAP_OPTION_CONTENT_FORMAT_SENSML_EXI 

application/sensml-exi: [RFC8428]

OT_COAP_OPTION_CONTENT_FORMAT_COAP_GROUP_JSON 

application/coap-group+json: [RFC7390]

OT_COAP_OPTION_CONTENT_FORMAT_SENML_XML 

application/senml+xml: [RFC8428]

OT_COAP_OPTION_CONTENT_FORMAT_SENSML_XML 

application/sensml+xml: [RFC8428]

◆ otCoapOptionType

CoAP Option Numbers.

Enumerator
OT_COAP_OPTION_IF_MATCH 

If-Match.

OT_COAP_OPTION_URI_HOST 

Uri-Host.

OT_COAP_OPTION_E_TAG 

ETag.

OT_COAP_OPTION_IF_NONE_MATCH 

If-None-Match.

OT_COAP_OPTION_OBSERVE 

Observe [RFC7641].

OT_COAP_OPTION_URI_PORT 

Uri-Port.

OT_COAP_OPTION_LOCATION_PATH 

Location-Path.

OT_COAP_OPTION_URI_PATH 

Uri-Path.

OT_COAP_OPTION_CONTENT_FORMAT 

Content-Format.

OT_COAP_OPTION_MAX_AGE 

Max-Age.

OT_COAP_OPTION_URI_QUERY 

Uri-Query.

OT_COAP_OPTION_ACCEPT 

Accept.

OT_COAP_OPTION_LOCATION_QUERY 

Location-Query.

OT_COAP_OPTION_BLOCK2 

Block2 (RFC7959)

OT_COAP_OPTION_BLOCK1 

Block1 (RFC7959)

OT_COAP_OPTION_PROXY_URI 

Proxy-Uri.

OT_COAP_OPTION_PROXY_SCHEME 

Proxy-Scheme.

OT_COAP_OPTION_SIZE1 

Size1.

◆ otCoapType

enum otCoapType

CoAP Type values.

Enumerator
OT_COAP_TYPE_CONFIRMABLE 

Confirmable.

OT_COAP_TYPE_NON_CONFIRMABLE 

Non-confirmable.

OT_COAP_TYPE_ACKNOWLEDGMENT 

Acknowledgment.

OT_COAP_TYPE_RESET 

Reset.

Function Documentation

◆ otCoapAddResource()

otError otCoapAddResource ( otInstance aInstance,
otCoapResource aResource 
)

This function adds a resource to the CoAP server.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aResourceA pointer to the resource.
Return values
OT_ERROR_NONESuccessfully added aResource.
OT_ERROR_ALREADYThe aResource was already added.

◆ otCoapBlockSizeFromExponent()

uint16_t otCoapBlockSizeFromExponent ( otCoapBlockSize  aSize)

This function converts a CoAP Block option SZX field to the actual block size.

Parameters
[in]aSizeBlock size exponent.
Returns
The actual size exponent value.

◆ otCoapMessageAppendBlock1Option()

otError otCoapMessageAppendBlock1Option ( otMessage aMessage,
uint32_t  aNum,
bool  aMore,
otCoapBlockSize  aSize 
)

This function appends a Block1 option.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aNumCurrent block number.
[in]aMoreBoolean to indicate more blocks are to be sent.
[in]aSizeBlock Size Exponent.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.

◆ otCoapMessageAppendBlock2Option()

otError otCoapMessageAppendBlock2Option ( otMessage aMessage,
uint32_t  aNum,
bool  aMore,
otCoapBlockSize  aSize 
)

This function appends a Block2 option.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aNumCurrent block number.
[in]aMoreBoolean to indicate more blocks are to be sent.
[in]aSizeBlock Size Exponent.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.

◆ otCoapMessageAppendContentFormatOption()

otError otCoapMessageAppendContentFormatOption ( otMessage aMessage,
otCoapOptionContentFormat  aContentFormat 
)

This function appends the Content Format CoAP option as specified in https://tools.ietf.org/html/rfc7252#page-92.

This must be called before setting otCoapMessageSetPayloadMarker if a payload is to be included in the message.

The function is a convenience wrapper around otCoapMessageAppendUintOption, and if the desired format type code isn't listed in otCoapOptionContentFormat, this base function should be used instead.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aContentFormatOne of the content formats listed in otCoapOptionContentFormat above.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.

◆ otCoapMessageAppendMaxAgeOption()

otError otCoapMessageAppendMaxAgeOption ( otMessage aMessage,
uint32_t  aMaxAge 
)

This function appends a Max-Age option.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aMaxAgeThe Max-Age value.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.

◆ otCoapMessageAppendObserveOption()

otError otCoapMessageAppendObserveOption ( otMessage aMessage,
uint32_t  aObserve 
)

This function appends an Observe option.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aObserveObserve field value.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.

◆ otCoapMessageAppendOption()

otError otCoapMessageAppendOption ( otMessage aMessage,
uint16_t  aNumber,
uint16_t  aLength,
const void *  aValue 
)

This function appends a CoAP option in a header.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aNumberThe CoAP Option number.
[in]aLengthThe CoAP Option length.
[in]aValueA pointer to the CoAP value.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.

◆ otCoapMessageAppendProxyUriOption()

otError otCoapMessageAppendProxyUriOption ( otMessage aMessage,
const char *  aUriPath 
)

This function appends a Proxy-Uri option.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aUriPathA pointer to a NULL-terminated string.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.

◆ otCoapMessageAppendUintOption()

otError otCoapMessageAppendUintOption ( otMessage aMessage,
uint16_t  aNumber,
uint32_t  aValue 
)

This function appends an unsigned integer CoAP option as specified in https://tools.ietf.org/html/rfc7252#section-3.2.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aNumberThe CoAP Option number.
[in]aValueThe CoAP Option unsigned integer value.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.
See also
otCoapMessageGetOptionUintValue

◆ otCoapMessageAppendUriPathOptions()

otError otCoapMessageAppendUriPathOptions ( otMessage aMessage,
const char *  aUriPath 
)

This function appends a Uri-Path option.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aUriPathA pointer to a NULL-terminated string.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.

◆ otCoapMessageAppendUriQueryOption()

otError otCoapMessageAppendUriQueryOption ( otMessage aMessage,
const char *  aUriQuery 
)

This function appends a single Uri-Query option.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aUriQueryA pointer to NULL-terminated string, which should contain a single key=value pair.
Return values
OT_ERROR_NONESuccessfully appended the option.
OT_ERROR_INVALID_ARGSThe option type is not equal or greater than the last option type.
OT_ERROR_NO_BUFSThe option length exceeds the buffer size.

◆ otCoapMessageCodeToString()

const char* otCoapMessageCodeToString ( const otMessage aMessage)

This method returns the CoAP Code as human readable string.

Parameters
[in]aMessageA pointer to the CoAP message.

@ returns The CoAP Code as string.

◆ otCoapMessageGenerateToken()

void otCoapMessageGenerateToken ( otMessage aMessage,
uint8_t  aTokenLength 
)

This function sets the Token length and randomizes its value.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aTokenLengthThe Length of a Token to set.

◆ otCoapMessageGetCode()

otCoapCode otCoapMessageGetCode ( const otMessage aMessage)

This function returns the Code value.

Parameters
[in]aMessageA pointer to the CoAP message.
Returns
The Code value.

◆ otCoapMessageGetMessageId()

uint16_t otCoapMessageGetMessageId ( const otMessage aMessage)

This function returns the Message ID value.

Parameters
[in]aMessageA pointer to the CoAP message.
Returns
The Message ID value.

◆ otCoapMessageGetToken()

const uint8_t* otCoapMessageGetToken ( const otMessage aMessage)

This function returns a pointer to the Token value.

Parameters
[in]aMessageA pointer to the CoAP message.
Returns
A pointer to the Token value.

◆ otCoapMessageGetTokenLength()

uint8_t otCoapMessageGetTokenLength ( const otMessage aMessage)

This function returns the Token length.

Parameters
[in]aMessageA pointer to the CoAP message.
Returns
The Token length.

◆ otCoapMessageGetType()

otCoapType otCoapMessageGetType ( const otMessage aMessage)

This function returns the Type value.

Parameters
[in]aMessageA pointer to the CoAP message.
Returns
The Type value.

◆ otCoapMessageInit()

void otCoapMessageInit ( otMessage aMessage,
otCoapType  aType,
otCoapCode  aCode 
)

This function initializes the CoAP header.

Parameters
[in,out]aMessageA pointer to the CoAP message to initialize.
[in]aTypeCoAP message type.
[in]aCodeCoAP message code.

◆ otCoapMessageInitResponse()

otError otCoapMessageInitResponse ( otMessage aResponse,
const otMessage aRequest,
otCoapType  aType,
otCoapCode  aCode 
)

This function initializes a response message.

Note
Both message ID and token are set according to aRequest.
Parameters
[in,out]aResponseA pointer to the CoAP response message.
[in]aRequestA pointer to the CoAP request message.
[in]aTypeCoAP message type.
[in]aCodeCoAP message code.
Return values
OT_ERROR_NONESuccessfully initialized the response message.
OT_ERROR_NO_BUFSInsufficient message buffers available to initialize the response message.

◆ otCoapMessageSetPayloadMarker()

otError otCoapMessageSetPayloadMarker ( otMessage aMessage)

This function adds Payload Marker indicating beginning of the payload to the CoAP header.

Parameters
[in,out]aMessageA pointer to the CoAP message.
Return values
OT_ERROR_NONEPayload Marker successfully added.
OT_ERROR_NO_BUFSHeader Payload Marker exceeds the buffer size.

◆ otCoapMessageSetToken()

otError otCoapMessageSetToken ( otMessage aMessage,
const uint8_t *  aToken,
uint8_t  aTokenLength 
)

This function sets the Token value and length in a header.

Parameters
[in,out]aMessageA pointer to the CoAP message.
[in]aTokenA pointer to the Token value.
[in]aTokenLengthThe Length of aToken.
Return values
OT_ERROR_NONESuccessfully set the Token value.
OT_ERROR_NO_BUFSInsufficient buffers to set the Token value.

◆ otCoapNewMessage()

otMessage* otCoapNewMessage ( otInstance aInstance,
const otMessageSettings aSettings 
)

This function creates a new CoAP message.

Note
If aSettings is 'NULL', the link layer security is enabled and the message priority is set to OT_MESSAGE_PRIORITY_NORMAL by default.
Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aSettingsA pointer to the message settings or NULL to set default settings.
Returns
A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid.

◆ otCoapOptionIteratorGetFirstOption()

const otCoapOption* otCoapOptionIteratorGetFirstOption ( otCoapOptionIterator aIterator)

This function returns a pointer to the first option.

Parameters
[in,out]aIteratorA pointer to the CoAP message option iterator.
Returns
A pointer to the first option. If no option is present NULL pointer is returned.

◆ otCoapOptionIteratorGetFirstOptionMatching()

const otCoapOption* otCoapOptionIteratorGetFirstOptionMatching ( otCoapOptionIterator aIterator,
uint16_t  aOption 
)

This function returns a pointer to the first option matching the specified option number.

Parameters
[in]aIteratorA pointer to the CoAP message option iterator.
[in]aOptionThe option number sought.
Returns
A pointer to the first matching option. If no matching option is present NULL pointer is returned.

◆ otCoapOptionIteratorGetNextOption()

const otCoapOption* otCoapOptionIteratorGetNextOption ( otCoapOptionIterator aIterator)

This function returns a pointer to the next option.

Parameters
[in,out]aIteratorA pointer to the CoAP message option iterator.
Returns
A pointer to the next option. If no more options are present NULL pointer is returned.

◆ otCoapOptionIteratorGetNextOptionMatching()

const otCoapOption* otCoapOptionIteratorGetNextOptionMatching ( otCoapOptionIterator aIterator,
uint16_t  aOption 
)

This function returns a pointer to the next option matching the specified option number.

Parameters
[in]aIteratorA pointer to the CoAP message option iterator.
[in]aOptionThe option number sought.
Returns
A pointer to the next matching option. If no further matching option is present NULL pointer is returned.

◆ otCoapOptionIteratorGetOptionUintValue()

otError otCoapOptionIteratorGetOptionUintValue ( otCoapOptionIterator aIterator,
uint64_t *const  aValue 
)

This function fills current option value into aValue assuming the current value is an unsigned integer encoded according to https://tools.ietf.org/html/rfc7252#section-3.2.

Parameters
[in,out]aIteratorA pointer to the CoAP message option iterator.
[out]aValueA pointer to an unsigned integer to receive the option value.
Return values
OT_ERROR_NONESuccessfully filled value.
OT_ERROR_NOT_FOUNDNo current option.
OT_ERROR_NO_BUFSValue is too long to fit in a uint64_t.
See also
otCoapMessageAppendUintOption

◆ otCoapOptionIteratorGetOptionValue()

otError otCoapOptionIteratorGetOptionValue ( otCoapOptionIterator aIterator,
void *  aValue 
)

This function fills current option value into aValue.

Parameters
[in,out]aIteratorA pointer to the CoAP message option iterator.
[out]aValueA pointer to a buffer to receive the option value.
Return values
OT_ERROR_NONESuccessfully filled value.
OT_ERROR_NOT_FOUNDNo current option.

◆ otCoapOptionIteratorInit()

otError otCoapOptionIteratorInit ( otCoapOptionIterator aIterator,
const otMessage aMessage 
)

This function initialises an iterator for the options in the given message.

Parameters
[in,out]aIteratorA pointer to the CoAP message option iterator.
[in]aMessageA pointer to the CoAP message.
Return values
OT_ERROR_NONESuccessfully initialised.
OT_ERROR_PARSEMessage state is inconsistent.

◆ otCoapRemoveResource()

void otCoapRemoveResource ( otInstance aInstance,
otCoapResource aResource 
)

This function removes a resource from the CoAP server.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aResourceA pointer to the resource.

◆ otCoapSendRequest()

static otError otCoapSendRequest ( otInstance aInstance,
otMessage aMessage,
const otMessageInfo aMessageInfo,
otCoapResponseHandler  aHandler,
void *  aContext 
)
inlinestatic

This function sends a CoAP request.

If a response for a request is expected, respective function and context information should be provided. If no response is expected, these arguments should be NULL pointers.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aMessageA pointer to the message to send.
[in]aMessageInfoA pointer to the message info associated with aMessage.
[in]aHandlerA function pointer that shall be called on response reception or timeout.
[in]aContextA pointer to arbitrary context information. May be NULL if not used.
Return values
OT_ERROR_NONESuccessfully sent CoAP message.
OT_ERROR_NO_BUFSFailed to allocate retransmission data.

◆ otCoapSendRequestWithParameters()

otError otCoapSendRequestWithParameters ( otInstance aInstance,
otMessage aMessage,
const otMessageInfo aMessageInfo,
otCoapResponseHandler  aHandler,
void *  aContext,
const otCoapTxParameters aTxParameters 
)

This function sends a CoAP request with custom transmission parameters.

If a response for a request is expected, respective function and context information should be provided. If no response is expected, these arguments should be NULL pointers.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aMessageA pointer to the message to send.
[in]aMessageInfoA pointer to the message info associated with aMessage.
[in]aHandlerA function pointer that shall be called on response reception or timeout.
[in]aContextA pointer to arbitrary context information. May be NULL if not used.
[in]aTxParametersA pointer to transmission parameters for this request. Use NULL for defaults. Otherwise, parameters given must meet the following conditions:
  1. mMaxRetransmit is no more than OT_COAP_MAX_RETRANSMIT.
  2. mAckRandomFactorNumerator / mAckRandomFactorDenominator must not be below 1.0.
  3. The calculated exchange life time must not overflow uint32_t.
Return values
OT_ERROR_INVALID_ARGSaTxParameters is invalid.
OT_ERROR_NONESuccessfully sent CoAP message.
OT_ERROR_NO_BUFSFailed to allocate retransmission data.

◆ otCoapSendResponse()

static otError otCoapSendResponse ( otInstance aInstance,
otMessage aMessage,
const otMessageInfo aMessageInfo 
)
inlinestatic

This function sends a CoAP response from the server.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aMessageA pointer to the CoAP response to send.
[in]aMessageInfoA pointer to the message info associated with aMessage.
Return values
OT_ERROR_NONESuccessfully enqueued the CoAP response message.
OT_ERROR_NO_BUFSInsufficient buffers available to send the CoAP response.

◆ otCoapSendResponseWithParameters()

otError otCoapSendResponseWithParameters ( otInstance aInstance,
otMessage aMessage,
const otMessageInfo aMessageInfo,
const otCoapTxParameters aTxParameters 
)

This function sends a CoAP response from the server with custom transmission parameters.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aMessageA pointer to the CoAP response to send.
[in]aMessageInfoA pointer to the message info associated with aMessage.
[in]aTxParametersA pointer to transmission parameters for this response. Use NULL for defaults.
Return values
OT_ERROR_NONESuccessfully enqueued the CoAP response message.
OT_ERROR_NO_BUFSInsufficient buffers available to send the CoAP response.

◆ otCoapSetDefaultHandler()

void otCoapSetDefaultHandler ( otInstance aInstance,
otCoapRequestHandler  aHandler,
void *  aContext 
)

This function sets the default handler for unhandled CoAP requests.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aHandlerA function pointer that shall be called when an unhandled request arrives.
[in]aContextA pointer to arbitrary context information. May be NULL if not used.

◆ otCoapStart()

otError otCoapStart ( otInstance aInstance,
uint16_t  aPort 
)

This function starts the CoAP server.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aPortThe local UDP port to bind to.
Return values
OT_ERROR_NONESuccessfully started the CoAP server.

◆ otCoapStop()

otError otCoapStop ( otInstance aInstance)

This function stops the CoAP server.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Return values
OT_ERROR_NONESuccessfully stopped the CoAP server.