CoAP endpoint, resource identifiers, and schemes. More...

Detailed Description

CoAP endpoint, resource identifiers, and schemes.

Files
file	transport.h
	CoAP transport protocol abstraction layer.

Data Structures
struct	unicoap_endpoint_t
	A CoAP endpoint. More...

struct	unicoap_destination_t
	A type abstracting over CoAP resource identifiers. More...

Endpoints
enum	unicoap_proto_t { UNICOAP_PROTO_UDP = 1 << 1 , UNICOAP_PROTO_DTLS = 2 << 1 , UNICOAP_PROTO_SLIPMUX = 3 << 1 }
	Transport protocol CoAP is used over. More...

static bool	unicoap_transport_is_reliable (unicoap_proto_t proto)
	Determines whether the given transport protocol is reliable.

static bool	unicoap_transport_uses_sock_tl_ep (unicoap_proto_t proto)
	Determines whether the given transport driver uses a transport layer socket in RIOT.

static ipv6_addr_t *	unicoap_endpoint_get_ipv6_addr (unicoap_endpoint_t *endpoint)
	Retrieves IPv6 address from endpoint, if present and supported by endpoint type.

static ipv4_addr_t *	unicoap_endpoint_get_ipv4_addr (unicoap_endpoint_t *endpoint)
	Retrieves IPv4 address from endpoint, if present and supported by endpoint type.

static int *	unicoap_endpoint_get_address_family (unicoap_endpoint_t *endpoint)
	Retrieves address family from endpoint, if present and supported by endpoint type.

static uint16_t *	unicoap_endpoint_get_port (unicoap_endpoint_t *endpoint)
	Retrieves port from endpoint, if present and supported by endpoint type.

static uint16_t *	unicoap_endpoint_get_netif_id (unicoap_endpoint_t *endpoint)
	Retrieves network interface ID from endpoint, if present and supported by endpoint type.

static sock_udp_ep_t *	unicoap_endpoint_t::unicoap_endpoint_get_udp (unicoap_endpoint_t *endpoint)
	Retrieves UDP endpoint from CoAP endpoint.

static sock_udp_ep_t *	unicoap_endpoint_t::unicoap_endpoint_get_dtls (unicoap_endpoint_t *endpoint)
	Retrieves DTLS endpoint from CoAP endpoint.

#define	UNICOAP_PROTO_UNSPECIFIED (0)
	Unspecified protocol number.

#define	UNICOAP_PROTO_FLAG_RELIABLE_TRANSPORT (1)
	Protocol number flag indicating the transport is considered reliable on its own.

Request destinations
enum	unicoap_destination_type_t { UNICOAP_DESTINATION_ENDPOINT = 0 , UNICOAP_DESTINATION_HOST = 1 , UNICOAP_DESTINATION_URI = 2 }
	Resource identifier type. More...

static unicoap_destination_t	unicoap_destination_t::unicoap_destination_endpoint (unicoap_endpoint_t *endpoint)
	Creates destination identifier from endpoint.

static unicoap_destination_t	unicoap_destination_t::unicoap_destination_host (const char *host, size_t length)
	Creates destination identifier from hostname string.

static unicoap_destination_t	unicoap_destination_t::unicoap_destination_host_string (const char *host)
	Creates destination identifier from null-terminated hostname string.

static unicoap_destination_t	unicoap_destination_t::unicoap_destination_uri (const char *uri, size_t length)
	Creates destination identifier from URI string.

static unicoap_destination_t	unicoap_destination_t::unicoap_destination_uri_string (const char *uri)
	Creates destination identifier from URI string.

Conversions and Tools
int	unicoap_proto_from_scheme_and_host (const char scheme, size_t scheme_length, const char host, size_t length)
	Converts a given scheme string like `coap+tcp` to the corresponding protocol identifier.

static int	unicoap_transport_proto_from_scheme_and_host_string (const char scheme, const char host)
	Converts a given null-terminated scheme string like `coap+tcp` to the corresponding protocol identifier.

const char *	unicoap_scheme_from_proto (unicoap_proto_t proto)
	Returns scheme from protocol number.

const char *	unicoap_string_from_proto (unicoap_proto_t proto)
	Returns scheme from protocol number.

bool	unicoap_endpoint_is_equal (const unicoap_endpoint_t source, const unicoap_endpoint_t destination)
	Compares two endpoints.

bool	unicoap_endpoint_is_multicast (const unicoap_endpoint_t *endpoint)
	Determines whether the given endpoint is a multicast endpoint.

void	unicoap_print_sock_tl_ep (const struct _sock_tl_ep *ep)
	Prints the given transport layer endpoint.

void	unicoap_print_endpoint (const unicoap_endpoint_t *endpoint)
	Prints the given CoAP endpoint.

CoAP URI schemes
The goal for CoAP is to have `coap` as the only scheme, with the underlying transport being inferred using CoAP Transport Indication.
#define	UNICOAP_SCHEME "coap"
	Default CoAP URI scheme.

#define	UNICOAP_SCHEME_UDP "coap"
	URI scheme for CoAP over UDP.

#define	UNICOAP_SCHEME_DTLS "coaps"
	URI scheme for CoAP over DTLS.

#define	UNICOAP_SCHEME_TCP "coap+tcp"
	URI scheme for CoAP over TCP.

#define	UNICOAP_SCHEME_TLS "coaps+tcp"
	URI scheme for CoAP over TLS.

#define	UNICOAP_SCHEME_WEBSOCKET "coap+ws"
	URI scheme for CoAP over WebSockets.

#define	UNICOAP_SCHEME_WEBSOCKET_TLS "coaps+ws"
	URI scheme for CoAP over secure WebSockets (over TLS)

#define	UNICOAP_SCHEME_BLE_GATT "coap"
	URI scheme for CoAP over GATT over Bluetooth Low Energy (BLE)

#define	UNICOAP_SCHEME_SLIPMUX "coap+uart"
	URI scheme for CoAP over Slipmux.

#define	UNICOAP_DOMAIN_BLE ".ble.arpa"
	Domain for for CoAP over GATT over Bluetooth Low Energy (BLE)

Macro Definition Documentation

◆ UNICOAP_DOMAIN_BLE

#define UNICOAP_DOMAIN_BLE ".ble.arpa"

Domain for for CoAP over GATT over Bluetooth Low Energy (BLE)

Example URI: coap://001122334455.ble.arpa/.well-known/core, with 001122334455 being the MAC address of the BLE device.

Definition at line 115 of file transport.h.

◆ UNICOAP_PROTO_FLAG_RELIABLE_TRANSPORT

#define UNICOAP_PROTO_FLAG_RELIABLE_TRANSPORT (1)

Protocol number flag indicating the transport is considered reliable on its own.

Definition at line 135 of file transport.h.

◆ UNICOAP_PROTO_UNSPECIFIED

#define UNICOAP_PROTO_UNSPECIFIED (0)

Unspecified protocol number.

Use this protocol number to mark endpoints uninitialized.

Definition at line 130 of file transport.h.

◆ UNICOAP_SCHEME

#define UNICOAP_SCHEME "coap"

Default CoAP URI scheme.

Definition at line 67 of file transport.h.

◆ UNICOAP_SCHEME_BLE_GATT

#define UNICOAP_SCHEME_BLE_GATT "coap"

URI scheme for CoAP over GATT over Bluetooth Low Energy (BLE)

Definition at line 102 of file transport.h.

◆ UNICOAP_SCHEME_DTLS

#define UNICOAP_SCHEME_DTLS "coaps"

URI scheme for CoAP over DTLS.

Definition at line 77 of file transport.h.

◆ UNICOAP_SCHEME_SLIPMUX

#define UNICOAP_SCHEME_SLIPMUX "coap+uart"

URI scheme for CoAP over Slipmux.

Definition at line 107 of file transport.h.

◆ UNICOAP_SCHEME_TCP

#define UNICOAP_SCHEME_TCP "coap+tcp"

URI scheme for CoAP over TCP.

Definition at line 82 of file transport.h.

◆ UNICOAP_SCHEME_TLS

#define UNICOAP_SCHEME_TLS "coaps+tcp"

URI scheme for CoAP over TLS.

Definition at line 87 of file transport.h.

◆ UNICOAP_SCHEME_UDP

#define UNICOAP_SCHEME_UDP "coap"

URI scheme for CoAP over UDP.

Definition at line 72 of file transport.h.

◆ UNICOAP_SCHEME_WEBSOCKET

#define UNICOAP_SCHEME_WEBSOCKET "coap+ws"

URI scheme for CoAP over WebSockets.

Definition at line 92 of file transport.h.

◆ UNICOAP_SCHEME_WEBSOCKET_TLS

#define UNICOAP_SCHEME_WEBSOCKET_TLS "coaps+ws"

URI scheme for CoAP over secure WebSockets (over TLS)

Definition at line 97 of file transport.h.

Enumeration Type Documentation

◆ unicoap_destination_type_t

enum unicoap_destination_type_t

Resource identifier type.

Enumerator
UNICOAP_DESTINATION_ENDPOINT	Endpoint.
UNICOAP_DESTINATION_HOST	Hostname.
UNICOAP_DESTINATION_URI	URI (Uniform Resource Identifier)

Definition at line 407 of file transport.h.

◆ unicoap_proto_t

enum unicoap_proto_t

Transport protocol CoAP is used over.

The LSB is used to check if the transport is inherently reliable.

Enumerator
UNICOAP_PROTO_UDP	CoAP over UDP endpoint.
UNICOAP_PROTO_DTLS	CoAP over DTLS over UDP endpoint.
UNICOAP_PROTO_SLIPMUX	CoAP over Slipmux endpoint.

Definition at line 142 of file transport.h.

Function Documentation

◆ unicoap_destination_endpoint()

static unicoap_destination_t unicoap_destination_endpoint ( unicoap_endpoint_t * endpoint )

inlinestatic

Creates destination identifier from endpoint.

Parameters

[in] endpoint Endpoint. Must remain valid for as long as the returned destination is used (pointer stored, not copied).

Returns: New resource identifier from endpoint

Definition at line 461 of file transport.h.

◆ unicoap_destination_host()

static unicoap_destination_t unicoap_destination_host	(	const char *	host,
		size_t	length )

inlinestatic

Creates destination identifier from hostname string.

Parameters

[in]	host	Host name or address string. Must remain valid for as long as the returned destination is used (pointer stored, not copied).
	length	Number of ASCII code units (bytes) in `host`, excluding potential null-terminator

Precondition: length must not be greater than 1023

Returns: New resource identifier from endpoint

Definition at line 486 of file transport.h.

◆ unicoap_destination_host_string()

static unicoap_destination_t unicoap_destination_host_string ( const char * host )

inlinestatic

Creates destination identifier from null-terminated hostname string.

Parameters

[in] host Null-terminated host name or address string. Must remain valid for as long as the returned destination is used (pointer stored, not copied).

Returns: New resource identifier from endpoint

Definition at line 505 of file transport.h.

◆ unicoap_destination_uri()

static unicoap_destination_t unicoap_destination_uri	(	const char *	uri,
		size_t	length )

inlinestatic

Creates destination identifier from URI string.

Parameters

[in]	uri	Uniform Resource Identifier (URI). Must remain valid for as long as the returned destination is used (pointer stored, not copied).
	length	Number of ASCII code units (bytes) in `uri`, excluding potential null-terminator

Precondition: length must not be greater than 1023

Returns: New resource identifier from URI

Definition at line 527 of file transport.h.

◆ unicoap_destination_uri_string()

static unicoap_destination_t unicoap_destination_uri_string ( const char * uri )

inlinestatic

Creates destination identifier from URI string.

Parameters

[in] uri Null-terminated Uniform Resource Identifier (URI). Must remain valid for as long as the returned destination is used (pointer stored, not copied).

Returns: New resource identifier from URI

Definition at line 546 of file transport.h.

◆ unicoap_endpoint_get_address_family()

static int * unicoap_endpoint_get_address_family ( unicoap_endpoint_t * endpoint )

inlinestatic

Retrieves address family from endpoint, if present and supported by endpoint type.

Parameters

endpoint Endpoint

Returns: Application address reference if present and supported, NULL otherwise

Definition at line 342 of file transport.h.

◆ unicoap_endpoint_get_dtls()

static sock_udp_ep_t * unicoap_endpoint_get_dtls ( unicoap_endpoint_t * endpoint )

inlinestatic

Retrieves DTLS endpoint from CoAP endpoint.

Precondition: endpoint is a CoAP over DTLS endpoint (proto == UNICOAP_PROTO_DTLS)

Parameters

[in,out] endpoint CoAP over DTLS endpoint

Returns: sock_udp_ep_t

Definition at line 260 of file transport.h.

◆ unicoap_endpoint_get_ipv4_addr()

static ipv4_addr_t * unicoap_endpoint_get_ipv4_addr ( unicoap_endpoint_t * endpoint )

inlinestatic

Retrieves IPv4 address from endpoint, if present and supported by endpoint type.

Parameters

endpoint Endpoint

Returns: IPv4 address if present and supported, NULL otherwise

Definition at line 319 of file transport.h.

◆ unicoap_endpoint_get_ipv6_addr()

static ipv6_addr_t * unicoap_endpoint_get_ipv6_addr ( unicoap_endpoint_t * endpoint )

inlinestatic

Retrieves IPv6 address from endpoint, if present and supported by endpoint type.

Parameters

endpoint Endpoint

Returns: IPv6 address if present and supported, NULL otherwise

Definition at line 296 of file transport.h.

◆ unicoap_endpoint_get_netif_id()

static uint16_t * unicoap_endpoint_get_netif_id ( unicoap_endpoint_t * endpoint )

inlinestatic

Retrieves network interface ID from endpoint, if present and supported by endpoint type.

Parameters

endpoint Endpoint

Returns: Network interface ID reference if present and supported, NULL otherwise

Definition at line 382 of file transport.h.

◆ unicoap_endpoint_get_port()

static uint16_t * unicoap_endpoint_get_port ( unicoap_endpoint_t * endpoint )

inlinestatic

Retrieves port from endpoint, if present and supported by endpoint type.

Parameters

endpoint Endpoint

Returns: Port reference if present and supported, NULL otherwise

Definition at line 362 of file transport.h.

◆ unicoap_endpoint_get_udp()

static sock_udp_ep_t * unicoap_endpoint_get_udp ( unicoap_endpoint_t * endpoint )

inlinestatic

Retrieves UDP endpoint from CoAP endpoint.

Precondition: endpoint is a CoAP over UDP endpoint (proto == UNICOAP_PROTO_UDP)

Parameters

[in,out] endpoint CoAP over UDP endpoint

Returns: sock_udp_ep_t

Definition at line 240 of file transport.h.

◆ unicoap_endpoint_is_equal()

bool unicoap_endpoint_is_equal	(	const unicoap_endpoint_t *	source,
		const unicoap_endpoint_t *	destination )

Compares two endpoints.

Parameters

[in]	source	Endpoint 1
[in]	destination	Endpoint 2

Returns: A boolean value indicating whether the two endpoints are considered identical semantically

◆ unicoap_endpoint_is_multicast()

bool unicoap_endpoint_is_multicast ( const unicoap_endpoint_t * endpoint )

Determines whether the given endpoint is a multicast endpoint.

Parameters

[in] endpoint Endpoint to check

Returns: A boolean value indicating whether the endpoint is considered a multicast endpoint

◆ unicoap_print_endpoint()

void unicoap_print_endpoint ( const unicoap_endpoint_t * endpoint )

Prints the given CoAP endpoint.

Parameters

[in] endpoint Endpoint

◆ unicoap_print_sock_tl_ep()

void unicoap_print_sock_tl_ep ( const struct _sock_tl_ep * ep )

Prints the given transport layer endpoint.

Parameters

[in] ep Transport layer endpoint

◆ unicoap_proto_from_scheme_and_host()

int unicoap_proto_from_scheme_and_host	(	const char *	scheme,
		size_t	scheme_length,
		const char *	host,
		size_t	length )

Converts a given scheme string like coap+tcp to the corresponding protocol identifier.

Parameters

[in]	scheme	Scheme string
	scheme_length	Length of scheme string
[in]	host	Optional Host string
[in]	length	Scheme string length, must be zero if `host` is `NULL` or empty (i.e., points to 0x00)

Return values

0	for valid schemes
-1	if the scheme is invalid or unknown

◆ unicoap_scheme_from_proto()

const char * unicoap_scheme_from_proto ( unicoap_proto_t proto )

Returns scheme from protocol number.

Parameters

proto Protocol number

Return values

Null-terminated	transport scheme string
NULL	if protocol number is unknown

◆ unicoap_string_from_proto()

const char * unicoap_string_from_proto ( unicoap_proto_t proto )

Returns scheme from protocol number.

Parameters

proto Protocol number

Returns: Null-terminated transport description, or NULL if there is no such protocol number

◆ unicoap_transport_is_reliable()

static bool unicoap_transport_is_reliable ( unicoap_proto_t proto )

inlinestatic

Determines whether the given transport protocol is reliable.

Used for enabling the Block-wise Extension for Reliable Transports (BERT).

Parameters

proto Protocol number for transport

Returns: A boolean value determining whether the transport is considered reliable

Note: BERT allows multiple blocks of size 1024 bytes to be included in a single CoAP message.

Definition at line 165 of file transport.h.

◆ unicoap_transport_proto_from_scheme_and_host_string()

static int unicoap_transport_proto_from_scheme_and_host_string	(	const char *	scheme,
		const char *	host )

inlinestatic

Converts a given null-terminated scheme string like coap+tcp to the corresponding protocol identifier.

Parameters

[in]	scheme	Null-terminated scheme string
[in]	host	Null-terminated host string

Return values

0	for valid schemes
-1	if the scheme is invalid or unknown

Definition at line 586 of file transport.h.

◆ unicoap_transport_uses_sock_tl_ep()

static bool unicoap_transport_uses_sock_tl_ep ( unicoap_proto_t proto )

inlinestatic

Determines whether the given transport driver uses a transport layer socket in RIOT.

Parameters

proto Protocol number for transport

Returns: A boolean value indicating whether the transport uses a transport layer socket in RIOT

Used when parsing URIs and when printing an endpoint. If true, the socket endpoint can be casted to struct _sock_tl_ep*.

Examples

Definition at line 185 of file transport.h.

Detailed Description

Files

Data Structures

Endpoints

Request destinations

Conversions and Tools

CoAP URI schemes

Macro Definition Documentation

◆ UNICOAP_DOMAIN_BLE

◆ UNICOAP_PROTO_FLAG_RELIABLE_TRANSPORT

◆ UNICOAP_PROTO_UNSPECIFIED

◆ UNICOAP_SCHEME

◆ UNICOAP_SCHEME_BLE_GATT

◆ UNICOAP_SCHEME_DTLS

◆ UNICOAP_SCHEME_SLIPMUX

◆ UNICOAP_SCHEME_TCP

◆ UNICOAP_SCHEME_TLS

◆ UNICOAP_SCHEME_UDP

◆ UNICOAP_SCHEME_WEBSOCKET

◆ UNICOAP_SCHEME_WEBSOCKET_TLS

Enumeration Type Documentation

◆ unicoap_destination_type_t

◆ unicoap_proto_t

Function Documentation

◆ unicoap_destination_endpoint()

◆ unicoap_destination_host()

◆ unicoap_destination_host_string()

◆ unicoap_destination_uri()

◆ unicoap_destination_uri_string()

◆ unicoap_endpoint_get_address_family()

◆ unicoap_endpoint_get_dtls()

◆ unicoap_endpoint_get_ipv4_addr()

◆ unicoap_endpoint_get_ipv6_addr()

◆ unicoap_endpoint_get_netif_id()

◆ unicoap_endpoint_get_port()

◆ unicoap_endpoint_get_udp()

◆ unicoap_endpoint_is_equal()

◆ unicoap_endpoint_is_multicast()

◆ unicoap_print_endpoint()

◆ unicoap_print_sock_tl_ep()

◆ unicoap_proto_from_scheme_and_host()

◆ unicoap_scheme_from_proto()

◆ unicoap_string_from_proto()

◆ unicoap_transport_is_reliable()

◆ unicoap_transport_proto_from_scheme_and_host_string()

◆ unicoap_transport_uses_sock_tl_ep()

Examples