_ARM_DRIVER_CFSTORE Struct Reference

Close the hkey context previously recovered from CFSTORE.

Parameters:

hkey	IN: a previously returned handle from (*Create((), (*Open)() or (*Find)() to close.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*Close)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, KV deleted, else failure.
cmd_code	== CFSTORE_OPCODE_CLOSE
client	context as registered with ARM_CFSTORE_DRIVER::(*Initialize)()
hkey	== NULL

Definition at line 361 of file configuration_store.h.

Create a key-value int he configuration strore.

Once created, the following attributes of a KV cannot be changed:

• the key_name
• the permissions or attributes specifies by the key descriptor kdesc. To change these properties, the key must be deleted and then created again with the new properties.

Parameters:

key_name	IN: zero terminated string specifying the key name.
value_len	the client specifies the length of the value data item in the KV being created.
kdesc	IN: key descriptor, specifying how the details of the key create operations. Note the following cases: 1) if key_name is not present in the CFSTORE and kdesc is NULL (i.e. a new KV pair is being created), then CFSTORE will chose the most appropriate defaults e.g. CFSTORE will store the KV in nv store if the value size is large, with no security guarantees just safety. 2) if key_name is present in the CFSTORE and kdesc is NULL (i.e. there is a pre-existing KV pair), then CFSTORE will grow/shrink the value data buffer to value_len octets. This idiom can be used to increase/decrease the size of the KV value storage. 3) If the kdesc->flags.storage_detect == 1 then the function does not create the key but reports whether the key with the specified size and storage media attributes could/could not be created by configuration storage.
hkey	IN: pointer to client owned buffer of CFSTORE_HANDLE_BUFSIZE bytes OUT: on success, hkey is a valid handle to a KV.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*Create)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, KV deleted, else failure.
cmd_code	== CFSTORE_OPCODE_CREATE
client	context as registered with ARM_CFSTORE_DRIVER::(*Initialize)()
hkey	now contains returned handle to newly created key.

Definition at line 413 of file configuration_store.h.

Delete key-value from configuration store.

This method is used in the following ways:

• (*Open)() to get a handle to the key, (*Delete)() to delete the key, (*Close)() to close the handle to the key.
• (*Find)() to get a handle to the key, (*Delete)() to delete the key, (*Close)() to close the handle to the key.

Parameters:

hkey	IN: the handle of the key to delete.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*Delete)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, KV deleted, else failure.
cmd_code	== CFSTORE_OPCODE_DELETE
client	context as registered with ARM_CFSTORE_DRIVER::(*Initialize)()
hkey,unused.

Definition at line 440 of file configuration_store.h.

find stored keys that match a query string

find a list of pre-existing keys according to a query pattern. The search pattern can have the following formats

• 'com.arm.mbed.wifi.accesspoint.essid'. Find whether an object exists that has a key matching 'com.arm.mbed.wifi.accesspoint.essid'
• 'com.arm.mbed.wifi.accesspoint*.essid'. Find all keys that start with the substring 'com.arm.mbed.wifi.accesspoint' and end with the substring '.essid'
• 'com.arm.mbed.your-registry-module-name.*'. Find all key_name strings that begin with the substring 'com.arm.mbed.your-registry-module-name.'
• 'com.arm.mbed.hello-world.animal{dog}{foot}{*}'. Find all key_name strings beginning com.arm.mbed.hello-world.animal{dog}{foot}
• 'com.arm.mbed.hello-world.animal{dog}{foot}*'
• 'com.arm.mbed.hello-world.animal{dog*3}'

It is possible to iterate over the list of matching keys by using the idiom below (in the synchronous case): ``` int32_t ret = ARM_DRIVER_ERROR; const char* key_name_query = "*"; char key_name[CFSTORE_KEY_NAME_MAX_LENGTH+1]; uint8_t len = CFSTORE_KEY_NAME_MAX_LENGTH+1; ARM_CFSTORE_HANDLE_INIT(next); ARM_CFSTORE_HANDLE_INIT(prev);

while(drv->Find(key_name_query, prev, next) == ARM_DRIVER_OK) { len = CFSTORE_KEY_NAME_MAX_LENGTH+1; drv->GetKeyName(next, key_name, &len); printf("Found matching key-value with key_name=%s\n", key_name); CFSTORE_HANDLE_SWAP(prev, next); } ``` The iteration over the find results can be terminated before the end of the list is reached by closing the last open file handle and not making any further calls to find() e.g.

``` int32_t ret = ARM_DRIVER_ERROR; const char* key_name_query = "*"; char key_name[CFSTORE_KEY_NAME_MAX_LENGTH+1]; uint8_t len = CFSTORE_KEY_NAME_MAX_LENGTH+1; ARM_CFSTORE_HANDLE_INIT(next); ARM_CFSTORE_HANDLE_INIT(prev);

while(drv->Find(key_name_query, prev, next) == ARM_DRIVER_OK) { len = CFSTORE_KEY_NAME_MAX_LENGTH+1; drv->GetKeyName(next, key_name, &len); if(strncmp(key_name, "my.key_name", CFSTORE_KEY_NAME_MAX_LENGTH)) { printf("Found matching key-value with key_name=%s\n", key_name; // terminating walk of find results drv->Close(next); break; CFSTORE_HANDLE_SWAP(prev, next); } ```

Parameters:

key_name_query	IN: a search string to find. This can include the wildcard '*' character
previous	IN: On the first call to (*Find) then previous is a pointer (the handle) to a buffer initialised to 0. On the subsequent calls to (*Find), a previously returned key handle can be supplied as the previous argument. The next available search result will be returned. If no further search results are available then (*Find) will return ARM_CFSTORE_DRIVER_ERROR_KEY_NOT_FOUND. Once the file handle has been supplied to the function as the prev argument, CFSTORE close the open file handle. Otherwise, the client must call (*Close)() on the open file handle.
next	IN: pointer to client owned buffer of CFSTORE_HANDLE_BUFSIZE bytes to hold the OUT: Success: In the case that a match has been found then hkey is a valid handle to an open KV. The key must be explicitly closed by the client. Note this is a read-only key. Async operation: The storage at hkey must be available until after the completion notification has been received by the client.

Returns:

On success (finding a KV matching the query) ARM_DRIVER_OK is returned. If a KV is not found matching the description then ARM_CFSTORE_DRIVER_ERROR_KEY_NOT_FOUND is returned. See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*Find)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, hkey contains open key else failure.
cmd_code	== CFSTORE_OPCODE_FIND
client	context as registered with ARM_CFSTORE_DRIVER::(*Initialize)()
hkey	ARM_DRIVER_OK => contains returned handle to newly found key. else, indeterminate data.

Definition at line 545 of file configuration_store.h.

Flush (write) the configuration changes to the nv backing store.

All open key handles must be closed before flushing the CFSTORE to nv backing store.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*Flush)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, hkey contains open key else failure.
cmd_code	== CFSTORE_OPCODE_FLUSH
client	context, registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey,unused

Definition at line 566 of file configuration_store.h.

Get configuration store capabilities.

This synchronous function returns a ARM_CFSTORE_CAPABILITIES information structure describing configuration store implementation attributes.

Returns:

ARM_CFSTORE_CAPABILITIES

Definition at line 577 of file configuration_store.h.

Get the name of an open key handle.

Parameters:

hkey	open handle of key to get the key_name
key_name.	The key name string is guaranteed to be terminated with '\0'.
key_len,the	length of the buffer available at data to receive the key_name string

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*GetKeyName)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, key_name contains key_name string, len contains length of string. else failure.
cmd_code	== CFSTORE_OPCODE_GET_KEY_NAME
client	context, registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey	supplied to the GetKeyName() call at hkey.
key_name	on success, the buffer holds the name of the key
key_len	on success, the supplied integer is set to strlen(key_name)+1, where the additional character corresponds to the terminating null.

Definition at line 606 of file configuration_store.h.

Get the status of the configuration store.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation ARM_DRIVER_OK if the command has been accepted and enqueued by the underlying controller, else an appropriate error code. Getting a return value of ARM_DRIVER_OK implies that basic argument validation was successful, and the caller can expect a command completion callback to be invoked at a later time.

ARM_CFSTORE_DRIVER::(*GetStatus)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	status of next command pending completion
cmd_code	next command pending completion.
client	context registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey	unused.

Definition at line 630 of file configuration_store.h.

Get the value length from an open key handle.

Parameters:

hkey	open handle of key for which to get value length
value_len,the	location in which to store the value length.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*GetValueLen)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, value_len contains length value. else failure.
cmd_code	== CFSTORE_OPCODE_GET_VALUE_LEN
client	context, registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey	supplied to the GetValueLen() call at hkey.

Definition at line 650 of file configuration_store.h.

Get driver version.

The synchronous function GetVersion() returns version information of the driver implementation in ARM_DRIVER_VERSION.

• ARM_DRIVER_VERSION::api the version of the CMSIS-Driver specification used to implement this driver.
• ARM_DRIVER_VERSION::drv the source code version of the actual configuration store driver implementation.

Returns:

ARM_DRIVER_VERSION, the configuration store driver version information

Definition at line 340 of file configuration_store.h.

Initialize the Configuration Store.

This function:

• initialised the configuration store service
• allows the client to subscribe to event notifications, in particular the asynchronous completion events for the driver dispatch interface (see ARM_CFSTORE_OPCODE).

The configuration store should be initialised as follows: drv->initialise(client_callback, client_callback_context); drv->PowerControl(ARM_POWER_FULL) where:

• client_callback is a client implemented callback function.
• client_callback_context is a client registered context that will be supplied as an argument to the client_callback when called.
• PowerControl indicates that any underlying system services that are in the low power state should be powered up.

The configuration store should be de-initialised as follows: drv->PowerControl(ARM_POWER_OFF) drv->Deinitialise();

Parameters:

client_callback	this is a client implemented callback function for receiving asynchronous event notifications (see ARM_CFSTORE_CALLBACK). NULL indicates client does not subscribed to event notifications.
client_callback_context	this is the client registered context that will be supplied as an argument to the client_callback when called. This argument can be NULL.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*Initialize)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, configuration store initialised, else failure
CFSTORE_OPCODE_INITIALIZE
client	context registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey,unused.

Definition at line 699 of file configuration_store.h.

Open a key-value object for future operations.

Parameters:

key_name	IN: zero terminated string specifying the key name.
flags	can open a RW key in read only mode.
hkey	IN: pointer to client owned buffer of CFSTORE_HANDLE_BUFSIZE bytes OUT: on success, hkey is a valid handle to an open KV.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*Open)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, KV opened, else failure.
cmd_code	== CFSTORE_OPCODE_OPEN
client	context, registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey	now contains returned handle to newly opened key.

Definition at line 786 of file configuration_store.h.

Function to set the target configuration store power state.

Parameters:

state

ARM_POWER_STATE. The target power-state for the configuration store. The parameter state can have the following values: ARM_POWER_FULL => set the mode to full power state ARM_POWER_LOW => set the mode to low power state ARM_POWER_OFF => set the mode to off power state

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. CFSTORE_OPCODE_POWER_CONTROL ARM_CFSTORE_DRIVER::(*PowerControl)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, power control set, else failure.
cmd_code	== CFSTORE_OPCODE_POWER_CONTROL
client	context, registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey,unused.

Definition at line 723 of file configuration_store.h.

Read the value data associated with a specified key.

Parameters:

hkey	IN: the handle returned from a previous call to (*Open)() to get a handle to the key
data	IN: a pointer to a data buffer supplied by the caller for CFSTORE to fill with value data OUT: on ARM_DRIVER_OK the data is (or will be when asynchronously completed) available in the buffer. The data will be read from the current form the current location (see (*Rseek)().
len	IN: the client specifies the length of the buffer available at data OUT: the CFSTORE specifies how many octets have been stored in the supplied buffer. Note fewer octets may be stored than the input len depending on the CFSTORE internal representation of the value.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. return_value == ARM_DRIVER_OK (==0) => asynchronous transaction pending. return_value > 0 => synchronous completion of read with the number of bytes read == return_value return_value < 0, error condition.

ARM_CFSTORE_DRIVER::(*Read)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	>= 0 => success with number of bytes read as indicated by the value of status < 0 => error, data in the data buffer is undefined, len is undefined.
cmd_code	== CFSTORE_OPCODE_READ
client	context, registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey,unused.

Definition at line 762 of file configuration_store.h.

Move the position of the read pointer within a value.

Parameters:

hkey	IN: the key referencing the value data for which the read location should be updated. Note that this function can only be called on pre-existing keys opened with read-only flag. Performing a seek operation on a writable key will fail.
offset	IN: the new offset position from the start of the value data

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. ARM_CFSTORE_DRIVER::(*Rseek)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	>=0 => success, read location set, else failure. upon success, the function returns the current read location measured from the beginning of the data value. <0 => error
cmd_code	== CFSTORE_OPCODE_RSEEK
client	context, registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey,unused.

Definition at line 812 of file configuration_store.h.

Function to de-initialise the Configuration Store.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. CFSTORE_OPCODE_UNINITIALIZE ARM_CFSTORE_DRIVER::(*Uninitialize)() asynchronous completion command code (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	ARM_DRIVER_OK => success, read location set, else failure.
cmd_code	== CFSTORE_OPCODE_UNINITIALIZE
client	context, registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey,unused.

Definition at line 828 of file configuration_store.h.

Write the value data associated with a specified key.

Note:

Note that Write() only supports sequential-access.

Parameters:

hkey	IN: the key for which value data will be written
data	IN: a pointer to a data buffer supplied by the caller for CFSTORE to write as the binary blob value data. Async operation: the buffer must be available until after completion notification is received by the client.
len	IN: the client specifies the length of the data buffer available. len must not exceed the value_len field specified when the KV pair was created. OUT: the CFSTORE specifies how many octets have been stored. Note that fewer octets may be stored than the input len depending on the CFSTORE internal representation of the value. Async operation: the len storage location must be available until after completion notification is received by the client.

Returns:

See REFERENCE_1 and the ARM_CFSTORE_CALLBACK documentation. return_value == ARM_DRIVER_OK (==0) => asynchronous transaction pending. return_value > 0 => synchronous completion of write with the number of bytes written == return_value return_value < 0, error condition.

ARM_CFSTORE_DRIVER::(*Write)() asynchronous completion (*ARM_CFSTORE_CALLBACK) function argument values on return:

Parameters:

status	>= 0 => success with the number bytes written equal to the value of the return status ARM_CFSTORE_CALLBACK status argument < 0 => error
cmd_code	== CFSTORE_OPCODE_WRITE
client	context, registered ARM_CFSTORE_DRIVER::(*Initialize)()
hkey,unused.

Definition at line 870 of file configuration_store.h.