State Management

Detailed Description

Files
file	state.h
	State and Memo API.

Data Structures
struct	unicoap_memo_t
	A type used to retain state spanning across a single or multiple message exchanges. More...
struct	unicoap_client_memo_t
	Client exchange. More...

Event Scheduling
typedef void(*	unicoap_event_callback_t) (unicoap_scheduled_event_t *event)
	Scheduled event callback.
static const char *	unicoap_scheduled_event_name (unicoap_scheduled_event_t *event)
	Name of scheduled event.
static unicoap_scheduled_event_t *	unicoap_scheduled_event_of_event (event_t *event)
	Returns scheduled event subclass of event.
void	unicoap_event_schedule (unicoap_scheduled_event_t *event, unicoap_event_callback_t callback, uint32_t duration, const char *name)
	Schedules an event on the internal unicoap queue.
void	unicoap_event_reschedule (unicoap_scheduled_event_t *event, uint32_t duration)
	Discards the currently set timeout, and reschedules the event to be posted in duration ms.
void	unicoap_event_cancel (unicoap_scheduled_event_t *event)
	Cancels the event.
#define	UNICOAP_CLOCK   ZTIMER_MSEC
	The ztimer clock used for event scheduling.

Layered notification system
typedef int	unicoap_layer_notification_t
	A signal sent from one layer to another indicating a change to a state object.
static int	unicoap_layer_notification_async_failure_to_errno (unicoap_layer_notification_t type)
	Converts notification to negative error number.
static unicoap_layer_notification_t	unicoap_layer_notification_async_failure_from_errno (int error)
	Converts error number into notification.
void	unicoap_messaging_notify (void *state, unicoap_layer_notification_t type, void *arg, unicoap_proto_t proto)
	Informs messaging layer of event.
void	unicoap_exchange_notify (void *state, unicoap_layer_notification_t type, void *arg)
	Informs exchange layer of event.
void	unicoap_exchange_notify_all (const unicoap_endpoint_t *endpoint, unicoap_layer_notification_t type, void *arg)
	Informs exchange layer of event that applies to all exchange state objects associated with given endpoint.
#define	UNICOAP_LAYER_NOTIFICATION_ASYNC_FAILURE   (~(~0U >> 1))
	Event indicating a failure on the layer this message is sent from.
#define	UNICOAP_LAYER_NOTIFICATION_STATE_RELEASE   (0)
	Event indicating a layer is finished and is releasing its allocated state objects of this exchange/transmission.
#define	UNICOAP_LAYER_NOTIFICATION_STATE_ALLOC   (1)
	Event indicating a layer is allocating a state object.

Common state
static void *	unicoap_memo_messaging_state (unicoap_memo_t *memo)
	Returns messaging state associated with memo.
static unicoap_memo_t *	unicoap_memo_of_timeout (unicoap_scheduled_event_t *timeout)
	Returns memo of scheduled event.
static unicoap_memo_t *	unicoap_memo_of_event (event_t *event)
	Returns memo of scheduled event.
#define	UNICOAP_HAVE_MESSAGING_STATE    IS_USED(MODULE_UNICOAP_DRIVER_RFC7252_COMMON)
	A feature check macro that determines whether there's at least one driver that stores messaging-layer state for transmissions.
#define	UNICOAP_HAVE_CLIENT_STATE    IS_USED(MODULE_UNICOAP_CLIENT) && CONFIG_UNICOAP_CLIENT_MEMOS_CAPACITY > 0
	A feature check macro that determines whether client state objects are supported.

Client state
static bool	unicoap_callback_is_present (const unicoap_callback_t callback)
	Determines whether the given callback is not NULL
static unicoap_client_memo_t *	unicoap_client_memo_of_super (unicoap_memo_t *memo)
	Returns client memo of common memo state object.
static unicoap_client_memo_t *	unicoap_client_memo_of_event (event_t *event)
	Returns client memo of event.
static unicoap_client_memo_t *	unicoap_client_memo_of_timeout (unicoap_scheduled_event_t *timeout)
	Returns client memo of scheduled event.
int	unicoap_client_callback_success (unicoap_client_memo_t *memo, const unicoap_packet_t *packet, unicoap_block_option_t block)
	Invokes the client callback.
void	unicoap_client_callback_failure (unicoap_client_memo_t *memo, int error)
	Invokes the client callback indicating an error occurred.
unicoap_client_memo_t *	unicoap_client_memo_create (const unicoap_endpoint_t *endpoint)
	Allocates and sets up a new memo.
unicoap_client_memo_t *	unicoap_client_memo_find_token (const unicoap_endpoint_t *endpoint, const uint8_t *token, size_t token_length)
	Tries to find a client exchange memo by endpoint and token.
unicoap_client_memo_t *	unicoap_client_memo_find_refno (int refno)
	Tries to find client state object based on reference number.
int	unicoap_client_memo_assign_refno (unicoap_client_memo_t *memo)
	Assigns a refno to the given client memo.
void	unicoap_client_memo_free (unicoap_client_memo_t *memo, int error)
	Frees memo and associated buffers.

Macro Definition Documentation

UNICOAP_CLOCK

#define UNICOAP_CLOCK   ZTIMER_MSEC

The ztimer clock used for event scheduling.

Definition at line 124 of file state.h.

UNICOAP_HAVE_CLIENT_STATE

#define UNICOAP_HAVE_CLIENT_STATE    IS_USED(MODULE_UNICOAP_CLIENT) && CONFIG_UNICOAP_CLIENT_MEMOS_CAPACITY > 0

A feature check macro that determines whether client state objects are supported.

Definition at line 189 of file state.h.

UNICOAP_HAVE_MESSAGING_STATE

#define UNICOAP_HAVE_MESSAGING_STATE    IS_USED(MODULE_UNICOAP_DRIVER_RFC7252_COMMON)

A feature check macro that determines whether there's at least one driver that stores messaging-layer state for transmissions.

Definition at line 182 of file state.h.

UNICOAP_LAYER_NOTIFICATION_ASYNC_FAILURE

#define UNICOAP_LAYER_NOTIFICATION_ASYNC_FAILURE   (~(~0U >> 1))

Event indicating a failure on the layer this message is sent from.

The recipient layer should try to release state objects as soon as possible.

Warning

Only notify the exchange layer of errors that were produced on the messaging layer and that happened asynchronously (not while in a call frame from the exchange layer). Synchronous errors shall be reported by returning negative integers.

See also

unicoap_exchange_notify.

Definition at line 296 of file state.h.

UNICOAP_LAYER_NOTIFICATION_STATE_ALLOC

#define UNICOAP_LAYER_NOTIFICATION_STATE_ALLOC   (1)

Event indicating a layer is allocating a state object.

The recipient layer can attach state it itself allocated.

Definition at line 332 of file state.h.

UNICOAP_LAYER_NOTIFICATION_STATE_RELEASE

#define UNICOAP_LAYER_NOTIFICATION_STATE_RELEASE   (0)

Event indicating a layer is finished and is releasing its allocated state objects of this exchange/transmission.

The recipient layer must determine whether it still needs to retain its allocated state objects.

Definition at line 325 of file state.h.

Typedef Documentation

unicoap_event_callback_t

typedef void(* unicoap_event_callback_t) (unicoap_scheduled_event_t *event)

Scheduled event callback.

Use the event parameter and the container_of macro to get a pointer to the parent structure.

Parameters

[in]

event

pointer to event

Definition at line 134 of file state.h.

unicoap_layer_notification_t

typedef int unicoap_layer_notification_t

A signal sent from one layer to another indicating a change to a state object.

See also

UNICOAP_LAYER_NOTIFICATION_STATE_RELEASE

UNICOAP_LAYER_NOTIFICATION_STATE_ALLOC

UNICOAP_LAYER_NOTIFICATION_ASYNC_FAILURE

unicoap_layer_notification_async_failure_to_errno

unicoap_layer_notification_async_failure_from_errno

Definition at line 284 of file state.h.

Function Documentation

unicoap_callback_is_present()

static bool unicoap_callback_is_present ( const unicoap_callback_t callback )

inlinestatic

Determines whether the given callback is not NULL

Parameters

[in]

callback

Callbacks

Returns

A boolean value indicating whether the given callback is NULL

Definition at line 405 of file state.h.

unicoap_client_callback_success()

int unicoap_client_callback_success	(	unicoap_client_memo_t *	memo,
		const unicoap_packet_t *	packet,
		unicoap_block_option_t	block )

Invokes the client callback.

Parameters

[in,out]	memo	Client state object
[in]	packet	A packet containing the response to the request
	block	Block option, used to choose correct callback prototype

unicoap_client_memo_assign_refno()

int unicoap_client_memo_assign_refno

(

unicoap_client_memo_t *

memo

)

Assigns a refno to the given client memo.

Parameters

[in,out]

memo

Client memo

Returns

Refno assigned

Requires Request cancellation.

Constructs a refno, a stable reference to a memo while it is being used for a specific exchange. Should the memo struct in the memo array get reused for another exchange, the refno can be detected to be obsolete.

unicoap_client_memo_create()

unicoap_client_memo_t * unicoap_client_memo_create

(

const unicoap_endpoint_t *

endpoint

)

Allocates and sets up a new memo.

Note

This function is thread-safe.

Parameters

[in]

endpoint

Remote endpoint

Returns

New memo

unicoap_client_memo_find_refno()

unicoap_client_memo_t * unicoap_client_memo_find_refno

(

int

refno

)

Tries to find client state object based on reference number.

Parameters

refno

Reference number associated with client memo

Returns

Client state object or NULL if memo is no longer associated with reference number

Note

Requires Request cancellation

This function may be used to find client exchange-layer state objects without keeping a pointer to it. This is useful for handing public API callers a reference to, e.g., cancellable state objects. With solely a pointer to the memo, unicoap would be at risk of accessing a memo that had subsequently been released and then got reused, thus no longer relates to the original exchange. Relying on the reference number prevents this as it contains a fingerprint of the memo contents. Should the memo get released, obsolete references can be detected and discarded.

unicoap_client_memo_find_token()

unicoap_client_memo_t * unicoap_client_memo_find_token	(	const unicoap_endpoint_t *	endpoint,
		const uint8_t *	token,
		size_t	token_length )

Tries to find a client exchange memo by endpoint and token.

Parameters

[in]	endpoint	Remote endpoint of exchange
[in]	token	Token
	token_length	Token length

Returns

Memo, if found

unicoap_client_memo_free()

void unicoap_client_memo_free	(	unicoap_client_memo_t *	memo,
		int	error )

Frees memo and associated buffers.

Parameters

[in,out]	memo	Memo state bucket to discard and free
	error	Error number indicating a failure on the exchange layer to propagate to the messaging layer, instructing it to release state. May be zero.

You do not need to forward every error on the exchange layer to the messaging layer when calling this function. For example, when cancelling a pending request, you can treat this as an -ECANCELED error on the exchange layer and call the client callback with said error, but you may as well pass 0 for error as propagating the error down will indicate a hard failure and make the messaging layer release state including connections.

unicoap_client_memo_of_event()

static unicoap_client_memo_t * unicoap_client_memo_of_event ( event_t * event )

inlinestatic

Returns client memo of event.

Parameters

[in]

event

Superclass event

Returns

Client memo state object

Definition at line 452 of file state.h.

unicoap_client_memo_of_super()

static unicoap_client_memo_t * unicoap_client_memo_of_super ( unicoap_memo_t * memo )

inlinestatic

Returns client memo of common memo state object.

Parameters

[in]

memo

Superclass memo

Returns

Client memo state object

Definition at line 443 of file state.h.

unicoap_client_memo_of_timeout()

static unicoap_client_memo_t * unicoap_client_memo_of_timeout ( unicoap_scheduled_event_t * timeout )

inlinestatic

Returns client memo of scheduled event.

Parameters

[in]

timeout

Timeout event

Returns

Client memo state object

Definition at line 461 of file state.h.

unicoap_event_cancel()

void unicoap_event_cancel

(

unicoap_scheduled_event_t *

event

)

Cancels the event.

Parameters

[in]

event

Scheduled event you want to cancel

Internally, the timer is removed from the clock.

Note

If the event has already been posted on the queue, this method will try to remove the cancel the event that has already been posted to the queue.

unicoap_event_reschedule()

void unicoap_event_reschedule	(	unicoap_scheduled_event_t *	event,
		uint32_t	duration )

Discards the currently set timeout, and reschedules the event to be posted in duration ms.

Use this method to rerun the timer with the same callbacks but a new timeout value. E.g., the RFC 7252 driver utilizes this method for setting the next acknowledgement timeout.

Parameters

[in]	event	Scheduled event you want to reschedule
[in]	duration	Number of milliseconds the event should be posted on the queue

unicoap_event_schedule()

void unicoap_event_schedule	(	unicoap_scheduled_event_t *	event,
		unicoap_event_callback_t	callback,
		uint32_t	duration,
		const char *	name )

Schedules an event on the internal unicoap queue.

If you instead want to execute as soon as possible, use unicoap_loop_enqueue instead.

Parameters

[in,out]	event	The event to schedule. Provide a pointer to a pre-allocated event
[in]	callback	Function pointer to be called on the internal queue after duration ms have elapses
	duration	Number of milliseconds to wait
[in]	name	A null-terminated string identifier to distinguish the event in debug logs

name has no effect when DEVELHELP is disabled.

unicoap_exchange_notify()

void unicoap_exchange_notify	(	void *	state,
		unicoap_layer_notification_t	type,
		void *	arg )

Informs exchange layer of event.

Parameters

	state	Exchange-layer state reference
	type	Event type
[in]	arg	Optional opaque state object in this layer the notification relates to.

Usually called from messaging layer. Do not notify the exchange layer of failures that occur in a synchronous call from the exchange layer into the messaging layer (send) or that originate from the exchange layer (preprocess and process). Only propagate errors that arise asynchronously, e.g., negative acknowledgement or connection resets directly on the messaging layer.

Warning

**The messaging layer must not send a notification of type UNICOAP_LAYER_NOTIFICATION_ASYNC_FAILURE before unicoap_messaging_send has returned!** In this case, unicoap_messaging_send shall return a negative integer indicating an error instead, such as -ENOBUFS or -ECONNABORTED.

**The messaging layer must also not send a notification of type UNICOAP_LAYER_NOTIFICATION_ASYNC_FAILURE when unicoap_exchange_preprocess or unicoap_exchange_process already returned an error for the same incoming message!** In these cases, the exchange layer will take care of handling the error, and the messaging layer must not notify the exchange layer of this error again.

unicoap_exchange_notify_all()

void unicoap_exchange_notify_all	(	const unicoap_endpoint_t *	endpoint,
		unicoap_layer_notification_t	type,
		void *	arg )

Informs exchange layer of event that applies to all exchange state objects associated with given endpoint.

Parameters

	endpoint	Endpoint
	type	Event type
[in]	arg	Optional opaque state object in this (sending) layer the notification relates to.

Usually called from messaging layer.

unicoap_layer_notification_async_failure_from_errno()

static unicoap_layer_notification_t unicoap_layer_notification_async_failure_from_errno ( int error )

inlinestatic

Converts error number into notification.

Parameters

error

Positive or negative integer indicating error, e.g., -ETIMEDOUT or ETIMEDOUT

Returns

Notification

Definition at line 314 of file state.h.

unicoap_layer_notification_async_failure_to_errno()

static int unicoap_layer_notification_async_failure_to_errno ( unicoap_layer_notification_t type )

inlinestatic

Converts notification to negative error number.

Parameters

type	Notification

Returns

Negative integer indicating error

Definition at line 303 of file state.h.

unicoap_memo_messaging_state()

static void * unicoap_memo_messaging_state ( unicoap_memo_t * memo )

inlinestatic

Returns messaging state associated with memo.

Parameters

memo	Client state object

Returns

Messaging state object pointer

Definition at line 242 of file state.h.

unicoap_memo_of_event()

static unicoap_memo_t * unicoap_memo_of_event ( event_t * event )

inlinestatic

Returns memo of scheduled event.

Parameters

[in]

event

Superclass event

Returns

Common memo state object

Definition at line 265 of file state.h.

unicoap_memo_of_timeout()

static unicoap_memo_t * unicoap_memo_of_timeout ( unicoap_scheduled_event_t * timeout )

inlinestatic

Returns memo of scheduled event.

Parameters

[in]

timeout

Scheduled timeout event

Returns

Common memo state object

Definition at line 256 of file state.h.

unicoap_messaging_notify()

void unicoap_messaging_notify	(	void *	state,
		unicoap_layer_notification_t	type,
		void *	arg,
		unicoap_proto_t	proto )

Informs messaging layer of event.

Parameters

	state	Messaging-layer state reference
	type	Event type
[in]	arg	Optional opaque state object in this layer the notification relates to.
	proto	The protocol number for the underlying CoAP driver

Usually called from exchange layer.

unicoap_scheduled_event_name()

static const char * unicoap_scheduled_event_name ( unicoap_scheduled_event_t * event )

inlinestatic

Name of scheduled event.

Returns

Null-terminated string when DEVELHELP is turned on, NULL otherwise

Parameters

event

Scheduled event

Definition at line 105 of file state.h.

unicoap_scheduled_event_of_event()

static unicoap_scheduled_event_t * unicoap_scheduled_event_of_event ( event_t * event )

inlinestatic

Returns scheduled event subclass of event.

Parameters

[in]

event

Superclass event

Returns

Scheduled event

Definition at line 119 of file state.h.