245 lines
9.8 KiB
C
245 lines
9.8 KiB
C
/*
|
|
* Copyright (c) 2016, The OpenThread Authors.
|
|
* All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are met:
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
* 3. Neither the name of the copyright holder nor the
|
|
* names of its contributors may be used to endorse or promote products
|
|
* derived from this software without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
|
|
/**
|
|
* @file
|
|
* @brief
|
|
* This file includes platform abstractions for non-volatile storage of settings.
|
|
*/
|
|
|
|
#ifndef OT_PLATFORM_SETTINGS_H
|
|
#define OT_PLATFORM_SETTINGS_H 1
|
|
|
|
#include <stdint.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* Performs any initialization for the settings subsystem, if necessary.
|
|
*/
|
|
void otPlatSettingsInit(void);
|
|
|
|
/// Begin atomic change set
|
|
/** This function is called at the start of a sequence of changes
|
|
* that should be made atomically.
|
|
*
|
|
* This function, along with `otPlatSettingsCommitChange()` are designed
|
|
* to ensure atomicity of changes to multiple settings. Once
|
|
* this function has been called, any changes made to the settings
|
|
* store are only committed when `otPlatSettingsCommitChange()` is
|
|
* called.
|
|
*
|
|
* The implementation of this function is optional. If not
|
|
* implemented, it should return kThreadError_None.
|
|
*
|
|
* @retval kThreadError_None The settings commit lock has been set.
|
|
* @retval kThreadError_Already The commit lock is already set.
|
|
*
|
|
* @sa otPlatSettingsCommitChange(), otPlatSettingsAbandonChange()
|
|
*/
|
|
ThreadError otPlatSettingsBeginChange(void);
|
|
|
|
/// Commit all settings changes since previous call to otPlatSettingsBeginChange()
|
|
/** This function is called at the end of a sequence of changes.
|
|
* The implementation of this function is optional. If not
|
|
* implemented, it should return kThreadError_NotImplemented.
|
|
*
|
|
* @retval kThreadError_None
|
|
* The changes made since the last call to
|
|
* otPlatSettingsBeginChange() have been successfully
|
|
* committed.
|
|
* @retval kThreadError_InvalidState
|
|
* otPlatSettingsBeginChange() has not been called.
|
|
* @retval kThreadError_NotImplemented
|
|
* This function is not implemented on this platform.
|
|
*
|
|
* @sa otPlatSettingsBeginChange(), otPlatSettingsAbandonChange()
|
|
*/
|
|
ThreadError otPlatSettingsCommitChange(void);
|
|
|
|
/// Abandon all settings changes since previous call to otPlatSettingsBeginChange()
|
|
/** This function may be called at the end of a sequence of changes.
|
|
* instead of otPlatSettingsCommitChange(). If implemented, it
|
|
* causes all changes made since otPlatSettingsBeginChange() to be
|
|
* rolled back and abandoned.
|
|
*
|
|
* The implementation of this function is optional. If not
|
|
* implemented, it should return kThreadError_NotImplemented..
|
|
*
|
|
* @retval kThreadError_None
|
|
* The changes made since the last call to
|
|
* otPlatSettingsBeginChange() have been successfully
|
|
* rolled back.
|
|
* @retval kThreadError_InvalidState
|
|
* otPlatSettingsBeginChange() has not been called.
|
|
* @retval kThreadError_NotImplemented
|
|
* This function is not implemented on this platform.
|
|
*
|
|
* @sa otPlatSettingsBeginChange(), otPlatSettingsCommitChange()
|
|
*/
|
|
ThreadError otPlatSettingsAbandonChange(void);
|
|
|
|
/// 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.
|
|
*
|
|
* 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.
|
|
*
|
|
* @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.
|
|
*
|
|
* @retval kThreadError_None
|
|
* The given setting was found and fetched successfully.
|
|
* @retval kThreadError_NotFound
|
|
* The given setting was not found in the setting store.
|
|
* @retval kThreadError_NotImplemented
|
|
* This function is not implemented on this platform.
|
|
*/
|
|
ThreadError otPlatSettingsGet(uint16_t aKey, int aIndex, uint8_t *aValue, int *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.
|
|
*
|
|
* Calling this function successfully may cause unrelated
|
|
* settings with multiple values to be reordered.
|
|
*
|
|
* @param[in] aKey
|
|
* The key associated with the setting to change.
|
|
* @param[out] 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 kThreadError_None
|
|
* The given setting was changed or staged.
|
|
* @retval kThreadError_NotImplemented
|
|
* This function is not implemented on this platform.
|
|
*/
|
|
ThreadError otPlatSettingsSet(uint16_t aKey, const uint8_t *aValue, int aValueLength);
|
|
|
|
/// Adds a value to a setting
|
|
/** 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.
|
|
*
|
|
* @param[in] aKey
|
|
* The key associated with the setting to change.
|
|
* @param[out] 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/out] aValueLength
|
|
* The length of the data pointed to by aValue.
|
|
* May be zero.
|
|
*
|
|
* @retval kThreadError_None
|
|
* The given setting was added or staged to be added.
|
|
* @retval kThreadError_NotImplemented
|
|
* This function is not implemented on this platform.
|
|
*/
|
|
ThreadError otPlatSettingsAdd(uint16_t aKey, const uint8_t *aValue, int aValueLength);
|
|
|
|
/// Removes a setting from the setting store
|
|
/** This function deletes a specific value from the
|
|
* setting identified by aKey from the settings store.
|
|
*
|
|
* This is the only function which mutates the settings store
|
|
* that is required to maintain the relative order of the
|
|
* values associated with aKey. For example, if you have three
|
|
* items ordered (A, B, C) and you delete B, the resulting order
|
|
* is guaranteed to be (A, C).
|
|
*
|
|
* @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.
|
|
*
|
|
* @retval kThreadError_None
|
|
* The given key and index was found and removed successfully.
|
|
* @retval kThreadError_NotFound
|
|
* The given key or index was not found in the setting store.
|
|
* @retval kThreadError_NotImplemented
|
|
* This function is not implemented on this platform.
|
|
*/
|
|
ThreadError otPlatSettingsDelete(uint16_t aKey, int index);
|
|
|
|
/// Removes all settings from the setting store
|
|
/** This function deletes all settings from the settings
|
|
* store, resetting it to its initial factory state.
|
|
*/
|
|
void otPlatSettingsWipe(void);
|
|
|
|
#ifdef __cplusplus
|
|
} // extern "C"
|
|
#endif
|
|
|
|
#endif // OT_PLATFORM_SETTINGS_H
|