Attribute Store Public Interface

Public functions from the attribute store. It allows other components to manipulate the Attribute Store tree. and register callbacks for Attribute Store updates. More...

Modules
	Attribute Store Configuration
	Allows to configure how the attribute store behaves.
	Attribute Store Type registration
	Type registration to the Attribute Store.
	Internal configuration functions
	Internal functions for the attribute store configuration.

Classes
struct	attribute_changed_event
	structure that contains information about the current state of a given node in the attribute store. More...

Macros
#define	ATTRIBUTE_STORE_MAXIMUM_VALUE_LENGTH   DATASTORE_ATTRIBUTE_VALUE_SIZE
	Maximum length for a value associated to an attribute. More...
#define	ATTRIBUTE_STORE_INVALID_NODE   (attribute_store_node_t)0
	Special attribute_store_node_t value indicating that it does not exist. More...

Typedefs
typedef datastore_attribute_id_t	attribute_store_node_t
	Handle to identify attribute store nodes. More...
typedef void(*	attribute_store_node_changed_callback_t) (attribute_store_node_t, attribute_store_change_t)
	Attribute store callback type for tree node updates. More...
typedef void(*	attribute_store_node_touch_callback_t) (attribute_store_node_t)
	Attribute store callback type for "touch" events. More...
typedef void(*	attribute_store_node_delete_callback_t) (attribute_store_node_t)
	Attribute store callback type for deletion events. More...
typedef struct attribute_changed_event	attribute_changed_event_t
	structure that contains information about the current state of a given node in the attribute store. More...
typedef void(*	attribute_store_node_update_callback_t) (attribute_changed_event_t *event_data)
	Attribute store callback type for tree node updates. More...

Enumerations
enum	attribute_store_change_t { ATTRIBUTE_CREATED , ATTRIBUTE_UPDATED , ATTRIBUTE_DELETED }
	Attribute Store type to indicate the modification type that triggered a callback. More...
enum	attribute_store_node_value_state_t { REPORTED_ATTRIBUTE , DESIRED_ATTRIBUTE , DESIRED_OR_REPORTED_ATTRIBUTE }
	This is the value state of a value. More...

Functions
attribute_store_node_t	attribute_store_get_root ()
	Retrieve the root node of the tree. More...
attribute_store_node_t	attribute_store_add_node (attribute_store_type_t type, attribute_store_node_t parent_node)
	Add a new node in the current attribute store. More...
sl_status_t	attribute_store_delete_node (attribute_store_node_t node)
	Delete a node and all its children from the attribute store. More...
attribute_store_node_t	attribute_store_get_node_parent (attribute_store_node_t node)
	Get the node handle of the parent of a node. More...
attribute_store_node_t	attribute_store_get_first_parent_with_type (attribute_store_node_t node, attribute_store_type_t parent_type)
	Traverse up the tree from a node and finds the first parent with a given type. More...
sl_status_t	attribute_store_set_node_attribute_value (attribute_store_node_t node, attribute_store_node_value_state_t value_state, const uint8_t *value, uint8_t value_size)
	Set the attribute value of a node in the current attribute store tree. More...
sl_status_t	attribute_store_get_node_attribute_value (attribute_store_node_t node, attribute_store_node_value_state_t value_state, uint8_t *value, uint8_t *value_size)
	Get the attribute value of a node. More...
attribute_store_type_t	attribute_store_get_node_type (attribute_store_node_t node)
	Get the type of a node. More...
attribute_store_node_t	attribute_store_get_node_child (attribute_store_node_t node, uint32_t child_index)
	Get the node handle of a child of a node. More...
size_t	attribute_store_get_node_child_count (attribute_store_node_t node)
	Get the number of children of the given node. More...
size_t	attribute_store_get_node_child_count_by_type (attribute_store_node_t node, attribute_store_type_t child_type)
	Get the number of children of a certain type for a node. More...
size_t	attribute_store_get_node_total_child_count (attribute_store_node_t node)
	Get the number of total children of the given node. More...
attribute_store_node_t	attribute_store_get_node_child_by_type (attribute_store_node_t node, attribute_store_type_t child_type, uint32_t child_index)
	Get the node handle of a child of a node with a certain type. More...
static attribute_store_node_t	attribute_store_get_first_child_by_type (attribute_store_node_t node, attribute_store_type_t child_type)
attribute_store_node_t	attribute_store_get_node_child_by_value (attribute_store_node_t node, attribute_store_type_t child_type, attribute_store_node_value_state_t value_state, const uint8_t *value, uint8_t value_size, uint32_t child_index)
	Get the node handle of a child of a node with a certain type and value. More...
sl_status_t	attribute_store_register_callback (attribute_store_node_update_callback_t callback_function)
	Register a callback function to any node change. More...
sl_status_t	attribute_store_register_touch_notification_callback (attribute_store_node_touch_callback_t callback_function)
	Register a callback function that will be called on touch events. More...
sl_status_t	attribute_store_register_delete_callback (attribute_store_node_delete_callback_t callback_function)
	Register a callback function that will be called when an attribute is deleted. More...
sl_status_t	attribute_store_register_callback_by_type (attribute_store_node_changed_callback_t callback_function, attribute_store_type_t type)
	Register a callback function to any node with a given type. More...
sl_status_t	attribute_store_register_callback_by_type_and_state (attribute_store_node_changed_callback_t callback_function, attribute_store_type_t type, attribute_store_node_value_state_t value_state)
	Register a callback function to any node with a given type for a given value_state update. More...
bool	attribute_store_node_exists (attribute_store_node_t node)
	Verify whether a node is in the Attribute Store. More...
bool	attribute_store_is_node_a_child (attribute_store_node_t node, attribute_store_node_t possible_parent)
	Verify whether a node is a child of another node. More...
uint8_t	attribute_store_get_node_value_size (attribute_store_node_t node, attribute_store_node_value_state_t value_state)
	Checks the size of the REPORTED or DESIRED value for a node. More...
sl_status_t	attribute_store_refresh_node_and_children_callbacks (attribute_store_node_t node)
	Invoking update of callbacks for the given node and all children nodes. More...
void	attribute_store_log (void)
	Log the content of the Attribute Store tree using Unify Logging system. More...
void	attribute_store_log_node (attribute_store_node_t node, bool log_children)
	Log the content of the Attribute Store tree using Unify Logging system from a given node. More...

Detailed Description

Public functions from the attribute store. It allows other components to manipulate the Attribute Store tree. and register callbacks for Attribute Store updates.

Macro Definition Documentation

ATTRIBUTE_STORE_INVALID_NODE

#define ATTRIBUTE_STORE_INVALID_NODE   (attribute_store_node_t)0

Special attribute_store_node_t value indicating that it does not exist.

ATTRIBUTE_STORE_MAXIMUM_VALUE_LENGTH

#define ATTRIBUTE_STORE_MAXIMUM_VALUE_LENGTH   DATASTORE_ATTRIBUTE_VALUE_SIZE

Maximum length for a value associated to an attribute.

Typedef Documentation

attribute_changed_event_t

typedef struct attribute_changed_event attribute_changed_event_t

structure that contains information about the current state of a given node in the attribute store.

attribute_store_node_changed_callback_t

typedef void(* attribute_store_node_changed_callback_t) (attribute_store_node_t, attribute_store_change_t)

Attribute store callback type for tree node updates.

attribute_store_node_delete_callback_t

typedef void(* attribute_store_node_delete_callback_t) (attribute_store_node_t)

Attribute store callback type for deletion events.

attribute_store_node_t

typedef datastore_attribute_id_t attribute_store_node_t

Handle to identify attribute store nodes.

attribute_store_node_touch_callback_t

typedef void(* attribute_store_node_touch_callback_t) (attribute_store_node_t)

Attribute store callback type for "touch" events.

attribute_store_node_update_callback_t

typedef void(* attribute_store_node_update_callback_t) (attribute_changed_event_t *event_data)

Attribute store callback type for tree node updates.

Enumeration Type Documentation

attribute_store_change_t

enum attribute_store_change_t

Attribute Store type to indicate the modification type that triggered a callback.

Enumerator
ATTRIBUTE_CREATED
ATTRIBUTE_UPDATED
ATTRIBUTE_DELETED

attribute_store_node_value_state_t

enum attribute_store_node_value_state_t

This is the value state of a value.

Enumerator
REPORTED_ATTRIBUTE	This is the value reported by the node or actual value.
DESIRED_ATTRIBUTE	This is the value to be applied to the node.
DESIRED_OR_REPORTED_ATTRIBUTE	Retrieve the desired value if it exists if not then provide the reported attribute only used for readding.

Function Documentation

attribute_store_add_node()

attribute_store_node_t attribute_store_add_node	(	attribute_store_type_t	type,
		attribute_store_node_t	parent_node
	)

Add a new node in the current attribute store.

Parameters

type	The type to assign to the new node. MUST be different than ATTRIBUTE_STORE_INVALID_ATTRIBUTE_TYPE
parent_node	Parent node for the node to add.

Returns

attribute_store_node_t handle for the newly created node

ATTRIBUTE_STORE_INVALID_NODE in case of error

attribute_store_delete_node()

sl_status_t attribute_store_delete_node

(

attribute_store_node_t

node

)

Delete a node and all its children from the attribute store.

Parameters

node	The identifier of the node to delete.

Note

The root node cannot be deleted. If passed as argument, only its children will be deleted.

Returns

SL_STATUS_OK if the node and its children were deleted successfully or if it was not in the attribute store anyway

SL_STATUS_FAIL if an error happened.

SL_STATUS_NOT_INITIALIZED if the attribute store is not initialized

attribute_store_get_first_child_by_type()

static attribute_store_node_t attribute_store_get_first_child_by_type ( attribute_store_node_t  node, attribute_store_type_t  child_type  )

inlinestatic

attribute_store_get_first_parent_with_type()

attribute_store_node_t attribute_store_get_first_parent_with_type	(	attribute_store_node_t	node,
		attribute_store_type_t	parent_type
	)

Traverse up the tree from a node and finds the first parent with a given type.

Parameters

node	The Attribute Store node for which the parents will be searched for the given type
parent_type	The type of the parent that we search

Returns

ATTRIBUTE_STORE_INVALID_NODE If the node has no (distant) parent with the given type.

attribute_store_node_t handle for the parent node on success

attribute_store_get_node_attribute_value()

sl_status_t attribute_store_get_node_attribute_value	(	attribute_store_node_t	node,
		attribute_store_node_value_state_t	value_state,
		uint8_t *	value,
		uint8_t *	value_size
	)

Get the attribute value of a node.

Parameters

node	The node handle of the node for which attribute value is to be retrieved
value_state	The attribute_store_node_value_state_t value state to retrieve from the node. (Desired or Reported)
value	A uint8_t pointer to an array for which the value/value state will be written to. This array should be able to contain 255 bytes.
value_size	Pointer to an uint8_t variable where the size of the value/payload written to the value pointer will be written.

Returns

SL_STATUS_OK If the attribute value of the node was successfully written to the pointers value/value_size

SL_STATUS_FAIL If an error occurred

SL_STATUS_NOT_INITIALIZED if the attribute store is not initialized properly

attribute_store_get_node_child()

attribute_store_node_t attribute_store_get_node_child	(	attribute_store_node_t	node,
		uint32_t	child_index
	)

Get the node handle of a child of a node.

Parameters

node	The tree handle of the node for which the child handle will be returned
child_index	Value to indicate which child to find. 0 will match the first child, 1 the second child, etc.

Returns

attribute_store_node_t handle for the child node at the indicated index.

ATTRIBUTE_STORE_INVALID_NODE If the child index does not exist (i.e. there are less children than the child index). or if node itself does not exist

attribute_store_get_node_child_by_type()

attribute_store_node_t attribute_store_get_node_child_by_type	(	attribute_store_node_t	node,
		attribute_store_type_t	child_type,
		uint32_t	child_index
	)

Get the node handle of a child of a node with a certain type.

Parameters

node	The node handle of the node for which the child identifier will be written
child_type	The attribute store type of the child.
child_index	Value to indicate which child to find. 0 will match the first child (with that type), 1 the second child (with that type), etc.

Returns

attribute_store_node_t handle for the child node at the indicated index with the type.

ATTRIBUTE_STORE_INVALID_NODE if the child index does not exist. (i.e. there are less children with that type than the child index). or if node itself does not exist

attribute_store_get_node_child_by_value()

attribute_store_node_t attribute_store_get_node_child_by_value	(	attribute_store_node_t	node,
		attribute_store_type_t	child_type,
		attribute_store_node_value_state_t	value_state,
		const uint8_t *	value,
		uint8_t	value_size,
		uint32_t	child_index
	)

Get the node handle of a child of a node with a certain type and value.

Parameters

node	The node handle of the node for which the child identifier will be written
child_type	The attribute type of the child.
value_state	The attribute_store_node_value_state_t value state to compare for the child. (Desired or Reported)
value	A uint8_t pointer to an array for which the value/value state will be compared.
value_size	The number of bytes to compare from the value pointer.
child_index	Value to indicate which child to find. 0 will match the first child (with that type and value), 1 the second child (with that type and value), etc.

Returns

attribute_store_node_t handle for the child node at the indicated index with the type and value.

ATTRIBUTE_STORE_INVALID_NODE if the child index does not exist. (i.e. there are less children with that type and value than the child index). or if node itself does not exist

attribute_store_get_node_child_count()

size_t attribute_store_get_node_child_count

(

attribute_store_node_t

node

)

Get the number of children of the given node.

Parameters

node	The tree handle of the node for which the child handle will be returned

Returns

int Number of children

attribute_store_get_node_child_count_by_type()

size_t attribute_store_get_node_child_count_by_type	(	attribute_store_node_t	node,
		attribute_store_type_t	child_type
	)

Get the number of children of a certain type for a node.

Parameters

node	The tree handle of the node for which the child with a type will be returned
child_type	The attribute type of the children.

Returns

int Number of children that have the type

attribute_store_get_node_parent()

attribute_store_node_t attribute_store_get_node_parent

(

attribute_store_node_t

node

)

Get the node handle of the parent of a node.

Parameters

node	The tree handle of the node for which the parent identifier will be returned

Returns

ATTRIBUTE_STORE_INVALID_NODE If the node has no parent or does not exist.

attribute_store_node_t handle for the parent node on success

attribute_store_get_node_total_child_count()

size_t attribute_store_get_node_total_child_count

(

attribute_store_node_t

node

)

Get the number of total children of the given node.

Parameters

node	The tree handle of the node for which the child handle will be returned

Returns

int Total number of children

attribute_store_get_node_type()

attribute_store_type_t attribute_store_get_node_type

(

attribute_store_node_t

node

)

Get the type of a node.

Parameters

node	The node handle of the node for which the type is to be returned

Returns

attribute_store_type_t The assigned type for the node

ATTRIBUTE_STORE_INVALID_ATTRIBUTE_TYPE if the node does not exist

attribute_store_get_node_value_size()

uint8_t attribute_store_get_node_value_size	(	attribute_store_node_t	node,
		attribute_store_node_value_state_t	value_state
	)

Checks the size of the REPORTED or DESIRED value for a node.

Parameters

node	The identifier of the node to check one of its value sizes
value_state	The attribute_store_node_value_state_t value state to check. (Desired or Reported)

Returns

a size if the node exists, 0 if the node does not exist

attribute_store_get_root()

attribute_store_node_t attribute_store_get_root

(

)

Retrieve the root node of the tree.

Returns

ATTRIBUTE_STORE_INVALID_NODE If the tree is not initialized, or there is no root node

attribute_store_node_t handle for the root node

attribute_store_is_node_a_child()

bool attribute_store_is_node_a_child	(	attribute_store_node_t	node,
		attribute_store_node_t	possible_parent
	)

Verify whether a node is a child of another node.

Parameters

node	The identifier of the node to verify if it is a child of the possible parent node.
possible_parent	The identifier of the node to verify if it is a parent of the node

Returns

true if the node is located under the possible parent node in the Attribute Store, false otherwise

attribute_store_log()

void attribute_store_log

(

void

)

Log the content of the Attribute Store tree using Unify Logging system.

attribute_store_log_node()

void attribute_store_log_node	(	attribute_store_node_t	node,
		bool	log_children
	)

Log the content of the Attribute Store tree using Unify Logging system from a given node.

Parameters

node	The node handle of the node for which the tree will be printed out.
log_children	bool value indicating if children should be printed out as well.

attribute_store_node_exists()

bool attribute_store_node_exists

(

attribute_store_node_t

node

)

Verify whether a node is in the Attribute Store.

Parameters

node	The identifier of the node to verify if it is present in the Attribute Store

Returns

true if the Node ID is in the Attribute Store

false if the Node ID is in the Attribute Store

attribute_store_refresh_node_and_children_callbacks()

sl_status_t attribute_store_refresh_node_and_children_callbacks

(

attribute_store_node_t

node

)

Invoking update of callbacks for the given node and all children nodes.

WARNING: Callbacks registered by DESIRED_ATTRIBUTE or DESIRED_OR_REPORTED_ATTRIBUTE will not be invoked.

Parameters

node	The identifier of the node to update and all its children

Returns

SL_STATUS_OK if all nodes callbacks was successfully updated

SL_STATUS_FAIL if invoking update callbacks on any node fails

attribute_store_register_callback()

sl_status_t attribute_store_register_callback

(

attribute_store_node_update_callback_t

callback_function

)

Register a callback function to any node change.

WARNING: Do not use this function, unless you are a component that really wants to know about almost all updates in the attribute store. See attribute_store_register_callback_by_type and attribute_store_register_callback_by_type_and_state

Parameters

callback_function

The function to invoke when the node's value is updated.

Returns

SL_STATUS_OK If the callback was registered successfully.

attribute_store_register_callback_by_type()

sl_status_t attribute_store_register_callback_by_type	(	attribute_store_node_changed_callback_t	callback_function,
		attribute_store_type_t	type
	)

Register a callback function to any node with a given type.

Parameters

callback_function	The function to invoke when the node's value is updated.
type	The attribute node type for which a callback will be registered.

Returns

SL_STATUS_OK If the callback was registered successfully.

attribute_store_register_callback_by_type_and_state()

sl_status_t attribute_store_register_callback_by_type_and_state	(	attribute_store_node_changed_callback_t	callback_function,
		attribute_store_type_t	type,
		attribute_store_node_value_state_t	value_state
	)

Register a callback function to any node with a given type for a given value_state update.

Parameters

callback_function	The function to invoke when the node's value is updated.
type	The attribute node type for which a callback will be registered.
value_state	The value-state that will trigger a callback when it's modified.

Returns

SL_STATUS_OK If the callback was registered successfully.

attribute_store_register_delete_callback()

sl_status_t attribute_store_register_delete_callback

(

attribute_store_node_delete_callback_t

callback_function

)

Register a callback function that will be called when an attribute is deleted.

Parameters

callback_function

The function to invoke when a node is deleted

Returns

SL_STATUS_OK If the callback was registered successfully.

attribute_store_register_touch_notification_callback()

sl_status_t attribute_store_register_touch_notification_callback

(

attribute_store_node_touch_callback_t

callback_function

)

Register a callback function that will be called on touch events.

NOTE: Use this function only if necessary, as it may trigger a lot of touched callbacks

Parameters

callback_function

The function to invoke when a node desired or reported value is touched.

Returns

SL_STATUS_OK If the callback was registered successfully.

attribute_store_set_node_attribute_value()

sl_status_t attribute_store_set_node_attribute_value	(	attribute_store_node_t	node,
		attribute_store_node_value_state_t	value_state,
		const uint8_t *	value,
		uint8_t	value_size
	)

Set the attribute value of a node in the current attribute store tree.

Parameters

node	The node handle for which the value must be updated.
value_state	The attribute_store_node_value_state_t value state to write for the node. (Desired or Reported)
value	A uint8_t pointer to an array containing the data to be written for the node. This array may contain up to 255 bytes.
value_size	The number of bytes to read from the value pointer.

Returns

SL_STATUS_OK If the tree node value has been set correctly.

SL_STATUS_FAIL If the value state is not understood.

SL_STATUS_NOT_INITIALIZED if the attribute store is not initialized properly