Resource Observation

API for interfacing with the observe handling (RFC7641) More...

Collaboration diagram for Resource Observation:

Macros
#define	COAP_OBSERVE_ESTABLISH   0
	The value COAP_OBSERVE_ESTABLISH in a GET/FETCH request option COAP_OPTION_OBSERVE indicates a new observe relationship for (sender address, token) is requested.
#define	COAP_OBSERVE_CANCEL   1
	The value COAP_OBSERVE_CANCEL in a GET/FETCH request option COAP_OPTION_OBSERVE indicates that the observe relationship for (sender address, token) must be cancelled.

Typedefs
typedef int(*	coap_observe_added_t) (coap_session_t *session, coap_subscription_t *observe_key, coap_proto_t e_proto, coap_address_t *e_listen_addr, coap_addr_tuple_t *s_addr_info, coap_bin_const_t *raw_packet, coap_bin_const_t *oscore_info, void *user_data)
	Callback handler definition called when a new observe has been set up, as defined in coap_persist_track_funcs().
typedef int(*	coap_observe_deleted_t) (coap_session_t *session, coap_subscription_t *observe_key, void *user_data)
	Callback handler definition called when an observe is being removed, as defined in coap_persist_track_funcs().
typedef int(*	coap_track_observe_value_t) (coap_context_t *context, coap_str_const_t *resource_name, uint32_t observe_num, void *user_data)
	Callback handler definition called when an observe unsolicited response is being sent, as defined in coap_persist_track_funcs().
typedef int(*	coap_dyn_resource_added_t) (coap_session_t *session, coap_str_const_t *resource_name, coap_bin_const_t *raw_packet, void *user_data)
	Callback handler definition called when a dynamic resource is getting created, as defined in coap_persist_track_funcs().
typedef int(*	coap_resource_deleted_t) (coap_context_t *context, coap_str_const_t *resource_name, void *user_data)
	Callback handler definition called when resource is removed, as defined in coap_persist_track_funcs().

Functions
void	coap_resource_set_get_observable (coap_resource_t *resource, int mode)
	Set whether a resource is observable.
COAP_API int	coap_resource_notify_observers (coap_resource_t *resource, const coap_string_t *query)
	Initiate the sending of an Observe packet for all observers of resource, optionally matching query if not NULL.
COAP_API void	coap_check_notify (coap_context_t *context)
	Checks all known resources to see if they are dirty and then notifies subscribed observers.
void	coap_persist_track_funcs (coap_context_t *context, coap_observe_added_t observe_added, coap_observe_deleted_t observe_deleted, coap_track_observe_value_t track_observe_value, coap_dyn_resource_added_t dyn_resource_added, coap_resource_deleted_t resource_deleted, uint32_t save_freq, void *user_data)
	Set up callbacks to handle persist tracking so on a coap-server inadvertent restart, existing observe subscriptions can continue.
COAP_API coap_subscription_t *	coap_persist_observe_add (coap_context_t *context, coap_proto_t e_proto, const coap_address_t *e_listen_addr, const coap_addr_tuple_t *s_addr_info, const coap_bin_const_t *raw_packet, const coap_bin_const_t *oscore_info)
	Set up an active subscription for an observe that was previously active over a coap-server inadvertant restart.
COAP_API int	coap_persist_startup (coap_context_t *context, const char *dyn_resource_save_file, const char *observe_save_file, const char *obs_cnt_save_file, uint32_t save_freq)
	Start up persist tracking using the libcoap module.
COAP_API void	coap_persist_stop (coap_context_t *context)
	Stop tracking persist information, leaving the current persist information in the files defined in coap_persist_startup().
void	coap_persist_set_observe_num (coap_resource_t *resource, uint32_t observe_num)
	Sets the current observe number value.
COAP_API int	coap_cancel_observe (coap_session_t *session, coap_binary_t *token, coap_pdu_type_t message_type)
	Cancel an observe that is being tracked by the client large receive logic.

Detailed Description

API for interfacing with the observe handling (RFC7641)

Macro Definition Documentation

COAP_OBSERVE_CANCEL

#define COAP_OBSERVE_CANCEL   1

The value COAP_OBSERVE_CANCEL in a GET/FETCH request option COAP_OPTION_OBSERVE indicates that the observe relationship for (sender address, token) must be cancelled.

Definition at line 40 of file coap_subscribe.h.

COAP_OBSERVE_ESTABLISH

#define COAP_OBSERVE_ESTABLISH   0

The value COAP_OBSERVE_ESTABLISH in a GET/FETCH request option COAP_OPTION_OBSERVE indicates a new observe relationship for (sender address, token) is requested.

Definition at line 33 of file coap_subscribe.h.

Typedef Documentation

coap_dyn_resource_added_t

typedef int(* coap_dyn_resource_added_t) (coap_session_t *session, coap_str_const_t *resource_name, coap_bin_const_t *raw_packet, void *user_data)

Callback handler definition called when a dynamic resource is getting created, as defined in coap_persist_track_funcs().

Parameters

session	The current CoAP session.
resource_name	The uri path name of the resource.
raw_packet	L7 packet as seen on the wire (could be concatenated if Block1 PUT/POST/FETCH used to create resource).
user_data	Application provided information from coap_persist_track_funcs().

Returns

1 if success else 0.

Definition at line 149 of file coap_subscribe.h.

coap_observe_added_t

typedef int(* coap_observe_added_t) (coap_session_t *session, coap_subscription_t *observe_key, coap_proto_t e_proto, coap_address_t *e_listen_addr, coap_addr_tuple_t *s_addr_info, coap_bin_const_t *raw_packet, coap_bin_const_t *oscore_info, void *user_data)

Callback handler definition called when a new observe has been set up, as defined in coap_persist_track_funcs().

Parameters

session	The current session.
observe_key	The pointer to the subscription.
e_proto	The CoAP protocol in use for the session / endpoint.
e_listen_addr	The IP/port that the endpoint is listening on.
s_addr_info	Local / Remote IP addresses. ports etc. of session.
raw_packet	L7 packet as seen on the wire (could be concatenated if Block1 FETCH is being used).
oscore_info	Has OSCORE information if OSCORE is protecting the session or NULL if OSCORE is not in use.
user_data	Application provided information from coap_persist_track_funcs().

Returns

1 if success else 0.

Definition at line 92 of file coap_subscribe.h.

coap_observe_deleted_t

typedef int(* coap_observe_deleted_t) (coap_session_t *session, coap_subscription_t *observe_key, void *user_data)

Callback handler definition called when an observe is being removed, as defined in coap_persist_track_funcs().

Parameters

session	The current session.
observe_key	The pointer to the subscription.
user_data	Application provided information from coap_persist_track_funcs().

Returns

1 if success else 0.

Definition at line 112 of file coap_subscribe.h.

coap_resource_deleted_t

typedef int(* coap_resource_deleted_t) (coap_context_t *context, coap_str_const_t *resource_name, void *user_data)

Callback handler definition called when resource is removed, as defined in coap_persist_track_funcs().

This will remove any dynamic resources that are being tracked as well as any observe value tracking.

Parameters

context	The current CoAP context.
resource_name	The uri path name of the resource.
user_data	Application provided information from coap_persist_track_funcs().

Returns

1 if success else 0.

Definition at line 168 of file coap_subscribe.h.

coap_track_observe_value_t

typedef int(* coap_track_observe_value_t) (coap_context_t *context, coap_str_const_t *resource_name, uint32_t observe_num, void *user_data)

Callback handler definition called when an observe unsolicited response is being sent, as defined in coap_persist_track_funcs().

Note: This will only get called every save_freq as defined by coap_persist_track_funcs().

Parameters

context	The current CoAP context.
resource_name	The uri path name of the resource.
observe_num	The current observe value just sent.
user_data	Application provided information from coap_persist_track_funcs().

Returns

1 if success else 0.

Definition at line 131 of file coap_subscribe.h.

Function Documentation

coap_cancel_observe()

COAP_API int coap_cancel_observe	(	coap_session_t *	session,
		coap_binary_t *	token,
		coap_pdu_type_t	message_type
	)

Cancel an observe that is being tracked by the client large receive logic.

(coap_context_set_block_mode() has to be called) This will trigger the sending of an observe cancel pdu to the server.

Parameters

session	The session that is being used for the observe.
token	The original token used to initiate the observation.
message_type	The COAP_MESSAGE_ type (NON or CON) to send the observe cancel pdu as.

Returns

1 if observe cancel transmission initiation is successful, else 0.

coap_check_notify()

COAP_API void coap_check_notify

(

coap_context_t *

context

)

Checks all known resources to see if they are dirty and then notifies subscribed observers.

Parameters

context

The context to check for dirty resources.

coap_persist_observe_add()

COAP_API coap_subscription_t * coap_persist_observe_add	(	coap_context_t *	context,
		coap_proto_t	e_proto,
		const coap_address_t *	e_listen_addr,
		const coap_addr_tuple_t *	s_addr_info,
		const coap_bin_const_t *	raw_packet,
		const coap_bin_const_t *	oscore_info
	)

Set up an active subscription for an observe that was previously active over a coap-server inadvertant restart.

Only UDP sessions currently supported.

Parameters

context	The context that the session is to be associated with.
e_proto	The CoAP protocol in use for the session / endpoint.
e_listen_addr	The IP/port that the endpoint is listening on.
s_addr_info	Local / Remote IP addresses. ports etc. of previous session.
raw_packet	L7 packet as seen on the wire (could be concatenated if Block1 FETCH is being used).
oscore_info	Has OSCORE information if OSCORE is protecting the session or NULL if OSCORE is not in use.

Returns

ptr to subscription if success else NULL.

coap_persist_set_observe_num()

void coap_persist_set_observe_num	(	coap_resource_t *	resource,
		uint32_t	observe_num
	)

Sets the current observe number value.

Parameters

resource	The resource to update.
observe_num	The value to set the observe number to.

coap_persist_startup()

COAP_API int coap_persist_startup	(	coap_context_t *	context,
		const char *	dyn_resource_save_file,
		const char *	observe_save_file,
		const char *	obs_cnt_save_file,
		uint32_t	save_freq
	)

Start up persist tracking using the libcoap module.

If the files already exist with saved data, then this information is used in building back up the persist information.

Parameters

context	The current CoAP context.
dyn_resource_save_file	File where dynamically created resource information is stored or NULL if not required.
observe_save_file	File where observe information is stored or NULL if not required.
obs_cnt_save_file	File where resource observe counter information is stored or NULL if not required.
save_freq	Frequency of change of observe value for calling the save observe counter logic.

Returns

1 if success else 0.

coap_persist_stop()

COAP_API void coap_persist_stop

(

coap_context_t *

context

)

Stop tracking persist information, leaving the current persist information in the files defined in coap_persist_startup().

It is then safe to call coap_free_context() to close the application down cleanly.

Alternatively, if coap_persist_track_funcs() was called, then this will disable all the callbacks, as well as making sure that no 4.04 is sent out for any active observe subscriptions when the resource is deleted after subsequently calling coap_free_context().

Parameters

context

The context that tracking information is to be stopped on.

coap_persist_track_funcs()

void coap_persist_track_funcs	(	coap_context_t *	context,
		coap_observe_added_t	observe_added,
		coap_observe_deleted_t	observe_deleted,
		coap_track_observe_value_t	track_observe_value,
		coap_dyn_resource_added_t	dyn_resource_added,
		coap_resource_deleted_t	resource_deleted,
		uint32_t	save_freq,
		void *	user_data
	)

Set up callbacks to handle persist tracking so on a coap-server inadvertent restart, existing observe subscriptions can continue.

Parameters

context	The current CoAP context.
observe_added	Called when a new observe subscription is set up.
observe_deleted	Called when a observe subscription is de-registered.
track_observe_value	Called every save_freq so current observe value can be tracked.
dyn_resource_added	Called whan a dynamic resource is created from the 'unknown' resource for tracking.
resource_deleted	Called when a resource is removed.
save_freq	Frequency of change of observe value for calling save_observe_value
user_data	App defined data (can be NULL) passed into various callbacks.

coap_resource_notify_observers()

COAP_API int coap_resource_notify_observers	(	coap_resource_t *	resource,
		const coap_string_t *	query
	)

Initiate the sending of an Observe packet for all observers of resource, optionally matching query if not NULL.

Parameters

resource	The CoAP resource to use.
query	The Query to match against or NULL

Returns

1 if the Observe has been triggered, 0 otherwise.

coap_resource_set_get_observable()

void coap_resource_set_get_observable	(	coap_resource_t *	resource,
		int	mode
	)

Set whether a resource is observable.

If the resource is observable and the client has set the COAP_OPTION_OBSERVE in a request packet, then whenever the state of the resource changes (a call to coap_resource_trigger_observe()), an Observer response will get sent.

Parameters

resource	The CoAP resource to use.
mode	1 if Observable is to be set, 0 otherwise.