nRF51 IoT SDK
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
CoAP Application Programming Interface

Public API of Nordic's CoAP implementation. More...

Modules

 Resource content type bitmask values
 
 Resource method permission bitmask values
 

Data Structures

struct  coap_option_t
 Structure to hold a CoAP option. More...
 
struct  coap_message_conf_t
 Structure to hold a CoAP message configuration. More...
 
struct  coap_message_header_t
 Structure to hold a CoAP message header. More...
 
struct  coap_message_t
 Structure to hold a CoAP message. More...
 
struct  coap_resource_t
 Structure to hold a CoAP endpoint resource. More...
 

Typedefs

typedef void(* coap_response_callback_t )(coap_message_t *p_message)
 Callback function to be registered with CoAP messages.
 
typedef void(* coap_method_callback_t )(coap_message_t *p_request, coap_message_t *p_response)
 Callback function to be registered with CoAP endpoint resources.
 

Enumerations

enum  coap_content_type_t {
  COAP_CT_PLAIN_TEXT = 0,
  COAP_CT_APP_LINK_FORMAT = 40,
  COAP_CT_APP_XML = 41,
  COAP_CT_APP_OCTET_STREAM = 42,
  COAP_CT_APP_EXI = 47,
  COAP_CT_APP_JSON = 50
}
 Enumeration of CoAP content types. More...
 
enum  coap_opt_number_t {
  COAP_OPT_RESERVED0 = 0,
  COAP_OPT_IF_MATCH = 1,
  COAP_OPT_URI_HOST = 3,
  COAP_OPT_ETAG = 4,
  COAP_OPT_IF_NONE_MATCH = 5,
  COAP_OPT_URI_PORT = 7,
  COAP_OPT_LOCATION_PATH = 8,
  COAP_OPT_URI_PATH = 11,
  COAP_OPT_CONTENT_FORMAT = 12,
  COAP_OPT_MAX_AGE = 14,
  COAP_OPT_URI_QUERY = 15,
  COAP_OPT_ACCEPT = 17,
  COAP_OPT_LOCATION_QUERY = 20,
  COAP_OPT_PROXY_URI = 35,
  COAP_OPT_PROXY_SCHEME = 39,
  COAP_OPT_SIZE1 = 60,
  COAP_OPT_RESERVED1 = 128,
  COAP_OPT_RESERVED2 = 132,
  COAP_OPT_RESERVED3 = 136,
  COAP_OPT_RESERVED4 = 140
}
 Enumeration of CoAP options numbers. More...
 
enum  coap_msg_type_t {
  COAP_TYPE_CON = 0,
  COAP_TYPE_NON,
  COAP_TYPE_ACK,
  COAP_TYPE_RST
}
 Enumeration of CoAP message types. More...
 

Functions

uint32_t coap_init (uint32_t token_rand_seed)
 Initializes the CoAP module. More...
 
uint32_t coap_request_send (coap_message_t *p_message)
 Sends a CoAP message. More...
 
uint32_t coap_request_create (coap_message_t **p_request, coap_message_conf_t *p_config)
 Creates CoAP message, initializes, and allocates the needed memory. More...
 
uint32_t coap_request_delete (coap_message_t *p_message)
 Deletes the CoAP request message. More...
 
uint32_t coap_message_payload_set (coap_message_t *p_message, void *p_payload, uint16_t payload_len)
 Adds a payload to a CoAP message. More...
 
uint32_t coap_message_opt_empty_add (coap_message_t *p_message, uint16_t option_num)
 Adds an empty CoAP option to the message. More...
 
uint32_t coap_message_opt_uint_add (coap_message_t *p_message, uint16_t option_num, uint32_t data)
 Adds a uint CoAP option to the message. More...
 
uint32_t coap_message_opt_str_add (coap_message_t *p_message, uint16_t option_num, uint8_t *p_data, uint16_t length)
 Adds a string CoAP option to the message. More...
 
uint32_t coap_message_opt_opaque_add (coap_message_t *p_message, uint16_t option_num, uint8_t *p_data, uint16_t length)
 Adds an opaque CoAP option to the message. More...
 
uint32_t coap_message_remote_addr_set (coap_message_t *p_message, coap_remote_t *p_address)
 Sets a remote address and port number to a CoAP message. More...
 
uint32_t coap_resource_create (coap_resource_t *p_resource, const char *name)
 Creates a CoAP endpoint resource. More...
 
uint32_t coap_resource_child_add (coap_resource_t *p_parent, coap_resource_t *p_child)
 Adds a child resource. More...
 
uint32_t coap_resource_well_known_generate (uint8_t *string, uint16_t *length)
 Generates .well-known/core string. More...
 

Detailed Description

Public API of Nordic's CoAP implementation.

Enumeration Type Documentation

Enumeration of CoAP content types.

Enumerator
COAP_CT_PLAIN_TEXT 

Plain text content format number. Default.

COAP_CT_APP_LINK_FORMAT 

Application/link-format content format number.

COAP_CT_APP_XML 

Application/xml content format number.

COAP_CT_APP_OCTET_STREAM 

Application/octet-stream content format number.

COAP_CT_APP_EXI 

Application/exi content format number.

COAP_CT_APP_JSON 

Application/json content format number.

Enumeration of CoAP message types.

Enumerator
COAP_TYPE_CON 

Confirmable Message type.

COAP_TYPE_NON 

Non-Confirmable Message type.

COAP_TYPE_ACK 

Acknowledge Message type.

COAP_TYPE_RST 

Reset Message type.

Enumeration of CoAP options numbers.

Enumerator
COAP_OPT_RESERVED0 

Reserved option number.

COAP_OPT_IF_MATCH 

If-Match option number.

COAP_OPT_URI_HOST 

URI-Host option number.

COAP_OPT_ETAG 

ETag option number.

COAP_OPT_IF_NONE_MATCH 

If-None-Match option number.

COAP_OPT_URI_PORT 

URI-Port option number.

COAP_OPT_LOCATION_PATH 

Location-Path option number.

COAP_OPT_URI_PATH 

URI-Path option number.

COAP_OPT_CONTENT_FORMAT 

Content-Format option number.

COAP_OPT_MAX_AGE 

Max-Age option number.

COAP_OPT_URI_QUERY 

URI-Query option number.

COAP_OPT_ACCEPT 

Accept option number.

COAP_OPT_LOCATION_QUERY 

Location-Query option number.

COAP_OPT_PROXY_URI 

Proxy-URI option number.

COAP_OPT_PROXY_SCHEME 

Proxy-Scheme option number.

COAP_OPT_SIZE1 

Size1 option number.

COAP_OPT_RESERVED1 

Reserved option number.

COAP_OPT_RESERVED2 

Reserved option number.

COAP_OPT_RESERVED3 

Reserved option number.

COAP_OPT_RESERVED4 

Reserved option number.

Function Documentation

uint32_t coap_init ( uint32_t  token_rand_seed)

Initializes the CoAP module.

Initializes the library module and resets internal queues and resource registrations.

Parameters
[in]token_rand_seedRandom number seed to be used to generate the token numbers.
Return values
NRF_SUCCESSIf initialization succeeded.
uint32_t coap_message_opt_empty_add ( coap_message_t p_message,
uint16_t  option_num 
)

Adds an empty CoAP option to the message.

Option numbers must be in ascending order, adding the one with the smallest number first and greatest last. If the order is incorrect, the delta number calculation will result in an invalid or wrong delta number for the option.

Parameters
[in,out]p_messagePointer to the message to add the option to.
[in]option_numThe option number to add to the message.
Return values
NRF_ERROR_DATA_SIZEIf the data exceeds the available message buffer data size.
NRF_ERROR_NO_MEMIf the maximum number of options that can be added to a message has been reached.
uint32_t coap_message_opt_opaque_add ( coap_message_t p_message,
uint16_t  option_num,
uint8_t *  p_data,
uint16_t  length 
)

Adds an opaque CoAP option to the message.

Option numbers must be in ascending order, adding the one with the smallest number first and greatest last. If the order is incorrect, the delta number calculation will result in an invalid or wrong delta number for the option.

Parameters
[in,out]p_messagePointer to the message to add the option to.
[in]option_numThe option number to add to the message.
[in]p_dataPointer to an opaque buffer to be used as value for the option.
[in]lengthLength of the opaque buffer provided.
Return values
NRF_ERROR_DATA_SIZEIf the data exceeds the available message buffer data size.
NRF_ERROR_NO_MEMIf the maximum number of options that can be added to a message has been reached.
uint32_t coap_message_opt_str_add ( coap_message_t p_message,
uint16_t  option_num,
uint8_t *  p_data,
uint16_t  length 
)

Adds a string CoAP option to the message.

Option numbers must be in ascending order, adding the one with the smallest number first and greatest last. If the order is incorrect, the delta number calculation will result in an invalid or wrong delta number for the option.

Parameters
[in,out]p_messagePointer to the message to add the option to.
[in]option_numThe option number to add to the message.
[in]p_dataPointer to a string buffer to be used as value for the option.
[in]lengthLength of the string buffer provided.
Return values
NRF_ERROR_DATA_SIZEIf the data exceeds the available message buffer data size.
NRF_ERROR_NO_MEMIf the maximum number of options that can be added to a message has been reached.
uint32_t coap_message_opt_uint_add ( coap_message_t p_message,
uint16_t  option_num,
uint32_t  data 
)

Adds a uint CoAP option to the message.

Option numbers must be in ascending order, adding the one with the smallest number first and greatest last. If the order is incorrect, the delta number calculation will result in an invalid or wrong delta number for the option.

Parameters
[in,out]p_messagePointer to the message to add the option to.
[in]option_numThe option number to add to the message.
[in]dataAn unsigned value (8-bit, 16-bit, or 32-bit) casted to uint32_t. The value of the data is used to determine how many bytes CoAP must use to represent this option value.
Return values
NRF_ERROR_DATA_SIZEIf the data exceeds the available message buffer data size.
NRF_ERROR_NO_MEMIf the maximum number of options that can be added to a message has been reached.
uint32_t coap_message_payload_set ( coap_message_t p_message,
void *  p_payload,
uint16_t  payload_len 
)

Adds a payload to a CoAP message.

Sets a data payload to a request or response message.

This function must be called after all CoAP options have been added. Due to internal buffers in the library, the payload will be added after any options in the buffer. If an option is added after the payload, this option will over-write the payload in the internal buffer.

Parameters
[in,out]p_messagePointer to the message to add the payload to.
[in]p_payloadPointer to the payload to be added.
[in]payload_lenSize of the payload to be added.
uint32_t coap_message_remote_addr_set ( coap_message_t p_message,
coap_remote_t p_address 
)

Sets a remote address and port number to a CoAP message.

Copies the content of the provided pointer into the CoAP message.

Parameters
[in,out]p_messagePointer to the message to add the address information to.
[in]p_addressPointer to a structure holding the address information for the remote server or client.
Return values
NRF_SUCCESSWhen copying the content has finished.
uint32_t coap_request_create ( coap_message_t **  p_request,
coap_message_conf_t p_config 
)

Creates CoAP message, initializes, and allocates the needed memory.

Creates a CoAP message. This is an intermediate representation of the message, because the message will be serialized by the library before it is transmitted. The structure is verbose to facilitate configuring the message. Options, payload, and remote address information can be added using API function calls.

Parameters
[in,out]p_requestPointer to be filled by the allocated CoAP message structures.
[in]p_configConfiguration for the message to be created. Manual configuration can be performed after the message creation, except for the CLIENT port association.
Return values
NRF_SUCCESSIf the request was successfully allocated and initialized.
uint32_t coap_request_delete ( coap_message_t p_message)

Deletes the CoAP request message.

Frees up memory associated with the request message.

Parameters
[in]p_messagePointer to the request message to delete.
uint32_t coap_request_send ( coap_message_t p_message)

Sends a CoAP message.

Sends out a request using the underlying transport layer. Before sending, the coap_message_t structure is serialized and added to an internal message queue in the library.

Parameters
[in]p_messageMessage to be sent.
Return values
NRF_SUCCESSIf the message was successfully encoded and scheduled for transmission.
uint32_t coap_resource_child_add ( coap_resource_t p_parent,
coap_resource_t p_child 
)

Adds a child resource.

The hierarchy is constructed as a linked list with a maximum number of children. COAP_RESOURCE_MAX_DEPTH in coap_config.h sets the maximum depth. The maximum number of children can be adjusted if more levels are needed.

Parameters
[in]p_parentResource to attach the child to.
[in]p_childChild resource to attach.
Return values
NRF_SUCCESSIf the child was successfully added.
COAP_ERROR_MAX_DEPTH_REACHEDIf the child is exceeding the maximum depth defined.
uint32_t coap_resource_create ( coap_resource_t p_resource,
const char *  name 
)

Creates a CoAP endpoint resource.

Initializes the coap_resource_t members.

The first resource that is created will be set as the root of the resource hierarchy.

Parameters
[in]p_resourcePointer to coap_resource_t passed in by reference. This variable must be stored in non-volatile memory.
[in]nameVerbose name of the service (zero-terminated string). The maximum length of a name is defined by COAP_RESOURCE_MAX_NAME_LEN in coap_config.h and can be adjusted if needed.
Return values
NRF_ERROR_DATA_SIZEIf the provided name is larger than the available name buffer.
NRF_ERROR_NULLIf the pointer to the resource or the provided name buffer is NULL.
uint32_t coap_resource_well_known_generate ( uint8_t *  string,
uint16_t *  length 
)

Generates .well-known/core string.

This is a helper function for generating a CoRE link-format encoded string used for CoAP discovery. The function traverse the resource hierarchy recursively. The result will be resources listed in link-format. This function can be called when all resources have been added by the application.

Parameters
[in,out]stringBuffer to use for the .well-known/core string.
[in,out]lengthLength of the string buffer. Returns the used number of bytes from the provided buffer.
Return values
NRF_SUCCESSIf string generation was successful.
NRF_ERROR_NULLIf the string buffer was a NULL pointer.
NRF_ERROR_DATA_SIZEIf the size of the generated string exceeds the given buffer size.
NRF_ERROR_INVALID_STATEIf no resource has been registered.