mirror of
https://github.com/espressif/openthread.git
synced 2026-09-15 21:50:08 +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.
|
* @note This number versions both OpenThread platform and user APIs.
|
||||||
*
|
*
|
||||||
*/
|
*/
|
||||||
#define OPENTHREAD_API_VERSION (215)
|
#define OPENTHREAD_API_VERSION (216)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @addtogroup api-instance
|
* @addtogroup api-instance
|
||||||
|
|||||||
@@ -108,80 +108,100 @@ void otPlatSettingsInit(otInstance *aInstance, const uint16_t *aSensitiveKeys, u
|
|||||||
*/
|
*/
|
||||||
void otPlatSettingsDeinit(otInstance *aInstance);
|
void otPlatSettingsDeinit(otInstance *aInstance);
|
||||||
|
|
||||||
/// Fetches the value of a setting
|
/**
|
||||||
/** This function fetches the value of the setting identified
|
* Fetches the value of a setting.
|
||||||
* 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
|
* This function fetches the value of the setting identified
|
||||||
* a key without fetching the value by setting aValue and
|
* by @p aKey and write it to the memory pointed to by aValue.
|
||||||
* aValueLength to NULL. You can also check the length of
|
* It then writes the length to the integer pointed to by
|
||||||
* the setting without fetching it by setting only aValue
|
* @p aValueLength. The initial value of @p aValueLength is the
|
||||||
* to NULL.
|
* maximum number of bytes to be written to @p aValue.
|
||||||
*
|
*
|
||||||
* Note that the underlying storage implementation is not
|
* This function can be used to check for the existence of
|
||||||
* required to maintain the order of settings with multiple
|
* a key without fetching the value by setting @p aValue and
|
||||||
* values. The order of such values MAY change after ANY
|
* @p aValueLength to NULL. You can also check the length of
|
||||||
* write operation to the store.
|
* the setting without fetching it by setting only aValue
|
||||||
|
* to NULL.
|
||||||
*
|
*
|
||||||
* @param[in] aInstance The OpenThread instance structure.
|
* Note that the underlying storage implementation is not
|
||||||
* @param[in] aKey The key associated with the requested setting.
|
* required to maintain the order of settings with multiple
|
||||||
* @param[in] aIndex The index of the specific item to get.
|
* values. The order of such values MAY change after ANY
|
||||||
* @param[out] aValue A pointer to where the value of the setting should be written. May be set to NULL if
|
* write operation to the store.
|
||||||
* 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.
|
|
||||||
*
|
*
|
||||||
* @retval OT_ERROR_NONE The given setting was found and fetched successfully.
|
* @param[in] aInstance The OpenThread instance structure.
|
||||||
* @retval OT_ERROR_NOT_FOUND The given setting was not found in the setting store.
|
* @param[in] aKey The key associated with the requested setting.
|
||||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
* @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);
|
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
|
* 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
|
* This function sets or replaces the value of a setting
|
||||||
* settings with multiple values to be reordered.
|
* identified by @p aKey.
|
||||||
*
|
*
|
||||||
* @param[in] aInstance The OpenThread instance structure.
|
* Calling this function successfully may cause unrelated
|
||||||
* @param[in] aKey The key associated with the setting to change.
|
* settings with multiple values to be reordered.
|
||||||
* @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.
|
|
||||||
*
|
*
|
||||||
* @retval OT_ERROR_NONE The given setting was changed or staged.
|
* OpenThread stack guarantees to use `otPlatSettingsSet()`
|
||||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
* method for a @p aKey that was either previously set using
|
||||||
* @retval OT_ERROR_NO_BUFS No space remaining to store the given setting.
|
* `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);
|
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
|
* Adds a value to a setting.
|
||||||
* identified by aKey, without replacing any existing
|
|
||||||
* values.
|
|
||||||
*
|
*
|
||||||
* Note that the underlying implementation is not required
|
* This function adds the value to a setting
|
||||||
* to maintain the order of the items associated with a
|
* identified by @p aKey, without replacing any existing
|
||||||
* specific key. The added value may be added to the end,
|
* values.
|
||||||
* 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
|
* Note that the underlying implementation is not required
|
||||||
* settings with multiple values to be reordered.
|
* 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] aInstance The OpenThread instance structure.
|
||||||
* @param[in] aKey The key associated with the setting to change.
|
* @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
|
* @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.
|
* if @p aValueLength is non-zero.
|
||||||
* @param[in] aValueLength The length of the data pointed to by aValue. May be 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_NONE The given setting was added or staged to be added.
|
||||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
* @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);
|
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
|
* Removes a setting from the setting store.
|
||||||
* setting identified by aKey from the settings store.
|
|
||||||
*
|
*
|
||||||
* Note that the underlying implementation is not required
|
* This function deletes a specific value from the
|
||||||
* to maintain the order of the items associated with a
|
* setting identified by aKey from the settings store.
|
||||||
* specific key.
|
|
||||||
*
|
*
|
||||||
* @param[in] aInstance The OpenThread instance structure.
|
* Note that the underlying implementation is not required
|
||||||
* @param[in] aKey The key associated with the requested setting.
|
* to maintain the order of the items associated with a
|
||||||
* @param[in] aIndex The index of the value to be removed. If set to -1, all values for this aKey will be removed.
|
* specific key.
|
||||||
*
|
*
|
||||||
* @retval OT_ERROR_NONE The given key and index was found and removed successfully.
|
* @param[in] aInstance The OpenThread instance structure.
|
||||||
* @retval OT_ERROR_NOT_FOUND The given key or index was not found in the setting store.
|
* @param[in] aKey The key associated with the requested setting.
|
||||||
* @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform.
|
* @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);
|
otError otPlatSettingsDelete(otInstance *aInstance, uint16_t aKey, int aIndex);
|
||||||
|
|
||||||
/// Removes all settings from the setting store
|
/**
|
||||||
/** This function deletes all settings from the settings
|
* Removes all settings from the setting store.
|
||||||
* store, resetting it to its initial factory state.
|
|
||||||
*
|
*
|
||||||
* @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);
|
void otPlatSettingsWipe(otInstance *aInstance);
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user