mirror of
https://github.com/espressif/openthread.git
synced 2026-07-27 22:37:45 +00:00
[platform] update documentation of otPlatSettings API (#7774)
Signed-off-by: Lukasz Duda <[email protected]>
This commit is contained in:
Łukasz Duda
@@ -53,7 +53,7 @@ extern "C" {
|
||||
* @note This number versions both OpenThread platform and user APIs.
|
||||
*
|
||||
*/
|
||||
#define OPENTHREAD_API_VERSION (215)
|
||||
#define OPENTHREAD_API_VERSION (216)
|
||||
|
||||
/**
|
||||
* @addtogroup api-instance
|
||||
|
||||
@@ -108,80 +108,100 @@ void otPlatSettingsInit(otInstance *aInstance, const uint16_t *aSensitiveKeys, u
|
||||
*/
|
||||
void otPlatSettingsDeinit(otInstance *aInstance);
|
||||
|
||||
/// Fetches the value of a setting
|
||||
/** 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.
|
||||
/**
|
||||
* Fetches the value of a setting.
|
||||
*
|
||||
* 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.
|
||||
* This function fetches the value of the setting identified
|
||||
* by @p aKey and write it to the memory pointed to by aValue.
|
||||
* It then writes the length to the integer pointed to by
|
||||
* @p aValueLength. The initial value of @p aValueLength is the
|
||||
* maximum number of bytes to be written to @p aValue.
|
||||
*
|
||||
* 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.
|
||||
* This function can be used to check for the existence of
|
||||
* a key without fetching the value by setting @p aValue and
|
||||
* @p aValueLength to NULL. You can also check the length of
|
||||
* the setting without fetching it by setting only aValue
|
||||
* to NULL.
|
||||
*
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
* @param[in] aKey The key associated with the requested setting.
|
||||
* @param[in] aIndex The index of the specific item to get.
|
||||
* @param[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.
|
||||
* @param[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.
|
||||
* 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.
|
||||
*
|
||||
* @retval OT_ERROR_NONE The given setting was found and fetched successfully.
|
||||
* @retval OT_ERROR_NOT_FOUND The given setting was not found in the setting store.
|
||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
* @param[in] aKey The key associated with the requested setting.
|
||||
* @param[in] aIndex The index of the specific item to get.
|
||||
* @param[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.
|
||||
* @param[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 @p aValue. At return,
|
||||
* the actual length of the setting is written. This may be set to NULL if performing
|
||||
* a presence check.
|
||||
*
|
||||
* @retval OT_ERROR_NONE The given setting was found and fetched successfully.
|
||||
* @retval OT_ERROR_NOT_FOUND The given setting was not found in the setting store.
|
||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
||||
*/
|
||||
otError otPlatSettingsGet(otInstance *aInstance, uint16_t aKey, int aIndex, 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.
|
||||
/**
|
||||
* Sets or replaces the value of a setting.
|
||||
*
|
||||
* Calling this function successfully may cause unrelated
|
||||
* settings with multiple values to be reordered.
|
||||
* This function sets or replaces the value of a setting
|
||||
* identified by @p aKey.
|
||||
*
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
* @param[in] aKey The key associated with the setting to change.
|
||||
* @param[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.
|
||||
* @param[in] aValueLength The length of the data pointed to by aValue. May be zero.
|
||||
* Calling this function successfully may cause unrelated
|
||||
* settings with multiple values to be reordered.
|
||||
*
|
||||
* @retval OT_ERROR_NONE The given setting was changed or staged.
|
||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
||||
* @retval OT_ERROR_NO_BUFS No space remaining to store the given setting.
|
||||
* OpenThread stack guarantees to use `otPlatSettingsSet()`
|
||||
* method for a @p 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.
|
||||
*
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
* @param[in] aKey The key associated with the setting to change.
|
||||
* @param[in] aValue A pointer to where the new value of the setting should be read from. MUST NOT be NULL if
|
||||
* @p aValueLength is non-zero.
|
||||
* @param[in] aValueLength The length of the data pointed to by aValue. May be zero.
|
||||
*
|
||||
* @retval OT_ERROR_NONE The given setting was changed or staged.
|
||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
||||
* @retval OT_ERROR_NO_BUFS No space remaining to store the given setting.
|
||||
*/
|
||||
otError otPlatSettingsSet(otInstance *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.
|
||||
/**
|
||||
* Adds a value to a setting.
|
||||
*
|
||||
* 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.
|
||||
* This function adds the value to a setting
|
||||
* identified by @p aKey, without replacing any existing
|
||||
* values.
|
||||
*
|
||||
* Calling this function successfully may cause unrelated
|
||||
* settings with multiple values to be reordered.
|
||||
* 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 @p 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.
|
||||
*
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
* @param[in] aKey The key associated with the setting to change.
|
||||
* @param[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.
|
||||
* @param[in] aValueLength The length of the data pointed to by aValue. May be zero.
|
||||
* if @p aValueLength is non-zero.
|
||||
* @param[in] aValueLength The length of the data pointed to by @p aValue. May be zero.
|
||||
*
|
||||
* @retval OT_ERROR_NONE The given setting was added or staged to be added.
|
||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
||||
@@ -189,29 +209,34 @@ otError otPlatSettingsSet(otInstance *aInstance, uint16_t aKey, const uint8_t *a
|
||||
*/
|
||||
otError otPlatSettingsAdd(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength);
|
||||
|
||||
/// Removes a setting from the setting store
|
||||
/** This function deletes a specific value from the
|
||||
* setting identified by aKey from the settings store.
|
||||
/**
|
||||
* Removes a setting from the setting store.
|
||||
*
|
||||
* Note that the underlying implementation is not required
|
||||
* to maintain the order of the items associated with a
|
||||
* specific key.
|
||||
* This function deletes a specific value from the
|
||||
* setting identified by aKey from the settings store.
|
||||
*
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
* @param[in] aKey The key associated with the requested setting.
|
||||
* @param[in] aIndex The index of the value to be removed. If set to -1, all values for this aKey will be removed.
|
||||
* Note that the underlying implementation is not required
|
||||
* to maintain the order of the items associated with a
|
||||
* specific key.
|
||||
*
|
||||
* @retval OT_ERROR_NONE The given key and index was found and removed successfully.
|
||||
* @retval OT_ERROR_NOT_FOUND The given key or index was not found in the setting store.
|
||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
* @param[in] aKey The key associated with the requested setting.
|
||||
* @param[in] aIndex The index of the value to be removed. If set to -1, all values for this @p aKey will be
|
||||
* removed.
|
||||
*
|
||||
* @retval OT_ERROR_NONE The given key and index was found and removed successfully.
|
||||
* @retval OT_ERROR_NOT_FOUND The given key or index was not found in the setting store.
|
||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
||||
*/
|
||||
otError otPlatSettingsDelete(otInstance *aInstance, uint16_t aKey, int aIndex);
|
||||
|
||||
/// Removes all settings from the setting store
|
||||
/** This function deletes all settings from the settings
|
||||
* store, resetting it to its initial factory state.
|
||||
/**
|
||||
* Removes all settings from the setting store.
|
||||
*
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
* This function deletes all settings from the settings
|
||||
* store, resetting it to its initial factory state.
|
||||
*
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
*/
|
||||
void otPlatSettingsWipe(otInstance *aInstance);
|
||||
|
||||
|
||||
Reference in New Issue
Block a user