This module includes functions that control CoAP communication. More...

Data Structures
struct	otCoapOption

struct	otCoapOptionIterator

struct	otCoapResource

struct	otCoapTxParameters

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))

Typedefs
typedef enum otCoapType	otCoapType

typedef enum otCoapCode	otCoapCode

typedef enum otCoapOptionType	otCoapOptionType

typedef enum otCoapBlockSize	otCoapBlockSize

typedef struct otCoapOption	otCoapOption

typedef struct otCoapOptionIterator	otCoapOptionIterator

typedef enum otCoapOptionContentFormat	otCoapOptionContentFormat

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

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

typedef struct otCoapResource	otCoapResource

typedef struct otCoapTxParameters	otCoapTxParameters

Enumerations
enum	otCoapType { OT_COAP_TYPE_CONFIRMABLE = 0x00, OT_COAP_TYPE_NON_CONFIRMABLE = 0x10, OT_COAP_TYPE_ACKNOWLEDGMENT = 0x20, OT_COAP_TYPE_RESET = 0x30 }

enum	otCoapCode { OT_COAP_CODE_EMPTY = (((( 0 )&0x7) << 5) \| (( 0 )&0x1f)), OT_COAP_CODE_GET = (((( 0 )&0x7) << 5) \| (( 1 )&0x1f)), OT_COAP_CODE_POST = (((( 0 )&0x7) << 5) \| (( 2 )&0x1f)), OT_COAP_CODE_PUT = (((( 0 )&0x7) << 5) \| (( 3 )&0x1f)), OT_COAP_CODE_DELETE = (((( 0 )&0x7) << 5) \| (( 4 )&0x1f)), OT_COAP_CODE_RESPONSE_MIN = (((( 2 )&0x7) << 5) \| (( 0 )&0x1f)), OT_COAP_CODE_CREATED = (((( 2 )&0x7) << 5) \| (( 1 )&0x1f)), OT_COAP_CODE_DELETED = (((( 2 )&0x7) << 5) \| (( 2 )&0x1f)), OT_COAP_CODE_VALID = (((( 2 )&0x7) << 5) \| (( 3 )&0x1f)), OT_COAP_CODE_CHANGED = (((( 2 )&0x7) << 5) \| (( 4 )&0x1f)), OT_COAP_CODE_CONTENT = (((( 2 )&0x7) << 5) \| (( 5 )&0x1f)), OT_COAP_CODE_CONTINUE = (((( 2 )&0x7) << 5) \| (( 31 )&0x1f)), OT_COAP_CODE_BAD_REQUEST = (((( 4 )&0x7) << 5) \| (( 0 )&0x1f)), OT_COAP_CODE_UNAUTHORIZED = (((( 4 )&0x7) << 5) \| (( 1 )&0x1f)), OT_COAP_CODE_BAD_OPTION = (((( 4 )&0x7) << 5) \| (( 2 )&0x1f)), OT_COAP_CODE_FORBIDDEN = (((( 4 )&0x7) << 5) \| (( 3 )&0x1f)), OT_COAP_CODE_NOT_FOUND = (((( 4 )&0x7) << 5) \| (( 4 )&0x1f)), OT_COAP_CODE_METHOD_NOT_ALLOWED = (((( 4 )&0x7) << 5) \| (( 5 )&0x1f)), OT_COAP_CODE_NOT_ACCEPTABLE = (((( 4 )&0x7) << 5) \| (( 6 )&0x1f)), OT_COAP_CODE_REQUEST_INCOMPLETE = (((( 4 )&0x7) << 5) \| (( 8 )&0x1f)), OT_COAP_CODE_PRECONDITION_FAILED = (((( 4 )&0x7) << 5) \| (( 12 )&0x1f)), OT_COAP_CODE_REQUEST_TOO_LARGE = (((( 4 )&0x7) << 5) \| (( 13 )&0x1f)), OT_COAP_CODE_UNSUPPORTED_FORMAT = (((( 4 )&0x7) << 5) \| (( 15 )&0x1f)), OT_COAP_CODE_INTERNAL_ERROR = (((( 5 )&0x7) << 5) \| (( 0 )&0x1f)), OT_COAP_CODE_NOT_IMPLEMENTED = (((( 5 )&0x7) << 5) \| (( 1 )&0x1f)), OT_COAP_CODE_BAD_GATEWAY = (((( 5 )&0x7) << 5) \| (( 2 )&0x1f)), OT_COAP_CODE_SERVICE_UNAVAILABLE = (((( 5 )&0x7) << 5) \| (( 3 )&0x1f)), OT_COAP_CODE_GATEWAY_TIMEOUT = (((( 5 )&0x7) << 5) \| (( 4 )&0x1f)), OT_COAP_CODE_PROXY_NOT_SUPPORTED = (((( 5 )&0x7) << 5) \| (( 5 )&0x1f)) }

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 }

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 }

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 }

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

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

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

void	otCoapMessageGenerateToken (otMessage *aMessage, uint8_t aTokenLength)

otError	otCoapMessageAppendContentFormatOption (otMessage *aMessage, otCoapOptionContentFormat aContentFormat)

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

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

otError	otCoapMessageAppendObserveOption (otMessage *aMessage, uint32_t aObserve)

otError	otCoapMessageAppendUriPathOptions (otMessage aMessage, const char aUriPath)

uint16_t	otCoapBlockSizeFromExponent (otCoapBlockSize aSize)

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

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

otError	otCoapMessageAppendProxyUriOption (otMessage aMessage, const char aUriPath)

otError	otCoapMessageAppendMaxAgeOption (otMessage *aMessage, uint32_t aMaxAge)

otError	otCoapMessageAppendUriQueryOption (otMessage aMessage, const char aUriQuery)

otError	otCoapMessageSetPayloadMarker (otMessage *aMessage)

otCoapType	otCoapMessageGetType (const otMessage *aMessage)

otCoapCode	otCoapMessageGetCode (const otMessage *aMessage)

const char *	otCoapMessageCodeToString (const otMessage *aMessage)

uint16_t	otCoapMessageGetMessageId (const otMessage *aMessage)

uint8_t	otCoapMessageGetTokenLength (const otMessage *aMessage)

const uint8_t *	otCoapMessageGetToken (const otMessage *aMessage)

otError	otCoapOptionIteratorInit (otCoapOptionIterator aIterator, const otMessage aMessage)

const otCoapOption *	otCoapOptionIteratorGetFirstOptionMatching (otCoapOptionIterator *aIterator, uint16_t aOption)

const otCoapOption *	otCoapOptionIteratorGetFirstOption (otCoapOptionIterator *aIterator)

const otCoapOption *	otCoapOptionIteratorGetNextOptionMatching (otCoapOptionIterator *aIterator, uint16_t aOption)

const otCoapOption *	otCoapOptionIteratorGetNextOption (otCoapOptionIterator *aIterator)

otError	otCoapOptionIteratorGetOptionUintValue (otCoapOptionIterator aIterator, uint64_t const aValue)

otError	otCoapOptionIteratorGetOptionValue (otCoapOptionIterator aIterator, void aValue)

otMessage *	otCoapNewMessage (otInstance aInstance, const otMessageSettings aSettings)

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

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

otError	otCoapStart (otInstance *aInstance, uint16_t aPort)

otError	otCoapStop (otInstance *aInstance)

void	otCoapAddResource (otInstance aInstance, otCoapResource aResource)

void	otCoapRemoveResource (otInstance aInstance, otCoapResource aResource)

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

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

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

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.

Macro Definition Documentation

#define OT_COAP_CODE	(	c,
		d
	)	((((c)&0x7) << 5) \| ((d)&0x1f))

Helper macro to define CoAP Code values.

Typedef Documentation

typedef enum otCoapBlockSize otCoapBlockSize

CoAP Block Size Exponents

typedef enum otCoapCode otCoapCode

CoAP Code values.

typedef struct otCoapOption otCoapOption

This structure represents a CoAP option.

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

typedef struct otCoapOptionIterator otCoapOptionIterator

This structure acts as an iterator for CoAP options

typedef enum otCoapOptionType otCoapOptionType

CoAP Option Numbers

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`.

typedef struct otCoapResource otCoapResource

This structure represents a CoAP resource.

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.

typedef struct otCoapTxParameters otCoapTxParameters

This structure represents the CoAP transmission parameters.

typedef enum otCoapType otCoapType

CoAP Type values.

Enumeration Type Documentation

enum otCoapBlockSize

CoAP Block Size Exponents

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.

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]

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.

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

void 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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

otCoapCode otCoapMessageGetCode ( const otMessage * aMessage )

This function returns the Code value.

Parameters

[in] aMessage A pointer to the CoAP message.

Returns: The Code value.

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.

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.

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.

otCoapType otCoapMessageGetType ( const otMessage * aMessage )

This function returns the Type value.

Parameters

[in] aMessage A pointer to the CoAP message.

Returns: The Type value.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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]	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.

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.

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

inlinestatic

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.

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.

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.

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.

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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation