src/lib/core/CHIPPersistentStorageDelegate.h

/*
 *
 *    Copyright (c) 2020-2022 Project CHIP Authors
 *    All rights reserved.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

#pragma once

#include <lib/core/CHIPError.h>
#include <lib/support/DLLUtil.h>
#include <stddef.h>
#include <stdint.h>

namespace chip {

class DLL_EXPORT PersistentStorageDelegate
{
public:
    /**
     *  Maximum length of a key required by implementations. Any implementer of PersistentStorageDelegate
     *  must support keys AT LEAST this long.
     */
    static constexpr size_t kKeyLengthMax = 32;

    virtual ~PersistentStorageDelegate() {}

    /**
     * @brief
     *   This is a synchronous Get API, where the value is returned via the output
     *   buffer.
     *
     *   This API can be used to retrieve a byte buffer value from the storage.
     *   There is no implied data format and and data will be stored/fetched binary.
     *   Caller is responsible to take care of any special formatting needs (e.g. byte
     *   order, null terminators, consistency checks or versioning).
     *
     *   If a key is found and the `buffer`'s `size` is large enough, then the value will
     *   be copied to `buffer` and `size` will be updated to the actual size used.
     *
     *   Whenever the passed `size` is smaller than the size of the stored value for the given key,
     *   CHIP_ERROR_BUFFER_TOO_SMALL will be returned, but the `buffer` will still be filled with the
     *   first `size` bytes of the stored value.
     *
     *   In the case where `size` of 0 is given, and the value stored is of size 0, CHIP_NO_ERROR is
     *   returned. It is recommended to use helper method SyncDoesKeyExist(key) to determine if key
     *   exists.
     *
     *   It is legal to use `nullptr` for `buffer` if `size` is 0.
     *
     * @param[in]      key Key to lookup
     * @param[out]     buffer Pointer to a buffer where the place the read value.
     * @param[in, out] size Input is maximum buffer size, output updated to number of bytes written into `buffer`.
     *
     * @return CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND the key is not found in storage.
     * @return CHIP_ERROR_BUFFER_TOO_SMALL the provided buffer is not big enough.  In this case
     *                                     the first `size` bytes of the value will be placed in `buffer`.
     */
    virtual CHIP_ERROR SyncGetKeyValue(const char * key, void * buffer, uint16_t & size) = 0;

    /**
     * @brief
     *   Set the value for the key to a byte buffer. Empty values can be stored
     *   with size == 0, in which case `value` may be nullptr.
     *
     * @param[in] key Key to set
     * @param[in] value Pointer to bytes of value to be set. `value` can only be `nullptr` if size == 0.
     * @param[in] size Size of the `value` to store.
     *
     * @return CHIP_NO_ERROR on success, CHIP_INVALID_ARGUMENT on `value` being `nullptr` with size > 0,
     *         or another CHIP_ERROR value from implementation on failure.
     */
    virtual CHIP_ERROR SyncSetKeyValue(const char * key, const void * value, uint16_t size) = 0;

    /**
     * @brief
     *   Deletes the value for the key
     *
     * @param[in] key Key to be deleted
     *
     * @return CHIP_NO_ERROR on success, CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND if the key is not found in storage,
     *         or another CHIP_ERROR value from implementation on failure.
     */
    virtual CHIP_ERROR SyncDeleteKeyValue(const char * key) = 0;

    /**
     * @brief
     *   Helper function that identifies if a key exists.
     *
     *   This may be overridden to provide an implementation that is simpler or more direct.
     *
     * @param[in] key Key to check if it exist
     *
     * @return true if key exists in storage. It returns false if key does not exist in storage or an internal error arises.
     */
    virtual bool SyncDoesKeyExist(const char * key)
    {
        uint16_t size  = 0;
        CHIP_ERROR err = SyncGetKeyValue(key, nullptr, size);
        return (err == CHIP_ERROR_BUFFER_TOO_SMALL) || (err == CHIP_NO_ERROR);
    }
};

} // namespace chip