Settings#

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

Enumerations#

enum
@22 {
OT_SETTINGS_KEY_ACTIVE_DATASET = 0x0001
OT_SETTINGS_KEY_PENDING_DATASET = 0x0002
OT_SETTINGS_KEY_NETWORK_INFO = 0x0003
OT_SETTINGS_KEY_PARENT_INFO = 0x0004
OT_SETTINGS_KEY_CHILD_INFO = 0x0005
OT_SETTINGS_KEY_SLAAC_IID_SECRET_KEY = 0x0007
OT_SETTINGS_KEY_DAD_INFO = 0x0008
OT_SETTINGS_KEY_SRP_ECDSA_KEY = 0x000b
OT_SETTINGS_KEY_SRP_CLIENT_INFO = 0x000c
OT_SETTINGS_KEY_SRP_SERVER_INFO = 0x000d
OT_SETTINGS_KEY_BR_ULA_PREFIX = 0x000f
OT_SETTINGS_KEY_BR_ON_LINK_PREFIXES = 0x0010
OT_SETTINGS_KEY_BORDER_AGENT_ID = 0x0011
OT_SETTINGS_KEY_VENDOR_RESERVED_MIN = 0x8000
OT_SETTINGS_KEY_VENDOR_RESERVED_MAX = 0xffff
}

This enumeration defines the keys of settings.

Functions#

void
otPlatSettingsInit(otInstance *aInstance, const uint16_t *aSensitiveKeys, uint16_t aSensitiveKeysLength)

Performs any initialization for the settings subsystem, if necessary.

void
otPlatSettingsDeinit(otInstance *aInstance)

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

otPlatSettingsGet(otInstance *aInstance, uint16_t aKey, int aIndex, uint8_t *aValue, uint16_t *aValueLength)

Fetches the value of a setting.

otPlatSettingsSet(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength)

Sets or replaces the value of a setting.

otPlatSettingsAdd(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength)

Adds a value to a setting.

otPlatSettingsDelete(otInstance *aInstance, uint16_t aKey, int aIndex)

Removes a setting from the setting store.

void
otPlatSettingsWipe(otInstance *aInstance)

Removes all settings from the setting store.

Enumeration Documentation#

@22#

@22

This enumeration defines the keys of settings.

Note: When adding a new settings key, if the settings corresponding to the key contains security sensitive information, the developer MUST add the key to the array aSensitiveKeys which is passed in otPlatSettingsInit().

Enumerator
OT_SETTINGS_KEY_ACTIVE_DATASET

Active Operational Dataset.

OT_SETTINGS_KEY_PENDING_DATASET

Pending Operational Dataset.

OT_SETTINGS_KEY_NETWORK_INFO

Thread network information.

OT_SETTINGS_KEY_PARENT_INFO

Parent information.

OT_SETTINGS_KEY_CHILD_INFO

Child information.

OT_SETTINGS_KEY_SLAAC_IID_SECRET_KEY

SLAAC key to generate semantically opaque IID.

OT_SETTINGS_KEY_DAD_INFO

Duplicate Address Detection (DAD) information.

OT_SETTINGS_KEY_SRP_ECDSA_KEY

SRP client ECDSA public/private key pair.

OT_SETTINGS_KEY_SRP_CLIENT_INFO

The SRP client info (selected SRP server address).

OT_SETTINGS_KEY_SRP_SERVER_INFO

The SRP server info (UDP port).

OT_SETTINGS_KEY_BR_ULA_PREFIX

BR ULA prefix.

OT_SETTINGS_KEY_BR_ON_LINK_PREFIXES

BR local on-link prefixes.

OT_SETTINGS_KEY_BORDER_AGENT_ID

Unique Border Agent/Router ID.

OT_SETTINGS_KEY_VENDOR_RESERVED_MIN
OT_SETTINGS_KEY_VENDOR_RESERVED_MAX

Definition at line 62 of file include/openthread/platform/settings.h

Function Documentation#

otPlatSettingsInit#

void otPlatSettingsInit (otInstance * aInstance, const uint16_t * aSensitiveKeys, uint16_t aSensitiveKeysLength)

Performs any initialization for the settings subsystem, if necessary.

Parameters
[in]aInstance

The OpenThread instance structure.

[in]aSensitiveKeys

A pointer to an array containing the list of sensitive keys. May be NULL only if aSensitiveKeysLength is 0, which means that there is no sensitive keys.

[in]aSensitiveKeysLength

The number of entries in the aSensitiveKeys array.

This function also sets the sensitive keys that should be stored in the secure area.

Note that the memory pointed by aSensitiveKeys MUST not be released before aInstance is destroyed.


Definition at line 103 of file include/openthread/platform/settings.h

otPlatSettingsDeinit#

void otPlatSettingsDeinit (otInstance * aInstance)

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

Parameters
[in]aInstance

The OpenThread instance structure.


Definition at line 111 of file include/openthread/platform/settings.h

otPlatSettingsGet#

otError otPlatSettingsGet (otInstance * aInstance, uint16_t aKey, int aIndex, uint8_t * aValue, uint16_t * aValueLength)

Fetches the value of a setting.

Parameters
[in]aInstance

The OpenThread 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.

[inout]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.

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.


Definition at line 147 of file include/openthread/platform/settings.h

otPlatSettingsSet#

otError otPlatSettingsSet (otInstance * aInstance, uint16_t aKey, const uint8_t * aValue, uint16_t aValueLength)

Sets or replaces the value of a setting.

Parameters
[in]aInstance

The OpenThread 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.

This function sets or replaces the value of a setting identified by aKey.

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

OpenThread stack guarantees to use otPlatSettingsSet() method for a aKey that was either previously set using otPlatSettingsSet() (i.e., contains a single value) or is empty and/or fully deleted (contains no value).

Platform layer can rely and use this fact for optimizing its implementation.


Definition at line 176 of file include/openthread/platform/settings.h

otPlatSettingsAdd#

otError otPlatSettingsAdd (otInstance * aInstance, uint16_t aKey, const uint8_t * aValue, uint16_t aValueLength)

Adds a value to a setting.

Parameters
[in]aInstance

The OpenThread 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.

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.

OpenThread stack guarantees to use otPlatSettingsAdd() method for a aKey that was either previously managed by otPlatSettingsAdd() (i.e., contains one or more items) or is empty and/or fully deleted (contains no value).

Platform layer can rely and use this fact for optimizing its implementation.


Definition at line 212 of file include/openthread/platform/settings.h

otPlatSettingsDelete#

otError otPlatSettingsDelete (otInstance * aInstance, uint16_t aKey, int aIndex)

Removes a setting from the setting store.

Parameters
[in]aInstance

The OpenThread 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.

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.


Definition at line 233 of file include/openthread/platform/settings.h

otPlatSettingsWipe#

void otPlatSettingsWipe (otInstance * aInstance)

Removes all settings from the setting store.

Parameters
[in]aInstance

The OpenThread instance structure.

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


Definition at line 243 of file include/openthread/platform/settings.h