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 otCoapOption *	otCoapOptionIteratorGetFirstOptionMatching ( otCoapOptionIterator *aIterator, uint16_t aOption)
	This function returns a pointer to the first option matching the specified option number.

const otCoapOption *	otCoapOptionIteratorGetFirstOption ( otCoapOptionIterator *aIterator)
	This function returns a pointer to the first option.

const otCoapOption *	otCoapOptionIteratorGetNextOptionMatching ( otCoapOptionIterator *aIterator, uint16_t aOption)
	This function returns a pointer to the next option matching the specified option number.

const otCoapOption *	otCoapOptionIteratorGetNextOption ( 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` .

otMessage *	otCoapNewMessage ( 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

typedef enum otCoapOptionContentFormat otCoapOptionContentFormat

CoAP Content Format codes.

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

◆ otCoapOptionIterator

typedef struct otCoapOptionIterator 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]	`aContext`	A pointer to arbitrary context information.
[in]	`aMessage`	A pointer to the message.
[in]	`aMessageInfo`	A 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]	`aContext`	A pointer to application-specific context.
[in]	`aMessage`	A pointer to the message buffer containing the response. NULL if no response was received.
[in]	`aMessageInfo`	A pointer to the message info for `aMessage` . NULL if no response was received.
[in]	`aResult`	A result of the CoAP transaction.

Return values

`OT_ERROR_NONE`	A response was received successfully.
`OT_ERROR_ABORT`	A CoAP transaction was reset by peer.
`OT_ERROR_RESPONSE_TIMEOUT`	No 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

enum 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

enum 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]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aResource`	A pointer to the resource.

Return values

`OT_ERROR_NONE`	Successfully added `aResource` .
`OT_ERROR_ALREADY`	The `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] aSize Block 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]	`aMessage`	A pointer to the CoAP message.
[in]	`aNum`	Current block number.
[in]	`aMore`	Boolean to indicate more blocks are to be sent.
[in]	`aSize`	Block Size Exponent.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The 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]	`aMessage`	A pointer to the CoAP message.
[in]	`aNum`	Current block number.
[in]	`aMore`	Boolean to indicate more blocks are to be sent.
[in]	`aSize`	Block Size Exponent.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The 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]	`aMessage`	A pointer to the CoAP message.
[in]	`aContentFormat`	One of the content formats listed in otCoapOptionContentFormat above.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The option length exceeds the buffer size.

◆ otCoapMessageAppendMaxAgeOption()

otError otCoapMessageAppendMaxAgeOption	(	otMessage *	`aMessage,`
		uint32_t	`aMaxAge`
	)

This function appends a Max-Age option.

Parameters

[in,out]	`aMessage`	A pointer to the CoAP message.
[in]	`aMaxAge`	The Max-Age value.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The option length exceeds the buffer size.

◆ otCoapMessageAppendObserveOption()

otError otCoapMessageAppendObserveOption	(	otMessage *	`aMessage,`
		uint32_t	`aObserve`
	)

This function appends an Observe option.

Parameters

[in,out]	`aMessage`	A pointer to the CoAP message.
[in]	`aObserve`	Observe field value.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The 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]	`aMessage`	A pointer to the CoAP message.
[in]	`aNumber`	The CoAP Option number.
[in]	`aLength`	The CoAP Option length.
[in]	`aValue`	A pointer to the CoAP value.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The option length exceeds the buffer size.

◆ otCoapMessageAppendProxyUriOption()

otError otCoapMessageAppendProxyUriOption	(	otMessage *	`aMessage,`
		const char *	`aUriPath`
	)

This function appends a Proxy-Uri option.

Parameters

[in,out]	`aMessage`	A pointer to the CoAP message.
[in]	`aUriPath`	A pointer to a NULL-terminated string.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The 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]	`aMessage`	A pointer to the CoAP message.
[in]	`aNumber`	The CoAP Option number.
[in]	`aValue`	The CoAP Option unsigned integer value.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The 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]	`aMessage`	A pointer to the CoAP message.
[in]	`aUriPath`	A pointer to a NULL-terminated string.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The 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]	`aMessage`	A pointer to the CoAP message.
[in]	`aUriQuery`	A pointer to NULL-terminated string, which should contain a single key=value pair.

Return values

`OT_ERROR_NONE`	Successfully appended the option.
`OT_ERROR_INVALID_ARGS`	The option type is not equal or greater than the last option type.
`OT_ERROR_NO_BUFS`	The 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] aMessage A 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]	`aMessage`	A pointer to the CoAP message.
[in]	`aTokenLength`	The Length of a Token to set.

◆ otCoapMessageGetCode()

otCoapCode otCoapMessageGetCode ( const otMessage * aMessage )

This function returns the Code value.

Parameters

[in] aMessage A 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] aMessage A 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] aMessage A 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] aMessage A pointer to the CoAP message.

Returns: The Token length.

◆ otCoapMessageGetType()

otCoapType otCoapMessageGetType ( const otMessage * aMessage )

This function returns the Type value.

Parameters

[in] aMessage A 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]	`aMessage`	A pointer to the CoAP message to initialize.
[in]	`aType`	CoAP message type.
[in]	`aCode`	CoAP 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]	`aResponse`	A pointer to the CoAP response message.
[in]	`aRequest`	A pointer to the CoAP request message.
[in]	`aType`	CoAP message type.
[in]	`aCode`	CoAP message code.

Return values

`OT_ERROR_NONE`	Successfully initialized the response message.
`OT_ERROR_NO_BUFS`	Insufficient 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] aMessage A pointer to the CoAP message.

Return values

`OT_ERROR_NONE`	Payload Marker successfully added.
`OT_ERROR_NO_BUFS`	Header 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]	`aMessage`	A pointer to the CoAP message.
[in]	`aToken`	A pointer to the Token value.
[in]	`aTokenLength`	The Length of `aToken` .

Return values

`OT_ERROR_NONE`	Successfully set the Token value.
`OT_ERROR_NO_BUFS`	Insufficient 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]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aSettings`	A 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] aIterator A 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]	`aIterator`	A pointer to the CoAP message option iterator.
[in]	`aOption`	The 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] aIterator A 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]	`aIterator`	A pointer to the CoAP message option iterator.
[in]	`aOption`	The 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]	`aIterator`	A pointer to the CoAP message option iterator.
[out]	`aValue`	A pointer to an unsigned integer to receive the option value.

Return values

`OT_ERROR_NONE`	Successfully filled value.
`OT_ERROR_NOT_FOUND`	No current option.
`OT_ERROR_NO_BUFS`	Value 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]	`aIterator`	A pointer to the CoAP message option iterator.
[out]	`aValue`	A pointer to a buffer to receive the option value.

Return values

`OT_ERROR_NONE`	Successfully filled value.
`OT_ERROR_NOT_FOUND`	No 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]	`aIterator`	A pointer to the CoAP message option iterator.
[in]	`aMessage`	A pointer to the CoAP message.

Return values

`OT_ERROR_NONE`	Successfully initialised.
`OT_ERROR_PARSE`	Message state is inconsistent.

◆ otCoapRemoveResource()

void otCoapRemoveResource	(	otInstance *	`aInstance,`
		otCoapResource *	`aResource`
	)

This function removes a resource from the CoAP server.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aResource`	A pointer to the resource.

◆ otCoapSendRequest()

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

inline static

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]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aMessage`	A pointer to the message to send.
[in]	`aMessageInfo`	A pointer to the message info associated with `aMessage` .
[in]	`aHandler`	A function pointer that shall be called on response reception or timeout.
[in]	`aContext`	A pointer to arbitrary context information. May be NULL if not used.

Return values

`OT_ERROR_NONE`	Successfully sent CoAP message.
`OT_ERROR_NO_BUFS`	Failed 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]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aMessage`	A pointer to the message to send.
[in]	`aMessageInfo`	A pointer to the message info associated with `aMessage` .
[in]	`aHandler`	A function pointer that shall be called on response reception or timeout.
[in]	`aContext`	A pointer to arbitrary context information. May be NULL if not used.
[in]	`aTxParameters`	A pointer to transmission parameters for this request. Use NULL for defaults. Otherwise, parameters given must meet the following conditions: mMaxRetransmit is no more than OT_COAP_MAX_RETRANSMIT. mAckRandomFactorNumerator / mAckRandomFactorDenominator must not be below 1.0. The calculated exchange life time must not overflow uint32_t.

Return values

`OT_ERROR_INVALID_ARGS`	`aTxParameters` is invalid.
`OT_ERROR_NONE`	Successfully sent CoAP message.
`OT_ERROR_NO_BUFS`	Failed to allocate retransmission data.

◆ otCoapSendResponse()

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

inline static

This function sends a CoAP response from the server.

Parameters

[in]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aMessage`	A pointer to the CoAP response to send.
[in]	`aMessageInfo`	A pointer to the message info associated with `aMessage` .

Return values

`OT_ERROR_NONE`	Successfully enqueued the CoAP response message.
`OT_ERROR_NO_BUFS`	Insufficient 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]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aMessage`	A pointer to the CoAP response to send.
[in]	`aMessageInfo`	A pointer to the message info associated with `aMessage` .
[in]	`aTxParameters`	A pointer to transmission parameters for this response. Use NULL for defaults.

Return values

`OT_ERROR_NONE`	Successfully enqueued the CoAP response message.
`OT_ERROR_NO_BUFS`	Insufficient 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]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aHandler`	A function pointer that shall be called when an unhandled request arrives.
[in]	`aContext`	A 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]	`aInstance`	A pointer to an OpenThread instance.
[in]	`aPort`	The local UDP port to bind to.

Return values

OT_ERROR_NONE Successfully started the CoAP server.

◆ otCoapStop()

otError otCoapStop ( otInstance * aInstance )

This function stops the CoAP server.

Parameters

[in] aInstance A pointer to an OpenThread instance.

Return values

OT_ERROR_NONE Successfully stopped the CoAP server.

CoAP API > Add-Ons > CoAP

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ otCoapOptionContentFormat

◆ otCoapOptionIterator

◆ otCoapRequestHandler

◆ otCoapResponseHandler

Enumeration Type Documentation

◆ otCoapCode

◆ otCoapOptionContentFormat

◆ otCoapOptionType

◆ otCoapType

Function Documentation

◆ otCoapAddResource()

◆ otCoapBlockSizeFromExponent()

◆ otCoapMessageAppendBlock1Option()

◆ otCoapMessageAppendBlock2Option()

◆ otCoapMessageAppendContentFormatOption()

◆ otCoapMessageAppendMaxAgeOption()

◆ otCoapMessageAppendObserveOption()

◆ otCoapMessageAppendOption()

◆ otCoapMessageAppendProxyUriOption()

◆ otCoapMessageAppendUintOption()

◆ otCoapMessageAppendUriPathOptions()

◆ otCoapMessageAppendUriQueryOption()

◆ otCoapMessageCodeToString()

◆ otCoapMessageGenerateToken()

◆ otCoapMessageGetCode()

◆ otCoapMessageGetMessageId()

◆ otCoapMessageGetToken()

◆ otCoapMessageGetTokenLength()

◆ otCoapMessageGetType()

◆ otCoapMessageInit()

◆ otCoapMessageInitResponse()

◆ otCoapMessageSetPayloadMarker()

◆ otCoapMessageSetToken()

◆ otCoapNewMessage()

◆ otCoapOptionIteratorGetFirstOption()

◆ otCoapOptionIteratorGetFirstOptionMatching()

◆ otCoapOptionIteratorGetNextOption()

◆ otCoapOptionIteratorGetNextOptionMatching()

◆ otCoapOptionIteratorGetOptionUintValue()

◆ otCoapOptionIteratorGetOptionValue()

◆ otCoapOptionIteratorInit()

◆ otCoapRemoveResource()

◆ otCoapSendRequest()

◆ otCoapSendRequestWithParameters()

◆ otCoapSendResponse()

◆ otCoapSendResponseWithParameters()

◆ otCoapSetDefaultHandler()

◆ otCoapStart()

◆ otCoapStop()

CoAP
API > Add-Ons > CoAP