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 |
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.
#define OT_COAP_CODE | ( | c, | |
d | |||
) | ((((c)&0x7) << 5) | ((d)&0x1f)) |
Helper macro to define CoAP Code values.
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.
[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.
[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. |
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.
enum otCoapBlockSize |
CoAP Block Size Exponents
enum otCoapCode |
CoAP Code values.
CoAP Content Format codes. The full list is documented at https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats
enum otCoapOptionType |
CoAP Option Numbers
enum otCoapType |
otError otCoapAddResource | ( | otInstance * | aInstance, |
otCoapResource * | aResource | ||
) |
This function adds a resource to the CoAP server.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aResource | A pointer to the resource. |
OT_ERROR_NONE | Successfully added aResource . |
OT_ERROR_ALREADY | The aResource was already added. |
uint16_t otCoapBlockSizeFromExponent | ( | otCoapBlockSize | aSize | ) |
This function converts a CoAP Block option SZX field to the actual block size
[in] | aSize | Block size exponent. |
otError otCoapMessageAppendBlock1Option | ( | otMessage * | aMessage, |
uint32_t | aNum, | ||
bool | aMore, | ||
otCoapBlockSize | aSize | ||
) |
This function appends a Block1 option
[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. |
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
[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. |
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.
[in,out] | aMessage | A pointer to the CoAP message. |
[in] | aContentFormat | One of the content formats listed in otCoapOptionContentFormat above. |
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. |
This function appends a Max-Age option.
[in,out] | aMessage | A pointer to the CoAP message. |
[in] | aMaxAge | The Max-Age value. |
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. |
This function appends an Observe option.
[in,out] | aMessage | A pointer to the CoAP message. |
[in] | aObserve | Observe field value. |
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.
[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. |
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. |
This function appends a Proxy-Uri option.
[in,out] | aMessage | A pointer to the CoAP message. |
[in] | aUriPath | A pointer to a NULL-terminated string. |
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. |
This function appends an unsigned integer CoAP option as specified in https://tools.ietf.org/html/rfc7252#section-3.2
[in,out] | aMessage | A pointer to the CoAP message. |
[in] | aNumber | The CoAP Option number. |
[in] | aValue | The CoAP Option unsigned integer value. |
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. |
This function appends a Uri-Path option.
[in,out] | aMessage | A pointer to the CoAP message. |
[in] | aUriPath | A pointer to a NULL-terminated string. |
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. |
This function appends a single Uri-Query option.
[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. |
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.
[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.
[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.
[in] | aMessage | A pointer to the CoAP message. |
uint16_t otCoapMessageGetMessageId | ( | const otMessage * | aMessage | ) |
This function returns the Message ID value.
[in] | aMessage | A pointer to the CoAP message. |
const uint8_t* otCoapMessageGetToken | ( | const otMessage * | aMessage | ) |
This function returns a pointer to the Token value.
[in] | aMessage | A pointer to the CoAP message. |
uint8_t otCoapMessageGetTokenLength | ( | const otMessage * | aMessage | ) |
This function returns the Token length.
[in] | aMessage | A pointer to the CoAP message. |
otCoapType otCoapMessageGetType | ( | const otMessage * | aMessage | ) |
This function returns the Type value.
[in] | aMessage | A pointer to the CoAP message. |
void otCoapMessageInit | ( | otMessage * | aMessage, |
otCoapType | aType, | ||
otCoapCode | aCode | ||
) |
This function initializes the CoAP header.
[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.
aRequest
.[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. |
OT_ERROR_NONE | Successfully initialized the response message. |
OT_ERROR_NO_BUFS | Insufficient message buffers available to initialize the response message. |
This function adds Payload Marker indicating beginning of the payload to the CoAP header.
[in,out] | aMessage | A pointer to the CoAP message. |
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.
[in,out] | aMessage | A pointer to the CoAP message. |
[in] | aToken | A pointer to the Token value. |
[in] | aTokenLength | The Length of aToken . |
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.
aSettings
is 'NULL', the link layer security is enabled and the message priority is set to OT_MESSAGE_PRIORITY_NORMAL by default.[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aSettings | A pointer to the message settings or NULL to set default settings. |
const otCoapOption* otCoapOptionIteratorGetFirstOption | ( | otCoapOptionIterator * | aIterator | ) |
This function returns a pointer to the first option.
[in,out] | aIterator | A pointer to the CoAP message option iterator. |
const otCoapOption* otCoapOptionIteratorGetFirstOptionMatching | ( | otCoapOptionIterator * | aIterator, |
uint16_t | aOption | ||
) |
This function returns a pointer to the first option matching the specified option number.
[in] | aIterator | A pointer to the CoAP message option iterator. |
[in] | aOption | The option number sought. |
const otCoapOption* otCoapOptionIteratorGetNextOption | ( | otCoapOptionIterator * | aIterator | ) |
This function returns a pointer to the next option.
[in,out] | aIterator | A pointer to the CoAP message option iterator. |
const otCoapOption* otCoapOptionIteratorGetNextOptionMatching | ( | otCoapOptionIterator * | aIterator, |
uint16_t | aOption | ||
) |
This function returns a pointer to the next option matching the specified option number.
[in] | aIterator | A pointer to the CoAP message option iterator. |
[in] | aOption | The option number sought. |
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
[in,out] | aIterator | A pointer to the CoAP message option iterator. |
[out] | aValue | A pointer to an unsigned integer to receive the option value. |
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. |
otError otCoapOptionIteratorGetOptionValue | ( | otCoapOptionIterator * | aIterator, |
void * | aValue | ||
) |
This function fills current option value into aValue
.
[in,out] | aIterator | A pointer to the CoAP message option iterator. |
[out] | aValue | A pointer to a buffer to receive the option value. |
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.
[in,out] | aIterator | A pointer to the CoAP message option iterator. |
[in] | aMessage | A pointer to the CoAP message. |
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.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aResource | A pointer to the resource. |
|
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.
[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. |
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.
[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:
|
OT_ERROR_INVALID_ARGS | aTxParameters is invalid. |
OT_ERROR_NONE | Successfully sent CoAP message. |
OT_ERROR_NO_BUFS | Failed to allocate retransmission data. |
|
inlinestatic |
This function sends a CoAP response from the server.
[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 . |
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.
[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. |
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.
[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.
[in] | aInstance | A pointer to an OpenThread instance. |
[in] | aPort | The local UDP port to bind to. |
OT_ERROR_NONE | Successfully started the CoAP server. |
otError otCoapStop | ( | otInstance * | aInstance | ) |
This function stops the CoAP server.
[in] | aInstance | A pointer to an OpenThread instance. |
OT_ERROR_NONE | Successfully stopped the CoAP server. |