nRF5 IoT SDK  v0.9.0
 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...
 

Macros

#define COAP_OPT_RESERVED0   0
 Enumeration of CoAP options numbers. More...
 
#define COAP_OPT_IF_MATCH   1
 
#define COAP_OPT_URI_HOST   3
 
#define COAP_OPT_ETAG   4
 
#define COAP_OPT_IF_NONE_MATCH   5
 
#define COAP_OPT_URI_PORT   7
 
#define COAP_OPT_LOCATION_PATH   8
 
#define COAP_OPT_URI_PATH   11
 
#define COAP_OPT_CONTENT_FORMAT   12
 
#define COAP_OPT_MAX_AGE   14
 
#define COAP_OPT_URI_QUERY   15
 
#define COAP_OPT_ACCEPT   17
 
#define COAP_OPT_LOCATION_QUERY   20
 
#define COAP_OPT_BLOCK2   23
 
#define COAP_OPT_BLOCK1   27
 
#define COAP_OPT_SIZE2   28
 
#define COAP_OPT_PROXY_URI   35
 
#define COAP_OPT_PROXY_SCHEME   39
 
#define COAP_OPT_SIZE1   60
 
#define COAP_OPT_RESERVED1   128
 
#define COAP_OPT_RESERVED2   132
 
#define COAP_OPT_RESERVED3   136
 
#define COAP_OPT_RESERVED4   140
 

Typedefs

typedef void(* coap_error_callback_t )(uint32_t error_code, coap_message_t *p_message)
 Callback function to call upon undefined behaviour. More...
 
typedef void(* coap_response_callback_t )(uint32_t status, void *p_arg, coap_message_t *p_message)
 Callback function to be registered with CoAP messages. More...
 
typedef uint32_t(* coap_request_handler_t )(coap_message_t *p_request)
 Handler function for manually handling all incomming requests. More...
 
typedef void(* coap_method_callback_t )(coap_resource_t *p_resource, coap_message_t *p_request)
 Callback function to be registered with CoAP endpoint resources. in auto-mode. More...
 

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_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, coap_transport_init_t *p_transport_params)
 Initializes the CoAP module. More...
 
uint32_t coap_error_handler_register (coap_error_callback_t error_callback)
 Register error handler callback to the CoAP module. More...
 
uint32_t coap_request_handler_register (coap_request_handler_t p_request_handler)
 Register request handler which should handle all incomming requests. More...
 
uint32_t coap_message_send (uint32_t *p_handle, coap_message_t *p_message)
 Sends a CoAP message. More...
 
uint32_t coap_message_abort (uint32_t handle)
 Abort a CoAP message. More...
 
uint32_t coap_message_new (coap_message_t **p_request, coap_message_conf_t *p_config)
 Creates CoAP message, initializes, and allocates the needed memory. More...
 
uint32_t coap_message_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...
 
uint32_t coap_resource_root_get (coap_resource_t **pp_resource)
 Get the root resource pointer. More...
 
uint32_t coap_message_opt_present (coap_message_t *p_message, uint16_t option)
 Check whether a message contains a given CoAP Option. More...
 
uint32_t coap_message_opt_index_get (uint8_t *p_index, coap_message_t *p_message, uint16_t option)
 Check whether a message contains a given CoAP Option and return the index of the entry in the message option list. More...
 
uint32_t coap_message_ct_match_select (coap_content_type_t *p_ct, coap_message_t *p_message, coap_resource_t *p_resource)
 Find common content type between the CoAP message and the resource. More...
 
uint32_t coap_time_tick (void)
 CoAP time tick used for retransmitting any message in the queue if needed. More...
 
uint32_t coap_security_setup (uint16_t local_port, nrf_tls_role_t role, coap_remote_t *const p_remote, nrf_tls_key_settings_t *const p_settings)
 Setup secure DTLS session. More...
 
uint32_t coap_security_destroy (uint16_t local_port, coap_remote_t *const p_remote)
 Destroy a secure DTLS session. More...
 

Detailed Description

Public API of Nordic's CoAP implementation.

Macro Definition Documentation

#define COAP_OPT_ACCEPT   17

Accept option number.

#define COAP_OPT_BLOCK1   27

Block1 option number.

#define COAP_OPT_BLOCK2   23

Block2 option number.

#define COAP_OPT_CONTENT_FORMAT   12

Content-Format option number.

#define COAP_OPT_ETAG   4

ETag option number.

#define COAP_OPT_IF_MATCH   1

If-Match option number.

#define COAP_OPT_IF_NONE_MATCH   5

If-None-Match option number.

#define COAP_OPT_LOCATION_PATH   8

Location-Path option number.

#define COAP_OPT_LOCATION_QUERY   20

Location-Query option number.

#define COAP_OPT_MAX_AGE   14

Max-Age option number.

#define COAP_OPT_PROXY_SCHEME   39

Proxy-Scheme option number.

#define COAP_OPT_PROXY_URI   35

Proxy-URI option number.

#define COAP_OPT_RESERVED0   0

Enumeration of CoAP options numbers.

Reserved option number.

#define COAP_OPT_RESERVED1   128

Reserved option number.

#define COAP_OPT_RESERVED2   132

Reserved option number.

#define COAP_OPT_RESERVED3   136

Reserved option number.

#define COAP_OPT_RESERVED4   140

Reserved option number.

#define COAP_OPT_SIZE1   60

Size1 option number.

#define COAP_OPT_SIZE2   28

Size2 option number.

#define COAP_OPT_URI_HOST   3

URI-Host option number.

#define COAP_OPT_URI_PATH   11

URI-Path option number.

#define COAP_OPT_URI_PORT   7

URI-Port option number.

#define COAP_OPT_URI_QUERY   15

URI-Query option number.

Typedef Documentation

typedef void(* coap_error_callback_t)(uint32_t error_code, coap_message_t *p_message)

Callback function to call upon undefined behaviour.

Parameters
[in]error_codeError code from CoAP module.
[in]p_messageCoAP message processed when error ocoured. Could be NULL.
typedef void(* coap_method_callback_t)(coap_resource_t *p_resource, coap_message_t *p_request)

Callback function to be registered with CoAP endpoint resources. in auto-mode.

The callback needs to implement any action based on the request. The callback is responsible of handling the sending of any response back to the requester. The memory for p_request will be freed up by the coap module after the callback has been completed.

Parameters
[in]p_resourcePointer to the request message's target resource.
[in]p_requestPointer to the request message.
typedef uint32_t(* coap_request_handler_t)(coap_message_t *p_request)

Handler function for manually handling all incomming requests.

If the function is set, the error code given back will trigger error messages to be sent back by CoAP to indicate failure. Default error message will be 4.00 BAD REQUEST. On success, it is expected that the callback has already sent a response message.

Parameters
[in]p_requestPointer to a CoAP Request message.
Return values
NRF_SUCCESSIf the message was successfully has been handled.
NRF_ERROR_NOT_FOUNDIf the message did not match any recognized resources, and a 4.04 NOT FOUND error message should be sent back to the requester.
NRF_ERROR_NULLIf the message resolved the resource and operation not permitted, and a 4.05 METHOD NOT ALLOWED error message should be sent back to the reqester.
typedef void(* coap_response_callback_t)(uint32_t status, void *p_arg, coap_message_t *p_message)

Callback function to be registered with CoAP messages.

Parameters
[in]statusResponse status. Possible status codes: NRF_SUCCESS If response was successfully received, COAP_TRANSMISSION_RESET_BY_PEER if a reset response was recieved or, COAP_TRANSMISSION_TIMEOUT if transmission
[in]p_argMiscellaneous pointer to application provided data that is associated with the message.
[in]p_messagePointer to a CoAP Response message.

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.

Function Documentation

uint32_t coap_error_handler_register ( coap_error_callback_t  error_callback)

Register error handler callback to the CoAP module.

Parameters
[in]error_callbackFunction to be called upon unknown messages and failure.
Return values
NRF_SUCCESSIf registration was successful.
uint32_t coap_init ( uint32_t  token_rand_seed,
coap_transport_init_t p_transport_params 
)

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.
[in]p_transport_paramsPointer to transport parameters. Providing the list of ports to be used by CoAP.
Return values
NRF_SUCCESSIf initialization succeeded.
uint32_t coap_message_abort ( uint32_t  handle)

Abort a CoAP message.

Aborts an ongoing transmission. If the message has not yet been sent, it will be deleted from the message queue as well as stop any ongoing re-transmission of the message.

Parameters
[in]handleHandle of the message to abort.
Return values
NRF_SUCCESSIf the message was successfully aborted and removed from the message queue.
NRF_ERROR_NOT_FOUNDIf the message with the given handle was not located in the message queue.
uint32_t coap_message_ct_match_select ( coap_content_type_t p_ct,
coap_message_t p_message,
coap_resource_t p_resource 
)

Find common content type between the CoAP message and the resource.

The return value will be the first match between the ACCEPT options and the supported content types in the resource. The priority is by content-format ID starting going from the lowest value to the highest.

Parameters
[out]p_ctResolved content type given by reference. Should not be NULL.
[in]p_messagePointer to the message. Should not be NULL.
[in]p_resourcePointer to the resource. Should not be NULL.
Return values
NRF_SUCCESSIf match was found.
NRF_ERROR_NOT_FOUNDIf no match was found.
uint32_t coap_message_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_message_new ( 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.
NRF_ERROR_INVALID_PARAMIf local port number was not configured.
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. Should not be NULL.
[in]option_numThe option number to add to the message.
Return values
NRF_SUCCESSIf the empty option was successfully added to the message.
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_index_get ( uint8_t *  p_index,
coap_message_t p_message,
uint16_t  option 
)

Check whether a message contains a given CoAP Option and return the index of the entry in the message option list.

Parameters
[in]p_indexValue by reference to fill the resolved index into. Should not be NULL.
[in]p_messagePointer to the to check for the CoAP Option. Should not be NULL.
[in]optionCoAP Option to check for in the CoAP message.
Return values
NRF_SUCCESSIf the CoAP Option is present in the message.
NRF_ERROR_NULLIf the pointer to the message or the p_index is NULL.
NRF_ERROR_NOT_FOUNDIf the CoAP Option is not present in the message.
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. Should not be NULL.
[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. Should not be NULL.
[in]lengthLength of the opaque buffer provided.
Return values
NRF_SUCCESSIf the opaque option was successfully added to the message.
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_present ( coap_message_t p_message,
uint16_t  option 
)

Check whether a message contains a given CoAP Option.

Parameters
[in]p_messagePointer to the to check for the CoAP Option. Should not be NULL.
[in]optionCoAP Option to check for in the CoAP message.
Return values
NRF_SUCCESSIf the CoAP Option is present in the message.
NRF_ERROR_NULLIf the pointer to the message is NULL.
NRF_ERROR_NOT_FOUNDIf the CoAP Option is not present in the message.
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. Should not be NULL.
[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. Should not be NULL.
[in]lengthLength of the string buffer provided.
Return values
NRF_SUCCESSIf the string option was successfully added to the message.
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. Should not be NULL.
[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_SUCCESSIf the unsigned integer option was successfully added to the message.
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.
Return values
NRF_SUCCESSIf the payload was successfully added to the message.
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. Should not be NULL.
[in]p_addressPointer to a structure holding the address information for the remote server or client. Should not be NULL.
Return values
NRF_SUCCESSWhen copying the content has finished.
uint32_t coap_message_send ( uint32_t *  p_handle,
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. The handle returned can be used to abort the message from being retransmitted at any time.

Parameters
[out]p_handleHandle to the message if CoAP CON/ACK messages has been used. Returned by reference.
[in]p_messageMessage to be sent.
Return values
NRF_SUCCESSIf the message was successfully encoded and scheduled for transmission.
uint32_t coap_request_handler_register ( coap_request_handler_t  p_request_handler)

Register request handler which should handle all incomming requests.

Setting this request handler redirects all requests to the application provided callback routine. The callback handler might be cleared by NULL, making coap module handle the requests and do resource lookup in order to process the requests.

Parameters
[in]p_request_handlerFunction pointer to the provided request handler.
Return values
NRF_SUCCESSIf registration was successful.
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 sdk_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. Should not be NULL.
[in]p_childChild resource to attach. Should not be NULL.
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. Should not be NULL.
[in]nameVerbose name of the service (zero-terminated string). The maximum length of a name is defined by COAP_RESOURCE_MAX_NAME_LEN in sdk_config.h and can be adjusted if needed. Should not be NULL.
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_root_get ( coap_resource_t **  pp_resource)

Get the root resource pointer.

Parameters
[out]pp_resourcePointer to be filled with pointer to the root resource.
Return values
NRF_SUCCESSIf root resource was located.
NRF_ERROR_NOT_FOUNDIf root resource was not located.
NRF_ERROR_NULLIf output pointer was 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. Should not be NULL.
[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.
uint32_t coap_security_destroy ( uint16_t  local_port,
coap_remote_t *const  p_remote 
)

Destroy a secure DTLS session.

Terminate and clean up any session associated with the local port and the remote.

Parameters
[in]local_portLocal port to unbind the session from.
[in]p_remotePointer to a structure holding the address information for the remote endpoint. Providing a NULL as p_remote will clean up all DTLS sessions associated with the local port.
Return values
NRF_SUCCESSIf the destruction of the secure DTLS session was successfull.
uint32_t coap_security_setup ( uint16_t  local_port,
nrf_tls_role_t  role,
coap_remote_t *const  p_remote,
nrf_tls_key_settings_t *const  p_settings 
)

Setup secure DTLS session.

For the client role, this API triggers a DTLS handshake. Until the handshake is complete with the remote, coap_message_send will fail. For the server role, this API does not create any DTLS session. A DTLS session is created each time a new client remote endpoint sends a request on the local port of the server.

Note
The success of this function does not imply that the DTLS handshake is successfull.
Only one DTLS session is permitted between a local and remote endpoint. Therefore, in case a DTLS session was established between the local and remote endpoint, the existing DTLS session will be reused irrespective of the role and number of times this API was called. In case the application desires a fresh security setup, it must first call the coap_security_destroy to tear down the existing setup.
Parameters
[in]local_portLocal port to bind the session to.
[in]roleRole of the session. DTLS server or client defined in the enumeration nrf_tls_role_t.
[in]p_remotePointer to a structure holding the address information for the remote endpoint. If a the device is acting as a server, a NULL pointer shall be given as in this parameter. Rationale: The server is not envisioned to be bound a pre-known client endpoint. Therefore, security server settings shall be setup irrespective of the remote client.
[in]p_settingsPointer to a structure holding the DTLS credentials.
Return values
NRF_SUCCESSIf setup of the secure DTLS session was successfull.
uint32_t coap_time_tick ( void  )

CoAP time tick used for retransmitting any message in the queue if needed.

Return values
NRF_SUCCESSIf time tick update was successfully handled.