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_code	Error code from CoAP module.
[in]	p_message	CoAP 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_resource	Pointer to the request message's target resource.
[in]	p_request	Pointer 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_request Pointer to a CoAP Request message.

Return values

NRF_SUCCESS	If the message was successfully has been handled.
NRF_ERROR_NOT_FOUND	If 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_NULL	If 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]	status	Response 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_arg	Miscellaneous pointer to application provided data that is associated with the message.
[in]	p_message	Pointer to a CoAP Response message.

Enumeration Type Documentation

enum coap_content_type_t

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.

enum coap_msg_type_t

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_callback Function to be called upon unknown messages and failure.

Return values

NRF_SUCCESS If 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_seed	Random number seed to be used to generate the token numbers.
[in]	p_transport_params	Pointer to transport parameters. Providing the list of ports to be used by CoAP.

Return values

NRF_SUCCESS If 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] handle Handle of the message to abort.

Return values

NRF_SUCCESS	If the message was successfully aborted and removed from the message queue.
NRF_ERROR_NOT_FOUND	If 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_ct	Resolved content type given by reference. Should not be NULL.
[in]	p_message	Pointer to the message. Should not be NULL.
[in]	p_resource	Pointer to the resource. Should not be NULL.

Return values

NRF_SUCCESS	If match was found.
NRF_ERROR_NOT_FOUND	If 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_message Pointer 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_request	Pointer to be filled by the allocated CoAP message structures.
[in]	p_config	Configuration for the message to be created. Manual configuration can be performed after the message creation, except for the CLIENT port association.

Return values

NRF_SUCCESS	If the request was successfully allocated and initialized.
NRF_ERROR_INVALID_PARAM	If 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_message	Pointer to the message to add the option to. Should not be NULL.
[in]	option_num	The option number to add to the message.

Return values

NRF_SUCCESS	If the empty option was successfully added to the message.
NRF_ERROR_DATA_SIZE	If the data exceeds the available message buffer data size.
NRF_ERROR_NO_MEM	If 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_index	Value by reference to fill the resolved index into. Should not be NULL.
[in]	p_message	Pointer to the to check for the CoAP Option. Should not be NULL.
[in]	option	CoAP Option to check for in the CoAP message.

Return values

NRF_SUCCESS	If the CoAP Option is present in the message.
NRF_ERROR_NULL	If the pointer to the message or the p_index is NULL.
NRF_ERROR_NOT_FOUND	If 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_message	Pointer to the message to add the option to. Should not be NULL.
[in]	option_num	The option number to add to the message.
[in]	p_data	Pointer to an opaque buffer to be used as value for the option. Should not be NULL.
[in]	length	Length of the opaque buffer provided.

Return values

NRF_SUCCESS	If the opaque option was successfully added to the message.
NRF_ERROR_DATA_SIZE	If the data exceeds the available message buffer data size.
NRF_ERROR_NO_MEM	If 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_message	Pointer to the to check for the CoAP Option. Should not be NULL.
[in]	option	CoAP Option to check for in the CoAP message.

Return values

NRF_SUCCESS	If the CoAP Option is present in the message.
NRF_ERROR_NULL	If the pointer to the message is NULL.
NRF_ERROR_NOT_FOUND	If 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_message	Pointer to the message to add the option to. Should not be NULL.
[in]	option_num	The option number to add to the message.
[in]	p_data	Pointer to a string buffer to be used as value for the option. Should not be NULL.
[in]	length	Length of the string buffer provided.

Return values

NRF_SUCCESS	If the string option was successfully added to the message.
NRF_ERROR_DATA_SIZE	If the data exceeds the available message buffer data size.
NRF_ERROR_NO_MEM	If 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_message	Pointer to the message to add the option to. Should not be NULL.
[in]	option_num	The option number to add to the message.
[in]	data	An 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_SUCCESS	If the unsigned integer option was successfully added to the message.
NRF_ERROR_DATA_SIZE	If the data exceeds the available message buffer data size.
NRF_ERROR_NO_MEM	If 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_message	Pointer to the message to add the payload to.
[in]	p_payload	Pointer to the payload to be added.
[in]	payload_len	Size of the payload to be added.

Return values

NRF_SUCCESS If 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_message	Pointer to the message to add the address information to. Should not be NULL.
[in]	p_address	Pointer to a structure holding the address information for the remote server or client. Should not be NULL.

Return values

NRF_SUCCESS When 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_handle	Handle to the message if CoAP CON/ACK messages has been used. Returned by reference.
[in]	p_message	Message to be sent.

Return values

NRF_SUCCESS If 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_handler Function pointer to the provided request handler.

Return values

NRF_SUCCESS If 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_parent	Resource to attach the child to. Should not be NULL.
[in]	p_child	Child resource to attach. Should not be NULL.

Return values

NRF_SUCCESS	If the child was successfully added.
COAP_ERROR_MAX_DEPTH_REACHED	If 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_resource	Pointer to coap_resource_t passed in by reference. This variable must be stored in non-volatile memory. Should not be NULL.
[in]	name	Verbose 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_SIZE	If the provided name is larger than the available name buffer.
NRF_ERROR_NULL	If 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_resource Pointer to be filled with pointer to the root resource.

Return values

NRF_SUCCESS	If root resource was located.
NRF_ERROR_NOT_FOUND	If root resource was not located.
NRF_ERROR_NULL	If 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]	string	Buffer to use for the .well-known/core string. Should not be NULL.
[in,out]	length	Length of the string buffer. Returns the used number of bytes from the provided buffer.

Return values

NRF_SUCCESS	If string generation was successful.
NRF_ERROR_NULL	If the string buffer was a NULL pointer.
NRF_ERROR_DATA_SIZE	If the size of the generated string exceeds the given buffer size.
NRF_ERROR_INVALID_STATE	If 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_port	Local port to unbind the session from.
[in]	p_remote	Pointer 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_SUCCESS If 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_port	Local port to bind the session to.
[in]	role	Role of the session. DTLS server or client defined in the enumeration nrf_tls_role_t.
[in]	p_remote	Pointer 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_settings	Pointer to a structure holding the DTLS credentials.

Return values

NRF_SUCCESS If 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_SUCCESS If time tick update was successfully handled.

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation