le_cfg_interface.h File Reference

#include "legato.h"

Go to the source code of this file.

Typedefs
typedef struct le_cfg_Iterator *	le_cfg_IteratorRef_t
typedef struct le_cfg_ChangeHandler *	le_cfg_ChangeHandlerRef_t
typedef void(*	le_cfg_ChangeHandlerFunc_t )(void *contextPtr)

Enumerations
enum	le_cfg_nodeType_t {   LE_CFG_TYPE_EMPTY, LE_CFG_TYPE_STRING, LE_CFG_TYPE_BOOL, LE_CFG_TYPE_INT,   LE_CFG_TYPE_FLOAT, LE_CFG_TYPE_STEM, LE_CFG_TYPE_DOESNT_EXIST }

Functions
void	le_cfg_StartClient (const char *serviceInstanceName)
void	le_cfg_StopClient (void)
le_cfg_IteratorRef_t	le_cfg_CreateReadTxn (const char *basePath)
le_cfg_IteratorRef_t	le_cfg_CreateWriteTxn (const char *basePath)
void	le_cfg_CommitTxn (le_cfg_IteratorRef_t iteratorRef)
void	le_cfg_CancelTxn (le_cfg_IteratorRef_t iteratorRef)
void	le_cfg_GoToNode (le_cfg_IteratorRef_t iteratorRef, const char *newPath)
le_result_t	le_cfg_GoToParent (le_cfg_IteratorRef_t iteratorRef)
le_result_t	le_cfg_GoToFirstChild (le_cfg_IteratorRef_t iteratorRef)
le_result_t	le_cfg_GoToNextSibling (le_cfg_IteratorRef_t iteratorRef)
le_result_t	le_cfg_GetPath (le_cfg_IteratorRef_t iteratorRef, const char *path, char *pathBuffer, size_t pathBufferNumElements)
le_cfg_nodeType_t	le_cfg_GetNodeType (le_cfg_IteratorRef_t iteratorRef, const char *path)
le_result_t	le_cfg_GetNodeName (le_cfg_IteratorRef_t iteratorRef, const char *path, char *name, size_t nameNumElements)
le_result_t	le_cfg_SetNodeName (le_cfg_IteratorRef_t iteratorRef, const char *path, const char *name)
le_cfg_ChangeHandlerRef_t	le_cfg_AddChangeHandler (const char *newPath, le_cfg_ChangeHandlerFunc_t handlerPtr, void *contextPtr)
void	le_cfg_RemoveChangeHandler (le_cfg_ChangeHandlerRef_t addHandlerRef)
void	le_cfg_DeleteNode (le_cfg_IteratorRef_t iteratorRef, const char *path)
bool	le_cfg_IsEmpty (le_cfg_IteratorRef_t iteratorRef, const char *path)
void	le_cfg_SetEmpty (le_cfg_IteratorRef_t iteratorRef, const char *path)
bool	le_cfg_NodeExists (le_cfg_IteratorRef_t iteratorRef, const char *path)
le_result_t	le_cfg_GetString (le_cfg_IteratorRef_t iteratorRef, const char *path, char *value, size_t valueNumElements, const char *defaultValue)
void	le_cfg_SetString (le_cfg_IteratorRef_t iteratorRef, const char *path, const char *value)
int32_t	le_cfg_GetInt (le_cfg_IteratorRef_t iteratorRef, const char *path, int32_t defaultValue)
void	le_cfg_SetInt (le_cfg_IteratorRef_t iteratorRef, const char *path, int32_t value)
double	le_cfg_GetFloat (le_cfg_IteratorRef_t iteratorRef, const char *path, double defaultValue)
void	le_cfg_SetFloat (le_cfg_IteratorRef_t iteratorRef, const char *path, double value)
bool	le_cfg_GetBool (le_cfg_IteratorRef_t iteratorRef, const char *path, bool defaultValue)
void	le_cfg_SetBool (le_cfg_IteratorRef_t iteratorRef, const char *path, bool value)
void	le_cfg_QuickDeleteNode (const char *path)
void	le_cfg_QuickSetEmpty (const char *path)
le_result_t	le_cfg_QuickGetString (const char *path, char *value, size_t valueNumElements, const char *defaultValue)
void	le_cfg_QuickSetString (const char *path, const char *value)
int32_t	le_cfg_QuickGetInt (const char *path, int32_t defaultValue)
void	le_cfg_QuickSetInt (const char *path, int32_t value)
double	le_cfg_QuickGetFloat (const char *path, double defaultValue)
void	le_cfg_QuickSetFloat (const char *path, double value)
bool	le_cfg_QuickGetBool (const char *path, bool defaultValue)
void	le_cfg_QuickSetBool (const char *path, bool value)

Detailed Description

Configuration Tree API

Copyright (C) Sierra Wireless, Inc. 2014. All rights reserved. Use of this work is subject to license.

Typedef Documentation

typedef void(* le_cfg_ChangeHandlerFunc_t)(void *contextPtr)

Register a call back on a given node object. Once registered, if that node or if any of it's children are read from, written to, created or deleted, then this function will be called.

Returns

Handle to the event registration.

Parameters

contextPtr

typedef struct le_cfg_ChangeHandler* le_cfg_ChangeHandlerRef_t

Reference type for le_cfg_ChangeHandler handler ADD/REMOVE functions

Enumeration Type Documentation

enum le_cfg_nodeType_t

Enumerator
LE_CFG_TYPE_EMPTY	A node with no value.
LE_CFG_TYPE_STRING	A string encoded as utf8.
LE_CFG_TYPE_BOOL	Boolean value.
LE_CFG_TYPE_INT	Signed 32-bit.
LE_CFG_TYPE_FLOAT	64-bit floating point value.
LE_CFG_TYPE_STEM	Non-leaf node, this node is the parent of other nodes.
LE_CFG_TYPE_DOESNT_EXIST	Node doesn't exist.

Function Documentation

le_cfg_ChangeHandlerRef_t le_cfg_AddChangeHandler	(	const char *	newPath,
		le_cfg_ChangeHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

le_cfg_ChangeHandler handler ADD function

Parameters

[in]	newPath	Path to the object to watch.
[in]	handlerPtr
[in]	contextPtr

void le_cfg_CancelTxn

(

le_cfg_IteratorRef_t

iteratorRef

)

Close and free the given iterator object. If the iterator is a write iterator, the transaction will be canceled. If the iterator is a read iterator, the transaction will be closed.

Note

: This operation will also delete the iterator object.

Parameters

[in]

iteratorRef

Iterator object to close.

void le_cfg_CommitTxn

(

le_cfg_IteratorRef_t

iteratorRef

)

Close the write iterator and commit the write transaction. This updates the config tree with all of the writes that occured using the iterator.

Note

: This operation will also delete the iterator object.

Parameters

[in]

iteratorRef

Iterator object to commit.

le_cfg_IteratorRef_t le_cfg_CreateReadTxn

(

const char *

basePath

)

Create a read transaction and open a new iterator for traversing the configuration tree.

Note

: This action creates a read lock on the given tree. Which will start a read-timeout. Once the read timeout expires, then all active read iterators on that tree will be expired and the clients killed.

: A tree transaction is global to that tree; a long held read transaction will block other users write transactions from being comitted.

Returns

This will return a newly created iterator reference.

Parameters

[in]

basePath

Path to the location to create the new iterator.

le_cfg_IteratorRef_t le_cfg_CreateWriteTxn

(

const char *

basePath

)

Create a write transaction and open a new iterator for both reading and writing.

Note

: This action creates a write transaction. If the application holds the iterator for longer than the configured write transaction timeout, the iterator will cancel the transaction. All further reads will fail to return data and all writes will be thrown away.

A tree transaction is global to that tree, so a long held write transaction will block other user's write transactions from being started. However other trees in the system will be unaffected.

Returns

This will return a newly created iterator reference.

Parameters

[in]

basePath

Path to the location to create the new iterator.

void le_cfg_DeleteNode	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path
	)

Delete the node specified by the path. If the node doesn't exist, nothing happens. All child nodes are also deleted.

If the path is empty, then the iterator's current node is deleted.

This function is only valid during a write transaction.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.

bool le_cfg_GetBool	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		bool	defaultValue
	)

Read a value from the tree as a boolean. If the node is empty or doesn't exist then the default value is returned. The default value is also returned if the node is of a different type than expected.

This function is valid for both read and write transactions.

If the path is empty, then the iterator's current node will be read.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[in]	defaultValue	The default value to use if the original can not be read.

double le_cfg_GetFloat	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		double	defaultValue
	)

Read a 64-bit floating point value from the configuration tree.

If the value is an integer then the value will be promoted to a float. Otherwise, if the underlying value is not a float or integer, the default value will be returned.

If the path is empty, then the iterator's current node will be read.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[in]	defaultValue	The default value to use if the original can not be read.

int32_t le_cfg_GetInt	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		int32_t	defaultValue
	)

Read a signed integer value from the configuration tree.

If the underlying value is not an integer, the default value will be returned instead. The default value is also returned if the node does not exist or if it's empty.

If the value is a floating point value, then it will be rounded and returned as an integer.

This function is valid for both read and write transactions.

If the path is empty, then the iterator's current node will be read.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[in]	defaultValue	The default value to use if the original can not be read.

le_result_t le_cfg_GetNodeName	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		char *	name,
		size_t	nameNumElements
	)

Get the name of the node where the iterator is currently pointing.

Returns

- LE_OK Read was completed successfully.

• LE_OVERFLOW Supplied string buffer was not large enough to hold the value.

Parameters

[in]	iteratorRef	Iterator object to use to read from the tree.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[out]	name	Read the name of the node object.
[in]	nameNumElements

le_cfg_nodeType_t le_cfg_GetNodeType	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path
	)

Get the type of node where the iterator is currently pointing.

Returns

le_cfg_nodeType_t value indicating the stored value.

Parameters

[in]	iteratorRef	Iterator object to use to read from the tree.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.

le_result_t le_cfg_GetPath	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		char *	pathBuffer,
		size_t	pathBufferNumElements
	)

Get path to the node where the iterator is currently pointed.

Assuming the following tree:

baseNode/
  childA/
    valueA
    valueB

If the iterator was currently pointing at valueA, GetPath would return the following path:

/baseNode/childA/valueA

Optionally, a path to another node can be supplied to this function. So, if the iterator is again on valueA and the relative path ".." is supplied then this function will return the following path:

/baseNode/childA/

Returns

- LE_OK - The write was completed successfully.

• LE_OVERFLOW - The supplied string buffer was not large enough to hold the value.

Parameters

[in]	iteratorRef	Iterator to move.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[out]	pathBuffer	Absolute path to the iterator's current node.
[in]	pathBufferNumElements

le_result_t le_cfg_GetString	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		char *	value,
		size_t	valueNumElements,
		const char *	defaultValue
	)

Read a string value from the configuration tree. If the value isn't a string, or if the node is empty or doesn't exist then the default value will be returned.

This function is valid for both read and write transactions.

If the path is empty, then the iterator's current node will be read.

Returns

- LE_OK - Read was completed successfully.

• LE_OVERFLOW - Supplied string buffer was not large enough to hold the value.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[out]	value	Buffer to write the value into.
[in]	valueNumElements
[in]	defaultValue	The default value to use if the original can not be read.

le_result_t le_cfg_GoToFirstChild

(

le_cfg_IteratorRef_t

iteratorRef

)

Move the iterator to the the first child of the node where the iterator is currently pointed.

For read iterators without children, this function will fail. If the iterator is a write iterator, then a new node is automatically created. If this node or newly created children of this node are not written to, then this node will not persist even if the iterator is comitted.

Returns

Return code will be one of the following values:

    - LE_OK        - Move was completed successfully.
    - LE_NOT_FOUND - The given node has no children.

Parameters

[in]

iteratorRef

Iterator object to move.

le_result_t le_cfg_GoToNextSibling

(

le_cfg_IteratorRef_t

iteratorRef

)

Jump the iterator to the next child node of the current node. Assuming the following tree:

baseNode/
  childA/
    valueA
    valueB

If the iterator is moved to the path, "/baseNode/childA/valueA". After the first GoToNextSibling the iterator will be pointing at valueB. A second call to GoToNextSibling will cause the function to return LE_NOT_FOUND.

Returns

Returns one of the following values:

    - LE_OK            - Commit was completed successfully.
    - LE_NOT_FOUND     - Iterator has reached the end of the current list of siblings.
                         Also returned if the the current node has no siblings.

Parameters

[in]

iteratorRef

Iterator to iterate.

void le_cfg_GoToNode	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	newPath
	)

Change the node that the iterator is pointing to. The path passed can be an absolute or a relative path from the iterators current location.

The target node does not need to exist. Writing a value to a non-existant node will automatically create that node and any ancestor nodes (parent, parent's parent, etc.) that also don't exist.

Parameters

[in]	iteratorRef	Iterator to move.
[in]	newPath	Absolute or relative path from the current location.

le_result_t le_cfg_GoToParent

(

le_cfg_IteratorRef_t

iteratorRef

)

Move the iterator to the parent of the node.

Returns

Return code will be one of the following values:

    - LE_OK        - Commit was completed successfully.
    - LE_NOT_FOUND - Current node is the root node: has no parent.

Parameters

[in]

iteratorRef

Iterator to move.

bool le_cfg_IsEmpty	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path
	)

Check if the given node is empty. A node is also considered empty if it doesn't yet exist. A node is also considered empty if it has no value or is a stem with no children.

If the path is empty, then the iterator's current node is queried for emptiness.

This function is valid for both read and write transactions.

Returns

A true if the node is considered empty, false if not.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.

bool le_cfg_NodeExists	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path
	)

Check to see if a given node in the configuration tree exists.

Returns

True if the specified node exists in the tree. False if not.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.

void le_cfg_QuickDeleteNode

(

const char *

path

)

Delete the node specified by the path. If the node doesn't exist, nothing happens. All child nodes are also deleted.

Parameters

[in]

path

Path to the node to delete.

bool le_cfg_QuickGetBool	(	const char *	path,
		bool	defaultValue
	)

Read a value from the tree as a boolean. If the node is empty or doesn't exist then the default value is returned. This is also true if the node is of a different type than expected.

If the value is empty or the node doesn't exist then the default value is returned instead.

Parameters

[in]	path	Path to the value to write.
[in]	defaultValue	The default value to use if the original can not be read.

double le_cfg_QuickGetFloat	(	const char *	path,
		double	defaultValue
	)

Read a 64-bit floating point value from the configuration tree. If the value is an integer, then it is promoted to a float. Otherwise, if the underlying value is not a float, or an integer the default value will be returned.

If the value is empty or the node doesn't exist then the default value is returned.

Parameters

[in]	path	Path to the value to write.
[in]	defaultValue	The default value to use if the original can not be read.

int32_t le_cfg_QuickGetInt	(	const char *	path,
		int32_t	defaultValue
	)

Read a signed integer value from the configuration tree. If the value is a floating point value, then it will be rounded and returned as an integer. Otherwise If the underlying value is not an integer or a float, the default value will be returned instead.

If the value is empty or the node doesn't exist then the default value is returned instead.

Parameters

[in]	path	Path to the value to write.
[in]	defaultValue	The default value to use if the original can not be read.

le_result_t le_cfg_QuickGetString	(	const char *	path,
		char *	value,
		size_t	valueNumElements,
		const char *	defaultValue
	)

Read a string value from the configuration tree. If the value isn't a string, or if the node is empty or doesn't exist then the default value will be returned.

Returns

- LE_OK - Commit was completed successfully.

• LE_OVERFLOW - Supplied string buffer was not large enough to hold the value.

Parameters

[in]	path	Path to read from.
[out]	value	Value read from the requested node.
[in]	valueNumElements
[in]	defaultValue	The default value to use if the original can not be read.

void le_cfg_QuickSetBool	(	const char *	path,
		bool	value
	)

Write a boolean value to the configuration tree.

Parameters

[in]	path	Path to the value to write.
[in]	value	Value to write.

void le_cfg_QuickSetEmpty

(

const char *

path

)

Make a given node empty. If the node doesn't currently exist then it is created as a new empty node.

Parameters

[in]

path

Absolute or relative path to read from.

void le_cfg_QuickSetFloat	(	const char *	path,
		double	value
	)

Write a 64-bit floating point value to the configuration tree.

Parameters

[in]	path	Path to the value to write.
[in]	value	Value to write.

void le_cfg_QuickSetInt	(	const char *	path,
		int32_t	value
	)

Write a signed integer value to the configuration tree.

Parameters

[in]	path	Path to the value to write.
[in]	value	Value to write.

void le_cfg_QuickSetString	(	const char *	path,
		const char *	value
	)

Write a string value to the configuration tree.

Parameters

[in]	path	Path to the value to write.
[in]	value	Value to write.

void le_cfg_RemoveChangeHandler

(

le_cfg_ChangeHandlerRef_t

addHandlerRef

)

le_cfg_ChangeHandler handler REMOVE function

Parameters

[in]

addHandlerRef

void le_cfg_SetBool	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		bool	value
	)

Write a boolean value to the configuration tree. This function is only valid during a write transaction.

If the path is empty, then the iterator's current node will be set.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[in]	value	Value to write.

void le_cfg_SetEmpty	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path
	)

Clear out the nodes's value. If it doesn't exist it will be created, but have no value.

If the path is empty, then the iterator's current node will be cleared. If the node is a stem then all children will be removed from the tree.

This function is only valid during a write transaction.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.

void le_cfg_SetFloat	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		double	value
	)

Write a 64-bit floating point value to the configuration tree. This function is only valid during a write transaction.

If the path is empty, then the iterator's current node will be set.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[in]	value	Value to write.

void le_cfg_SetInt	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		int32_t	value
	)

Write a signed integer value to the configuration tree. This function is only valid during a write transaction.

If the path is empty, then the iterator's current node will be set.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[in]	value	Value to write.

le_result_t le_cfg_SetNodeName	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		const char *	name
	)

Change the name of the node that the iterator is currently pointing at.

Returns

• LE_OK Write was completed successfully.
• LE_FORMAT_ERROR The new name included illegal characters, '/', or ':'. Or used one of the reserved names: '.', or '..'. Format error is also returned if the new name is empty.
• LE_DUPLICATE If there is another node with the new name in the same collection.

Parameters

[in]	iteratorRef	Iterator object to use to read from the tree.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[in]	name	New name for the node object.

void le_cfg_SetString	(	le_cfg_IteratorRef_t	iteratorRef,
		const char *	path,
		const char *	value
	)

Write a string value to the configuration tree. This function is only valid during a write transaction.

If the path is empty, then the iterator's current node will be set.

Parameters

[in]	iteratorRef	Iterator to use as a basis for the transaction.
[in]	path	Path to the target node. Can be an absolute path, or a path relative from the iterator's current position.
[in]	value	Value to write.

void le_cfg_StartClient

(

const char *

serviceInstanceName

)

Start the service for the client main thread

Parameters

[in]

serviceInstanceName

void le_cfg_StopClient

(

void

)

Stop the service for the current client thread