Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2020-2022 Project CHIP Authors
4 : * All rights reserved.
5 : *
6 : * Licensed under the Apache License, Version 2.0 (the "License");
7 : * you may not use this file except in compliance with the License.
8 : * You may obtain a copy of the License at
9 : *
10 : * http://www.apache.org/licenses/LICENSE-2.0
11 : *
12 : * Unless required by applicable law or agreed to in writing, software
13 : * distributed under the License is distributed on an "AS IS" BASIS,
14 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 : * See the License for the specific language governing permissions and
16 : * limitations under the License.
17 : */
18 :
19 : #pragma once
20 :
21 : #include <lib/core/CHIPError.h>
22 : #include <lib/support/DLLUtil.h>
23 : #include <stddef.h>
24 : #include <stdint.h>
25 :
26 : namespace chip {
27 :
28 : class DLL_EXPORT PersistentStorageDelegate
29 : {
30 : public:
31 : /**
32 : * Maximum length of a key required by implementations. Any implementer of PersistentStorageDelegate
33 : * must support keys AT LEAST this long.
34 : */
35 : static constexpr size_t kKeyLengthMax = 32;
36 :
37 0 : virtual ~PersistentStorageDelegate() {}
38 :
39 : /**
40 : * @brief
41 : * This is a synchronous Get API, where the value is returned via the output
42 : * buffer.
43 : *
44 : * This API can be used to retrieve a byte buffer value from the storage.
45 : * There is no implied data format and and data will be stored/fetched binary.
46 : * Caller is responsible to take care of any special formatting needs (e.g. byte
47 : * order, null terminators, consistency checks or versioning).
48 : *
49 : * If a key is found and the `buffer`'s `size` is large enough, then the value will
50 : * be copied to `buffer` and `size` will be updated to the actual size used.
51 : *
52 : * Whenever the passed `size` is smaller than the size of the stored value for the given key,
53 : * CHIP_ERROR_BUFFER_TOO_SMALL will be returned, but the `buffer` will still be filled with the
54 : * first `size` bytes of the stored value.
55 : *
56 : * In the case where `size` of 0 is given, and the value stored is of size 0, CHIP_NO_ERROR is
57 : * returned. It is recommended to use helper method SyncDoesKeyExist(key) to determine if key
58 : * exists.
59 : *
60 : * It is legal to use `nullptr` for `buffer` if `size` is 0.
61 : *
62 : * @param[in] key Key to lookup
63 : * @param[out] buffer Pointer to a buffer where the place the read value.
64 : * @param[in, out] size Input is maximum buffer size, output updated to number of bytes written into `buffer`.
65 : *
66 : * @return CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND the key is not found in storage.
67 : * @return CHIP_ERROR_BUFFER_TOO_SMALL the provided buffer is not big enough. In this case
68 : * the first `size` bytes of the value will be placed in `buffer`.
69 : */
70 : virtual CHIP_ERROR SyncGetKeyValue(const char * key, void * buffer, uint16_t & size) = 0;
71 :
72 : /**
73 : * @brief
74 : * Set the value for the key to a byte buffer. Empty values can be stored
75 : * with size == 0, in which case `value` may be nullptr.
76 : *
77 : * @param[in] key Key to set
78 : * @param[in] value Pointer to bytes of value to be set. `value` can only be `nullptr` if size == 0.
79 : * @param[in] size Size of the `value` to store.
80 : *
81 : * @return CHIP_NO_ERROR on success, CHIP_INVALID_ARGUMENT on `value` being `nullptr` with size > 0,
82 : * or another CHIP_ERROR value from implementation on failure.
83 : */
84 : virtual CHIP_ERROR SyncSetKeyValue(const char * key, const void * value, uint16_t size) = 0;
85 :
86 : /**
87 : * @brief
88 : * Deletes the value for the key
89 : *
90 : * @param[in] key Key to be deleted
91 : *
92 : * @return CHIP_NO_ERROR on success, CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND if the key is not found in storage,
93 : * or another CHIP_ERROR value from implementation on failure.
94 : */
95 : virtual CHIP_ERROR SyncDeleteKeyValue(const char * key) = 0;
96 :
97 : /**
98 : * @brief
99 : * Helper function that identifies if a key exists.
100 : *
101 : * This may be overridden to provide an implementation that is simpler or more direct.
102 : *
103 : * @param[in] key Key to check if it exist
104 : *
105 : * @return true if key exists in storage. It returns false if key does not exist in storage or an internal error arises.
106 : */
107 0 : virtual bool SyncDoesKeyExist(const char * key)
108 : {
109 0 : uint16_t size = 0;
110 0 : CHIP_ERROR err = SyncGetKeyValue(key, nullptr, size);
111 0 : return (err == CHIP_ERROR_BUFFER_TOO_SMALL) || (err == CHIP_NO_ERROR);
112 : }
113 : };
114 :
115 : } // namespace chip
|
