1/*
2 * Copyright (c) 2024 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/**
17 * @addtogroup PREFERENCES
18 * @{
19 *
20 * @brief Provides APIs for processing data in the form of key-value (KV) pairs.
21 * You can use the APIs provided by the Preferences module to query, modify, and persist KV pairs.
22 * The key is of the string type, and the value can be a number, a string, a boolean value.
23 *
24 * @since 13
25 */
26
27/**
28 * @file oh_preferences.h
29 *
30 * @brief Defines the APIS and enums of Preference.
31 *
32 * @kit ArkData
33 * @library libohpreferences.so
34 * @syscap SystemCapability.DistributedDataManager.Preferences.Core
35 *
36 * @since 13
37 */
38
39#ifndef OH_PREFERENCES_H
40#define OH_PREFERENCES_H
41
42#include <stdbool.h>
43#include <stdint.h>
44
45#include "oh_preferences_value.h"
46#include "oh_preferences_option.h"
47
48#ifdef __cplusplus
49extern "C" {
50#endif
51
52/**
53 * @brief Represents a Preferences instance.
54 *
55 * @since 13
56 */
57typedef struct OH_Preferences OH_Preferences;
58
59/**
60 * @brief Call to return the change in KV pairs.
61 *
62 * @param context Pointer to the context of data observer.
63 * @param pairs Pointer to the KV pairs to be observed.
64 * @param count Number of KV pairs to be observed.
65 * @see OH_PreferencesPair.
66 * @since 13
67 */
68typedef void (*OH_PreferencesDataObserver)(void *context, const OH_PreferencesPair *pairs, uint32_t count);
69
70/**
71 * @brief Opens a Preferences object.
72 *
73 * @param option Pointer to an {@Link OH_PreferencesOption} instance.
74 * @param errCode Pointer to the status code of the execution. For details, See {@link OH_Preferences_ErrCode}.
75 * @return Returns an pointer to the Preferences object in {@Link OH_Preferences} if the operation is successful,
76 * returns nullptr otherwise.
77 *         {@link PREFERENCES_OK} indicates the operation is successful.
78 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
79 *         {@link PREFERENCES_ERROR_NOT_SUPPORTED} indicates the capability is not supported.
80 *         {@link PREFERENCES_ERROR_DELETE_FILE} indicates delete file failed.
81 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
82 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
83 * @see OH_Preferences OH_PreferencesOption.
84 * @since 13
85 */
86OH_Preferences *OH_Preferences_Open(OH_PreferencesOption *option, int *errCode);
87
88/**
89 * @brief Closes a Preferences object.
90 *
91 * @param preference Pointer to the {@Link OH_Preferences} instance to close.
92 * @return Returns the status code of the execution. For details, see {@Link OH_Preferences_ErrCode}.
93 *         {@link PREFERENCES_OK} indicates the operation is successful.
94 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
95 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
96 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
97 * @see OH_Preferences.
98 * @since 13
99 */
100int OH_Preferences_Close(OH_Preferences *preference);
101
102/**
103 * @brief Obtains the integer value in a Preferences object based on the given key.
104 *
105 * @param preference Pointer to the target {@Link OH_Preferences} instance.
106 * @param key Pointer to the key of the value to obtain.
107 * @param value Pointer to the value obtained.
108 * @return Returns the status code of the execution.
109 *         {@link PREFERENCES_OK} indicates the operation is successful.
110 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
111 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
112 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
113 *         {@link PREFERENCES_ERROR_KEY_NOT_FOUND} indicates the key does not exist.
114 * @see OH_Preferences.
115 * @since 13
116 */
117int OH_Preferences_GetInt(OH_Preferences *preference, const char *key, int *value);
118
119/**
120 * @brief Obtains the Boolean value in a Preferences object based on the given key.
121 *
122 * @param preference Pointer to the target {@Link OH_Preferences} instance.
123 * @param key Pointer to the key of the value to obtain.
124 * @param value Pointer to the Boolean value obtained.
125 * @return Returns the status code of the execution.
126 *         {@link PREFERENCES_OK} indicates the operation is successful.
127 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
128 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
129 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
130 *         {@link PREFERENCES_ERROR_KEY_NOT_FOUND} indicates the key does not exist.
131 * @see OH_Preferences.
132 * @since 13
133 */
134int OH_Preferences_GetBool(OH_Preferences *preference, const char *key, bool *value);
135
136/**
137 * @brief Obtains the string value in a Preferences object based on the given key.
138 *
139 * @param preference Pointer to the target {@Link OH_Preferences} instance.
140 * @param key Pointer to the key of the value to obtain.
141 * @param value Double pointer to the value obtained in an char * array. Release {@Link OH_Preferences_FreeString} the
142 * memory by user when this parameter is no longer required.
143 * @param valueLen Pointer to the length of the string obtained.
144 * @return Returns the status code of the execution.
145 *         {@link PREFERENCES_OK} indicates the operation is successful.
146 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
147 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
148 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
149 *         {@link PREFERENCES_ERROR_KEY_NOT_FOUND} indicates the key does not exist.
150 * @see OH_Preferences.
151 * @since 13
152 */
153int OH_Preferences_GetString(OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen);
154
155/**
156 * @brief Free a string got by Preferences object.
157 *
158 * @param string Point to string need to free.
159 * @see OH_Preferences.
160 * @since 13
161 */
162void OH_Preferences_FreeString(char *string);
163
164/**
165 * @brief Sets an integer in a Preferences object.
166 *
167 * @param preference Pointer to the target {@Link OH_Preferences} instance.
168 * @param key Pointer to the key to set.
169 * @param value Value to set.
170 * @return Returns the status code of the execution.
171 *         {@link PREFERENCES_OK} indicates the operation is successful.
172 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
173 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
174 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
175 * @see OH_Preferences.
176 * @since 13
177 */
178int OH_Preferences_SetInt(OH_Preferences *preference, const char *key, int value);
179
180/**
181 * @brief Sets a Boolean value in a Preferences object.
182 *
183 * @param preference Pointer to the target {@Link OH_Preferences} instance.
184 * @param key Pointer to the key to set.
185 * @param value Boolean value to set.
186 * @return Returns the status code of the execution.
187 *         {@link PREFERENCES_OK} indicates the operation is successful.
188 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
189 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
190 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
191 * @see OH_Preferences.
192 * @since 13
193 */
194int OH_Preferences_SetBool(OH_Preferences *preference, const char *key, bool value);
195
196/**
197 * @brief Sets a string in a Preferences object.
198 *
199 * @param preference Pointer to the target {@Link OH_Preferences} instance.
200 * @param key Pointer to the key to set.
201 * @param value Point to string to set.
202 * @return Returns the status code of the execution.
203 *         {@link PREFERENCES_OK} indicates the operation is successful.
204 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
205 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
206 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
207 * @see OH_Preferences.
208 * @since 13
209 */
210int OH_Preferences_SetString(OH_Preferences *preference, const char *key, const char *value);
211
212/**
213 * @brief Deletes a KV pair from a Preferences object.
214 *
215 * @param preference Pointer to the target {@Link OH_Preferences} instance.
216 * @param key Pointer to the key of the data to delete.
217 * @return Returns the status code of the execution.
218 *         {@link PREFERENCES_OK} indicates the operation is successful.
219 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
220 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
221 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
222 * @see OH_Preferences.
223 * @since 13
224 */
225int OH_Preferences_Delete(OH_Preferences *preference, const char *key);
226
227/**
228 * @brief Registers a data observer for a Preferences object.
229 *
230 * @param preference Pointer to the target {@Link OH_Preferences} instance.
231 * @param context Pointer to the context of the data observer.
232 * @param observer the {@Link OH_PreferencesDataObserver} to register.
233 * @param keys Pointer to the keys to observe.
234 * @param keyCount Number of keys to observe.
235 * @return Returns the status code of the execution.
236 *         {@link PREFERENCES_OK} indicates the operation is successful.
237 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
238 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
239 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
240 *         {@link PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT} indicates get dataObsMgrClient error.
241 * @see OH_Preferences OH_PreferencesDataObserver.
242 * @since 13
243 */
244int OH_Preferences_RegisterDataObserver(OH_Preferences *preference, void *context,
245    OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount);
246
247/**
248 * @brief Unregisters a data observer for a Preferences object.
249 *
250 * @param preference Pointer to the target {@Link OH_Preferences} instance.
251 * @param context Pointer to the context of the data observer.
252 * @param observer the {@Link OH_PreferencesDataObserver} to unregister.
253 * @param keys Pointer to the keys observed. If this parameter is null, this API unregisters the listening for all keys.
254 * @param keyCount Number of the keys.
255 * @return Returns the status code of the execution.
256 *         {@link PREFERENCES_OK} indicates the operation is successful.
257 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
258 *         {@link PREFERENCES_ERROR_STORAGE} indicates an storage error.
259 *         {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error.
260 * @see OH_Preferences OH_PreferencesDataObserver.
261 * @since 13
262 */
263int OH_Preferences_UnregisterDataObserver(OH_Preferences *preference, void *context,
264    OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount);
265
266#ifdef __cplusplus
267};
268#endif
269
270/** @} */
271#endif // OH_PREFERENCES_H