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_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 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)
	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_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_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...

Detailed Description

Public API of Nordic's CoAP implementation.

Macro Definition Documentation

#define COAP_OPT_ACCEPT 17

Accept 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_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 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 )

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.

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.

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