This module includes the platform abstraction for non-volatile storage of settings. More...

Classes
struct	settingBuffer
	Data structure for vectored I/O using caUtilSettingsAddVector. More...

Functions
void	caUtilSettingsInit (struct ca821x_dev aInstance, const char aApplicationName, uint32_t aNodeId)
	Performs any initialization for the settings subsystem, if necessary. More...

void	caUtilSettingsDeinit (struct ca821x_dev *aInstance)
	Performs any de-initialization for the settings subsystem, if necessary. More...

ca_error	caUtilSettingsGet (struct ca821x_dev aInstance, uint16_t aKey, int aIndex, uint8_t aValue, uint16_t *aValueLength)
	This function fetches the value of the setting identified by aKey and write it to the memory pointed to by aValue. More...

ca_error	caUtilSettingsSet (struct ca821x_dev aInstance, uint16_t aKey, const uint8_t aValue, uint16_t aValueLength)
	Sets or replaces the value of a setting. More...

ca_error	caUtilSettingsAdd (struct ca821x_dev aInstance, uint16_t aKey, const uint8_t aValue, uint16_t aValueLength)
	Adds a value to a setting This function adds the value to a setting identified by aKey, without replacing any existing values. More...

ca_error	caUtilSettingsDelete (struct ca821x_dev *aInstance, uint16_t aKey, int aIndex)
	Removes a setting from the setting store. More...

void	caUtilSettingsWipe (struct ca821x_dev aInstance, const char aApplicationName, uint32_t aNodeId)
	Removes all settings from the setting store. More...

ca_error	caUtilSettingsGetAddress (struct ca821x_dev aInstance, uint16_t aKey, int aIndex, void aValue, uint16_t aValueLength)
	Get the address at which a particular setting is stored. More...

ca_error	caUtilSettingsAddVector (struct ca821x_dev aInstance, uint16_t aKey, struct settingBuffer aVector, size_t aCount)
	Add a vector of buffers to the storage. More...

Detailed Description

This module includes the platform abstraction for non-volatile storage of settings.

Function Documentation

◆ caUtilSettingsAdd()

ca_error caUtilSettingsAdd	(	struct ca821x_dev *	aInstance,
		uint16_t	aKey,
		const uint8_t *	aValue,
		uint16_t	aValueLength
	)

Adds a value to a setting This function adds the value to a setting identified by aKey, without replacing any existing values.

Note that the underlying implementation is not required to maintain the order of the items associated with a specific key. The added value may be added to the end, the beginning, or even somewhere in the middle. The order of any pre-existing values may also change.

Calling this function successfully may cause unrelated settings with multiple values to be reordered.

Parameters

[in]	aInstance	The Cascoda instance structure.
[in]	aKey	The key associated with the setting to change.
[in]	aValue	A pointer to where the new value of the setting should be read from. MUST NOT be NULL if aValueLength is non-zero.
[in]	aValueLength	The length of the data pointed to by aValue. May be zero.

Return values

CA_ERROR_SUCCESS	The given setting was added or staged to be added.
CA_ERROR_NOT_IMPLEMENTED	This function is not implemented on this platform.
CA_ERROR_NO_BUFFER	No space remaining to store the given setting.

◆ caUtilSettingsAddVector()

ca_error caUtilSettingsAddVector	(	struct ca821x_dev *	aInstance,
		uint16_t	aKey,
		struct settingBuffer *	aVector,
		size_t	aCount
	)

Add a vector of buffers to the storage.

Stored in continuous flash within the setting described by aKey

Parameters

aInstance	API instance. Unused on baremetal.
aKey	The key associated with the requested setting.
aVector	An array of settingBuffer structures that describes the buffers to copy into flash.
aCount	The number of buffers within the aVector array.

Return values

CA_ERROR_SUCCESS	The given setting was added or staged to be added.
CA_ERROR_NOT_IMPLEMENTED	This function is not implemented on this platform.
CA_ERROR_NO_BUFFER	No space remaining to store the given setting.

◆ caUtilSettingsDeinit()

void caUtilSettingsDeinit ( struct ca821x_dev * aInstance )

Performs any de-initialization for the settings subsystem, if necessary.

Parameters

[in] aInstance The Cascoda instance structure.

◆ caUtilSettingsDelete()

ca_error caUtilSettingsDelete	(	struct ca821x_dev *	aInstance,
		uint16_t	aKey,
		int	aIndex
	)

Removes a setting from the setting store.

This function deletes a specific value from the setting identified by aKey from the settings store.

Note that the underlying implementation is not required to maintain the order of the items associated with a specific key.

Parameters

[in]	aInstance	The Cascoda instance structure.
[in]	aKey	The key associated with the requested setting.
[in]	aIndex	The index of the value to be removed. If set to -1, all values for this aKey will be removed.

Return values

CA_ERROR_SUCCESS	The given key and index was found and removed successfully.
CA_ERROR_NOT_FOUND	The given key or index was not found in the setting store.
CA_ERROR_NOT_IMPLEMENTED	This function is not implemented on this platform.

◆ caUtilSettingsGet()

ca_error caUtilSettingsGet	(	struct ca821x_dev *	aInstance,
		uint16_t	aKey,
		int	aIndex,
		uint8_t *	aValue,
		uint16_t *	aValueLength
	)

This function fetches the value of the setting identified by aKey and write it to the memory pointed to by aValue.

It then writes the length to the integer pointed to by aValueLength. The initial value of aValueLength is the maximum number of bytes to be written to aValue.

This function can be used to check for the existence of a key without fetching the value by setting aValue and aValueLength to NULL. You can also check the length of the setting without fetching it by setting only aValue to NULL.

Note that the underlying storage implementation is not required to maintain the order of settings with multiple values. The order of such values MAY change after ANY write operation to the store.

Parameters

[in]	aInstance	The Cascoda instance structure.
[in]	aKey	The key associated with the requested setting.
[in]	aIndex	The index of the specific item to get.
[out]	aValue	A pointer to where the value of the setting should be written. May be set to NULL if just testing for the presence or length of a setting.
[in,out]	aValueLength	A pointer to the length of the value. When called, this pointer should point to an integer containing the maximum value size that can be written to aValue. At return, the actual length of the setting is written. This may be set to NULL if performing a presence check.

Return values

CA_ERROR_SUCCESS	The given setting was found and fetched successfully.
CA_ERROR_NOT_FOUND	The given setting was not found in the setting store.
CA_ERROR_NOT_IMPLEMENTED	This function is not implemented on this platform.

◆ caUtilSettingsGetAddress()

ca_error caUtilSettingsGetAddress	(	struct ca821x_dev *	aInstance,
		uint16_t	aKey,
		int	aIndex,
		void **	aValue,
		uint16_t *	aValueLength
	)

Get the address at which a particular setting is stored.

Parameters

aInstance	API instance of storage to inspect. Unused on baremetal
aKey	The key associated with the requested setting.
aIndex	The index of the value to be removed. If set to -1, all values for this aKey will be removed.
aValue	A pointer to where the address of the setting should be written.
aValueLength	The length of the setting

Return values

CA_ERROR_SUCCESS	The given setting was found and fetched successfully.
CA_ERROR_NOT_FOUND	The given setting was not found in the setting store.
CA_ERROR_NOT_IMPLEMENTED	This function is not implemented on this platform.

◆ caUtilSettingsInit()

void caUtilSettingsInit	(	struct ca821x_dev *	aInstance,
		const char *	aApplicationName,
		uint32_t	aNodeId
	)

Performs any initialization for the settings subsystem, if necessary.

On baremetal platforms, only one instance of the storage is created, and therefore the arguments are not important.

On host platforms (e.g. POSIX) multiple instances of the MAC may be in use at the same time, and it may be desirable to have persistent storage for each individual instance.

This function opens / creates a different settings context for every unique combination of application name & node ID, and binds it to the CA821x device instance. Subsequent settings API calls using the same device instance will use that same settings context.

The configurable application name is useful for distinguishing between applications (e.g. you would not want your integration test suite to overwrite your Thread credentials), while the node ID is useful for distinguishing between multiple SDKs running on the same host.

Parameters

[in]	aInstance	The Cascoda instance structure.
[in]	aApplicationName	Used to distinguish between applications. Unused on baremetal.
[in]	aNodeId	Used to distinguish between different nodes on the same host. Must be smaller than or equal to 9999. Unused on baremetal.

◆ caUtilSettingsSet()

ca_error caUtilSettingsSet	(	struct ca821x_dev *	aInstance,
		uint16_t	aKey,
		const uint8_t *	aValue,
		uint16_t	aValueLength
	)

Sets or replaces the value of a setting.

This function sets or replaces the value of a setting identified by aKey. If there was more than one value previously associated with aKey, then they are all deleted and replaced with this single entry.

Calling this function successfully may cause unrelated settings with multiple values to be reordered.

Parameters

[in]	aInstance	The Cascoda instance structure.
[in]	aKey	The key associated with the setting to change.
[in]	aValue	A pointer to where the new value of the setting should be read from. MUST NOT be NULL if aValueLength is non-zero.
[in]	aValueLength	The length of the data pointed to by aValue. May be zero.

Return values

CA_ERROR_SUCCESS	The given setting was changed or staged.
CA_ERROR_NOT_IMPLEMENTED	This function is not implemented on this platform.
CA_ERROR_NO_BUFFER	No space remaining to store the given setting.

◆ caUtilSettingsWipe()

void caUtilSettingsWipe	(	struct ca821x_dev *	aInstance,
		const char *	aApplicationName,
		uint32_t	aNodeId
	)

Removes all settings from the setting store.

This function deletes all settings from the settings store, resetting it to its initial factory state.

Parameters

[in]	aInstance	The Cascoda instance structure.
[in]	aApplicationName	Application of the storage file, used to distinguish between storage applications. Unused on baremetal.
[in]	aNodeId	Used to distinguish between different nodes on the same host. Must be smaller than or equal to 9999. Unused on baremetal.

Classes

Functions

Detailed Description

Function Documentation

◆ caUtilSettingsAdd()

◆ caUtilSettingsAddVector()

◆ caUtilSettingsDeinit()

◆ caUtilSettingsDelete()

◆ caUtilSettingsGet()

◆ caUtilSettingsGetAddress()

◆ caUtilSettingsInit()

◆ caUtilSettingsSet()

◆ caUtilSettingsWipe()