From ed665e95a73e40db486f0d52a3dbd2f86243de5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Duda?= Date: Wed, 1 Jun 2022 22:47:13 +0200 Subject: [PATCH] [platform] update documentation of otPlatSettings API (#7774) Signed-off-by: Lukasz Duda --- include/openthread/instance.h | 2 +- include/openthread/platform/settings.h | 167 ++++++++++++++----------- 2 files changed, 97 insertions(+), 72 deletions(-) diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 877e3267a..ae935f154 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -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 diff --git a/include/openthread/platform/settings.h b/include/openthread/platform/settings.h index dd6c41f84..2a4892baa 100644 --- a/include/openthread/platform/settings.h +++ b/include/openthread/platform/settings.h @@ -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);