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 * @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 */ 100 int 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 */ 117 int 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 */ 134 int 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 */ 153 int 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 */ 162 void 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 */ 178 int 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 */ 194 int 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 */ 210 int 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 */ 225 int 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 */ 244 int 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 */ 263 int OH_Preferences_UnregisterDataObserver(OH_Preferences *preference, void *context, 264 OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount); 265 266 /** 267 * @brief Check if a type is supported or not. 268 * 269 * @param type the storage type of {@Link Preferences_StorageType}. 270 * @param isSupported Pointer to the Boolean value obtained. 271 * @return Returns the status code of the execution. 272 * {@link PREFERENCES_OK} indicates the operation is successful. 273 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 274 * @since 18 275 */ 276 int OH_Preferences_IsStorageTypeSupported(Preferences_StorageType type, bool *isSupported); 277 278 #ifdef __cplusplus 279 }; 280 #endif 281 282 /** @} */ 283 #endif // OH_PREFERENCES_H