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 PREFERENCES_H
17 #define PREFERENCES_H
18 
19 #include <map>
20 #include <memory>
21 #include <string>
22 #include <vector>
23 
24 #include "preferences_errno.h"
25 #include "preferences_observer.h"
26 #include "preferences_value.h"
27 #include "preferences_visibility.h"
28 
29 namespace OHOS {
30 namespace NativePreferences {
31 using RegisterMode = PreferencesObserver::RegisterMode;
32 struct Options {
33 public:
OptionsOptions34     Options(const std::string inputFilePath) : filePath(inputFilePath)
35     {
36     }
37 
OptionsOptions38     Options(const char *inputFilePath) : filePath(inputFilePath)
39     {
40     }
41 
OptionsOptions42     Options(const std::string &inputFilePath, const std::string &inputbundleName, const std::string &inputdataGroupId)
43         : filePath(inputFilePath), bundleName(inputbundleName), dataGroupId(inputdataGroupId)
44     {
45     }
46 
OptionsOptions47     Options(const std::string &inputFilePath, const std::string &inputbundleName, const std::string &inputdataGroupId,
48         bool inputIsEnhance) : filePath(inputFilePath), bundleName(inputbundleName), dataGroupId(inputdataGroupId),
49         isEnhance(inputIsEnhance)
50     {
51     }
52 
53 public:
54     std::string filePath{ "" };
55     std::string bundleName{ "" };
56     std::string dataGroupId{ "" };
57     bool isEnhance = false;
58 };
59 /**
60  * The function class of the preference. Various operations on preferences instances are provided in this class.
61  */
62 class PREF_API_EXPORT Preferences {
63 public:
~Preferences()64     PREF_API_EXPORT virtual ~Preferences()
65     {
66     }
67 
68     /**
69     * @brief The constant Indicates the maximum length of the key in the preferences.
70     */
71     PREF_API_EXPORT static constexpr uint32_t MAX_KEY_LENGTH = 1024;
72 
73     /**
74      * @brief The constant Indicates the maximum length of the value in the preferences.
75      */
76     PREF_API_EXPORT static constexpr uint32_t MAX_VALUE_LENGTH = 16 * 1024 * 1024;
77 
78     /**
79      * @brief Obtains the value of a preferences.
80      *
81      * This function is used to get the value of the corresponding key in the preference.
82      *
83      * @param key Indicates the key of the preferences. It cannot be empty.
84      * @param defValue Indicates the default value of the preferences.
85      *
86      * @return Returns the value matching the specified key if it is found; returns the default value otherwise.
87      */
88     virtual PreferencesValue Get(const std::string &key, const PreferencesValue &defValue) = 0;
89 
90     /**
91      * @brief Sets a value for the key in the preferences.
92      *
93      *  This function is used to set or update the value of the corresponding key in the preferences.
94      *
95      * @param key Indicates the key of the preferences. It cannot be empty.
96      * @param value Indicates the default value of the preferences.
97      *
98      * @return Returns 0 for success, others for failure.
99      */
100     virtual int Put(const std::string &key, const PreferencesValue &value) = 0;
101 
102     /**
103      * @brief Obtains the int value of a preferences.
104      *
105      * This function is used to get an int value of the corresponding key in the preference.
106      *
107      * @param key Indicates the key of the preferences. It cannot be empty.
108      * @param defValue Indicates the default value of the preferences.
109      *
110      * @return Returns a int value matching the specified key if it is found; returns the default value otherwise.
111      */
112     virtual int GetInt(const std::string &key, const int &defValue = {}) = 0;
113 
114     /**
115      * @brief Obtains the string value of a preferences.
116      *
117      * This function is used to get string value of the corresponding key in the preference.
118      *
119      * @param key Indicates the key of the preferences. It cannot be empty.
120      * @param defValue Indicates the default value of the preferences.
121      *
122      * @return Returns string value matching the specified key if it is found; returns the default value otherwise.
123      */
124     virtual std::string GetString(const std::string &key, const std::string &defValue = {}) = 0;
125 
126     /**
127      * @brief Obtains the bool value of a preferences.
128      *
129      * This function is used to get a bool value of the corresponding key in the preference.
130      *
131      * @param key Indicates the key of the preferences. It cannot be empty.
132      * @param defValue Indicates the default value of the preferences.
133      *
134      * @return Returns a bool value matching the specified key if it is found; returns the default value otherwise.
135      */
136     virtual bool GetBool(const std::string &key, const bool &defValue = {}) = 0;
137 
138     /**
139      * @brief Obtains the float value of a preferences.
140      *
141      * This function is used to get a float value of the corresponding key in the preference.
142      *
143      * @param key Indicates the key of the preferences. It cannot be empty.
144      * @param defValue Indicates the default value of the preferences.
145      *
146      * @return Returns a float value matching the specified key if it is found; returns the default value otherwise.
147      */
148     virtual float GetFloat(const std::string &key, const float &defValue = {}) = 0;
149 
150     /**
151      * @brief Obtains the double value of a preferences.
152      *
153      * This function is used to get a double value of the corresponding key in the preference.
154      *
155      * @param key Indicates the key of the preferences. It cannot be empty.
156      * @param defValue Indicates the default value of the preferences.
157      *
158      * @return Returns a double value matching the specified key if it is found; returns the default value otherwise.
159      */
160     virtual double GetDouble(const std::string &key, const double &defValue = {}) = 0;
161 
162     /**
163      * @brief Obtains the long value of a preferences.
164      *
165      * This function is used to get a long value of the corresponding key in the preference.
166      *
167      * @param key Indicates the key of the preferences. It cannot be empty.
168      * @param defValue Indicates the default value of the preferences.
169      *
170      * @return Returns a long value matching the specified key if it is found; returns the default value otherwise.
171      */
172     virtual int64_t GetLong(const std::string &key, const int64_t &defValue = {}) = 0;
173 
174     /**
175      * @brief Obtains all the keys and values of a preferences.
176      *
177      * This function is used to get all keys and values in an object.
178      *
179      * @return Returns a map, the key is string type and the value is PreferencesValue type.
180      */
181     virtual std::map<std::string, PreferencesValue> GetAll() = 0;
182 
183     /**
184      * @brief Checks whether contains a preferences matching a specified key.
185      *
186      * This function is used to Checks whether contains a preferences matching a specified key.
187      *
188      * @param key Indicates the key of the preferences. It cannot be empty.
189      *
190      * @return Returning true means it contains, false means it doesn't.
191      */
192     virtual bool HasKey(const std::string &key) = 0;
193 
194     /**
195      * @brief Put or update an int value of a preferences.
196      *
197      * This function is used to put or update an int value of the corresponding key in the preference.
198      *
199      * @param key Indicates the key of the preferences. It cannot be empty.
200      * @param value Indicates the value of preferences to put or update.
201      *
202      * @return Returns 0 for success, others for failure.
203      */
204     virtual int PutInt(const std::string &key, int value) = 0;
205 
206     /**
207      * @brief Put or update an string value for the key.
208      *
209      * This function is used to put or update string value of the corresponding key in the preference.
210      *
211      * @param key Indicates the key of the preferences. It cannot be empty.
212      * @param value Indicates the value of preferences to put or update.
213      *
214      * @return Returns 0 for success, others for failure.
215      */
216     virtual int PutString(const std::string &key, const std::string &value) = 0;
217 
218     /**
219      * @brief Put or update bool string value for the key.
220      *
221      * This function is used to put or update a bool value of the corresponding key in the preference.
222      *
223      * @param key Indicates the key of the preferences. It cannot be empty.
224      * @param value Indicates the value of preferences to put or update.
225      *
226      * @return Returns 0 for success, others for failure.
227      */
228     virtual int PutBool(const std::string &key, bool value) = 0;
229 
230     /**
231      * @brief Put or update an long value for the key.
232      *
233      * This function is used to put or update a long value of the corresponding key in the preference.
234      *
235      * @param key Indicates the key of the preferences. It cannot be empty.
236      * @param value Indicates the value of preferences to put or update.
237      *
238      * @return Returns 0 for success, others for failure.
239      */
240     virtual int PutLong(const std::string &key, int64_t value) = 0;
241 
242     /**
243      * @brief Put or update an float value for the key.
244      *
245      * This function is used to put or update a float value of the corresponding key in the preference.
246      *
247      * @param key Indicates the key of the preferences. It cannot be empty.
248      * @param value Indicates the value of preferences to put or update.
249      *
250      * @return Returns 0 for success, others for failure.
251      */
252     virtual int PutFloat(const std::string &key, float value) = 0;
253 
254     /**
255      * @brief Put or update an double value for the key.
256      *
257      * This function is used to put or update a double value of the corresponding key in the preference.
258      *
259      * @param key Indicates the key of the preferences. It cannot be empty.
260      * @param value Indicates the value of preferences to put or update.
261      *
262      * @return Returns 0 for success, others for failure.
263      */
264     virtual int PutDouble(const std::string &key, double value) = 0;
265 
266     /**
267      * @brief Deletes the preferences with a specified key.
268      *
269      * This function is used to delete the preferences with a specified key in the preference.
270      *
271      * @param key Indicates the key of the preferences. It cannot be empty.
272      *
273      * @return Returns 0 for success, others for failure.
274      */
275     virtual int Delete(const std::string &key) = 0;
276 
277     /**
278      * @brief Clears all preferences.
279      *
280      * This function is used to clear all preferences in an object.
281      *
282      * @return Returns 0 for success, others for failure.
283      */
284     virtual int Clear() = 0;
285 
286     /**
287      * @brief Asynchronously saves the preferences to the file.
288      *
289      * This function is used to saves the preferences to the file. Files are written to disk only after
290      * this interface or {@link FlushSync}is called.
291      */
292     virtual void Flush() = 0;
293 
294     /**
295      * @brief Synchronously saves the preferences to the file.
296      *
297      * This function is used to saves the preferences to the file synchronously. Files are written to disk only after
298      * this interface or {@link Flush} is called.
299      *
300      * @return The result of write to disk. Returns 0 for success, others for failure.
301      */
302     virtual int FlushSync() = 0;
303 
304     /**
305      * @brief  Registers an observer.
306      *
307      * This function is used to registers an observer to listen for the change of a preferences.
308      *
309      * @param preferencesObserver Indicates callback function for data changes.
310      */
311     virtual int RegisterObserver(
312         std::shared_ptr<PreferencesObserver> preferencesObserver, RegisterMode mode = RegisterMode::LOCAL_CHANGE) = 0;
313 
314     int Subscribe(std::shared_ptr<PreferencesObserver> observer, RegisterMode mode = RegisterMode::LOCAL_CHANGE,
315         const std::vector<std::string> &keys = {})
316     {
317         switch (mode) {
318             case RegisterMode::LOCAL_CHANGE:
319             case RegisterMode::MULTI_PRECESS_CHANGE:
320                 return RegisterObserver(observer, mode);
321             case RegisterMode::DATA_CHANGE:
322                 return RegisterDataObserver(observer, keys);
323             default:
324                 break;
325         }
326         return E_INVALID_ARGS;
327     }
328 
329     /**
330      * @brief  Unregister an existing observer.
331      *
332      * This function is used to unregister an existing observer.
333      *
334      * @param preferencesObserver Indicates callback function for data changes.
335      */
336     virtual int UnRegisterObserver(
337         std::shared_ptr<PreferencesObserver> preferencesObserver, RegisterMode mode = RegisterMode::LOCAL_CHANGE) = 0;
338 
339     int Unsubscribe(std::shared_ptr<PreferencesObserver> observer, RegisterMode mode = RegisterMode::LOCAL_CHANGE,
340         const std::vector<std::string> &keys = {})
341     {
342         switch (mode) {
343             case RegisterMode::LOCAL_CHANGE:
344             case RegisterMode::MULTI_PRECESS_CHANGE:
345                 return UnRegisterObserver(observer, mode);
346             case RegisterMode::DATA_CHANGE:
347                 return UnRegisterDataObserver(observer, keys);
348             default:
349                 break;
350         }
351         return E_INVALID_ARGS;
352     }
353 
354     /**
355      * @brief  Get group id.
356      *
357      * This function is used to Get group id.
358      *
359      * @return Returns the groupId when it exists, otherwise returns an empty string.
360      */
GetGroupId()361     virtual std::string GetGroupId() const
362     {
363         return "";
364     }
365 
CloseDb()366     virtual int CloseDb()
367     {
368         return E_OK;
369     }
370 
371     /**
372      * @brief  Registers a data observer.
373      *
374      * This function is used to registers an observer to listen for changes in data based on the keys
375      *
376      * @param preferencesObserver Indicates callback function for data changes.
377      */
378     virtual int RegisterDataObserver(
379         std::shared_ptr<PreferencesObserver> preferencesObserver, const std::vector<std::string> &keys = {})
380     {
381         return E_OK;
382     }
383 
384     /**
385      * @brief  Unregister an existing observer.
386      *
387      * This function is used to unregister an existing observer based on the keys
388      *
389      * @param preferencesObserver Indicates callback function for data changes.
390      */
391     virtual int UnRegisterDataObserver(
392         std::shared_ptr<PreferencesObserver> preferencesObserver, const std::vector<std::string> &keys = {})
393     {
394         return E_OK;
395     }
396 
397     /**
398      * @brief Obtains the value of a preferences.
399      *
400      * This function is used to get the value of the corresponding key in the preference.
401      *
402      * @param key Indicates the key of the preferences. It cannot be empty.
403      * @param defValue Indicates the default value of the preferences.
404      *
405      * @return Returns a pair, the first is 0 for success, others for failure.
406      */
GetValue(const std::string & key,const PreferencesValue & defValue)407     virtual std::pair<int, PreferencesValue> GetValue(const std::string &key, const PreferencesValue &defValue)
408     {
409         return {E_OK, defValue};
410     }
411 
412     /**
413      * @brief Obtains all the keys and values of a preferences.
414      *
415      * This function is used to get all keys and values in an object.
416      *
417      * @return Returns a pair, the first is 0 for success, others for failure.
418      */
GetAllData()419     virtual std::pair<int, std::map<std::string, PreferencesValue>> GetAllData()
420     {
421         return {E_OK, {}};
422     }
423 };
424 } // End of namespace NativePreferences
425 } // End of namespace OHOS
426 #endif // End of #ifndef PREFERENCES_H