1/* 2* Copyright (c) 2022 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*/ 15import {AsyncCallback, Callback} from './basic'; 16import Context from "./application/BaseContext"; 17 18/** 19 * Provides interfaces to obtain and modify preferences data. 20 * 21 * @name preferences 22 * @since 9 23 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 24 * 25 */ 26declare namespace preferences { 27 /** 28 * Obtains a {@link Preferences} instance matching a specified preferences file name. 29 * 30 * <p>The {@link references} instance loads all data of the preferences file and 31 * resides in the memory. You can use removePreferencesFromCache to remove the instance from the memory. 32 * 33 * @param {Context} context - Indicates the context of application or capability. 34 * @param {string} name - Indicates the preferences file name. 35 * @param {AsyncCallback<Preferences>} callback - the {@link Preferences} instance matching the specified 36 * preferences file name. 37 * @throws {BusinessError} 401 - if the parameter type is incorrect. 38 * @since 9 39 */ 40 function getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void; 41 42 /** 43 * Obtains a {@link Preferences} instance matching a specified preferences file name. 44 * 45 * <p>The {@link references} instance loads all data of the preferences file and 46 * resides in the memory. You can use removePreferencesFromCache to remove the instance from the memory. 47 * 48 * @param {Context} context - Indicates the context of application or capability. 49 * @param {string} name - Indicates the preferences file name. 50 * @returns {Promise<Preferences>} the {@link Preferences} instance matching the specified preferences file name. 51 * @throws {BusinessError} 401 - if the parameter type is incorrect. 52 * @since 9 53 */ 54 function getPreferences(context: Context, name: string): Promise<Preferences>; 55 56 /** 57 * Deletes a {@link Preferences} instance matching a specified preferences file name 58 * from the cache which is performed by removePreferencesFromCache and deletes the 59 * preferences file. 60 * 61 * <p>When deleting the {@link Preferences} instance, you must release all references 62 * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency 63 * will occur. 64 * 65 * @param {Context} context - Indicates the context of application or capability. 66 * @param {string} name - Indicates the preferences file name. 67 * @param {AsyncCallback<void>} callback - Indicates the callback function. 68 * @throws {BusinessError} 401 - if the parameter type is incorrect. 69 * @throws {BusinessError} 15500010 - if failed to delete preferences file. 70 * @since 9 71 */ 72 function deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void; 73 74 /** 75 * Deletes a {@link Preferences} instance matching a specified preferences file name 76 * from the cache which is performed by removePreferencesFromCache and deletes the 77 * preferences file. 78 * 79 * <p>When deleting the {@link Preferences} instance, you must release all references 80 * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency 81 * will occur. 82 * 83 * @param {Context} context - Indicates the context of application or capability. 84 * @param {string} name - Indicates the preferences file name. 85 * @returns {Promise<void>} a promise object. 86 * @throws {BusinessError} 401 - if the parameter type is incorrect. 87 * @throws {BusinessError} 15500010 - if failed to delete preferences file. 88 * @since 9 89 */ 90 function deletePreferences(context: Context, name: string): Promise<void>; 91 92 /** 93 * Deletes a {@link Preferences} instance matching a specified preferences file name 94 * from the cache. 95 * 96 * <p>When deleting the {@link Preferences} instance, you must release all references 97 * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency 98 * will occur. 99 * 100 * @param {Context} context - Indicates the context of application or capability. 101 * @param {string} name - Indicates the preferences file name. 102 * @param {AsyncCallback<void>} callback - Indicates the callback function. 103 * @throws {BusinessError} 401 - if the parameter type is incorrect. 104 * @since 9 105 */ 106 function removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback<void>): void; 107 108 /** 109 * Deletes a {@link Preferences} instance matching a specified preferences file name 110 * from the cache. 111 * 112 * <p>When deleting the {@link Preferences} instance, you must release all references 113 * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency 114 * will occur. 115 * 116 * @param {Context} context - Indicates the context of application or capability. 117 * @param {string} name - Indicates the preferences file name. 118 * @returns {Promise<void>} a promise object. 119 * @throws {BusinessError} 401 - if the parameter type is incorrect. 120 * @since 9 121 */ 122 function removePreferencesFromCache(context: Context, name: string): Promise<void>; 123 124 /** 125 * Provides interfaces to obtain and modify preferences data. 126 * 127 * <p>The preferences data is stored in a file, which matches only one {@link Preferences} instance in the memory. 128 * You can use getPreferences to obtain the {@link Preferences} instance matching 129 * the file that stores preferences data, and use movePreferencesFromCache 130 * to remove the {@link Preferences} instance from the memory. 131 * 132 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 133 * 134 * @since 9 135 */ 136 interface Preferences { 137 /** 138 * Obtains the value of a preferences in the int format. 139 * 140 * <p>If the value is {@code null} or not in the int format, the default value is returned. 141 * 142 * @param {string} key - Indicates the key of the preferences. It cannot be {@code null} or empty. 143 * @param {ValueType} defValue - Indicates the default value to return. 144 * @param {AsyncCallback<ValueType>} callback - the value matching the specified key if it is found; 145 * returns the default value otherwise. 146 * @throws {BusinessError} 401 - if the parameter type is incorrect. 147 * @since 9 148 */ 149 get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void; 150 151 /** 152 * Obtains the value of a preferences in the int format. 153 * 154 * <p>If the value is {@code null} or not in the int format, the default value is returned. 155 * 156 * @param {string} key - Indicates the key of the preferences. It cannot be {@code null} or empty. 157 * @param {ValueType} defValue - Indicates the default value to return. 158 * @returns {Promise<ValueType>} the value matching the specified key if it is found; 159 * returns the default value otherwise. 160 * @throws {BusinessError} 401 - if the parameter type is incorrect. 161 * @since 9 162 */ 163 get(key: string, defValue: ValueType): Promise<ValueType>; 164 165 /** 166 * Obtains all the keys and values of a preferences in an object. 167 * 168 * @param {AsyncCallback<Object>} callback - the values and keys in an object. 169 * @throws {BusinessError} 401 - if the parameter type is incorrect. 170 * @since 9 171 */ 172 getAll(callback: AsyncCallback<Object>): void; 173 174 /** 175 * Obtains all the keys and values of a preferences in an object. 176 * 177 * @returns {Promise<Object>} the values and keys in an object. 178 * @throws {BusinessError} 401 - if the parameter type is incorrect. 179 * @since 9 180 */ 181 getAll(): Promise<Object>; 182 183 /** 184 * Checks whether the {@link Preferences} object contains a preferences matching a specified key. 185 * 186 * @param {string} key - Indicates the key of the preferences to modify. It cannot be {@code null} or empty. 187 * @param {AsyncCallback<boolean>} callback - {@code true} if the {@link Preferences} object contains a preferences 188 * with the specified key;returns {@code false} otherwise. 189 * @throws {BusinessError} 401 - if the parameter type is incorrect. 190 * @since 9 191 */ 192 has(key: string, callback: AsyncCallback<boolean>): void; 193 194 /** 195 * Checks whether the {@link Preferences} object contains a preferences matching a specified key. 196 * 197 * @param {string} key - Indicates the key of the preferences to modify. It cannot be {@code null} or empty. 198 * @returns {Promise<void>} {@code true} if the {@link Preferences} object contains 199 * a preferences with the specified key; returns {@code false} otherwise. 200 * @throws {BusinessError} 401 - if the parameter type is incorrect. 201 * @since 9 202 */ 203 has(key: string): Promise<boolean>; 204 205 /** 206 * Sets an int value for the key in the {@link Preferences} object. 207 * 208 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the 209 * file. 210 * 211 * @param {string} key - Indicates the key of the preferences to modify. It cannot be {@code null} or empty. 212 * @param {ValueType} value - Indicates the value of the preferences. 213 * <tt>MAX_KEY_LENGTH</tt>. 214 * @param {AsyncCallback<void>} callback - Indicates the callback function. 215 * @throws {BusinessError} 401 - if the parameter type is incorrect. 216 * @since 9 217 */ 218 put(key: string, value: ValueType, callback: AsyncCallback<void>): void; 219 220 /** 221 * Sets an int value for the key in the {@link Preferences} object. 222 * 223 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the 224 * file. 225 * 226 * @param {string} key - Indicates the key of the preferences to modify. It cannot be {@code null} or empty. 227 * @param {ValueType} value - Indicates the value of the preferences. 228 * <tt>MAX_KEY_LENGTH</tt>. 229 * @returns {Promise<void>} a promise object. 230 * @throws {BusinessError} 401 - if the parameter type is incorrect. 231 * @since 9 232 */ 233 put(key: string, value: ValueType): Promise<void>; 234 235 /** 236 * Deletes the preferences with a specified key from the {@link Preferences} object. 237 * 238 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the 239 * file. 240 * 241 * @param {string} key - Indicates the key of the preferences to delete. It cannot be {@code null} or empty. 242 * <tt>MAX_KEY_LENGTH</tt>. 243 * @param {AsyncCallback<void>} callback - Indicates the callback function. 244 * @throws {BusinessError} 401 - if the parameter type is incorrect. 245 * @since 9 246 */ 247 delete(key: string, callback: AsyncCallback<void>): void; 248 249 /** 250 * Deletes the preferences with a specified key from the {@link Preferences} object. 251 * 252 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the 253 * file. 254 * 255 * @param {string} key - Indicates the key of the preferences to delete. It cannot be {@code null} or empty. 256 * <tt>MAX_KEY_LENGTH</tt>. 257 * @returns {Promise<void>} a promise object. 258 * @throws {BusinessError} 401 - if the parameter type is incorrect. 259 * @since 9 260 */ 261 delete(key: string): Promise<void>; 262 263 /** 264 * Clears all preferences from the {@link Preferences} object. 265 * 266 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the file. 267 * 268 * @param {AsyncCallback<void>} callback - Indicates the callback function. 269 * @since 9 270 */ 271 clear(callback: AsyncCallback<void>): void; 272 273 /** 274 * Clears all preferences from the {@link Preferences} object. 275 * 276 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the file. 277 * 278 * @returns {Promise<void>} a promise object. 279 * @since 9 280 */ 281 clear(): Promise<void>; 282 283 /** 284 * Asynchronously saves the {@link Preferences} object to the file. 285 * 286 * @param {AsyncCallback<void>} callback - Indicates the callback function. 287 * @since 9 288 */ 289 flush(callback: AsyncCallback<void>): void; 290 291 /** 292 * Asynchronously saves the {@link Preferences} object to the file. 293 * 294 * @returns {Promise<void>} a promise object. 295 * @since 9 296 */ 297 flush(): Promise<void>; 298 299 /** 300 * Registers an observer to listen for the change of a {@link Preferences} object. 301 * 302 * @param {Callback} callback - indicates the callback when preferences changes. 303 * @param {Callback<{key: string}>} callback - Indicates the callback function. 304 * @throws {BusinessError} 401 - if the parameter type is incorrect. 305 * @since 9 306 */ 307 on(type: 'change', callback: Callback<{ key: string }>): void; 308 309 /** 310 * Unregisters an existing observer. 311 * 312 * @param {Callback} callback - indicates the callback when preferences changes. 313 * @param {Callback<{key: string}>} callback - Indicates the callback function. 314 * @throws {BusinessError} 401 - if the parameter type is incorrect. 315 * @since 9 316 */ 317 off(type: 'change', callback?: Callback<{ key: string }>): void; 318 } 319 320 /** 321 * Indicates possible value types 322 */ 323 type ValueType = number | string | boolean | Array<number> | Array<string> | Array<boolean>; 324 325 /** 326 * Indicates the maximum length of a key (80 characters). 327 */ 328 const MAX_KEY_LENGTH: 80; 329 330 /** 331 * Indicates the maximum length of a string (8192 characters). 332 */ 333 const MAX_VALUE_LENGTH: 8192; 334} 335 336export default preferences; 337