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

Endpoints
enum	unicoap_proto_t { UNICOAP_PROTO_UDP = 1 << 1 , UNICOAP_PROTO_DTLS = 2 << 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 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.

Conversions and Tools
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_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 105 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 125 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 120 of file transport.h.

◆ UNICOAP_SCHEME

#define UNICOAP_SCHEME "coap"

Default CoAP URI scheme.

Definition at line 62 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 97 of file transport.h.

◆ UNICOAP_SCHEME_DTLS

#define UNICOAP_SCHEME_DTLS "coaps"

URI scheme for CoAP over DTLS.

Definition at line 72 of file transport.h.

◆ UNICOAP_SCHEME_TCP

#define UNICOAP_SCHEME_TCP "coap+tcp"

URI scheme for CoAP over TCP.

Definition at line 77 of file transport.h.

◆ UNICOAP_SCHEME_TLS

#define UNICOAP_SCHEME_TLS "coaps+tcp"

URI scheme for CoAP over TLS.

Definition at line 82 of file transport.h.

◆ UNICOAP_SCHEME_UDP

#define UNICOAP_SCHEME_UDP "coap"

URI scheme for CoAP over UDP.

Definition at line 67 of file transport.h.

◆ UNICOAP_SCHEME_WEBSOCKET

#define UNICOAP_SCHEME_WEBSOCKET "coap+ws"

URI scheme for CoAP over WebSockets.

Definition at line 87 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 92 of file transport.h.

Enumeration Type Documentation

◆ unicoap_proto_t

enum unicoap_proto_t

Transport protocol CoAP is used over.

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

Definition at line 130 of file transport.h.

Function Documentation

◆ 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 232 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 217 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_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 150 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 170 of file transport.h.

Detailed Description

Files

Data Structures

Endpoints

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_TCP

◆ UNICOAP_SCHEME_TLS

◆ UNICOAP_SCHEME_UDP

◆ UNICOAP_SCHEME_WEBSOCKET

◆ UNICOAP_SCHEME_WEBSOCKET_TLS

Enumeration Type Documentation

◆ unicoap_proto_t

Function Documentation

◆ unicoap_endpoint_get_dtls()

◆ unicoap_endpoint_get_udp()

◆ unicoap_endpoint_is_equal()

◆ unicoap_endpoint_is_multicast()

◆ unicoap_print_endpoint()

◆ unicoap_print_sock_tl_ep()

◆ unicoap_string_from_proto()

◆ unicoap_transport_is_reliable()

◆ unicoap_transport_uses_sock_tl_ep()

Examples