Constrained Application Protocol API
Thread Stack API Reference > Messaging

Modules

Callbacks
Diagnostic Callbacks

Data Structures

struct EmberCoapOption
Structure that includes options in outgoing requests and responses.
struct EmberCoapResponseInfo
Additional information about an incoming response.
struct EmberCoapSendInfo
Optional information when sending a message.
struct EmberCoapRequestInfo
Additional information about an incoming request.
struct EmberCoapBlockOption

Macros

#define MAKE_COAP_CODE (class, detail)   ((class << 5) | detail)
#define GET_COAP_CLASS (code)   (((code) & 0xE0) >> 5)
#define GET_COAP_DETAIL (code)   ((code) & 0x1F)
#define EMBER_COAP_PORT 5683
#define EMBER_COAP_SECURE_PORT 5684
#define EMBER_COAP_MAX_TOKEN_LENGTH 8
#define EMBER_COAP_DEFAULT_TIMEOUT_MS 90000
#define BLOCK_OPTION_VALUE_LOG_SIZE_MIN 4
#define BLOCK_OPTION_VALUE_LOG_SIZE_MAX 10
#define emberBlockOptionSize (option)   (1 << (option)->logSize)

Typedefs

typedef struct EmberCoapReadOptions_s EmberCoapReadOptions
This function encapsulates incoming CoAP options.
typedef bool(* EmberCoapTransmitHandler ) (const uint8_t *payload, uint16_t payloadLength, const EmberIpv6Address *localAddress, uint16_t localPort, const EmberIpv6Address *remoteAddress, uint16_t remotePort, void *transmitHandlerData)
Function type for alternative transports.
typedef void(* EmberCoapResponseHandler ) ( EmberCoapStatus status, EmberCoapCode code, EmberCoapReadOptions *options, uint8_t *payload, uint16_t payloadLength, EmberCoapResponseInfo *info)
Type definition for callback handlers for a response.

Enumerations

enum EmberCoapClass {
EMBER_COAP_CLASS_REQUEST = 0,
EMBER_COAP_CLASS_SUCCESS_RESPONSE = 2,
EMBER_COAP_CLASS_CLIENT_ERROR_RESPONSE = 4,
EMBER_COAP_CLASS_SERVER_ERROR_RESPONSE = 5
}
enum EmberCoapCode {
EMBER_COAP_CODE_EMPTY = MAKE_COAP_CODE(0, 0),
EMBER_COAP_CODE_GET = MAKE_COAP_CODE(0, 1),
EMBER_COAP_CODE_POST = MAKE_COAP_CODE(0, 2),
EMBER_COAP_CODE_PUT = MAKE_COAP_CODE(0, 3),
EMBER_COAP_CODE_DELETE = MAKE_COAP_CODE(0, 4),
EMBER_COAP_CODE_201_CREATED = MAKE_COAP_CODE(2, 1),
EMBER_COAP_CODE_202_DELETED = MAKE_COAP_CODE(2, 2),
EMBER_COAP_CODE_203_VALID = MAKE_COAP_CODE(2, 3),
EMBER_COAP_CODE_204_CHANGED = MAKE_COAP_CODE(2, 4),
EMBER_COAP_CODE_205_CONTENT = MAKE_COAP_CODE(2, 5),
EMBER_COAP_CODE_231_CONTINUE = MAKE_COAP_CODE(2, 31),
EMBER_COAP_CODE_400_BAD_REQUEST = MAKE_COAP_CODE(4, 0),
EMBER_COAP_CODE_401_UNAUTHORIZED = MAKE_COAP_CODE(4, 1),
EMBER_COAP_CODE_402_BAD_OPTION = MAKE_COAP_CODE(4, 2),
EMBER_COAP_CODE_403_FORBIDDEN = MAKE_COAP_CODE(4, 3),
EMBER_COAP_CODE_404_NOT_FOUND = MAKE_COAP_CODE(4, 4),
EMBER_COAP_CODE_405_METHOD_NOT_ALLOWED = MAKE_COAP_CODE(4, 5),
EMBER_COAP_CODE_406_NOT_ACCEPTABLE = MAKE_COAP_CODE(4, 6),
EMBER_COAP_CODE_412_PRECONDITION_FAILED = MAKE_COAP_CODE(4, 12),
EMBER_COAP_CODE_413_REQUEST_ENTITY_TOO_LARGE = MAKE_COAP_CODE(4, 13),
EMBER_COAP_CODE_415_UNSUPPORTED_CONTENT_FORMAT = MAKE_COAP_CODE(4, 15),
EMBER_COAP_CODE_500_INTERNAL_SERVER_ERROR = MAKE_COAP_CODE(5, 0),
EMBER_COAP_CODE_501_NOT_IMPLEMENTED = MAKE_COAP_CODE(5, 1),
EMBER_COAP_CODE_502_BAD_GATEWAY = MAKE_COAP_CODE(5, 2),
EMBER_COAP_CODE_503_SERVICE_UNAVAILABLE = MAKE_COAP_CODE(5, 3),
EMBER_COAP_CODE_504_GATEWAY_TIMEOUT = MAKE_COAP_CODE(5, 4),
EMBER_COAP_CODE_505_PROXYING_NOT_SUPPORTED = MAKE_COAP_CODE(5, 5)
}
enum EmberCoapOptionType {
EMBER_COAP_NO_OPTION = 0,
EMBER_COAP_OPTION_IF_MATCH = 1,
EMBER_COAP_OPTION_URI_HOST = 3,
EMBER_COAP_OPTION_ETAG = 4,
EMBER_COAP_OPTION_IF_NONE_MATCH = 5,
EMBER_COAP_OPTION_OBSERVE = 6,
EMBER_COAP_OPTION_URI_PORT = 7,
EMBER_COAP_OPTION_LOCATION_PATH = 8,
EMBER_COAP_OPTION_URI_PATH = 11,
EMBER_COAP_OPTION_CONTENT_FORMAT = 12,
EMBER_COAP_OPTION_MAX_AGE = 14,
EMBER_COAP_OPTION_URI_QUERY = 15,
EMBER_COAP_OPTION_ACCEPT = 17,
EMBER_COAP_OPTION_LOCATION_QUERY = 20,
EMBER_COAP_OPTION_BLOCK2 = 23,
EMBER_COAP_OPTION_BLOCK1 = 27,
EMBER_COAP_OPTION_SIZE2 = 28,
EMBER_COAP_OPTION_PROXY_URI = 35,
EMBER_COAP_OPTION_PROXY_SCHEME = 39,
EMBER_COAP_OPTION_SIZE1 = 60
}
enum EmberCoapContentFormatType {
EMBER_COAP_CONTENT_FORMAT_TEXT_PLAIN = 0,
EMBER_COAP_CONTENT_FORMAT_LINK_FORMAT = 40,
EMBER_COAP_CONTENT_FORMAT_XML = 41,
EMBER_COAP_CONTENT_FORMAT_OCTET_STREAM = 42,
EMBER_COAP_CONTENT_FORMAT_EXI = 47,
EMBER_COAP_CONTENT_FORMAT_JSON = 50,
EMBER_COAP_CONTENT_FORMAT_CBOR = 60,
EMBER_COAP_CONTENT_FORMAT_LINK_FORMAT_PLUS_CBOR = 65064,
EMBER_COAP_CONTENT_FORMAT_NONE = -1
}
enum EmberCoapStatus {
EMBER_COAP_MESSAGE_TIMED_OUT ,
EMBER_COAP_MESSAGE_ACKED ,
EMBER_COAP_MESSAGE_RESET ,
EMBER_COAP_MESSAGE_RESPONSE
}
Status values passed to response handlers.

Functions

bool emberCoapIsSuccessResponse ( EmberCoapCode code)
This function indicates whether the code represents a successful response.
bool emberCoapIsClientErrorResponse ( EmberCoapCode code)
This function indicates whether the code represents a client error response.
bool emberCoapIsServerErrorResponse ( EmberCoapCode code)
This function indicates whether the code represents a server error response.
bool emberCoapIsRequest ( EmberCoapCode code)
This function indicates whether the code represents a request.
bool emberCoapIsResponse ( EmberCoapCode code)
This function indicates whether the code represents a response.
EmberCoapOptionType emberReadNextOption ( EmberCoapReadOptions *options, const uint8_t **valuePointerLoc, uint16_t *valueLengthLoc)
This function reads the next option from an incoming message.
void emberResetReadOptionPointer ( EmberCoapReadOptions *options)
This function resets the internal pointer back to the first option.
uint32_t emberReadOptionValue (const uint8_t *value, uint16_t valuelength)
This function decodes the value of an integer option.
bool emberReadIntegerOption ( EmberCoapReadOptions *options, EmberCoapOptionType type, uint32_t *valueLoc)
This function reads the value of an integer option.
bool emberReadBytesOption ( EmberCoapReadOptions *options, EmberCoapOptionType type, const uint8_t **valueLoc, uint16_t *valueLengthLoc)
This function reads the value of an option.
int16_t emberReadLocationPath ( EmberCoapReadOptions *options, uint8_t *pathBuffer, uint16_t pathBufferLength)
This function converts path options to a string.
EmberStatus emberCoapSend (const EmberIpv6Address *destination, EmberCoapCode code, const uint8_t *path, const uint8_t *payload, uint16_t payloadLength, EmberCoapResponseHandler responseHandler, const EmberCoapSendInfo *info)
This function sends a request.
EmberStatus emberCoapGet (const EmberIpv6Address *destination, const uint8_t *path, EmberCoapResponseHandler responseHandler, const EmberCoapSendInfo *info)
This function sends a GET request.
EmberStatus emberCoapPut (const EmberIpv6Address *destination, const uint8_t *path, const uint8_t *payload, uint16_t payloadLength, EmberCoapResponseHandler responseHandler, const EmberCoapSendInfo *info)
This function sends a PUT request.
EmberStatus emberCoapPost (const EmberIpv6Address *destination, const uint8_t *path, const uint8_t *payload, uint16_t payloadLength, EmberCoapResponseHandler responseHandler, const EmberCoapSendInfo *info)
This function sends a POST request.
EmberStatus emberCoapDelete (const EmberIpv6Address *destination, const uint8_t *path, EmberCoapResponseHandler responseHandler, const EmberCoapSendInfo *info)
This function sends a DELETE request.
void emberCoapRequestHandler ( EmberCoapCode code, uint8_t *uri, EmberCoapReadOptions *options, const uint8_t *payload, uint16_t payloadLength, const EmberCoapRequestInfo *info)
Callback for incoming requests.
EmberStatus emberCoapRespond (const EmberCoapRequestInfo *requestInfo, EmberCoapCode code, const EmberCoapOption *options, uint8_t numberOfOptions, const uint8_t *payload, uint16_t payloadLength)
Sending a response.
EmberStatus emberCoapRespondWithPath (const EmberCoapRequestInfo *requestInfo, EmberCoapCode code, const uint8_t *path, const EmberCoapOption *options, uint8_t numberOfOptions, const uint8_t *payload, uint16_t payloadLength)
Sending a response that includes a location path.
EmberStatus emberCoapRespondWithCode (const EmberCoapRequestInfo *requestInfo, EmberCoapCode code)
Sending a response that consists of just a code.
EmberStatus emberCoapRespondWithPayload (const EmberCoapRequestInfo *requestInfo, EmberCoapCode code, const uint8_t *payload, uint16_t payloadLength)
Sending a response that consists of a code and a payload.
void emberSaveRequestInfo (const EmberCoapRequestInfo *from, EmberCoapRequestInfo *to)
This function saves a EmberCoapRequestInfo for later use.
void emberProcessCoap (const uint8_t *message, uint16_t messageLength, EmberCoapRequestInfo *info)
This function processes a CoAP message received over an alternate transport.
uint32_t emberBlockOptionOffset ( EmberCoapBlockOption *option)
bool emberReadBlockOption ( EmberCoapReadOptions *options, EmberCoapOptionType type, EmberCoapBlockOption *option)
void emberParseBlockOptionValue (uint32_t value, EmberCoapBlockOption *option)
uint32_t emberBlockOptionValue (bool more, uint8_t logSize, uint32_t number)
void emberInitCoapOption ( EmberCoapOption *option, EmberCoapOptionType type, uint32_t value)
bool emberVerifyBlockOption (const EmberCoapBlockOption *blockOption, uint16_t payloadLength, uint8_t expectedLogSize)
EmberStatus emberCoapRequestNextBlock ( EmberCoapCode code, const uint8_t *path, EmberCoapBlockOption *block2Option, EmberCoapResponseHandler responseHandler, EmberCoapResponseInfo *responseInfo)

Detailed Description

The CoAP API was updated for the Silicon Labs Thread 2.2 release. The new API is simpler and more flexible. These notes provide a brief overview of the key parts of the API to help customers migrate from the old API to the new API.

Sending messages

The old API had two functions for sending messages:

1 EmberStatus emberCoapSend(EmberCoapMessage *message,
2 const uint8_t *uri,
3 uint32_t responseTimeoutMs,
4 EmberCoapResponseHandler responseHandler,
5 void *applicationData,
6 uint16_t applicationDataLength);
7
8 EmberStatus emberCoapSendUri(EmberCoapCode code,
9 const EmberIpv6Address *destination,
10 const uint8_t *uri,
11 const uint8_t *body,
12 uint16_t bodyLength,
13 EmberCoapResponseHandler responseHandler);

If the responseHandler was NULL, the message was sent as a non-confirmable message (NON). Otherwise, the message was sent as a confirmable message (CON) and responseHandler was called when a response was received or a timeout occurred.

Now a single function is used for sending:

1 EmberStatus emberCoapSend(const EmberIpv6Address *destination,
2 EmberCoapCode code,
3 const uint8_t *path,
4 const uint8_t *payload,
5 uint16_t payloadLength,
6 EmberCoapResponseHandler responseHandler,
7 const EmberCoapSendInfo *info);

Common settings are passed directly as arguments to the function with other settings passed through a structure. CON or NON is determined by a field in the structure. Default settings, which include sending a CON to unicast addresses or NON to multicast addresses, can be obtained by zeroing the structure:

1 // Clear the structure to use default settings.
2 EmberCoapSendInfo info;
3 MEMSET(&info, 0, sizeof(EmberCoapSendInfo));
4 EmberStatus status = emberCoapSend(destination,
5 EMBER_COAP_CODE_GET,
6 "an/example/path",
7 payload,
8 payloadLength,
9 myResponseHandler,
10 &info);

The old API had a number of utility functions for sending specific types of requests:

1 EmberStatus emberCoapGet(const EmberIpv6Address *destination,
2 const uint8_t *uri,
3 EmberCoapResponseHandler responseHandler);
4
5 EmberStatus emberCoapPost(const EmberIpv6Address *destination,
6 const uint8_t *uri,
7 const uint8_t *body,
8 uint16_t bodyLength,
9 EmberCoapResponseHandler responseHandler);
10
11 EmberStatus emberCoapPostNonconfirmable(const EmberIpv6Address *destination,
12 const uint8_t *uri,
13 const uint8_t *body,
14 uint16_t bodyLength);

Similar utility functions exist in the new API.

1 EmberStatus emberCoapGet(const EmberIpv6Address *destination,
2 const uint8_t *path,
3 EmberCoapResponseHandler responseHandler,
4 const EmberCoapSendInfo *info);
5
6 EmberStatus emberCoapPut(const EmberIpv6Address *destination,
7 const uint8_t *path,
8 const uint8_t *payload,
9 uint16_t payloadLength,
10 EmberCoapResponseHandler responseHandler,
11 const EmberCoapSendInfo *info);
12
13 EmberStatus emberCoapPost(const EmberIpv6Address *destination,
14 const uint8_t *path,
15 const uint8_t *payload,
16 uint16_t payloadLength,
17 EmberCoapResponseHandler responseHandler,
18 const EmberCoapSendInfo *info);
19
20 EmberStatus emberCoapDelete(const EmberIpv6Address *destination,
21 const uint8_t *path,
22 EmberCoapResponseHandler responseHandler,
23 const EmberCoapSendInfo *info);

Receiving messages

The old API had a single handler for receiving messages:

1 void emberCoapMessageHandler(EmberCoapMessage *message);

All details of the message were contained in a single structure. Responses had to be sent from within the context of the handler.

The new API also has a single handler for receiving messages:

1 void emberCoapRequestHandler(EmberCoapCode code,
2 uint8_t *uri,
3 EmberCoapReadOptions *options,
4 const uint8_t *payload,
5 uint16_t payloadLength,
6 const EmberCoapRequestInfo *info);

Common settings are passed directly as arguments to the handler, with other settings passed via structures. The EmberCoapRequestInfo structure is used to send a response to the request. By saving the contents of the structure, the application can send a delayed response to the message. If a response is sent within the context of the handler, the stack will send a piggybacked response, which has the acknowledgement and the response in a single message. If a response is not sent within the context of the handler, the stack will send an acknowledgement only. The application can send a separate response later.

Responding to messages

The old API had a number of functions for sending responses:

1 EmberStatus emberCoapRespond(EmberCoapCode responseCode,
2 const uint8_t *payload,
3 uint16_t payloadLength);
4
5 EmberStatus emberCoapRespondFormat(EmberCoapCode responseCode,
6 EmberCoapContentFormatType format,
7 const uint8_t *payload,
8 uint16_t payloadLength);
9
10 EmberStatus emberCoapRespondCreated(const uint8_t *locationPath);

Each of these were required to be called from within the context of emberCoapMessageHandler.

The new API has a single function for sending responses:

1 EmberStatus emberCoapRespondWithPath(const EmberCoapRequestInfo *requestInfo,
2 EmberCoapCode code,
3 const uint8_t *path,
4 const EmberCoapOption *options,
5 uint8_t numberOfOptions,
6 const uint8_t *payload,
7 uint16_t payloadLength);

The new API also has utility functions for sending specific types of responses.

1 EmberStatus emberCoapRespond(const EmberCoapRequestInfo *requestInfo,
2 EmberCoapCode code,
3 const EmberCoapOption *options,
4 uint8_t numberOfOptions,
5 const uint8_t *payload,
6 uint16_t payloadLength);
7
8 EmberStatus emberCoapRespondWithCode(const EmberCoapRequestInfo *requestInfo,
9 EmberCoapCode code);
10
11 EmberStatus emberCoapRespondWithPayload(const EmberCoapRequestInfo *requestInfo,
12 EmberCoapCode code,
13 const uint8_t *payload,
14 uint16_t payloadLength);

The EmberCoapRequestInfo structure from the request is passed in when sending a response. To send a piggybacked response, call one of the response APIs from within the handler:

1 void emberCoapRequestHandler(EmberCoapCode code,
2 uint8_t *uri,
3 EmberCoapReadOptions *options,
4 const uint8_t *payload,
5 uint16_t payloadLength,
6 const EmberCoapRequestInfo *info)
7 {
8 emberCoapRespondWithCode(info, EMBER_COAP_CODE_204_CHANGED);
9 }

To send a separate response, save the structure and use it to reply later. A utility function can be used to save the structure:

1 void emberSaveRequestInfo(const EmberCoapRequestInfo *from,
2 EmberCoapRequestInfo *to);
3
4 static EmberCoapRequestInfo myInfo;
5 void emberCoapRequestHandler(EmberCoapCode code,
6 uint8_t *uri,
7 EmberCoapReadOptions *options,
8 const uint8_t *payload,
9 uint16_t payloadLength,
10 const EmberCoapRequestInfo *info)
11 {
12 emberSaveRequestInfo(info, &myInfo);
13 }
14
15 static void sendResponse(void)
16 {
17 emberCoapRespondWithCode(&myInfo, EMBER_COAP_CODE_204_CHANGED);
18 }

Macro Definition Documentation

#define BLOCK_OPTION_VALUE_LOG_SIZE_MAX   10
#define BLOCK_OPTION_VALUE_LOG_SIZE_MIN   4
#define EMBER_COAP_DEFAULT_TIMEOUT_MS   90000
#define EMBER_COAP_MAX_TOKEN_LENGTH   8
#define EMBER_COAP_PORT   5683
#define EMBER_COAP_SECURE_PORT   5684
#define emberBlockOptionSize ( option ) (1 << (option)->logSize)
#define GET_COAP_CLASS ( code ) (((code) & 0xE0) >> 5)
#define GET_COAP_DETAIL ( code ) ((code) & 0x1F)
#define MAKE_COAP_CODE ( class,
detail
) ((class << 5) | detail)

Typedef Documentation

typedef struct EmberCoapReadOptions_s EmberCoapReadOptions

The EmberCoapReadOptions type encapsulates the incoming options from a message. It is opaque to the application and contains an interal pointer that can be used to walk down the list of options received. Options can be read sequentially, using emberReadNextOption() , or individually, using emberReadIntegerOption() or emberReadBytesOption() .

typedef void(* EmberCoapResponseHandler) ( EmberCoapStatus status, EmberCoapCode code, EmberCoapReadOptions *options, uint8_t *payload, uint16_t payloadLength, EmberCoapResponseInfo *info)

The arguments options , payload , and payloadLength are meaningful only when status is EMBER_COAP_MESSAGE_RESPONSE .

typedef bool(* EmberCoapTransmitHandler) (const uint8_t *payload, uint16_t payloadLength, const EmberIpv6Address *localAddress, uint16_t localPort, const EmberIpv6Address *remoteAddress, uint16_t remotePort, void *transmitHandlerData)

CoAP messages can be sent via transports other than UDP, such as DTLS, by providing a function of this type. The CoAP code calls the provided function whenever a message needs to be sent.

The addresses, ports, and transmitHandlerData are the values that were passed to the original call to emberCoapSend() (if the message is a request) or to emberProcessCoap() (if the message is a response). Their values are specific to the underlying transport and need not be actual IPv6 addresses or ports.

Returns
true if transmission was initiated and false otherwise

Enumeration Type Documentation

enum EmberCoapClass
Enumerator
EMBER_COAP_CLASS_REQUEST
EMBER_COAP_CLASS_SUCCESS_RESPONSE
EMBER_COAP_CLASS_CLIENT_ERROR_RESPONSE
EMBER_COAP_CLASS_SERVER_ERROR_RESPONSE
enum EmberCoapCode
Enumerator
EMBER_COAP_CODE_EMPTY
EMBER_COAP_CODE_GET
EMBER_COAP_CODE_POST
EMBER_COAP_CODE_PUT
EMBER_COAP_CODE_DELETE
EMBER_COAP_CODE_201_CREATED
EMBER_COAP_CODE_202_DELETED
EMBER_COAP_CODE_203_VALID
EMBER_COAP_CODE_204_CHANGED
EMBER_COAP_CODE_205_CONTENT
EMBER_COAP_CODE_231_CONTINUE
EMBER_COAP_CODE_400_BAD_REQUEST
EMBER_COAP_CODE_401_UNAUTHORIZED
EMBER_COAP_CODE_402_BAD_OPTION
EMBER_COAP_CODE_403_FORBIDDEN
EMBER_COAP_CODE_404_NOT_FOUND
EMBER_COAP_CODE_405_METHOD_NOT_ALLOWED
EMBER_COAP_CODE_406_NOT_ACCEPTABLE
EMBER_COAP_CODE_412_PRECONDITION_FAILED
EMBER_COAP_CODE_413_REQUEST_ENTITY_TOO_LARGE
EMBER_COAP_CODE_415_UNSUPPORTED_CONTENT_FORMAT
EMBER_COAP_CODE_500_INTERNAL_SERVER_ERROR
EMBER_COAP_CODE_501_NOT_IMPLEMENTED
EMBER_COAP_CODE_502_BAD_GATEWAY
EMBER_COAP_CODE_503_SERVICE_UNAVAILABLE
EMBER_COAP_CODE_504_GATEWAY_TIMEOUT
EMBER_COAP_CODE_505_PROXYING_NOT_SUPPORTED
enum EmberCoapContentFormatType
Enumerator
EMBER_COAP_CONTENT_FORMAT_TEXT_PLAIN
EMBER_COAP_CONTENT_FORMAT_LINK_FORMAT
EMBER_COAP_CONTENT_FORMAT_XML
EMBER_COAP_CONTENT_FORMAT_OCTET_STREAM
EMBER_COAP_CONTENT_FORMAT_EXI
EMBER_COAP_CONTENT_FORMAT_JSON
EMBER_COAP_CONTENT_FORMAT_CBOR
EMBER_COAP_CONTENT_FORMAT_LINK_FORMAT_PLUS_CBOR
EMBER_COAP_CONTENT_FORMAT_NONE
enum EmberCoapOptionType
Enumerator
EMBER_COAP_NO_OPTION
EMBER_COAP_OPTION_IF_MATCH
EMBER_COAP_OPTION_URI_HOST
EMBER_COAP_OPTION_ETAG
EMBER_COAP_OPTION_IF_NONE_MATCH
EMBER_COAP_OPTION_OBSERVE
EMBER_COAP_OPTION_URI_PORT
EMBER_COAP_OPTION_LOCATION_PATH
EMBER_COAP_OPTION_URI_PATH
EMBER_COAP_OPTION_CONTENT_FORMAT
EMBER_COAP_OPTION_MAX_AGE
EMBER_COAP_OPTION_URI_QUERY
EMBER_COAP_OPTION_ACCEPT
EMBER_COAP_OPTION_LOCATION_QUERY
EMBER_COAP_OPTION_BLOCK2
EMBER_COAP_OPTION_BLOCK1
EMBER_COAP_OPTION_SIZE2
EMBER_COAP_OPTION_PROXY_URI
EMBER_COAP_OPTION_PROXY_SCHEME
EMBER_COAP_OPTION_SIZE1
enum EmberCoapStatus

For unicast requests EmberCoapResponseHandler() will usually be called exactly once, with one of the following three status values:

EMBER_COAP_MESSAGE_RESPONSE EMBER_COAP_MESSAGE_TIMED_OUT EMBER_COAP_MESSAGE_RESET

If the server sends an ACK before any other response, EmberCoapResponseHandler() will be called twice, the first time with status EMBER_COAP_MESSAGE_ACKED and the second time with either status EMBER_COAP_MESSAGE_RESPONSE (if a response arrives after the ACK and before the timeout) or status EMBER_COAP_MESSAGE_TIMED_OUT (if no response arrives after the ACK and before the timeout).

For multicast requests, EmberCoapResponseHandler() will be called with status EMBER_COAP_MESSAGE_RESPONSE for each response that arrives and a final time with status EMBER_COAP_MESSAGE_TIMED_OUT .

Enumerator
EMBER_COAP_MESSAGE_TIMED_OUT
EMBER_COAP_MESSAGE_ACKED
EMBER_COAP_MESSAGE_RESET
EMBER_COAP_MESSAGE_RESPONSE

Function Documentation

uint32_t emberBlockOptionOffset ( EmberCoapBlockOption * option )
uint32_t emberBlockOptionValue ( bool more,
uint8_t logSize,
uint32_t number
)
EmberStatus emberCoapDelete ( const EmberIpv6Address * destination,
const uint8_t * path,
EmberCoapResponseHandler responseHandler,
const EmberCoapSendInfo * info
)

See emberCoapSend() for more information.

EmberStatus emberCoapGet ( const EmberIpv6Address * destination,
const uint8_t * path,
EmberCoapResponseHandler responseHandler,
const EmberCoapSendInfo * info
)

See emberCoapSend() for more information.

bool emberCoapIsClientErrorResponse ( EmberCoapCode code )
bool emberCoapIsRequest ( EmberCoapCode code )
bool emberCoapIsResponse ( EmberCoapCode code )
bool emberCoapIsServerErrorResponse ( EmberCoapCode code )
bool emberCoapIsSuccessResponse ( EmberCoapCode code )
EmberStatus emberCoapPost ( const EmberIpv6Address * destination,
const uint8_t * path,
const uint8_t * payload,
uint16_t payloadLength,
EmberCoapResponseHandler responseHandler,
const EmberCoapSendInfo * info
)

See emberCoapSend() for more information.

EmberStatus emberCoapPut ( const EmberIpv6Address * destination,
const uint8_t * path,
const uint8_t * payload,
uint16_t payloadLength,
EmberCoapResponseHandler responseHandler,
const EmberCoapSendInfo * info
)

See emberCoapSend() for more information.

void emberCoapRequestHandler ( EmberCoapCode code,
uint8_t * uri,
EmberCoapReadOptions * options,
const uint8_t * payload,
uint16_t payloadLength,
const EmberCoapRequestInfo * info
)

info can be passed as-is when sending an immediate response from within the call to emberCoapRequestHandler() . To send a delayed response, info data must be copied to a more permanent location using emberSaveRequestInfo() .

For more information, see stack/include/coap.h

info can be passed as-is when sending an immediate response from within the call to emberCoapRequestHandler() . To send a delayed response, the info data must be copied to a more permanent location using emberSaveRequestInfo() .

EmberStatus emberCoapRequestNextBlock ( EmberCoapCode code,
const uint8_t * path,
EmberCoapBlockOption * block2Option,
EmberCoapResponseHandler responseHandler,
EmberCoapResponseInfo * responseInfo
)
EmberStatus emberCoapRespond ( const EmberCoapRequestInfo * requestInfo,
EmberCoapCode code,
const EmberCoapOption * options,
uint8_t numberOfOptions,
const uint8_t * payload,
uint16_t payloadLength
)
EmberStatus emberCoapRespondWithCode ( const EmberCoapRequestInfo * requestInfo,
EmberCoapCode code
)
EmberStatus emberCoapRespondWithPath ( const EmberCoapRequestInfo * requestInfo,
EmberCoapCode code,
const uint8_t * path,
const EmberCoapOption * options,
uint8_t numberOfOptions,
const uint8_t * payload,
uint16_t payloadLength
)
EmberStatus emberCoapRespondWithPayload ( const EmberCoapRequestInfo * requestInfo,
EmberCoapCode code,
const uint8_t * payload,
uint16_t payloadLength
)
EmberStatus emberCoapSend ( const EmberIpv6Address * destination,
EmberCoapCode code,
const uint8_t * path,
const uint8_t * payload,
uint16_t payloadLength,
EmberCoapResponseHandler responseHandler,
const EmberCoapSendInfo * info
)

Any response is passed to responseHandler . For unicast requests, at most one response is processed. For multicast requests, the response handler is called once for each response that arrives before the response timeout. The payloadLength plus the (variable length) coap header must not exceed EMBER_MAX_UDP_HEADER_LENGTH (1232).

Returns
EMBER_SUCCESS if no errors occured.
void emberInitCoapOption ( EmberCoapOption * option,
EmberCoapOptionType type,
uint32_t value
)
void emberParseBlockOptionValue ( uint32_t value,
EmberCoapBlockOption * option
)
void emberProcessCoap ( const uint8_t * message,
uint16_t messageLength,
EmberCoapRequestInfo * info
)

Called to process a CoAP message that arrives via DTLS or other alternative transport. Only the address, port, and transmit handler fields of info are used. The token and ackData fields are ignored.

This function processes a CoAP message received over an alternate transport.

Called to process a CoAP message that arrived via DTLS or other alternative transport. Only the address, port and transmit handler fields of info are used. The token and ackData fields are ignored.

bool emberReadBlockOption ( EmberCoapReadOptions * options,
EmberCoapOptionType type,
EmberCoapBlockOption * option
)
bool emberReadBytesOption ( EmberCoapReadOptions * options,
EmberCoapOptionType type,
const uint8_t ** valueLoc,
uint16_t * valueLengthLoc
)

This function searches from the beginning of the options and leaves option s internal pointer pointing to the option following the one returned.

Returns
true if the option was found
bool emberReadIntegerOption ( EmberCoapReadOptions * options,
EmberCoapOptionType type,
uint32_t * valueLoc
)

This function searches from the beginning of the options and leaves option s internal pointer pointing to the option following the one returned.

Returns
true if the option was found
int16_t emberReadLocationPath ( EmberCoapReadOptions * options,
uint8_t * pathBuffer,
uint16_t pathBufferLength
)

Any path options are copied to pathBuffer with a '/' between each pair of path elements.

If the path is longer than pathBufferLength only the first pathBufferLength bytes are stored in pathBuffer .

Returns
the length of the complete path
EmberCoapOptionType emberReadNextOption ( EmberCoapReadOptions * options,
const uint8_t ** valuePointerLoc,
uint16_t * valueLengthLoc
)

Reads the next option from an incoming message, advancing the internal pointer to the following option. Returns EMBER_COAP_NO_OPTION if there are no more options to read.

uint32_t emberReadOptionValue ( const uint8_t * value,
uint16_t valuelength
)

This function should be passed the value and length returned by emberReadNextOption() .

void emberResetReadOptionPointer ( EmberCoapReadOptions * options )
void emberSaveRequestInfo ( const EmberCoapRequestInfo * from,
EmberCoapRequestInfo * to
)

This saves necesary fields from from to to so that to may later be used to send a response.

bool emberVerifyBlockOption ( const EmberCoapBlockOption * blockOption,
uint16_t payloadLength,
uint8_t expectedLogSize
)