Library for using RIOT as CoRE Resource Directory (RD) lookup client. More...

Detailed Description

Library for using RIOT as CoRE Resource Directory (RD) lookup client.

This module implements a CoRE Resource Directory lookup client library, that allows RIOT nodes to lookup resources, endpoints and groups with resource directories. It implements the standard lookup functionality as defined in RFC 9176.

See also: https://datatracker.ietf.org/doc/html/rfc9176

Lookup modes

The module defines two types of lookup for interacting with a RD server:

raw: result of the lookup is returned as is. No page or count filter is applied by default. Use cord_lc_raw() for this mode.
pre-parsed: result of the lookup is parsed and returned in a cord_lc_res_t or cord_lc_ep_t depending on the type of the lookup. The default count filter is set to 1 and page filter is incremented after each successful call and resets to 0 when lookup result is empty. Use cord_lc_res() or cord_lc_ep() for this mode.

Limitations

Currently, this module cannot do more than a single request concurrently and the request is fully synchronous. The client can only connects to one RD server at a time. The client will disconnect when a connection to a new RD server is made, regardless of whether the connection attempt is successful or not.

Files
file	lc.h
	CoRE Resource Directory lookup interface.

Data Structures
struct	cord_lc_rd_t
	Information about RD server and its lookup interface resources. More...

struct	cord_lc_result
	Result of lookup. More...

struct	cord_lc_filter
	Filters to use for a lookup. More...

Typedefs
typedef struct cord_lc_result	cord_lc_res_t
	Resource typedef.

typedef struct cord_lc_result	cord_lc_ep_t
	Endpoint typedef.

typedef struct cord_lc_filter	cord_lc_filter_t
	Filters to use for a lookup.

Enumerations
enum	{ CORD_LC_OK = 0 , CORD_LC_TIMEOUT = -1 , CORD_LC_ERR = -2 , CORD_LC_OVERFLOW = -3 , CORD_LC_NORSC = -4 }
	Return values and error codes used by this module. More...

enum	{ CORD_LC_RES , CORD_LC_EP }
	RD lookup types. More...

Functions
int	cord_lc_rd_init (cord_lc_rd_t rd, void buf, size_t maxlen, const sock_udp_ep_t *remote)
	Discover the lookup interfaces of a RD server.

ssize_t	cord_lc_raw (const cord_lc_rd_t rd, unsigned content_format, unsigned lookup_type, cord_lc_filter_t filters, void *result, size_t maxlen)
	Raw lookup for registered resources/endpoints at a RD server.

ssize_t	_lookup_result (cord_lc_rd_t rd, cord_lc_res_t result, cord_lc_filter_t filters, void buf, size_t maxlen, unsigned type)
	Get one resource from RD server.

static ssize_t	cord_lc_res (cord_lc_rd_t rd, cord_lc_res_t resource, cord_lc_filter_t filters, void buf, size_t maxlen)
	Get one resource from RD server.

static ssize_t	cord_lc_ep (cord_lc_rd_t rd, cord_lc_ep_t endpoint, cord_lc_filter_t filters, void buf, size_t maxlen)
	Get one endpoint from RD server.

Typedef Documentation

◆ cord_lc_ep_t

typedef struct cord_lc_result cord_lc_ep_t

Endpoint typedef.

Definition at line 100 of file lc.h.

◆ cord_lc_res_t

typedef struct cord_lc_result cord_lc_res_t

Resource typedef.

Definition at line 99 of file lc.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Return values and error codes used by this module.

Enumerator
CORD_LC_OK	everything went as expected
CORD_LC_TIMEOUT	no response from the network
CORD_LC_ERR	internal error or invalid reply
CORD_LC_OVERFLOW	internal buffers can not handle input
CORD_LC_NORSC	lookup interface not found

Definition at line 63 of file lc.h.

◆ anonymous enum

anonymous enum

RD lookup types.

Enumerator
CORD_LC_RES	Resource lookup type.
CORD_LC_EP	Endpoint lookup type.

Definition at line 74 of file lc.h.

Function Documentation

◆ _lookup_result()

ssize_t _lookup_result	(	cord_lc_rd_t *	rd,
		cord_lc_res_t *	result,
		cord_lc_filter_t *	filters,
		void *	buf,
		size_t	maxlen,
		unsigned	type
	)

Get one resource from RD server.

Gets only one resource from specified RD server each time called. Can be called iteratively to get all the resources on the server. If there is no more resource on the server, it will return CORD_LC_NORSC.

Parameters

[in]	rd	RD server to query
[out]	result	Result link
[in]	filters	Filters for the lookup
[out]	buf	Result buffer
[in]	maxlen	Maximum memory available at `buf`
[in]	type	Type of resource to query either CORD_LC_EP or CORD_LC_RES

Returns: bytes used on success; CORD_LC_INVALIF if the resource lookup interface at rd is invalid; CORD_LC_NORSC if there is no resource (anymore) at rd; CORD_LC_TIMEOUT if lookup timed out; CORD_LC_OVERFLOW if not enough memory available for result; CORD_LC_ERR on any other internal error

◆ cord_lc_ep()

static ssize_t cord_lc_ep	(	cord_lc_rd_t *	rd,
		cord_lc_ep_t *	endpoint,
		cord_lc_filter_t *	filters,
		void *	buf,
		size_t	maxlen
	)

inlinestatic

Get one endpoint from RD server.

Gets only one endpoint from specified RD server each time called. Can be called iteratively to get all the endpoints on the server. If there is no more endpoint on the server, it will return CORD_LC_NORSC.

Parameters

[in]	rd	RD server to query
[out]	endpoint	Resource link
[in]	filters	Filters for the lookup
[out]	buf	Result buffer
[in]	maxlen	Maximum memory available at `buf`

Returns: bytes used on success; CORD_LC_INVALIF if the endpoint lookup interface at rd is invalid; CORD_LC_NORSC if there is no endpoints (anymore) at rd; CORD_LC_TIMEOUT if lookup timed out; CORD_LC_OVERFLOW if not enough memory available for result; CORD_LC_ERR on any other internal error

Definition at line 234 of file lc.h.

◆ cord_lc_raw()

ssize_t cord_lc_raw	(	const cord_lc_rd_t *	rd,
		unsigned	content_format,
		unsigned	lookup_type,
		cord_lc_filter_t *	filters,
		void *	result,
		size_t	maxlen
	)

Raw lookup for registered resources/endpoints at a RD server.

To specify the number of resources/endpoints to search for, count and page attributes can be used as the filter. If the same filter used multiple times with different values, only the last filter will be applied.

Content format (e.g. link-format, coral) must be set through filters. If none defined, link-format will be used.

Parameters

[in]	rd	RD server to query
[in]	content_format	Data format wanted from RD server
[in]	lookup_type	Lookup type to use
[in]	filters	Filters for the lookup. Can be NULL.
[out]	result	Buffer holding the raw response
[in]	maxlen	Max length of `result`

Returns: bytes used on success; CORD_LC_NORSC if there is no lookup interface for lookup_type at rd; CORD_LC_TIMEOUT if lookup timed out; CORD_LC_OVERFLOW if not enough memory available for result; CORD_LC_ERR on any other internal error

◆ cord_lc_rd_init()

int cord_lc_rd_init	(	cord_lc_rd_t *	rd,
		void *	buf,
		size_t	maxlen,
		const sock_udp_ep_t *	remote
	)

Discover the lookup interfaces of a RD server.

Parameters

[out]	rd	Information about RD server at `remote`
[out]	buf	Buffer to store found lookup interfaces
[in]	maxlen	Maximum memory available at `lookif`
[in]	remote	Remote endpoint of RD server

Returns: bytes used on success; CORD_LC_TIMEOUT if the discovery request times out; CORD_LC_NORSC if no lookup interfaces found for all types of lookups; CORD_LC_OVERFLOW if not enough memory available for result; CORD_LC_ERR on any other internal error

◆ cord_lc_res()

static ssize_t cord_lc_res	(	cord_lc_rd_t *	rd,
		cord_lc_res_t *	resource,
		cord_lc_filter_t *	filters,
		void *	buf,
		size_t	maxlen
	)

inlinestatic

Get one resource from RD server.

Gets only one resource from specified RD server each time called. Can be called iteratively to get all the resources on the server. If there is no more resource on the server, it will return CORD_LC_NORSC.

Parameters

[in]	rd	RD server to query
[out]	resource	Resource link
[in]	filters	Filters for the lookup
[out]	buf	Result buffer
[in]	maxlen	Maximum memory available at `buf`

Returns: bytes used on success; CORD_LC_INVALIF if the resource lookup interface at rd is invalid; CORD_LC_NORSC if there is no resource (anymore) at rd; CORD_LC_TIMEOUT if lookup timed out; CORD_LC_OVERFLOW if not enough memory available for result; CORD_LC_ERR on any other internal error

Definition at line 206 of file lc.h.

Detailed Description

Lookup modes

Limitations

Files

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

◆ cord_lc_ep_t

◆ cord_lc_res_t

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ _lookup_result()

◆ cord_lc_ep()

◆ cord_lc_raw()

◆ cord_lc_rd_init()

◆ cord_lc_res()