COAP

mbed CoAP APIs and Ameba wrappers More...

Data Structures
struct	sn_coap_options_list_
	Structure for CoAP Options. More...
struct	sn_coap_hdr_
	Main CoAP message struct. More...
struct	registration_info_
	Used for creating manually registration message with sn_coap_register() More...
struct	sn_nsdl_addr_
	Address structure of Packet data. More...

Typedefs
typedef enum coap_version_	coap_version_e
	Enumeration for CoAP Version.
typedef enum sn_coap_msg_type_	sn_coap_msg_type_e
	Enumeration for CoAP Message type, used in CoAP Header.
typedef enum sn_coap_msg_code_	sn_coap_msg_code_e
	Enumeration for CoAP Message code, used in CoAP Header.
typedef enum sn_coap_option_numbers_	sn_coap_option_numbers_e
	Enumeration for CoAP Option number, used in CoAP Header.
typedef enum sn_coap_content_format_	sn_coap_content_format_e
	Enumeration for CoAP Content Format codes.
typedef enum sn_coap_observe_	sn_coap_observe_e
	Enumeration for CoAP Observe option values. More...
typedef enum sn_coap_status_	sn_coap_status_e
	Enumeration for CoAP status, used in CoAP Header.
typedef struct sn_coap_options_list_	sn_coap_options_list_s
	Structure for CoAP Options.
typedef struct sn_coap_hdr_	sn_coap_hdr_s
	Main CoAP message struct.
typedef enum sn_nsdl_capab_	sn_nsdl_capab_e
	Used protocol.
typedef struct registration_info_	registration_info_t
	Used for creating manually registration message with sn_coap_register()
typedef enum sn_nsdl_addr_type_	sn_nsdl_addr_type_e
	Address type of given address.
typedef struct sn_nsdl_addr_	sn_nsdl_addr_s
	Address structure of Packet data.

Enumerations
enum	coap_version_ { COAP_VERSION_1 = 0x40, COAP_VERSION_UNKNOWN = 0xFF }
	Enumeration for CoAP Version.
enum	sn_coap_msg_type_ { COAP_MSG_TYPE_CONFIRMABLE = 0x00, COAP_MSG_TYPE_NON_CONFIRMABLE = 0x10, COAP_MSG_TYPE_ACKNOWLEDGEMENT = 0x20, COAP_MSG_TYPE_RESET = 0x30 }
	Enumeration for CoAP Message type, used in CoAP Header. More...
enum	sn_coap_msg_code_ {   COAP_MSG_CODE_EMPTY = 0, COAP_MSG_CODE_REQUEST_GET = 1, COAP_MSG_CODE_REQUEST_POST = 2, COAP_MSG_CODE_REQUEST_PUT = 3,   COAP_MSG_CODE_REQUEST_DELETE = 4, COAP_MSG_CODE_RESPONSE_CREATED = 65, COAP_MSG_CODE_RESPONSE_DELETED = 66, COAP_MSG_CODE_RESPONSE_VALID = 67,   COAP_MSG_CODE_RESPONSE_CHANGED = 68, COAP_MSG_CODE_RESPONSE_CONTENT = 69, COAP_MSG_CODE_RESPONSE_CONTINUE = 95, COAP_MSG_CODE_RESPONSE_BAD_REQUEST = 128,   COAP_MSG_CODE_RESPONSE_UNAUTHORIZED = 129, COAP_MSG_CODE_RESPONSE_BAD_OPTION = 130, COAP_MSG_CODE_RESPONSE_FORBIDDEN = 131, COAP_MSG_CODE_RESPONSE_NOT_FOUND = 132,   COAP_MSG_CODE_RESPONSE_METHOD_NOT_ALLOWED = 133, COAP_MSG_CODE_RESPONSE_NOT_ACCEPTABLE = 134, COAP_MSG_CODE_RESPONSE_REQUEST_ENTITY_INCOMPLETE = 136, COAP_MSG_CODE_RESPONSE_PRECONDITION_FAILED = 140,   COAP_MSG_CODE_RESPONSE_REQUEST_ENTITY_TOO_LARGE = 141, COAP_MSG_CODE_RESPONSE_UNSUPPORTED_CONTENT_FORMAT = 143, COAP_MSG_CODE_RESPONSE_INTERNAL_SERVER_ERROR = 160, COAP_MSG_CODE_RESPONSE_NOT_IMPLEMENTED = 161,   COAP_MSG_CODE_RESPONSE_BAD_GATEWAY = 162, COAP_MSG_CODE_RESPONSE_SERVICE_UNAVAILABLE = 163, COAP_MSG_CODE_RESPONSE_GATEWAY_TIMEOUT = 164, COAP_MSG_CODE_RESPONSE_PROXYING_NOT_SUPPORTED = 165 }
	Enumeration for CoAP Message code, used in CoAP Header.
enum	sn_coap_option_numbers_ {   COAP_OPTION_IF_MATCH = 1, COAP_OPTION_URI_HOST = 3, COAP_OPTION_ETAG = 4, COAP_OPTION_IF_NONE_MATCH = 5,   COAP_OPTION_OBSERVE = 6, COAP_OPTION_URI_PORT = 7, COAP_OPTION_LOCATION_PATH = 8, COAP_OPTION_URI_PATH = 11,   COAP_OPTION_CONTENT_FORMAT = 12, COAP_OPTION_MAX_AGE = 14, COAP_OPTION_URI_QUERY = 15, COAP_OPTION_ACCEPT = 17,   COAP_OPTION_LOCATION_QUERY = 20, COAP_OPTION_BLOCK2 = 23, COAP_OPTION_BLOCK1 = 27, COAP_OPTION_SIZE2 = 28,   COAP_OPTION_PROXY_URI = 35, COAP_OPTION_PROXY_SCHEME = 39, COAP_OPTION_SIZE1 = 60 }
	Enumeration for CoAP Option number, used in CoAP Header.
enum	sn_coap_content_format_ {   COAP_CT_NONE = -1, COAP_CT_TEXT_PLAIN = 0, COAP_CT_LINK_FORMAT = 40, COAP_CT_XML = 41,   COAP_CT_OCTET_STREAM = 42, COAP_CT_EXI = 47, COAP_CT_JSON = 50, COAP_CT__MAX = 0xffff }
	Enumeration for CoAP Content Format codes.
enum	sn_coap_observe_ { COAP_OBSERVE_NONE = -1, COAP_OBSERVE_REGISTER = 0, COAP_OBSERVE_DEREGISTER = 1, COAP_OBSERVE__MAX = 0xffffff }
	Enumeration for CoAP Observe option values. More...
enum	sn_coap_status_ {   COAP_STATUS_OK = 0, COAP_STATUS_PARSER_ERROR_IN_HEADER = 1, COAP_STATUS_PARSER_DUPLICATED_MSG = 2, COAP_STATUS_PARSER_BLOCKWISE_MSG_RECEIVING = 3,   COAP_STATUS_PARSER_BLOCKWISE_ACK = 4, COAP_STATUS_PARSER_BLOCKWISE_MSG_REJECTED = 5, COAP_STATUS_PARSER_BLOCKWISE_MSG_RECEIVED = 6, COAP_STATUS_BUILDER_MESSAGE_SENDING_FAILED = 7 }
	Enumeration for CoAP status, used in CoAP Header. More...
enum	sn_nsdl_capab_ { SN_NSDL_PROTOCOL_HTTP = 0x01, SN_NSDL_PROTOCOL_HTTPS = 0x02, SN_NSDL_PROTOCOL_COAP = 0x04 }
	Used protocol. More...
enum	sn_nsdl_addr_type_ { SN_NSDL_ADDRESS_TYPE_IPV6 = 0x01, SN_NSDL_ADDRESS_TYPE_IPV4 = 0x02, SN_NSDL_ADDRESS_TYPE_HOSTNAME = 0x03, SN_NSDL_ADDRESS_TYPE_NONE = 0xFF }
	Address type of given address. More...

Functions
uint16_t	randLIB_get_16bit (void)
	This function is called in sn_coap_protocol_init() for ramdom message ID. More...
void *	coap_malloc (uint16_t size)
	Ameba malloc() function wrapper. More...
void	coap_free (void *addr)
	Ameba free() function wrapper. More...
void *	coap_calloc (uint32_t size)
	Ameba calloc() function wrapper, the effective result is the allocation of a zero-initialized memory block of size bytes. More...
int	coap_sock_open (void)
	Ameba socket() function wrapper, creates a Datagrams type i.e. SOCK_DGRAM socket. More...
int	coap_sock_close (int socket_fd)
	Ameba close() function wrapper, closes a socket file descriptor. More...
struct coap_s *	coap_protocol_init (uint8_t(*coap_tx_callback)(uint8_t *, uint16_t, sn_nsdl_addr_s *, void *), int8_t(*coap_rx_callback)(sn_coap_hdr_s *, sn_nsdl_addr_s *, void *))
	Ameba sn_coap_protocol_init() function wrapper, initializes CoAP Protocol part. More...
int	coap_send (char *to_address, uint16_t port, int socket, sn_coap_hdr_s *coap_msg_hdr)
	Send the constructed CoAP message to designated host address on the specific port number. More...
int	coap_recv (int socket, struct sockaddr_in *from_address, void *buf, uint32_t buf_size)
	Receive the constructed CoAP message from host. More...
void	coap_print_hdr (sn_coap_hdr_s *parsed_hdr)
	Print CoAP message header (for debug use) More...
sn_coap_hdr_s *	sn_coap_parser (struct coap_s *handle, uint16_t packet_data_len, uint8_t *packet_data_ptr, coap_version_e *coap_version_ptr)
	Parses CoAP message from given Packet data. More...
void	sn_coap_parser_release_allocated_coap_msg_mem (struct coap_s *handle, sn_coap_hdr_s *freed_coap_msg_ptr)
	Releases memory of given CoAP message. More...
int16_t	sn_coap_builder (uint8_t *dst_packet_data_ptr, sn_coap_hdr_s *src_coap_msg_ptr)
	Builds an outgoing message buffer from a CoAP header structure. More...
uint16_t	sn_coap_builder_calc_needed_packet_data_size (sn_coap_hdr_s *src_coap_msg_ptr)
	Calculates needed Packet data memory size for given CoAP message. More...
int16_t	sn_coap_builder_2 (uint8_t *dst_packet_data_ptr, sn_coap_hdr_s *src_coap_msg_ptr, uint16_t blockwise_payload_size)
	Builds an outgoing message buffer from a CoAP header structure. More...
uint16_t	sn_coap_builder_calc_needed_packet_data_size_2 (sn_coap_hdr_s *src_coap_msg_ptr, uint16_t blockwise_payload_size)
	Calculates needed Packet data memory size for given CoAP message. More...
sn_coap_hdr_s *	sn_coap_build_response (struct coap_s *handle, sn_coap_hdr_s *coap_packet_ptr, uint8_t msg_code)
	Prepares generic response packet from a request packet. This function allocates memory for the resulting sn_coap_hdr_s. More...
sn_coap_hdr_s *	sn_coap_parser_init_message (sn_coap_hdr_s *coap_msg_ptr)
	Initialise a message structure to empty. More...
sn_coap_hdr_s *	sn_coap_parser_alloc_message (struct coap_s *handle)
	Allocate an empty message structure. More...
sn_coap_options_list_s *	sn_coap_parser_alloc_options (struct coap_s *handle, sn_coap_hdr_s *coap_msg_ptr)
	Allocates and initializes options list structure. More...
struct coap_s *	sn_coap_protocol_init (void *(*used_malloc_func_ptr)(uint16_t), void(*used_free_func_ptr)(void *), uint8_t(*used_tx_callback_ptr)(uint8_t *, uint16_t, sn_nsdl_addr_s *, void *), int8_t(*used_rx_callback_ptr)(sn_coap_hdr_s *, sn_nsdl_addr_s *, void *))
	Initializes CoAP Protocol part. When using libNsdl, sn_nsdl_init() calls this function. More...
int8_t	sn_coap_protocol_destroy (struct coap_s *handle)
	Frees all memory from CoAP protocol part. More...
int16_t	sn_coap_protocol_build (struct coap_s *handle, sn_nsdl_addr_s *dst_addr_ptr, uint8_t *dst_packet_data_ptr, sn_coap_hdr_s *src_coap_msg_ptr, void *param)
	Builds Packet data from given CoAP header structure to be sent. More...
sn_coap_hdr_s *	sn_coap_protocol_parse (struct coap_s *handle, sn_nsdl_addr_s *src_addr_ptr, uint16_t packet_data_len, uint8_t *packet_data_ptr, void *param)
	Parses received CoAP message from given Packet data. More...
int8_t	sn_coap_protocol_exec (struct coap_s *handle, uint32_t current_time)
	Sends CoAP messages from re-sending queue, if there is any. Cleans also old messages from the duplication list and from block receiving list. More...
int8_t	sn_coap_protocol_set_block_size (struct coap_s *handle, uint16_t block_size)
	If block transfer is enabled, this function changes the block size. More...
int8_t	sn_coap_protocol_set_duplicate_buffer_size (struct coap_s *handle, uint8_t message_count)
	If dublicate message detection is enabled, this function changes buffer size. More...
int8_t	sn_coap_protocol_set_retransmission_parameters (struct coap_s *handle, uint8_t resending_count, uint8_t resending_interval)
	If re-transmissions are enabled, this function changes resending count and interval. More...
int8_t	sn_coap_protocol_set_retransmission_buffer (struct coap_s *handle, uint8_t buffer_size_messages, uint16_t buffer_size_bytes)
	If re-transmissions are enabled, this function changes message retransmission queue size. Set size to '0' to disable feature. If both are set to '0', then re-sendings are disabled. More...
void	sn_coap_protocol_clear_retransmission_buffer (struct coap_s *handle)
	If re-transmissions are enabled, this function removes all messages from the retransmission queue. More...
void	sn_coap_protocol_block_remove (struct coap_s *handle, sn_nsdl_addr_s *source_address, uint16_t payload_length, void *payload)
	Remove saved block data. Can be used to remove the data from RAM to enable storing it to other place. More...
int8_t	sn_coap_protocol_delete_retransmission (struct coap_s *handle, uint16_t msg_id)
	If re-transmissions are enabled, this function removes message from retransmission buffer. More...

Variables
uint8_t	etag_len
unsigned int	use_size1:1
unsigned int	use_size2:1
uint16_t	proxy_uri_len
uint16_t	uri_host_len
uint16_t	location_path_len
uint16_t	location_query_len
uint16_t	uri_query_len
sn_coap_content_format_e	accept
uint32_t	max_age
uint32_t	size1
uint32_t	size2
int32_t	uri_port
int32_t	observe
int32_t	block1
int32_t	block2
uint8_t *	proxy_uri_ptr
uint8_t *	etag_ptr
uint8_t *	uri_host_ptr
uint8_t *	location_path_ptr
uint8_t *	location_query_ptr
uint8_t *	uri_query_ptr
uint8_t	token_len
sn_coap_status_e	coap_status
sn_coap_msg_code_e	msg_code
sn_coap_msg_type_e	msg_type
sn_coap_content_format_e	content_format
uint16_t	msg_id
uint16_t	uri_path_len
uint16_t	payload_len
uint8_t *	token_ptr
uint8_t *	uri_path_ptr
uint8_t *	payload_ptr
sn_coap_options_list_s *	options_list_ptr
uint8_t	endpoint_len
uint8_t	endpoint_type_len
uint16_t	links_len
uint8_t *	endpoint_ptr
uint8_t *	endpoint_type_ptr
uint8_t *	links_ptr
uint8_t	addr_len
sn_nsdl_addr_type_e	type
uint16_t	port
uint8_t *	addr_ptr

Detailed Description

mbed CoAP APIs and Ameba wrappers

Typedef Documentation

typedef enum sn_coap_observe_ sn_coap_observe_e

Enumeration for CoAP Observe option values.

draft-ietf-core-observe-16

Enumeration Type Documentation

enum sn_coap_msg_type_

Enumeration for CoAP Message type, used in CoAP Header.

Enumerator
COAP_MSG_TYPE_CONFIRMABLE	Reliable Request messages
COAP_MSG_TYPE_NON_CONFIRMABLE	Non-reliable Request and Response messages
COAP_MSG_TYPE_ACKNOWLEDGEMENT	Response to a Confirmable Request
COAP_MSG_TYPE_RESET	Answer a Bad Request

enum sn_coap_observe_

Enumeration for CoAP Observe option values.

draft-ietf-core-observe-16

enum sn_coap_status_

Enumeration for CoAP status, used in CoAP Header.

Enumerator
COAP_STATUS_OK	Default value is OK
COAP_STATUS_PARSER_ERROR_IN_HEADER	CoAP will send Reset message to invalid message sender
COAP_STATUS_PARSER_DUPLICATED_MSG	CoAP will send Acknowledgement message to duplicated message sender
COAP_STATUS_PARSER_BLOCKWISE_MSG_RECEIVING	User will get whole message after all message blocks received. User must release messages with this status.
COAP_STATUS_PARSER_BLOCKWISE_ACK	Acknowledgement for sent Blockwise message received
COAP_STATUS_PARSER_BLOCKWISE_MSG_REJECTED	Blockwise message received but not supported by compiling switch
COAP_STATUS_PARSER_BLOCKWISE_MSG_RECEIVED	Blockwise message fully received and returned to app. User must take care of releasing whole payload of the blockwise messages
COAP_STATUS_BUILDER_MESSAGE_SENDING_FAILED	When re-transmissions have been done and ACK not received, CoAP library calls RX callback with this status

enum sn_nsdl_addr_type_

Address type of given address.

Enumerator
SN_NSDL_ADDRESS_TYPE_IPV6	Supported
SN_NSDL_ADDRESS_TYPE_IPV4	Supported
SN_NSDL_ADDRESS_TYPE_HOSTNAME	Unsupported

enum sn_nsdl_capab_

Used protocol.

Enumerator
SN_NSDL_PROTOCOL_HTTP	Unsupported
SN_NSDL_PROTOCOL_HTTPS	Unsupported
SN_NSDL_PROTOCOL_COAP	Supported

Function Documentation

void* coap_calloc

(

uint32_t

size

)

Ameba calloc() function wrapper, the effective result is the allocation of a zero-initialized memory block of size bytes.

Parameters

size	memory size to be allocated

Returns

NULL = if memory allocation failed

void* pointer to the allocated memory = if memory allocation success

void coap_free

(

void *

addr

)

Ameba free() function wrapper.

Parameters

*addr

memory address to be freed

void* coap_malloc

(

uint16_t

size

)

Ameba malloc() function wrapper.

Parameters

size	memory size to be allocated

Returns

NULL = if memory allocation failed

void* pointer to allocated memory = if allocation success

void coap_print_hdr

(

sn_coap_hdr_s *

parsed_hdr

)

Print CoAP message header (for debug use)

Parameters

*parsed_hdr

: pointer to constructed CoAP message header

struct coap_s* coap_protocol_init	(	uint8_t(*)(uint8_t *, uint16_t, sn_nsdl_addr_s *, void *)	coap_tx_callback,
		int8_t(*)(sn_coap_hdr_s *, sn_nsdl_addr_s *, void *)	coap_rx_callback
	)

Ameba sn_coap_protocol_init() function wrapper, initializes CoAP Protocol part.

Parameters

*coap_tx_callback	: function callback pointer to tx function for sending coap messages
*coap_rx_callback	: function callback pointer to rx function, used to return CoAP header struct with status COAP_STATUS_BUILDER_MESSAGE_SENDING_FAILED when re-sendings exceeded. If set to NULL, no error message is returned.

Returns

pointer to CoAP handle = if success

NULL = if failed

int coap_recv	(	int	socket,
		struct sockaddr_in *	from_address,
		void *	buf,
		uint32_t	buf_size
	)

Receive the constructed CoAP message from host.

Parameters

socket	: socket file descriptor used to receive the message
*from_address	: an internet address pointer, which the sender address is to be stored into
*buf	: memory buffer that used to store the received message
buf_size	: specifies the length in bytes of the buffer pointed to by the buf argument.

Returns

The length of the message in bytes : if successful completion

0 = If no messages are available to be received

-1 = receive message failed

int coap_send	(	char *	to_address,
		uint16_t	port,
		int	socket,
		sn_coap_hdr_s *	coap_msg_hdr
	)

Send the constructed CoAP message to designated host address on the specific port number.

Parameters

*to_address	: the host / domain / ip address that the message is targeted to
port	: port number that the host is used to receive the message
socket	: socket file descriptor used to send the message
*coap_msg_hdr	: constructed CoAP message pointer

Returns

The number of bytes sent = if fuccess

-1 = if failed

int coap_sock_close

(

int

socket_fd

)

Ameba close() function wrapper, closes a socket file descriptor.

Parameters

sock_fd

the socket file descriptor is going to be closed.

Returns

-1 = if close operation failed

0 = if close operation success

int coap_sock_open

(

void

)

Ameba socket() function wrapper, creates a Datagrams type i.e. SOCK_DGRAM socket.

Returns

Non-negative Integer (socket file descriptor) = if successfully completion

-1 = if failed to create socket

uint16_t randLIB_get_16bit

(

void

)

This function is called in sn_coap_protocol_init() for ramdom message ID.

Returns

A random 16bit unsigned value

sn_coap_hdr_s * sn_coap_build_response	(	struct coap_s *	handle,
		sn_coap_hdr_s *	coap_packet_ptr,
		uint8_t	msg_code
	)

Prepares generic response packet from a request packet. This function allocates memory for the resulting sn_coap_hdr_s.

Parameters

*handle	Pointer to CoAP library handle
*coap_packet_ptr	The request packet pointer
msg_code	response messages code

Returns

*coap_packet_ptr The allocated and pre-filled response packet pointer NULL Error in parsing the request

int16_t sn_coap_builder	(	uint8_t *	dst_packet_data_ptr,
		sn_coap_hdr_s *	src_coap_msg_ptr
	)

Builds an outgoing message buffer from a CoAP header structure.

Parameters

*dst_packet_data_ptr	is pointer to allocated destination to built CoAP packet
*src_coap_msg_ptr	is pointer to source structure for building Packet data

Returns

Return value is byte count of built Packet data. In failure cases:
-1 = Failure in given CoAP header structure
-2 = Failure in given pointer (= NULL)

int16_t sn_coap_builder_2	(	uint8_t *	dst_packet_data_ptr,
		sn_coap_hdr_s *	src_coap_msg_ptr,
		uint16_t	blockwise_size
	)

Builds an outgoing message buffer from a CoAP header structure.

Parameters

*dst_packet_data_ptr	is pointer to allocated destination to built CoAP packet
*src_coap_msg_ptr	is pointer to source structure for building Packet data
blockwise_payload_size	Blockwise message maximum payload size

Returns

Return value is byte count of built Packet data. In failure cases:
-1 = Failure in given CoAP header structure
-2 = Failure in given pointer (= NULL)

uint16_t sn_coap_builder_calc_needed_packet_data_size

(

sn_coap_hdr_s *

src_coap_msg_ptr

)

Calculates needed Packet data memory size for given CoAP message.

Parameters

*src_coap_msg_ptr

is pointer to data which needed Packet data length is calculated

Returns

Return value is count of needed memory as bytes for build Packet data Null if failed

uint16_t sn_coap_builder_calc_needed_packet_data_size_2	(	sn_coap_hdr_s *	src_coap_msg_ptr,
		uint16_t	blockwise_payload_size
	)

Calculates needed Packet data memory size for given CoAP message.

Parameters

*src_coap_msg_ptr	is pointer to data which needed Packet data length is calculated
blockwise_payload_size	Blockwise message maximum payload size

Returns

Return value is count of needed memory as bytes for build Packet data Null if failed

sn_coap_hdr_s * sn_coap_parser	(	struct coap_s *	handle,
		uint16_t	packet_data_len,
		uint8_t *	packet_data_ptr,
		coap_version_e *	coap_version_ptr
	)

Parses CoAP message from given Packet data.

Parameters

*handle	Pointer to CoAP library handle
packet_data_len	is length of given Packet data to be parsed to CoAP message
*packet_data_ptr	is source for Packet data to be parsed to CoAP message
*coap_version_ptr	is destination for parsed CoAP specification version

Returns

Return value is pointer to parsed CoAP message.
In following failure cases NULL is returned:
-Failure in given pointer (= NULL)
-Failure in memory allocation (malloc() returns NULL)

sn_coap_hdr_s* sn_coap_parser_alloc_message

(

struct coap_s *

handle

)

Allocate an empty message structure.

Parameters

*handle

Pointer to CoAP library handle

Returns

Return value is pointer to an empty CoAP message.
In following failure cases NULL is returned:
-Failure in given pointer (= NULL)
-Failure in memory allocation (malloc() returns NULL)

sn_coap_options_list_s* sn_coap_parser_alloc_options	(	struct coap_s *	handle,
		sn_coap_hdr_s *	coap_msg_ptr
	)

Allocates and initializes options list structure.

Parameters

*handle	Pointer to CoAP library handle
*coap_msg_ptr	is pointer to CoAP message that will contain the options

If the message already has a pointer to an option structure, that pointer is returned, rather than a new structure being allocated.

Returns

Return value is pointer to the CoAP options structure.
In following failure cases NULL is returned:
-Failure in given pointer (= NULL)
-Failure in memory allocation (malloc() returns NULL)

sn_coap_hdr_s* sn_coap_parser_init_message

(

sn_coap_hdr_s *

coap_msg_ptr

)

Initialise a message structure to empty.

Parameters

*coap_msg_ptr

is pointer to CoAP message to initialise

Returns

Return value is pointer passed in

void sn_coap_parser_release_allocated_coap_msg_mem	(	struct coap_s *	handle,
		sn_coap_hdr_s *	freed_coap_msg_ptr
	)

Releases memory of given CoAP message.

Note

Does not release Payload part

Parameters

*handle	Pointer to CoAP library handle
*freed_coap_msg_ptr	is pointer to released CoAP message

sn_coap_protocol_block_remove	(	struct coap_s *	handle,
		sn_nsdl_addr_s *	source_address,
		uint16_t	payload_length,
		void *	payload
	)

Remove saved block data. Can be used to remove the data from RAM to enable storing it to other place.

Parameters

handle	Pointer to CoAP library handle
source_address	Addres from where the block has been received.
payload_length	Length of the coap payload of the block.
payload	Coap payload of the block.

int16_t sn_coap_protocol_build	(	struct coap_s *	handle,
		sn_nsdl_addr_s *	dst_addr_ptr,
		uint8_t *	dst_packet_data_ptr,
		sn_coap_hdr_s *	src_coap_msg_ptr,
		void *	param
	)

Builds Packet data from given CoAP header structure to be sent.

Parameters

*dst_addr_ptr	is pointer to destination address where CoAP message will be sent (CoAP builder needs that information for message resending purposes)
*dst_packet_data_ptr	is pointer to destination of built Packet data
*src_coap_msg_ptr	is pointer to source of built Packet data
param	void pointer that will be passed to tx/rx function callback when those are called.

Note

If message is blockwised, all payload is not sent at the same time

Returns

Return value is byte count of built Packet data.
In failure cases:
-1 = Failure in CoAP header structure
-2 = Failure in given pointer (= NULL)
-3 = Failure in Reset message
-4 = Failure in Resending message store
If there is not enough memory (or User given limit exceeded) for storing resending messages, situation is ignored.

void sn_coap_protocol_clear_retransmission_buffer

(

struct coap_s *

handle

)

If re-transmissions are enabled, this function removes all messages from the retransmission queue.

Parameters

*handle

Pointer to CoAP library handle

void sn_coap_protocol_delete_retransmission	(	struct coap_s *	handle,
		uint16_t	msg_id
	)

If re-transmissions are enabled, this function removes message from retransmission buffer.

Parameters

*handle	Pointer to CoAP library handle
msg_id	message ID to be removed

Returns

0 = success
-1 = invalid parameter
-2 = message was not found

int8_t sn_coap_protocol_destroy

(

struct coap_s *

handle

)

Frees all memory from CoAP protocol part.

Parameters

*handle

Pointer to CoAP library handle

Returns

Return value is always 0

int8_t sn_coap_protocol_exec	(	struct coap_s *	handle,
		uint32_t	current_time
	)

Sends CoAP messages from re-sending queue, if there is any. Cleans also old messages from the duplication list and from block receiving list.

This function can be called e.g. once in a second but also more frequently.

Parameters

*handle	Pointer to CoAP library handle
current_time	is System time in seconds. This time is used for message re-sending timing and to identify old saved data.

Returns

0 = success
-1 = failed

struct coap_s * sn_coap_protocol_init	(	void *(*)(uint16_t)	used_malloc_func_ptr,
		void(*)(void *)	used_free_func_ptr,
		uint8_t(*)(uint8_t *, uint16_t, sn_nsdl_addr_s *, void *)	used_tx_callback_ptr,
		int8_t(*)(sn_coap_hdr_s *, sn_nsdl_addr_s *, void *)	used_rx_callback_ptr
	)

Initializes CoAP Protocol part. When using libNsdl, sn_nsdl_init() calls this function.

Parameters

*used_malloc_func_ptr	is function pointer for used memory allocation function.
*used_free_func_ptr	is function pointer for used memory free function.
*used_tx_callback_ptr	function callback pointer to tx function for sending coap messages
*used_rx_callback_ptr	used to return CoAP header struct with status COAP_STATUS_BUILDER_MESSAGE_SENDING_FAILED when re-sendings exceeded. If set to NULL, no error message is returned.

Returns

Pointer to handle when success
Null if failed

sn_coap_hdr_s * sn_coap_protocol_parse	(	struct coap_s *	handle,
		sn_nsdl_addr_s *	src_addr_ptr,
		uint16_t	packet_data_len,
		uint8_t *	packet_data_ptr,
		void *	param
	)

Parses received CoAP message from given Packet data.

Parameters

*src_addr_ptr	is pointer to source address of received CoAP message (CoAP parser needs that information for Message acknowledgement)
*handle	Pointer to CoAP library handle
packet_data_len	is length of given Packet data to be parsed to CoAP message
*packet_data_ptr	is pointer to source of Packet data to be parsed to CoAP message
*param	void pointer that will be passed to tx/rx function callback when those are called.

Returns

Return value is pointer to parsed CoAP message structure. This structure includes also coap_status field.
In following failure cases NULL is returned:
-Given NULL pointer
-Failure in parsed header of non-confirmable message
-Out of memory (malloc() returns NULL)

int8_t sn_coap_protocol_set_block_size	(	struct coap_s *	handle,
		uint16_t	block_size
	)

If block transfer is enabled, this function changes the block size.

Parameters

handle	Pointer to CoAP library handle
maximum	size of CoAP payload. Valid sizes are 16, 32, 64, 128, 256, 512 and 1024 bytes

Returns

0 = success
-1 = failure

int8_t sn_coap_protocol_set_duplicate_buffer_size	(	struct coap_s *	handle,
		uint8_t	message_count
	)

If dublicate message detection is enabled, this function changes buffer size.

Parameters

handle	Pointer to CoAP library handle
message_count	max number of messages saved for duplicate control

Returns

0 = success
-1 = failure

int8_t sn_coap_protocol_set_retransmission_buffer	(	struct coap_s *	handle,
		uint8_t	buffer_size_messages,
		uint16_t	buffer_size_bytes
	)

If re-transmissions are enabled, this function changes message retransmission queue size. Set size to '0' to disable feature. If both are set to '0', then re-sendings are disabled.

Parameters

*handle	Pointer to CoAP library handle
buffer_size_messages	queue size - maximum number of messages to be saved to queue
buffer_size_bytes	queue size - maximum size of messages saved to queue

Returns

0 = success
-1 = failure

int8_t sn_coap_protocol_set_retransmission_parameters	(	struct coap_s *	handle,
		uint8_t	resending_count,
		uint8_t	resending_intervall
	)

If re-transmissions are enabled, this function changes resending count and interval.

Parameters

*handle	Pointer to CoAP library handle
resending_count	max number of resendings for message
resending_intervall	message resending intervall in seconds

Returns

0 = success
-1 = failure

Variable Documentation

sn_coap_content_format_e accept

Value 0-65535. COAP_CT_NONE if not used

int32_t block1

Value 0-0xffffff. -1 if not used. Not for user

int32_t block2

Value 0-0xffffff. -1 if not used. Not for user

sn_coap_status_e coap_status

Used for telling to User special cases when parsing message

sn_coap_content_format_e content_format

Set to COAP_CT_NONE if not used

uint8_t* endpoint_ptr

Endpoint name

uint8_t* endpoint_type_ptr

Endpoint type

uint8_t etag_len

1-8 bytes. Repeatable

uint8_t* etag_ptr

Must be set to NULL if not used

uint8_t* links_ptr

Resource registration string

uint16_t location_path_len

0-255 bytes. Repeatable

uint8_t* location_path_ptr

Must be set to NULL if not used

uint16_t location_query_len

0-255 bytes. Repeatable

uint8_t* location_query_ptr

Must be set to NULL if not used

uint32_t max_age

Value in seconds (default is 60)

sn_coap_msg_code_e msg_code

Empty: 0; Requests: 1-31; Responses: 64-191

uint16_t msg_id

Message ID. Parser sets parsed message ID, builder sets message ID of built coap message

sn_coap_msg_type_e msg_type

Confirmable, Non-Confirmable, Acknowledgement or Reset

int32_t observe

Value 0-0xffffff. -1 if not used

sn_coap_options_list_s* options_list_ptr

Must be set to NULL if not used

uint16_t payload_len

Must be set to zero if not used

uint8_t* payload_ptr

Must be set to NULL if not used

uint16_t proxy_uri_len

1-1034 bytes.

uint8_t* proxy_uri_ptr

Must be set to NULL if not used

uint32_t size1

0-4 bytes.

uint32_t size2

0-4 bytes.

uint8_t token_len

1-8 bytes.

uint8_t* token_ptr

Must be set to NULL if not used

uint16_t uri_host_len

1-255 bytes.

uint8_t* uri_host_ptr

Must be set to NULL if not used

uint16_t uri_path_len

0-255 bytes. Repeatable.

uint8_t* uri_path_ptr

Must be set to NULL if not used. E.g: temp1/temp2

int32_t uri_port

Value 0-65535. -1 if not used

uint16_t uri_query_len

1-255 bytes. Repeatable

uint8_t* uri_query_ptr

Must be set to NULL if not used