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

Data Structures
struct	otCoapOption

struct	otCoapHeader

struct	otCoapResource

Macros
#define	OT_DEFAULT_COAP_PORT 5683
	Default CoAP port, as specified in RFC 7252.

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

#define	OT_COAP_HEADER_MAX_LENGTH 128
	Max CoAP header length (bytes)

Typedefs
typedef enum otCoapType	otCoapType

typedef enum otCoapCode	otCoapCode

typedef enum otCoapOptionType	otCoapOptionType

typedef struct otCoapOption	otCoapOption

typedef enum otCoapOptionContentFormat	otCoapOptionContentFormat

typedef struct otCoapHeader	otCoapHeader

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

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

typedef struct otCoapResource	otCoapResource

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_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_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_PROXY_URI = 35, OT_COAP_OPTION_PROXY_SCHEME = 39, OT_COAP_OPTION_SIZE1 = 60 }

enum	otCoapOptionContentFormat { OT_COAP_OPTION_CONTENT_FORMAT_TEXT_PLAIN = 0, 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 }

Functions
void	otCoapHeaderInit (otCoapHeader *aHeader, otCoapType aType, otCoapCode aCode)

void	otCoapHeaderSetToken (otCoapHeader aHeader, const uint8_t aToken, uint8_t aTokenLength)

void	otCoapHeaderGenerateToken (otCoapHeader *aHeader, uint8_t aTokenLength)

otError	otCoapHeaderAppendContentFormatOption (otCoapHeader *aHeader, otCoapOptionContentFormat aContentFormat)

otError	otCoapHeaderAppendOption (otCoapHeader aHeader, const otCoapOption aOption)

otError	otCoapHeaderAppendUintOption (otCoapHeader *aHeader, uint16_t aNumber, uint32_t aValue)

otError	otCoapHeaderAppendObserveOption (otCoapHeader *aHeader, uint32_t aObserve)

otError	otCoapHeaderAppendUriPathOptions (otCoapHeader aHeader, const char aUriPath)

otError	otCoapHeaderAppendMaxAgeOption (otCoapHeader *aHeader, uint32_t aMaxAge)

otError	otCoapHeaderAppendUriQueryOption (otCoapHeader aHeader, const char aUriQuery)

void	otCoapHeaderSetPayloadMarker (otCoapHeader *aHeader)

void	otCoapHeaderSetMessageId (otCoapHeader *aHeader, uint16_t aMessageId)

otCoapType	otCoapHeaderGetType (const otCoapHeader *aHeader)

otCoapCode	otCoapHeaderGetCode (const otCoapHeader *aHeader)

uint16_t	otCoapHeaderGetMessageId (const otCoapHeader *aHeader)

uint8_t	otCoapHeaderGetTokenLength (const otCoapHeader *aHeader)

const uint8_t *	otCoapHeaderGetToken (const otCoapHeader *aHeader)

const otCoapOption *	otCoapHeaderGetFirstOption (otCoapHeader *aHeader)

const otCoapOption *	otCoapHeaderGetNextOption (otCoapHeader *aHeader)

otMessage *	otCoapNewMessage (otInstance aInstance, const otCoapHeader aHeader)

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

otError	otCoapStart (otInstance *aInstance, uint16_t aPort)

otError	otCoapStop (otInstance *aInstance)

otError	otCoapAddResource (otInstance aInstance, otCoapResource aResource)

void	otCoapRemoveResource (otInstance aInstance, otCoapResource aResource)

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

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 application-coap feature (OPENTHREAD_ENABLE_APPLICATION_COAP) 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 otCoapCode otCoapCode

CoAP Code values.

typedef struct otCoapHeader otCoapHeader

This structure represents a CoAP header.

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://tools.ietf.org/html/rfc7252#page-92

typedef enum otCoapOptionType otCoapOptionType

CoAP Option Numbers

typedef void(* otCoapRequestHandler)(void *aContext, otCoapHeader *aHeader, 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]	aHeader	A pointer to the CoAP header.
[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, otCoapHeader *aHeader, 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]	aHeader	A pointer to the received CoAP header. NULL if no response was received.
[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 reseted by peer.
OT_ERROR_RESPONSE_TIMEOUT	No response or acknowledgment received during timeout period.

typedef enum otCoapType otCoapType

CoAP Type values.

Enumeration Type Documentation

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_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_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://tools.ietf.org/html/rfc7252#page-92

Enumerator
OT_COAP_OPTION_CONTENT_FORMAT_TEXT_PLAIN	text/plain
OT_COAP_OPTION_CONTENT_FORMAT_LINK_FORMAT	application/link-format
OT_COAP_OPTION_CONTENT_FORMAT_XML	application/xml
OT_COAP_OPTION_CONTENT_FORMAT_OCTET_STREAM	application/octet-stream
OT_COAP_OPTION_CONTENT_FORMAT_EXI	application/exi
OT_COAP_OPTION_CONTENT_FORMAT_JSON	application/json

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

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.

otError otCoapHeaderAppendContentFormatOption	(	otCoapHeader *	aHeader,
		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 otCoapHeaderSetPayloadMarker if a payload is to be included in the message.

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

Parameters

[in,out]	aHeader	A pointer to the CoAP header.
[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 otCoapHeaderAppendMaxAgeOption	(	otCoapHeader *	aHeader,
		uint32_t	aMaxAge
	)

This function appends a Max-Age option.

Parameters

[in,out]	aHeader	A pointer to the CoAP header.
[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 otCoapHeaderAppendObserveOption	(	otCoapHeader *	aHeader,
		uint32_t	aObserve
	)

This function appends an Observe option.

Parameters

[in,out]	aHeader	A pointer to the CoAP header.
[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 otCoapHeaderAppendOption	(	otCoapHeader *	aHeader,
		const otCoapOption *	aOption
	)

This function appends a CoAP option in a header.

Parameters

[in,out]	aHeader	A pointer to the CoAP header.
[in]	aOption	A pointer to the CoAP option.

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 otCoapHeaderAppendUintOption	(	otCoapHeader *	aHeader,
		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]	aHeader	A pointer to the CoAP header.
[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.

otError otCoapHeaderAppendUriPathOptions	(	otCoapHeader *	aHeader,
		const char *	aUriPath
	)

This function appends an Uri-Path option.

Parameters

[in,out]	aHeader	A pointer to the CoAP header.
[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 otCoapHeaderAppendUriQueryOption	(	otCoapHeader *	aHeader,
		const char *	aUriQuery
	)

This function appends a single Uri-Query option.

Parameters

[in,out]	aHeader	A pointer to the CoAP header.
[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.

void otCoapHeaderGenerateToken	(	otCoapHeader *	aHeader,
		uint8_t	aTokenLength
	)

This function sets the Token length and randomizes its value.

Parameters

[in,out]	aHeader	A pointer to the CoAP header.
[in]	aTokenLength	The Length of a Token to set.

otCoapCode otCoapHeaderGetCode ( const otCoapHeader * aHeader )

This function returns the Code value.

Parameters