1 /*
2  * Copyright (c) 2021 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef SINGLE_KV_STORE_H
17 #define SINGLE_KV_STORE_H
18 
19 #include <map>
20 #include "kvstore.h"
21 #include "kvstore_observer.h"
22 #include "kvstore_result_set.h"
23 #include "kvstore_sync_callback.h"
24 #include "types.h"
25 #include "data_query.h"
26 
27 namespace OHOS {
28 namespace DistributedKv {
29 // This is a public interface. Implementation of this class is in AppKvStoreImpl.
30 // This class provides put, delete, search, sync and subscribe functions of a key-value store.
31 class API_EXPORT SingleKvStore : public virtual KvStore {
32 public:
33     /**
34      * @brief Constructor.
35      */
36     API_EXPORT SingleKvStore() = default;
37 
38     /**
39      * @brief Destructor.
40      */
~SingleKvStore()41     API_EXPORT virtual ~SingleKvStore() {}
42 
43     /**
44      * @brief Get value from KvStore by its key.
45      * @param key   Key of this entry.
46      * @param value Value will be returned in this parameter.
47      * @return Return SUCCESS for success, others for failure.
48     */
49     virtual Status Get(const Key &key, Value &value) = 0;
50 
51     /**
52      * @brief Get value from KvStore by its key.
53      * A compensation synchronization will be automatically triggered to the
54      * specified device only when the networkId is valid.
55      * This interface is only effective for dynamic data, others do not support.
56      *
57      * @param key Key of this entry.
58      * @param networkId The networkId of online device.
59      * @param onResult Value and Status will be returned in this parameter.
60     */
Get(const Key & key,const std::string & networkId,const std::function<void (Status,Value &&)> & onResult)61     virtual void Get(const Key &key,
62         const std::string &networkId, const std::function<void(Status, Value &&)> &onResult) {}
63 
64     /**
65      * @brief Get all entries in this store which key start with prefixKey.
66      * A compensation synchronization will be automatically triggered to the
67      * specified device only when the networkId is valid.
68      * This interface is only effective for dynamic data, others do not support.
69      *
70      * @param prefix The prefix to be searched.
71      * @param networkId The networkId of online device.
72      * @param onResult Entries and Status will be returned in this parameter.
73     */
GetEntries(const Key & prefix,const std::string & networkId,const std::function<void (Status,std::vector<Entry> &&)> & onResult)74     virtual void GetEntries(const Key &prefix,
75         const std::string &networkId, const std::function<void(Status, std::vector<Entry> &&)> &onResult) {}
76 
77     /**
78      * @brief Get all entries in this store which key start with prefixKey.
79      * @param prefix  The prefix to be searched.
80      * @param entries Entries will be returned in this parameter.
81      * @return Return SUCCESS for success, others for failure.
82     */
83     virtual Status GetEntries(const Key &prefix, std::vector<Entry> &entries) const = 0;
84 
85     /**
86      * @brief Get all entries in this store by query.
87      * @param query   The query object.
88      * @param entries Entries will be returned in this parameter.
89      * @return Return SUCCESS for success, others for failure.
90     */
91     virtual Status GetEntries(const DataQuery &query, std::vector<Entry> &entries) const = 0;
92 
93     /**
94      * @brief Get resultSet in this store which key start with prefixKey.
95      * @param prefix    The prefix to be searched.
96      * @param resultSet ResultSet will be returned in this parameter.
97      * @return Return SUCCESS for success, others for failure.
98     */
99     virtual Status GetResultSet(const Key &prefix, std::shared_ptr<KvStoreResultSet> &resultSet) const = 0;
100 
101     /**
102      * @brief Get resultSet in this store by query.
103      * @param query     The query object.
104      * @param resultSet ResultSet will be returned in this parameter.
105      * @return Return SUCCESS for success, others for failure.
106     */
107     virtual Status GetResultSet(const DataQuery &query, std::shared_ptr<KvStoreResultSet> &resultSet) const = 0;
108 
109     /**
110      * @brief Close the resultSet returned by GetResultSet.
111      * @param resultSet ResultSet will be returned in this parameter.
112      * @return Return SUCCESS for success, others for failure.
113     */
114     virtual Status CloseResultSet(std::shared_ptr<KvStoreResultSet> &resultSet) = 0;
115 
116     /**
117      * @brief Get the number of result by query.
118      * @param query The query object.
119      * @param count Result will be returned in this parameter.
120      * @return Return SUCCESS for success, others for failure.
121     */
122     virtual Status GetCount(const DataQuery &query, int &count) const = 0;
123 
124     /**
125      * @brief Remove the device data synced from remote.
126      *
127      * Remove all the other devices data synced from remote if device is empty.
128      *
129      * @param device Device id.
130      * @return Return SUCCESS for success, others for failure.
131     */
132     virtual Status RemoveDeviceData(const std::string &device) = 0;
133 
134     /**
135      * @brief Get the kvstore security level.
136      *
137      * The security level is set when create store by options parameter.
138      *
139      * @param secLevel The security level will be returned.
140      * @return Return SUCCESS for success, others for failure.
141     */
142     virtual Status GetSecurityLevel(SecurityLevel &secLevel) const = 0;
143 
144     /**
145      * @brief Sync store with other devices.
146      *
147      * This is an asynchronous method.
148      * sync will fail if there is a syncing operation in progress.
149      *
150      * @param devices Device list to sync.
151      * @param mode    Mode can be set to SyncMode::PUSH, SyncMode::PULL and SyncMode::PUTH_PULL.
152      *                PUSH_PULL will firstly push all not-local store to listed devices,
153      *                then pull these stores back.
154      * @param delay   Allowed delay milli-second to sync.
155      * @return Return SUCCESS for success, others for failure.
156     */
157     virtual Status Sync(const std::vector<std::string> &devices, SyncMode mode, uint32_t delay) = 0;
158 
159     /**
160      * @brief Sync store with other devices only syncing the data which is satisfied with the condition.
161      *
162      * This is an asynchronous method.
163      * sync will fail if there is a syncing operation in progress.
164      *
165      * @param devices      Device list to sync.
166      * @param mode         Mode can be set to SyncMode::PUSH, SyncMode::PULL and SyncMode::PUSH_PULL.
167      *                     PUSH_PULL will firstly push all not-local store to listed devices,
168      *                     then pull these stores back.
169      * @param query        The query condition.
170      * @param syncCallback The callback will be called when sync finished.
171      * @return Return SUCCESS for success, others for failure.
172     */
Sync(const std::vector<std::string> & devices,SyncMode mode,const DataQuery & query,std::shared_ptr<KvStoreSyncCallback> syncCallback)173     virtual Status Sync(const std::vector<std::string> &devices, SyncMode mode, const DataQuery &query,
174         std::shared_ptr<KvStoreSyncCallback> syncCallback)
175     {
176         return Sync(devices, mode, query, syncCallback, 0);
177     }
178 
179     /**
180      * @brief Sync store with other devices only syncing the data which is satisfied with the condition.
181      *
182      * This is an asynchronous method.
183      * sync will fail if there is a syncing operation in progress.
184      *
185      * @param devices      Device list to sync.
186      * @param mode         Mode can be set to SyncMode::PUSH, SyncMode::PULL and SyncMode::PUSH_PULL.
187      *                     PUSH_PULL will firstly push all not-local store to listed devices,
188      *                     then pull these stores back.
189      * @param query        The query condition.
190      * @param delay   Allowed delay milli-second to sync.
191      * @param syncCallback The callback will be called when sync finished.
192      * @return Return SUCCESS for success, others for failure.
193     */
Sync(const std::vector<std::string> & devices,SyncMode mode,const DataQuery & query,std::shared_ptr<KvStoreSyncCallback> syncCallback,uint32_t delay)194     virtual Status Sync(const std::vector<std::string> &devices, SyncMode mode, const DataQuery &query,
195         std::shared_ptr<KvStoreSyncCallback> syncCallback, uint32_t delay)
196     {
197         return Status::SUCCESS;
198     }
199 
200     /**
201      * @brief Sync store with other device, while delay is 0.
202     */
Sync(const std::vector<std::string> & devices,SyncMode mode)203     API_EXPORT inline Status Sync(const std::vector<std::string> &devices, SyncMode mode)
204     {
205         return Sync(devices, mode, 0);
206     }
207 
208     /**
209      * @brief Sync store with other device.
210      *
211      * which is satisfied with the condition.
212      * the callback pointer is nullptr.
213     */
Sync(const std::vector<std::string> & devices,SyncMode mode,const DataQuery & query)214     API_EXPORT inline Status Sync(const std::vector<std::string> &devices, SyncMode mode, const DataQuery &query)
215     {
216         return Sync(devices, mode, query, nullptr);
217     }
218 
219     /**
220      * @brief Register message for sync operation.
221      * @param callback Callback to register.
222      * @return Return SUCCESS for success, others for failure.
223     */
224     virtual Status RegisterSyncCallback(std::shared_ptr<KvStoreSyncCallback> callback) = 0;
225 
226     /**
227      * @brief Unregister all message for sync operation.
228      * @return Return SUCCESS for success, others for failure.
229     */
230     virtual Status UnRegisterSyncCallback() = 0;
231 
232     /**
233      * @brief Set synchronization parameters of this store.
234      * @param syncParam Sync policy parameter.
235      * @return Return SUCCESS for success, others for failure.
236     */
237     virtual Status SetSyncParam(const KvSyncParam &syncParam) = 0;
238 
239     /**
240      * @brief Get synchronization parameters of this store.
241      * @param syncParam Sync policy parameter.
242      * @return Return SUCCESS for success, others for failure.
243     */
244     virtual Status GetSyncParam(KvSyncParam &syncParam) = 0;
245 
246     /**
247      * @brief Set capability available for sync.
248      *
249      * If enabled is true, it will check permission before sync operation.
250      * only local labels and remote labels overlapped syncing works.
251      *
252      * @param enabled Bool paramater
253      * @return Return SUCCESS for success, others for failure.
254     */
255     virtual Status SetCapabilityEnabled(bool enabled) const = 0;
256 
257     /**
258      * @brief Set capability range for syncing.
259      *
260      * Should set capability available firstly.
261      *
262      * @param localLabels  Local labels defined by a list of string value.
263      * @param remoteLabels Remote labels defined by a list of string value.
264      * @return Return SUCCESS for success, others for failure.
265     */
266     virtual Status SetCapabilityRange(const std::vector<std::string> &localLabels,
267                                       const std::vector<std::string> &remoteLabels) const = 0;
268 
269     /**
270      * @brief Subscribe store with other devices consistently Synchronize the data
271      *        which is satisfied with the condition.
272      * @param devices Device list to sync.
273      * @param query   The query condition.
274      * @return Return SUCCESS for success, others for failure.
275     */
276     virtual Status SubscribeWithQuery(const std::vector<std::string> &devices, const DataQuery &query) = 0;
277 
278     /**
279      * @brief Unsubscribe store with other devices which is satisfied with the condition.
280      * @param devices Device list to sync.
281      * @param query   The query condition.
282      * @return Return SUCCESS for success, others for failure.
283     */
284     virtual Status UnsubscribeWithQuery(const std::vector<std::string> &devices, const DataQuery &query) = 0;
285 
286     /**
287      * @brief Set identifier.
288      * @param accountId The accountId.
289      * @param appId The name of the application.
290      * @param storeId The name of kvstore.
291      * @param tagretDev target device list.
292      * @return Return SUCCESS for success, others for failure.
293     */
SetIdentifier(const std::string & accountId,const std::string & appId,const std::string & storeId,const std::vector<std::string> & tagretDev)294     virtual Status SetIdentifier(const std::string &accountId, const std::string &appId,
295         const std::string &storeId, const std::vector<std::string> &tagretDev)
296     {
297         return Status::SUCCESS;
298     };
299 
300     /**
301      * @brief Sync store to cloud.
302      *
303      * Sync store to cloud.
304      *
305      * @return Return SUCCESS for success, others for failure.
306      */
CloudSync(const AsyncDetail & async)307     virtual Status CloudSync(const AsyncDetail &async)
308     {
309         return Status::SUCCESS;
310     }
311 
312     /**
313      * @brief Get all entries in this store by deviceId.
314      * @param device   deviceId.
315      * @param entries Entries will be returned in this parameter.
316      * @return Return SUCCESS for success, others for failure.
317     */
GetDeviceEntries(const std::string & device,std::vector<Entry> & entries)318     virtual Status GetDeviceEntries(const std::string &device, std::vector<Entry> &entries) const
319     {
320         return Status::SUCCESS;
321     }
322 
323     /**
324      * @brief set option of store.
325      *
326      * set option of store
327      *
328      * @return Return SUCCESS for success, others for failure.
329      */
SetConfig(const StoreConfig & storeConfig)330     virtual Status SetConfig(const StoreConfig &storeConfig)
331     {
332         return Status::SUCCESS;
333     }
334 
335     /**
336      * @brief get database status.
337      * @return Return true for db rebuild.
338      */
IsRebuild()339     virtual bool IsRebuild()
340     {
341         return false;
342     }
343 };
344 }  // namespace DistributedKv
345 }  // namespace OHOS
346 #endif  // SINGLE_KV_STORE_H