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 49 extern "C" { 50 #endif 51 52 /** 53 * @brief Represents a Preferences instance. 54 * 55 * @since 13 56 */ 57 typedef 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 */ 68 typedef 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 */ 86 OH_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 * @param option Pointer to an {@Link OH_PreferencesOption} instance. 93 * @return Returns the status code of the execution. For details, see {@Link OH_Preferences_ErrCode}. 94 * {@link PREFERENCES_OK} indicates the operation is successful. 95 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 96 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 97 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 98 * @see OH_Preferences. 99 * @since 13 100 */ 101 int OH_Preferences_Close(OH_Preferences *preference); 102 103 /** 104 * @brief Obtains the integer value in a Preferences object based on the given key. 105 * 106 * @param preference Pointer to the target {@Link OH_Preferences} instance. 107 * @param key Pointer to the key of the value to obtain. 108 * @param value Pointer to the value obtained. 109 * @return Returns the status code of the execution. 110 * {@link PREFERENCES_OK} indicates the operation is successful. 111 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 112 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 113 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 114 * {@link PREFERENCES_ERROR_KEY_NOT_FOUND} indicates the key does not exist. 115 * @see OH_Preferences. 116 * @since 13 117 */ 118 int OH_Preferences_GetInt(OH_Preferences *preference, const char *key, int *value); 119 120 /** 121 * @brief Obtains the Boolean value in a Preferences object based on the given key. 122 * 123 * @param preference Pointer to the target {@Link OH_Preferences} instance. 124 * @param key Pointer to the key of the value to obtain. 125 * @param value Pointer to the Boolean value obtained. 126 * @return Returns the status code of the execution. 127 * {@link PREFERENCES_OK} indicates the operation is successful. 128 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 129 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 130 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 131 * {@link PREFERENCES_ERROR_KEY_NOT_FOUND} indicates the key does not exist. 132 * @see OH_Preferences. 133 * @since 13 134 */ 135 int OH_Preferences_GetBool(OH_Preferences *preference, const char *key, bool *value); 136 137 /** 138 * @brief Obtains the string value in a Preferences object based on the given key. 139 * 140 * @param preference Pointer to the target {@Link OH_Preferences} instance. 141 * @param key Pointer to the key of the value to obtain. 142 * @param value Double pointer to the value obtained in an char * array. Release {@Link OH_Preferences_FreeString} the 143 * memory by user when this parameter is no longer required. 144 * @param valueLen Pointer to the length of the string obtained. 145 * @return Returns the status code of the execution. 146 * {@link PREFERENCES_OK} indicates the operation is successful. 147 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 148 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 149 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 150 * {@link PREFERENCES_ERROR_KEY_NOT_FOUND} indicates the key does not exist. 151 * @see OH_Preferences. 152 * @since 13 153 */ 154 int OH_Preferences_GetString(OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen); 155 156 /** 157 * @brief Free a string got by Preferences object. 158 * 159 * @param string Point to string need to free. 160 * @see OH_Preferences. 161 * @since 13 162 */ 163 void OH_Preferences_FreeString(char *string); 164 165 /** 166 * @brief Sets an integer in a Preferences object. 167 * 168 * @param preference Pointer to the target {@Link OH_Preferences} instance. 169 * @param key Pointer to the key to set. 170 * @param value Value to set. 171 * @return Returns the status code of the execution. 172 * {@link PREFERENCES_OK} indicates the operation is successful. 173 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 174 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 175 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 176 * @see OH_Preferences. 177 * @since 13 178 */ 179 int OH_Preferences_SetInt(OH_Preferences *preference, const char *key, int value); 180 181 /** 182 * @brief Sets a Boolean value in a Preferences object. 183 * 184 * @param preference Pointer to the target {@Link OH_Preferences} instance. 185 * @param key Pointer to the key to set. 186 * @param value Boolean value to set. 187 * @return Returns the status code of the execution. 188 * {@link PREFERENCES_OK} indicates the operation is successful. 189 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 190 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 191 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 192 * @see OH_Preferences. 193 * @since 13 194 */ 195 int OH_Preferences_SetBool(OH_Preferences *preference, const char *key, bool value); 196 197 /** 198 * @brief Sets a string in a Preferences object. 199 * 200 * @param preference Pointer to the target {@Link OH_Preferences} instance. 201 * @param key Pointer to the key to set. 202 * @param value Point to string to set. 203 * @return Returns the status code of the execution. 204 * {@link PREFERENCES_OK} indicates the operation is successful. 205 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 206 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 207 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 208 * @see OH_Preferences. 209 * @since 13 210 */ 211 int OH_Preferences_SetString(OH_Preferences *preference, const char *key, const char *value); 212 213 /** 214 * @brief Deletes a KV pair from a Preferences object. 215 * 216 * @param preference Pointer to the target {@Link OH_Preferences} instance. 217 * @param key Pointer to the key of the data to delete. 218 * @return Returns the status code of the execution. 219 * {@link PREFERENCES_OK} indicates the operation is successful. 220 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 221 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 222 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 223 * @see OH_Preferences. 224 * @since 13 225 */ 226 int OH_Preferences_Delete(OH_Preferences *preference, const char *key); 227 228 /** 229 * @brief Registers a data observer for a Preferences object. 230 * 231 * @param preference Pointer to the target {@Link OH_Preferences} instance. 232 * @param context Pointer to the context of the data observer. 233 * @param observer the {@Link OH_PreferencesDataObserver} to register. 234 * @param keys Pointer to the keys to observe. 235 * @param keyCount Number of keys to observe. 236 * @return Returns the status code of the execution. 237 * {@link PREFERENCES_OK} indicates the operation is successful. 238 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 239 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 240 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 241 * {@link PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT} indicates get dataObsMgrClient error. 242 * @see OH_Preferences OH_PreferencesDataObserver. 243 * @since 13 244 */ 245 int OH_Preferences_RegisterDataObserver(OH_Preferences *preference, void *context, 246 OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount); 247 248 /** 249 * @brief Unregisters a data observer for a Preferences object. 250 * 251 * @param preference Pointer to the target {@Link OH_Preferences} instance. 252 * @param context Pointer to the context of the data observer. 253 * @param observer the {@Link OH_PreferencesDataObserver} to unregister. 254 * @param keys Pointer to the keys observed. If this parameter is null, this API unregisters the listening for all keys. 255 * @param keyCount Number of the keys. 256 * @return Returns the status code of the execution. 257 * {@link PREFERENCES_OK} indicates the operation is successful. 258 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 259 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 260 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 261 * @see OH_Preferences OH_PreferencesDataObserver. 262 * @since 13 263 */ 264 int OH_Preferences_UnregisterDataObserver(OH_Preferences *preference, void *context, 265 OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount); 266 267 #ifdef __cplusplus 268 }; 269 #endif 270 271 /** @} */ 272 #endif // OH_PREFERENCES_H