# Settings

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

## Summary

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga6b7b47dd702d9e331586d485013fd1ea{ https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa9c94b699591bef66f3c91ee58b63f727 = 0x0001, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa3fc81c856d1b5790ccafa05dd3ba2c30 = 0x0002, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa0e7ad0108319f35fa1bacb39324540ee = 0x0003, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa55e8a77cf00ccabe207671cdf09abd02 = 0x0004, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa3420b8617346b2b660c0c4c3383f08c5 = 0x0005, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa781835a118e55cfeb8e7760a1b04f7dc = 0x0007, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa4f605a2dd9a196cfd5df6f6fda2eee04 = 0x0008, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa3672eab33d00e887a9d3dc4971977e7d = 0x000b, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa3bedc813a9e7e408ddfb68f633a8568a = 0x000c, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa0013ba97f66f064f3ddd7b8713afe0f3 = 0x000d, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa80db239919440516fc138b69fdd468e2 = 0x000f, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa07f3d08ed79d99d93aedfbda301687b3 = 0x0010, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaa7ed5a9f7923bd0f7ba361ab1b5cdfb22 = 0x0011, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaab4db0ced4e51e61fc7933e59cb6b96ac = 0x0012, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaaaef2b2dedc3fb7cd109a313e385f6984 = 0x0013, https://openthread.io/reference/group/plat-settings#group__plat-settings_1gga6b7b47dd702d9e331586d485013fd1eaaabfee3d8872c24ee98b91937930c44b0 = 0x0014 }` | enumDefines the keys of settings. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga79f95407a75ed792af8058a164552c1e(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Adds a value to a setting. |
| `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga7b1cee0f330f0d257d9d585af93ee345(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Performs any de-initialization for the settings subsystem, if necessary. |
| `https://openthread.io/reference/group/plat-settings#group__plat-settings_1gaeaef25d37f98fabe792cebaf5b60dab2(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aKey, int aIndex)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Removes a setting from the setting store. |
| `https://openthread.io/reference/group/plat-settings#group__plat-settings_1gad0fa57fbb3dd2aafe0bb2af52518ee04(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aKey, int aIndex, uint8_t *aValue, uint16_t *aValueLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Fetches the value of a setting. |
| `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga98b18c36a4af0b218b7f71d7bc83f656(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const uint16_t *aSensitiveKeys, uint16_t aSensitiveKeysLength)` | `void` Performs any initialization for the settings subsystem, if necessary. |
| `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga8de8672dce112939ef04d0b4b182bbe3(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets or replaces the value of a setting. |
| `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga9512db56b3712ba7b5a263e0280fa20a(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Removes all settings from the setting store. |

## Enumerations

### Anonymous Enum 18

```
 Anonymous Enum 18
```
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 `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga98b18c36a4af0b218b7f71d7bc83f656`.

| Properties ||
|---|---|
| `OT_SETTINGS_KEY_ACTIVE_DATASET` | Active Operational Dataset. |
| `OT_SETTINGS_KEY_BORDER_AGENT_ID` | Unique Border Agent/Router ID. |
| `OT_SETTINGS_KEY_BR_ON_LINK_PREFIXES` | BR local on-link prefixes. |
| `OT_SETTINGS_KEY_BR_ULA_PREFIX` | BR ULA prefix. |
| `OT_SETTINGS_KEY_CHILD_INFO` | Child information. |
| `OT_SETTINGS_KEY_DAD_INFO` | Duplicate Address Detection (DAD) information. |
| `OT_SETTINGS_KEY_NETWORK_INFO` | Thread network information. |
| `OT_SETTINGS_KEY_PARENT_INFO` | Parent information. |
| `OT_SETTINGS_KEY_PENDING_DATASET` | Pending Operational Dataset. |
| `OT_SETTINGS_KEY_SLAAC_IID_SECRET_KEY` | SLAAC key to generate semantically opaque IID. |
| `OT_SETTINGS_KEY_SRP_CLIENT_INFO` | The SRP client info (selected SRP server address). |
| `OT_SETTINGS_KEY_SRP_ECDSA_KEY` | SRP client ECDSA public/private key pair. |
| `OT_SETTINGS_KEY_SRP_SERVER_INFO` | The SRP server info (UDP port). |
| `OT_SETTINGS_KEY_TCAT_COMMR_CERT` | TCAT Commissioner certificate. |
| `OT_SETTINGS_KEY_THREAD_DIRECT_KEYS` | Thread Direct Keys using literal key format. |
| `OT_SETTINGS_KEY_THREAD_DIRECT_KEY_REFS` | Thread Direct Keys using key references. |

## Functions

### otPlatSettingsAdd

```
otError otPlatSettingsAdd(
  otInstance *aInstance,
  uint16_t aKey,
  const uint8_t *aValue,
  uint16_t aValueLength
)
```
Adds a value to a setting.

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 `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga79f95407a75ed792af8058a164552c1e` method for a `aKey` that was either previously managed by `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga79f95407a75ed792af8058a164552c1e` (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.

<br />

Details 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. Return Values `OT_ERROR_NONE` The given setting was added or staged to be added. `OT_ERROR_NOT_IMPLEMENTED` This function is not implemented on this platform. `OT_ERROR_NO_BUFS` No space remaining to store the given setting.

### otPlatSettingsDeinit

```
void otPlatSettingsDeinit(
  otInstance *aInstance
)
```
Performs any de-initialization for the settings subsystem, if necessary.

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure.

### otPlatSettingsDelete

```
otError otPlatSettingsDelete(
  otInstance *aInstance,
  uint16_t aKey,
  int aIndex
)
```
Removes a setting from the setting store.

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.

<br />

Details 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. Return Values `OT_ERROR_NONE` The given key and index was found and removed successfully. `OT_ERROR_NOT_FOUND` The given key or index was not found in the setting store. `OT_ERROR_NOT_IMPLEMENTED` This function is not implemented on this platform.

### otPlatSettingsGet

```
otError otPlatSettingsGet(
  otInstance *aInstance,
  uint16_t aKey,
  int aIndex,
  uint8_t *aValue,
  uint16_t *aValueLength
)
```
Fetches the value of a setting.

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`.

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.

<br />

Details 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. `[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 `OT_ERROR_NONE` The given setting was found and fetched successfully. `OT_ERROR_NOT_FOUND` The given setting was not found in the setting store. `OT_ERROR_NOT_IMPLEMENTED` This function is not implemented on this platform.

### otPlatSettingsInit

```
void otPlatSettingsInit(
  otInstance *aInstance,
  const uint16_t *aSensitiveKeys,
  uint16_t aSensitiveKeysLength
)
```
Performs any initialization for the settings subsystem, if necessary.

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.

<br />

Details 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.

### otPlatSettingsSet

```
otError otPlatSettingsSet(
  otInstance *aInstance,
  uint16_t aKey,
  const uint8_t *aValue,
  uint16_t aValueLength
)
```
Sets or replaces the value of a setting.

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 `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga8de8672dce112939ef04d0b4b182bbe3` method for a `aKey` that was either previously set using `https://openthread.io/reference/group/plat-settings#group__plat-settings_1ga8de8672dce112939ef04d0b4b182bbe3` (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.

<br />

Details 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. Return Values `OT_ERROR_NONE` The given setting was changed or staged. `OT_ERROR_NOT_IMPLEMENTED` This function is not implemented on this platform. `OT_ERROR_NO_BUFS` No space remaining to store the given setting.

### otPlatSettingsWipe

```
void otPlatSettingsWipe(
  otInstance *aInstance
)
```
Removes all settings from the setting store.

Deletes all settings from the settings store, resetting it to its initial factory state.

<br />

Details Parameters `[in] aInstance` The OpenThread instance structure.

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).