COAP Library

COAP library. More...

Data Structures
struct	coap_resource
	Description of CoAP resource. More...
struct	coap_observer
	Represents a remote device that is observing a local resource. More...
struct	coap_packet
	Representation of a CoAP Packet. More...
struct	coap_option
struct	coap_pending
	Represents a request awaiting for an acknowledgment (ACK). More...
struct	coap_reply
	Represents the handler for the reply of a request, it is also used when observing resources. More...
struct	coap_block_context
	Represents the current state of a block-wise transaction. More...
struct	coap_core_metadata

Macros
#define	COAP_REQUEST_MASK   0x07
#define	COAP_VERSION_1   1U
#define	coap_make_response_code(class, det)   ((class << 5) | (det))
#define	COAP_CODE_EMPTY   (0)
#define	COAP_TOKEN_MAX_LEN   8UL
#define	GET_BLOCK_NUM(v)   ((v) >> 4)
#define	GET_BLOCK_SIZE(v)   (((v) & 0x7))
#define	GET_MORE(v)   (!!((v) & 0x08))
#define	COAP_DEFAULT_MAX_RETRANSMIT   4
#define	COAP_DEFAULT_ACK_RANDOM_FACTOR   1.5
#define	COAP_WELL_KNOWN_CORE_PATH    ((const char * const[]) { ".well-known", "core", NULL })

Typedefs
typedef int(*	coap_method_t) (struct coap_resource *resource, struct coap_packet *request, struct sockaddr *addr, socklen_t addr_len)
	Type of the callback being called when a resource's method is invoked by the remote entity. More...
typedef void(*	coap_notify_t) (struct coap_resource *resource, struct coap_observer *observer)
	Type of the callback being called when a resource's has observers to be informed when an update happens. More...
typedef int(*	coap_reply_t) (const struct coap_packet *response, struct coap_reply *reply, const struct sockaddr *from)
	Helper function to be called when a response matches the a pending request. More...

Enumerations
enum	coap_option_num {   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 }
	Set of CoAP packet options we are aware of. More...
enum	coap_method { COAP_METHOD_GET = 1 , COAP_METHOD_POST = 2 , COAP_METHOD_PUT = 3 , COAP_METHOD_DELETE = 4 }
	Available request methods. More...
enum	coap_msgtype { COAP_TYPE_CON = 0 , COAP_TYPE_NON_CON = 1 , COAP_TYPE_ACK = 2 , COAP_TYPE_RESET = 3 }
	CoAP packets may be of one of these types. More...
enum	coap_response_code {   COAP_RESPONSE_CODE_OK = (( 2 << 5) | ( 0 )) , COAP_RESPONSE_CODE_CREATED = (( 2 << 5) | ( 1 )) , COAP_RESPONSE_CODE_DELETED = (( 2 << 5) | ( 2 )) , COAP_RESPONSE_CODE_VALID = (( 2 << 5) | ( 3 )) ,   COAP_RESPONSE_CODE_CHANGED = (( 2 << 5) | ( 4 )) , COAP_RESPONSE_CODE_CONTENT = (( 2 << 5) | ( 5 )) , COAP_RESPONSE_CODE_CONTINUE = (( 2 << 5) | ( 31 )) , COAP_RESPONSE_CODE_BAD_REQUEST = (( 4 << 5) | ( 0 )) ,   COAP_RESPONSE_CODE_UNAUTHORIZED = (( 4 << 5) | ( 1 )) , COAP_RESPONSE_CODE_BAD_OPTION = (( 4 << 5) | ( 2 )) , COAP_RESPONSE_CODE_FORBIDDEN = (( 4 << 5) | ( 3 )) , COAP_RESPONSE_CODE_NOT_FOUND = (( 4 << 5) | ( 4 )) ,   COAP_RESPONSE_CODE_NOT_ALLOWED = (( 4 << 5) | ( 5 )) , COAP_RESPONSE_CODE_NOT_ACCEPTABLE = (( 4 << 5) | ( 6 )) , COAP_RESPONSE_CODE_INCOMPLETE = (( 4 << 5) | ( 8 )) , COAP_RESPONSE_CODE_PRECONDITION_FAILED = (( 4 << 5) | ( 12 )) ,   COAP_RESPONSE_CODE_REQUEST_TOO_LARGE = (( 4 << 5) | ( 13 )) , COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT , COAP_RESPONSE_CODE_INTERNAL_ERROR = (( 5 << 5) | ( 0 )) , COAP_RESPONSE_CODE_NOT_IMPLEMENTED = (( 5 << 5) | ( 1 )) ,   COAP_RESPONSE_CODE_BAD_GATEWAY = (( 5 << 5) | ( 2 )) , COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE = (( 5 << 5) | ( 3 )) , COAP_RESPONSE_CODE_GATEWAY_TIMEOUT = (( 5 << 5) | ( 4 )) , COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED }
	Set of response codes available for a response packet. More...
enum	coap_content_format {   COAP_CONTENT_FORMAT_TEXT_PLAIN = 0 , COAP_CONTENT_FORMAT_APP_LINK_FORMAT = 40 , COAP_CONTENT_FORMAT_APP_XML = 41 , COAP_CONTENT_FORMAT_APP_OCTET_STREAM = 42 ,   COAP_CONTENT_FORMAT_APP_EXI = 47 , COAP_CONTENT_FORMAT_APP_JSON = 50 , COAP_CONTENT_FORMAT_APP_CBOR = 60 }
	Set of Content-Format option values for CoAP. More...
enum	coap_block_size {   COAP_BLOCK_16 , COAP_BLOCK_32 , COAP_BLOCK_64 , COAP_BLOCK_128 ,   COAP_BLOCK_256 , COAP_BLOCK_512 , COAP_BLOCK_1024 }

Functions
uint8_t	coap_header_get_version (const struct coap_packet *cpkt)
	Returns the version present in a CoAP packet. More...
uint8_t	coap_header_get_type (const struct coap_packet *cpkt)
	Returns the type of the CoAP packet. More...
uint8_t	coap_header_get_token (const struct coap_packet *cpkt, uint8_t *token)
	Returns the token (if any) in the CoAP packet. More...
uint8_t	coap_header_get_code (const struct coap_packet *cpkt)
	Returns the code of the CoAP packet. More...
uint16_t	coap_header_get_id (const struct coap_packet *cpkt)
	Returns the message id associated with the CoAP packet. More...
const uint8_t *	coap_packet_get_payload (const struct coap_packet *cpkt, uint16_t *len)
	Returns the data pointer and length of the CoAP packet. More...
int	coap_packet_parse (struct coap_packet *cpkt, uint8_t *data, uint16_t len, struct coap_option *options, uint8_t opt_num)
	Parses the CoAP packet in data, validating it and initializing cpkt. data must remain valid while cpkt is used. More...
int	coap_packet_init (struct coap_packet *cpkt, uint8_t *data, uint16_t max_len, uint8_t ver, uint8_t type, uint8_t token_len, const uint8_t *token, uint8_t code, uint16_t id)
	Creates a new CoAP Packet from input data. More...
int	coap_ack_init (struct coap_packet *cpkt, const struct coap_packet *req, uint8_t *data, uint16_t max_len, uint8_t code)
	Create a new CoAP Acknowledgment message for given request. More...
uint8_t *	coap_next_token (void)
	Returns a randomly generated array of 8 bytes, that can be used as a message's token. More...
uint16_t	coap_next_id (void)
	Helper to generate message ids. More...
int	coap_find_options (const struct coap_packet *cpkt, uint16_t code, struct coap_option *options, uint16_t veclen)
	Return the values associated with the option of value code. More...
int	coap_packet_append_option (struct coap_packet *cpkt, uint16_t code, const uint8_t *value, uint16_t len)
	Appends an option to the packet. More...
unsigned int	coap_option_value_to_int (const struct coap_option *option)
	Converts an option to its integer representation. More...
int	coap_append_option_int (struct coap_packet *cpkt, uint16_t code, unsigned int val)
	Appends an integer value option to the packet. More...
int	coap_packet_append_payload_marker (struct coap_packet *cpkt)
	Append payload marker to CoAP packet. More...
int	coap_packet_append_payload (struct coap_packet *cpkt, const uint8_t *payload, uint16_t payload_len)
	Append payload to CoAP packet. More...
int	coap_handle_request (struct coap_packet *cpkt, struct coap_resource *resources, struct coap_option *options, uint8_t opt_num, struct sockaddr *addr, socklen_t addr_len)
	When a request is received, call the appropriate methods of the matching resources. More...
static uint16_t	coap_block_size_to_bytes (enum coap_block_size block_size)
	Helper for converting the enumeration to the size expressed in bytes. More...
int	coap_block_transfer_init (struct coap_block_context *ctx, enum coap_block_size block_size, size_t total_size)
	Initializes the context of a block-wise transfer. More...
int	coap_append_block1_option (struct coap_packet *cpkt, struct coap_block_context *ctx)
	Append BLOCK1 option to the packet. More...
int	coap_append_block2_option (struct coap_packet *cpkt, struct coap_block_context *ctx)
	Append BLOCK2 option to the packet. More...
int	coap_append_size1_option (struct coap_packet *cpkt, struct coap_block_context *ctx)
	Append SIZE1 option to the packet. More...
int	coap_append_size2_option (struct coap_packet *cpkt, struct coap_block_context *ctx)
	Append SIZE2 option to the packet. More...
int	coap_get_option_int (const struct coap_packet *cpkt, uint16_t code)
	Get the integer representation of a CoAP option. More...
int	coap_update_from_block (const struct coap_packet *cpkt, struct coap_block_context *ctx)
	Retrieves BLOCK{1,2} and SIZE{1,2} from cpkt and updates ctx accordingly. More...
size_t	coap_next_block (const struct coap_packet *cpkt, struct coap_block_context *ctx)
	Updates ctx so after this is called the current entry indicates the correct offset in the body of data being transferred. More...
void	coap_observer_init (struct coap_observer *observer, const struct coap_packet *request, const struct sockaddr *addr)
	Indicates that the remote device referenced by addr, with request, wants to observe a resource. More...
bool	coap_register_observer (struct coap_resource *resource, struct coap_observer *observer)
	After the observer is initialized, associate the observer with an resource. More...
void	coap_remove_observer (struct coap_resource *resource, struct coap_observer *observer)
	Remove this observer from the list of registered observers of that resource. More...
struct coap_observer *	coap_find_observer_by_addr (struct coap_observer *observers, size_t len, const struct sockaddr *addr)
	Returns the observer that matches address addr. More...
struct coap_observer *	coap_observer_next_unused (struct coap_observer *observers, size_t len)
	Returns the next available observer representation. More...
void	coap_reply_init (struct coap_reply *reply, const struct coap_packet *request)
	Indicates that a reply is expected for request. More...
int	coap_pending_init (struct coap_pending *pending, const struct coap_packet *request, const struct sockaddr *addr, uint8_t retries)
	Initialize a pending request with a request. More...
struct coap_pending *	coap_pending_next_unused (struct coap_pending *pendings, size_t len)
	Returns the next available pending struct, that can be used to track the retransmission status of a request. More...
struct coap_reply *	coap_reply_next_unused (struct coap_reply *replies, size_t len)
	Returns the next available reply struct, so it can be used to track replies and notifications received. More...
struct coap_pending *	coap_pending_received (const struct coap_packet *response, struct coap_pending *pendings, size_t len)
	After a response is received, returns if there is any matching pending request exits. User has to clear all pending retransmissions related to that response by calling coap_pending_clear(). More...
struct coap_reply *	coap_response_received (const struct coap_packet *response, const struct sockaddr *from, struct coap_reply *replies, size_t len)
	After a response is received, call coap_reply_t handler registered in coap_reply structure. More...
struct coap_pending *	coap_pending_next_to_expire (struct coap_pending *pendings, size_t len)
	Returns the next pending about to expire, pending->timeout informs how many ms to next expiration. More...
bool	coap_pending_cycle (struct coap_pending *pending)
	After a request is sent, user may want to cycle the pending retransmission so the timeout is updated. More...
void	coap_pending_clear (struct coap_pending *pending)
	Cancels the pending retransmission, so it again becomes available. More...
void	coap_pendings_clear (struct coap_pending *pendings, size_t len)
	Cancels all pending retransmissions, so they become available again. More...
void	coap_reply_clear (struct coap_reply *reply)
	Cancels awaiting for this reply, so it becomes available again. User responsibility to free the memory associated with data. More...
void	coap_replies_clear (struct coap_reply *replies, size_t len)
	Cancels all replies, so they become available again. More...
int	coap_resource_notify (struct coap_resource *resource)
	Indicates that this resource was updated and that the notify callback should be called for every registered observer. More...
bool	coap_request_is_observe (const struct coap_packet *request)
	Returns if this request is enabling observing a resource. More...
int	coap_well_known_core_get (struct coap_resource *resource, struct coap_packet *request, struct coap_packet *response, uint8_t *data, uint16_t len)

Detailed Description

COAP library.

Macro Definition Documentation

COAP_CODE_EMPTY

#define COAP_CODE_EMPTY   (0)

#include <include/net/coap.h>

COAP_DEFAULT_ACK_RANDOM_FACTOR

#define COAP_DEFAULT_ACK_RANDOM_FACTOR   1.5

#include <include/net/coap.h>

COAP_DEFAULT_MAX_RETRANSMIT

#define COAP_DEFAULT_MAX_RETRANSMIT   4

#include <include/net/coap.h>

coap_make_response_code

#define coap_make_response_code	(		class,
			det
	)		((class << 5) | (det))

#include <include/net/coap.h>

COAP_REQUEST_MASK

#define COAP_REQUEST_MASK   0x07

#include <include/net/coap.h>

COAP_TOKEN_MAX_LEN

#define COAP_TOKEN_MAX_LEN   8UL

#include <include/net/coap.h>

COAP_VERSION_1

#define COAP_VERSION_1   1U

#include <include/net/coap.h>

COAP_WELL_KNOWN_CORE_PATH

#define COAP_WELL_KNOWN_CORE_PATH    ((const char * const[]) { ".well-known", "core", NULL })

#include <include/net/coap_link_format.h>

This resource should be added before all other resources that should be included in the responses of the .well-known/core resource.

GET_BLOCK_NUM

#define GET_BLOCK_NUM

(

v

)

((v) >> 4)

#include <include/net/coap.h>

GET_BLOCK_SIZE

#define GET_BLOCK_SIZE

(

v

)

(((v) & 0x7))

#include <include/net/coap.h>

GET_MORE

#define GET_MORE

(

v

)

(!!((v) & 0x08))

#include <include/net/coap.h>

Typedef Documentation

coap_method_t

coap_method_t

#include <include/net/coap.h>

Type of the callback being called when a resource's method is invoked by the remote entity.

coap_notify_t

coap_notify_t

#include <include/net/coap.h>

Type of the callback being called when a resource's has observers to be informed when an update happens.

coap_reply_t

coap_reply_t

#include <include/net/coap.h>

Helper function to be called when a response matches the a pending request.

Enumeration Type Documentation

coap_block_size

enum coap_block_size

#include <include/net/coap.h>

Represents the size of each block that will be transferred using block-wise transfers [RFC7959]:

Each entry maps directly to the value that is used in the wire.

https://tools.ietf.org/html/rfc7959

Enumerator
COAP_BLOCK_16
COAP_BLOCK_32
COAP_BLOCK_64
COAP_BLOCK_128
COAP_BLOCK_256
COAP_BLOCK_512
COAP_BLOCK_1024

coap_content_format

enum coap_content_format

#include <include/net/coap.h>

Set of Content-Format option values for CoAP.

To be used when encoding or decoding a Content-Format option.

Enumerator
COAP_CONTENT_FORMAT_TEXT_PLAIN
COAP_CONTENT_FORMAT_APP_LINK_FORMAT
COAP_CONTENT_FORMAT_APP_XML
COAP_CONTENT_FORMAT_APP_OCTET_STREAM
COAP_CONTENT_FORMAT_APP_EXI
COAP_CONTENT_FORMAT_APP_JSON
COAP_CONTENT_FORMAT_APP_CBOR

coap_method

enum coap_method

#include <include/net/coap.h>

Available request methods.

To be used when creating a request or a response.

Enumerator
COAP_METHOD_GET
COAP_METHOD_POST
COAP_METHOD_PUT
COAP_METHOD_DELETE

coap_msgtype

enum coap_msgtype

#include <include/net/coap.h>

CoAP packets may be of one of these types.

Enumerator
COAP_TYPE_CON	Confirmable message. The packet is a request or response the destination end-point must acknowledge.
COAP_TYPE_NON_CON	Non-confirmable message. The packet is a request or response that doesn't require acknowledgements.
COAP_TYPE_ACK	Acknowledge. Response to a confirmable message.
COAP_TYPE_RESET	Reset. Rejecting a packet for any reason is done by sending a message of this type.

coap_option_num

enum coap_option_num

#include <include/net/coap.h>

Set of CoAP packet options we are aware of.

Users may add options other than these to their packets, provided they know how to format them correctly. The only restriction is that all options must be added to a packet in numeric order.

Refer to RFC 7252, section 12.2 for more information.

Enumerator
COAP_OPTION_IF_MATCH
COAP_OPTION_URI_HOST
COAP_OPTION_ETAG
COAP_OPTION_IF_NONE_MATCH
COAP_OPTION_OBSERVE
COAP_OPTION_URI_PORT
COAP_OPTION_LOCATION_PATH
COAP_OPTION_URI_PATH
COAP_OPTION_CONTENT_FORMAT
COAP_OPTION_MAX_AGE
COAP_OPTION_URI_QUERY
COAP_OPTION_ACCEPT
COAP_OPTION_LOCATION_QUERY
COAP_OPTION_BLOCK2
COAP_OPTION_BLOCK1
COAP_OPTION_SIZE2
COAP_OPTION_PROXY_URI
COAP_OPTION_PROXY_SCHEME
COAP_OPTION_SIZE1

coap_response_code

enum coap_response_code

#include <include/net/coap.h>

Set of response codes available for a response packet.

To be used when creating a response.

Enumerator
COAP_RESPONSE_CODE_OK
COAP_RESPONSE_CODE_CREATED
COAP_RESPONSE_CODE_DELETED
COAP_RESPONSE_CODE_VALID
COAP_RESPONSE_CODE_CHANGED
COAP_RESPONSE_CODE_CONTENT
COAP_RESPONSE_CODE_CONTINUE
COAP_RESPONSE_CODE_BAD_REQUEST
COAP_RESPONSE_CODE_UNAUTHORIZED
COAP_RESPONSE_CODE_BAD_OPTION
COAP_RESPONSE_CODE_FORBIDDEN
COAP_RESPONSE_CODE_NOT_FOUND
COAP_RESPONSE_CODE_NOT_ALLOWED
COAP_RESPONSE_CODE_NOT_ACCEPTABLE
COAP_RESPONSE_CODE_INCOMPLETE
COAP_RESPONSE_CODE_PRECONDITION_FAILED
COAP_RESPONSE_CODE_REQUEST_TOO_LARGE
COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT
COAP_RESPONSE_CODE_INTERNAL_ERROR
COAP_RESPONSE_CODE_NOT_IMPLEMENTED
COAP_RESPONSE_CODE_BAD_GATEWAY
COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE
COAP_RESPONSE_CODE_GATEWAY_TIMEOUT
COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED

Function Documentation

coap_ack_init()

int coap_ack_init	(	struct coap_packet *	cpkt,
		const struct coap_packet *	req,
		uint8_t *	data,
		uint16_t	max_len,
		uint8_t	code
	)

#include <include/net/coap.h>

Create a new CoAP Acknowledgment message for given request.

This function works like coap_packet_init, filling CoAP header type, CoAP header token, and CoAP header message id fields according to acknowledgment rules.

Parameters

cpkt	New packet to be initialized using the storage from data.
req	CoAP request packet that is being acknowledged
data	Data that will contain a CoAP packet information
max_len	Maximum allowable length of data
code	CoAP header code

Returns

0 in case of success or negative in case of error.

coap_append_block1_option()

int coap_append_block1_option	(	struct coap_packet *	cpkt,
		struct coap_block_context *	ctx
	)

#include <include/net/coap.h>

Append BLOCK1 option to the packet.

Parameters

cpkt	Packet to be updated
ctx	Block context from which to retrieve the information for the Block1 option

Returns

0 in case of success or negative in case of error.

coap_append_block2_option()

int coap_append_block2_option	(	struct coap_packet *	cpkt,
		struct coap_block_context *	ctx
	)

#include <include/net/coap.h>

Append BLOCK2 option to the packet.

Parameters

cpkt	Packet to be updated
ctx	Block context from which to retrieve the information for the Block2 option

Returns

0 in case of success or negative in case of error.

coap_append_option_int()

int coap_append_option_int	(	struct coap_packet *	cpkt,
		uint16_t	code,
		unsigned int	val
	)

#include <include/net/coap.h>

Appends an integer value option to the packet.

The option must be added in numeric order of their codes, and the least amount of bytes will be used to encode the value.

Parameters

cpkt	Packet to be updated
code	Option code to add to the packet, see coap_option_num
val	Integer value to be added

Returns

0 in case of success or negative in case of error.

coap_append_size1_option()

int coap_append_size1_option	(	struct coap_packet *	cpkt,
		struct coap_block_context *	ctx
	)

#include <include/net/coap.h>

Append SIZE1 option to the packet.

Parameters

cpkt	Packet to be updated
ctx	Block context from which to retrieve the information for the Size1 option

Returns

0 in case of success or negative in case of error.

coap_append_size2_option()

int coap_append_size2_option	(	struct coap_packet *	cpkt,
		struct coap_block_context *	ctx
	)

#include <include/net/coap.h>

Append SIZE2 option to the packet.

Parameters

cpkt	Packet to be updated
ctx	Block context from which to retrieve the information for the Size2 option

Returns

0 in case of success or negative in case of error.

coap_block_size_to_bytes()

static uint16_t coap_block_size_to_bytes ( enum coap_block_size  block_size )

inlinestatic

#include <include/net/coap.h>

Helper for converting the enumeration to the size expressed in bytes.

Parameters

block_size

The block size to be converted

Returns

The size in bytes that the block_size represents

coap_block_transfer_init()

int coap_block_transfer_init	(	struct coap_block_context *	ctx,
		enum coap_block_size	block_size,
		size_t	total_size
	)

#include <include/net/coap.h>

Initializes the context of a block-wise transfer.

Parameters

ctx	The context to be initialized
block_size	The size of the block
total_size	The total size of the transfer, if known

Returns

0 in case of success or negative in case of error.

coap_find_observer_by_addr()

struct coap_observer * coap_find_observer_by_addr	(	struct coap_observer *	observers,
		size_t	len,
		const struct sockaddr *	addr
	)

#include <include/net/coap.h>

Returns the observer that matches address addr.

Parameters

observers	Pointer to the array of observers
len	Size of the array of observers
addr	Address of the endpoint observing a resource

Returns

A pointer to a observer if a match is found, NULL otherwise.

coap_find_options()

int coap_find_options	(	const struct coap_packet *	cpkt,
		uint16_t	code,
		struct coap_option *	options,
		uint16_t	veclen
	)

#include <include/net/coap.h>

Return the values associated with the option of value code.

Parameters

cpkt	CoAP packet representation
code	Option number to look for
options	Array of coap_option where to store the value of the options found
veclen	Number of elements in the options array

Returns

The number of options found in packet matching code, negative on error.

coap_get_option_int()

int coap_get_option_int	(	const struct coap_packet *	cpkt,
		uint16_t	code
	)

#include <include/net/coap.h>

Get the integer representation of a CoAP option.

Parameters

cpkt	Packet to be inspected
code	CoAP option code

Returns

Integer value >= 0 in case of success or negative in case of error.

coap_handle_request()

int coap_handle_request	(	struct coap_packet *	cpkt,
		struct coap_resource *	resources,
		struct coap_option *	options,
		uint8_t	opt_num,
		struct sockaddr *	addr,
		socklen_t	addr_len
	)

#include <include/net/coap.h>

When a request is received, call the appropriate methods of the matching resources.

Parameters

cpkt	Packet received
resources	Array of known resources
options	Parsed options from coap_packet_parse()
opt_num	Number of options
addr	Peer address
addr_len	Peer address length

Returns

0 in case of success or negative in case of error.

coap_header_get_code()

uint8_t coap_header_get_code

(

const struct coap_packet *

cpkt

)

#include <include/net/coap.h>

Returns the code of the CoAP packet.

Parameters

cpkt	CoAP packet representation

Returns

the code present in the packet

coap_header_get_id()

uint16_t coap_header_get_id

(

const struct coap_packet *

cpkt

)

#include <include/net/coap.h>

Returns the message id associated with the CoAP packet.

Parameters

cpkt	CoAP packet representation

Returns

the message id present in the packet

coap_header_get_token()

uint8_t coap_header_get_token	(	const struct coap_packet *	cpkt,
		uint8_t *	token
	)

#include <include/net/coap.h>

Returns the token (if any) in the CoAP packet.

Parameters

cpkt	CoAP packet representation
token	Where to store the token, must point to a buffer containing at least COAP_TOKEN_MAX_LEN bytes

Returns

Token length in the CoAP packet (0 - COAP_TOKEN_MAX_LEN).

coap_header_get_type()

uint8_t coap_header_get_type

(

const struct coap_packet *

cpkt

)

#include <include/net/coap.h>

Returns the type of the CoAP packet.

Parameters

cpkt	CoAP packet representation

Returns

the type of the packet

coap_header_get_version()

uint8_t coap_header_get_version

(

const struct coap_packet *

cpkt

)

#include <include/net/coap.h>

Returns the version present in a CoAP packet.

Parameters

cpkt	CoAP packet representation

Returns

the CoAP version in packet

coap_next_block()

size_t coap_next_block	(	const struct coap_packet *	cpkt,
		struct coap_block_context *	ctx
	)

#include <include/net/coap.h>

Updates ctx so after this is called the current entry indicates the correct offset in the body of data being transferred.

Parameters

cpkt	Packet in which to look for block-wise transfers options
ctx	Block context to be updated

Returns

The offset in the block-wise transfer, 0 if the transfer has finished.

coap_next_id()

uint16_t coap_next_id

(

void

)

#include <include/net/coap.h>

Helper to generate message ids.

Returns

a new message id

coap_next_token()

uint8_t * coap_next_token

(

void

)

#include <include/net/coap.h>

Returns a randomly generated array of 8 bytes, that can be used as a message's token.

Returns

a 8-byte pseudo-random token.

coap_observer_init()

void coap_observer_init	(	struct coap_observer *	observer,
		const struct coap_packet *	request,
		const struct sockaddr *	addr
	)

#include <include/net/coap.h>

Indicates that the remote device referenced by addr, with request, wants to observe a resource.

Parameters

observer	Observer to be initialized
request	Request on which the observer will be based
addr	Address of the remote device

coap_observer_next_unused()

struct coap_observer * coap_observer_next_unused	(	struct coap_observer *	observers,
		size_t	len
	)

#include <include/net/coap.h>

Returns the next available observer representation.

Parameters

observers	Pointer to the array of observers
len	Size of the array of observers

Returns

A pointer to a observer if there's an available observer, NULL otherwise.

coap_option_value_to_int()

unsigned int coap_option_value_to_int

(

const struct coap_option *

option

)

#include <include/net/coap.h>

Converts an option to its integer representation.

Assumes that the number is encoded in the network byte order in the option.

Parameters

option

Pointer to the option value, retrieved by coap_find_options()

Returns

The integer representation of the option

coap_packet_append_option()

int coap_packet_append_option	(	struct coap_packet *	cpkt,
		uint16_t	code,
		const uint8_t *	value,
		uint16_t	len
	)

#include <include/net/coap.h>

Appends an option to the packet.

Note: options must be added in numeric order of their codes. Otherwise error will be returned. TODO: Add support for placing options according to its delta value.

Parameters

cpkt	Packet to be updated
code	Option code to add to the packet, see coap_option_num
value	Pointer to the value of the option, will be copied to the packet
len	Size of the data to be added

Returns

0 in case of success or negative in case of error.

coap_packet_append_payload()

int coap_packet_append_payload	(	struct coap_packet *	cpkt,
		const uint8_t *	payload,
		uint16_t	payload_len
	)

#include <include/net/coap.h>

Append payload to CoAP packet.

Parameters

cpkt	Packet to append the payload
payload	CoAP packet payload
payload_len	CoAP packet payload len

Returns

0 in case of success or negative in case of error.

coap_packet_append_payload_marker()

int coap_packet_append_payload_marker

(

struct coap_packet *

cpkt

)

#include <include/net/coap.h>

Append payload marker to CoAP packet.

Parameters

cpkt	Packet to append the payload marker (0xFF)

Returns

0 in case of success or negative in case of error.

coap_packet_get_payload()

const uint8_t * coap_packet_get_payload	(	const struct coap_packet *	cpkt,
		uint16_t *	len
	)

#include <include/net/coap.h>

Returns the data pointer and length of the CoAP packet.

Parameters

cpkt	CoAP packet representation
len	Total length of CoAP payload

Returns

data pointer and length if payload exists NULL pointer and length set to 0 in case there is no payload

coap_packet_init()

int coap_packet_init	(	struct coap_packet *	cpkt,
		uint8_t *	data,
		uint16_t	max_len,
		uint8_t	ver,
		uint8_t	type,
		uint8_t	token_len,
		const uint8_t *	token,
		uint8_t	code,
		uint16_t	id
	)

#include <include/net/coap.h>

Creates a new CoAP Packet from input data.

Parameters

cpkt	New packet to be initialized using the storage from data.
data	Data that will contain a CoAP packet information
max_len	Maximum allowable length of data
ver	CoAP header version
type	CoAP header type
token_len	CoAP header token length
token	CoAP header token
code	CoAP header code
id	CoAP header message id

Returns

0 in case of success or negative in case of error.

coap_packet_parse()

int coap_packet_parse	(	struct coap_packet *	cpkt,
		uint8_t *	data,
		uint16_t	len,
		struct coap_option *	options,
		uint8_t	opt_num
	)

#include <include/net/coap.h>

Parses the CoAP packet in data, validating it and initializing cpkt. data must remain valid while cpkt is used.

Parameters

cpkt	Packet to be initialized from received data.
data	Data containing a CoAP packet, its data pointer is positioned on the start of the CoAP packet.
len	Length of the data
options	Parse options and cache its details.
opt_num	Number of options

Returns

0 in case of success or negative in case of error.

coap_pending_clear()

void coap_pending_clear

(

struct coap_pending *

pending

)

#include <include/net/coap.h>

Cancels the pending retransmission, so it again becomes available.

Parameters

pending

Pending representation to be canceled

coap_pending_cycle()

bool coap_pending_cycle

(

struct coap_pending *

pending

)

#include <include/net/coap.h>

After a request is sent, user may want to cycle the pending retransmission so the timeout is updated.

Parameters

pending

Pending representation to have its timeout updated

Returns

false if this is the last retransmission.

coap_pending_init()

int coap_pending_init	(	struct coap_pending *	pending,
		const struct coap_packet *	request,
		const struct sockaddr *	addr,
		uint8_t	retries
	)

#include <include/net/coap.h>

Initialize a pending request with a request.

The request's fields are copied into the pending struct, so request doesn't have to live for as long as the pending struct lives, but "data" that needs to live for at least that long.

Parameters

pending	Structure representing the waiting for a confirmation message, initialized with data from request
request	Message waiting for confirmation
addr	Address to send the retransmission
retries	Maximum number of retransmissions of the message.

Returns

0 in case of success or negative in case of error.

coap_pending_next_to_expire()

struct coap_pending * coap_pending_next_to_expire	(	struct coap_pending *	pendings,
		size_t	len
	)

#include <include/net/coap.h>

Returns the next pending about to expire, pending->timeout informs how many ms to next expiration.

Parameters

pendings	Pointer to the array of coap_pending structures
len	Size of the array of coap_pending structures

Returns

The next coap_pending to expire, NULL if none is about to expire.

coap_pending_next_unused()

struct coap_pending * coap_pending_next_unused	(	struct coap_pending *	pendings,
		size_t	len
	)

#include <include/net/coap.h>

Returns the next available pending struct, that can be used to track the retransmission status of a request.

Parameters

pendings	Pointer to the array of coap_pending structures
len	Size of the array of coap_pending structures

Returns

pointer to a free coap_pending structure, NULL in case none could be found.

coap_pending_received()

struct coap_pending * coap_pending_received	(	const struct coap_packet *	response,
		struct coap_pending *	pendings,
		size_t	len
	)

#include <include/net/coap.h>

After a response is received, returns if there is any matching pending request exits. User has to clear all pending retransmissions related to that response by calling coap_pending_clear().

Parameters

response	The received response
pendings	Pointer to the array of coap_reply structures
len	Size of the array of coap_reply structures

Returns

pointer to the associated coap_pending structure, NULL in case none could be found.

coap_pendings_clear()

void coap_pendings_clear	(	struct coap_pending *	pendings,
		size_t	len
	)

#include <include/net/coap.h>

Cancels all pending retransmissions, so they become available again.

Parameters

pendings	Pointer to the array of coap_pending structures
len	Size of the array of coap_pending structures

coap_register_observer()

bool coap_register_observer	(	struct coap_resource *	resource,
		struct coap_observer *	observer
	)

#include <include/net/coap.h>

After the observer is initialized, associate the observer with an resource.

Parameters

resource	Resource to add an observer
observer	Observer to be added

Returns

true if this is the first observer added to this resource.

coap_remove_observer()

void coap_remove_observer	(	struct coap_resource *	resource,
		struct coap_observer *	observer
	)

#include <include/net/coap.h>

Remove this observer from the list of registered observers of that resource.

Parameters

resource	Resource in which to remove the observer
observer	Observer to be removed

coap_replies_clear()

void coap_replies_clear	(	struct coap_reply *	replies,
		size_t	len
	)

#include <include/net/coap.h>

Cancels all replies, so they become available again.

Parameters

replies	Pointer to the array of coap_reply structures
len	Size of the array of coap_reply structures

coap_reply_clear()

void coap_reply_clear

(

struct coap_reply *

reply

)

#include <include/net/coap.h>

Cancels awaiting for this reply, so it becomes available again. User responsibility to free the memory associated with data.

Parameters

reply

The reply to be canceled

coap_reply_init()

void coap_reply_init	(	struct coap_reply *	reply,
		const struct coap_packet *	request
	)

#include <include/net/coap.h>

Indicates that a reply is expected for request.

Parameters

reply	Reply structure to be initialized
request	Request from which reply will be based

coap_reply_next_unused()

struct coap_reply * coap_reply_next_unused	(	struct coap_reply *	replies,
		size_t	len
	)

#include <include/net/coap.h>

Returns the next available reply struct, so it can be used to track replies and notifications received.

Parameters

replies	Pointer to the array of coap_reply structures
len	Size of the array of coap_reply structures

Returns

pointer to a free coap_reply structure, NULL in case none could be found.

coap_request_is_observe()

bool coap_request_is_observe

(

const struct coap_packet *

request

)

#include <include/net/coap.h>

Returns if this request is enabling observing a resource.

Parameters

request

Request to be checked

Returns

True if the request is enabling observing a resource, False otherwise

coap_resource_notify()

int coap_resource_notify

(

struct coap_resource *

resource

)

#include <include/net/coap.h>

Indicates that this resource was updated and that the notify callback should be called for every registered observer.

Parameters

resource

Resource that was updated

Returns

0 in case of success or negative in case of error.

coap_response_received()

struct coap_reply * coap_response_received	(	const struct coap_packet *	response,
		const struct sockaddr *	from,
		struct coap_reply *	replies,
		size_t	len
	)

#include <include/net/coap.h>

After a response is received, call coap_reply_t handler registered in coap_reply structure.

Parameters

response	A response received
from	Address from which the response was received
replies	Pointer to the array of coap_reply structures
len	Size of the array of coap_reply structures

Returns

Pointer to the reply matching the packet received, NULL if none could be found.

coap_update_from_block()

int coap_update_from_block	(	const struct coap_packet *	cpkt,
		struct coap_block_context *	ctx
	)

#include <include/net/coap.h>

Retrieves BLOCK{1,2} and SIZE{1,2} from cpkt and updates ctx accordingly.

Parameters

cpkt	Packet in which to look for block-wise transfers options
ctx	Block context to be updated

Returns

0 in case of success or negative in case of error.

coap_well_known_core_get()

int coap_well_known_core_get	(	struct coap_resource *	resource,
		struct coap_packet *	request,
		struct coap_packet *	response,
		uint8_t *	data,
		uint16_t	len
	)

#include <include/net/coap_link_format.h>