Constrained Application Protocol API

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 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_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 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 argumentsoptions, 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

Enumerator
EMBER_COAP_CLASS_REQUEST 
EMBER_COAP_CLASS_SUCCESS_RESPONSE 
EMBER_COAP_CLASS_CLIENT_ERROR_RESPONSE 
EMBER_COAP_CLASS_SERVER_ERROR_RESPONSE 
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_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 
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 
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 

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.

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