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 * @file 18 * @kit ArkData 19 */ 20 21import { Callback } from './@ohos.base'; 22import Context from './application/BaseContext'; 23import collections from '../arkts/@arkts.collections'; 24import lang from '../arkts/@arkts.lang'; 25 26/** 27 * Provides interfaces to obtain and modify preferences data. 28 * 29 * @namespace sendablePreferences 30 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 31 * @atomicservice 32 * @since 12 33 * @name sendablePreferences 34 */ 35declare namespace sendablePreferences { 36 /** 37 * Maximum length of a key. 38 * 39 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 40 * @atomicservice 41 * @since 12 42 */ 43 const MAX_KEY_LENGTH: number; 44 45 /** 46 * Maximum length of a value. 47 * 48 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 49 * @atomicservice 50 * @since 12 51 */ 52 const MAX_VALUE_LENGTH: number; 53 54 /** 55 * Defines the configuration of a preferences file. 56 * 57 * @interface Options 58 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 59 * @atomicservice 60 * @since 12 61 */ 62 interface Options { 63 /** 64 * Name of the preferences file. 65 * 66 * @type { string } 67 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 68 * @atomicservice 69 * @since 12 70 */ 71 name: string; 72 73 /** 74 * Application group ID. 75 * 76 * @type { ?(string | null) } 77 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 78 * @StageModelOnly 79 * @atomicservice 80 * @since 12 81 */ 82 dataGroupId?: string | null; 83 } 84 85 /** 86 * Obtains a {@link Preferences} instance matching the specified preferences file name. 87 * <p>The {@link references} instance loads all data of the preferences file and 88 * resides in the cache. You can use removePreferencesFromCache to remove the instance from the cache. 89 * 90 * @param { Context } context - Indicates the context of application or capability. 91 * @param { Options } options - Indicates information about the preferences file. For details, see {@link Options}. 92 * @returns { Promise<Preferences> } Promise used to return the {@link Preferences}. 93 * @throws { BusinessError } 401 - Parameter error. Possible causes: 94 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 95 * <br>3. Parameter verification failed. 96 * @throws { BusinessError } 801 - Capability not supported. 97 * @throws { BusinessError } 15500000 - Inner error. 98 * @throws { BusinessError } 15501001 - The operations is supported in stage mode only. 99 * @throws { BusinessError } 15501002 - Invalid dataGroupId. 100 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 101 * @atomicservice 102 * @since 12 103 */ 104 function getPreferences(context: Context, options: Options): Promise<Preferences>; 105 106 /** 107 * Obtains a {@link Preferences} instance matching a specified preferences file name. 108 * This API returns the result synchronously. 109 * <p>The {@link references} instance loads all data of the preferences file and 110 * resides in the cache. You can use removePreferencesFromCache to remove the instance from the cache. 111 * 112 * @param { Context } context - Indicates the context of application or capability. 113 * @param { Options } options - Indicates information about the preferences file. For details, see {@link Options}. 114 * @returns { Preferences } return the {@link Preferences}. 115 * @throws { BusinessError } 401 - Parameter error. Possible causes: 116 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 117 * <br>3. Parameter verification failed. 118 * @throws { BusinessError } 801 - Capability not supported. 119 * @throws { BusinessError } 15500000 - Inner error. 120 * @throws { BusinessError } 15501001 - The operations is supported in stage mode only. 121 * @throws { BusinessError } 15501002 - Invalid dataGroupId. 122 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 123 * @atomicservice 124 * @since 12 125 */ 126 function getPreferencesSync(context: Context, options: Options): Preferences; 127 128 /** 129 * Deletes a {@link Preferences} instance matching the specified preferences file name 130 * from the cache (which is equivalent to calling removePreferencesFromCache) and deletes 131 * the preferences file. 132 * <p>When deleting a {@link Preferences} instance, you must release all references 133 * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency 134 * will occur. 135 * 136 * @param { Context } context - Indicates the context of application or capability. 137 * @param { Options } options - Indicates information about the preferences file. For details, see {@link Options}. 138 * @returns { Promise<void> } Promise that returns no value. 139 * @throws { BusinessError } 401 - Parameter error. Possible causes: 140 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 141 * <br>3. Parameter verification failed. 142 * @throws { BusinessError } 801 - Capability not supported. 143 * @throws { BusinessError } 15500000 - Inner error. 144 * @throws { BusinessError } 15500010 - Failed to delete the user preferences persistence file. 145 * @throws { BusinessError } 15501001 - The operations is supported in stage mode only. 146 * @throws { BusinessError } 15501002 - Invalid dataGroupId. 147 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 148 * @atomicservice 149 * @since 12 150 */ 151 function deletePreferences(context: Context, options: Options): Promise<void>; 152 153 /** 154 * Removes a {@link Preferences} instance matching the specified preferences file name 155 * from the cache. 156 * <p>When removing a {@link Preferences} instance, you must release all references 157 * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency 158 * will occur. 159 * 160 * @param { Context } context - Indicates the context of application or capability. 161 * @param { Options } options - Indicates information about the preferences file. For details, see {@link Options}. 162 * @returns { Promise<void> } Promise that returns no value. 163 * @throws { BusinessError } 401 - Parameter error. Possible causes: 164 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 165 * <br>3. Parameter verification failed. 166 * @throws { BusinessError } 801 - Capability not supported. 167 * @throws { BusinessError } 15500000 - Inner error. 168 * @throws { BusinessError } 15501001 - The operations is supported in stage mode only. 169 * @throws { BusinessError } 15501002 - Invalid dataGroupId. 170 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 171 * @atomicservice 172 * @since 12 173 */ 174 function removePreferencesFromCache(context: Context, options: Options): Promise<void>; 175 176 /** 177 * Removes a {@link Preferences} instance matching the specified preferences file name 178 * from the cache. This API returns the result synchronously. 179 * <p>When removing a {@link Preferences} instance, you must release all references 180 * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency 181 * will occur. 182 * 183 * @param { Context } context - Indicates the context of application or capability. 184 * @param { Options } options - Indicates information about the preferences file. For details, see {@link Options}. 185 * @throws { BusinessError } 401 - Parameter error. Possible causes: 186 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 187 * <br>3. Parameter verification failed. 188 * @throws { BusinessError } 801 - Capability not supported. 189 * @throws { BusinessError } 15500000 - Inner error. 190 * @throws { BusinessError } 15501001 - The operations is supported in stage mode only. 191 * @throws { BusinessError } 15501002 - Invalid dataGroupId. 192 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 193 * @atomicservice 194 * @since 12 195 */ 196 function removePreferencesFromCacheSync(context: Context, options: Options): void; 197 198 /** 199 * Provides interfaces to obtain and modify preferences data. 200 * <p>The preferences data is stored in a file, which matches only one {@link Preferences} instance in the cache. 201 * You can use getPreferences to obtain the {@link Preferences} instance matching 202 * the file that stores preferences data, and use removePreferencesFromCache 203 * to remove the {@link Preferences} instance from the cache. 204 * 205 * @interface Preferences 206 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 207 * @atomicservice 208 * @since 12 209 */ 210 interface Preferences extends lang.ISendable { 211 /** 212 * Obtains the value of a preferences instance. 213 * <p>If the value is {@code null} or not in the lang.ISendable format, the default value is returned. 214 * 215 * @param { string } key - Indicates the key of the preferences. It cannot be {@code null} or empty. 216 * <tt>MAX_KEY_LENGTH</tt>. 217 * @param { lang.ISendable } defValue - Indicates the default value to return. 218 * @returns { Promise<lang.ISendable> } Promise used to return the result. If a value matching the specified key 219 * is found, the value is returned. Otherwise, the default value is returned. 220 * @throws { BusinessError } 401 - Parameter error. Possible causes: 221 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 222 * <br>3. Parameter verification failed. 223 * @throws { BusinessError } 15500000 - Inner error. 224 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 225 * @atomicservice 226 * @since 12 227 */ 228 get(key: string, defValue: lang.ISendable): Promise<lang.ISendable>; 229 230 /** 231 * Obtains the value of a preferences instance. This API returns the result synchronously. 232 * <p>If the value is {@code null} or not in the lang.ISendable format, the default value is returned. 233 * 234 * @param { string } key - Indicates the key of the preferences. It cannot be {@code null} or empty. 235 * <tt>MAX_KEY_LENGTH</tt>. 236 * @param { lang.ISendable } defValue - Indicates the default value to return. 237 * @returns { lang.ISendable } If a value matching the specified key is found, the value is returned. Otherwise, 238 * the default value is returned. 239 * @throws { BusinessError } 401 - Parameter error. Possible causes: 240 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 241 * <br>3. Parameter verification failed. 242 * @throws { BusinessError } 15500000 - Inner error. 243 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 244 * @atomicservice 245 * @since 12 246 */ 247 getSync(key: string, defValue: lang.ISendable): lang.ISendable; 248 249 /** 250 * Obtains all the keys and values of a preferences instance in an object. 251 * 252 * @returns { Promise<lang.ISendable> } Promise used to return the values and keys obtained in an object. 253 * @throws { BusinessError } 15500000 - Inner error. 254 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 255 * @atomicservice 256 * @since 12 257 */ 258 getAll(): Promise<lang.ISendable>; 259 260 /** 261 * Obtains all the keys and values of a preferences instance. This API returns the result synchronously. 262 * 263 * @returns { lang.ISendable } Returns the values and keys obtained in an object. 264 * @throws { BusinessError } 15500000 - Inner error. 265 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 266 * @atomicservice 267 * @since 12 268 */ 269 getAllSync(): lang.ISendable; 270 271 /** 272 * Checks whether the {@link Preferences} instance contains a value matching the specified key. 273 * 274 * @param { string } key - Indicates the key of the value to check. It cannot be {@code null} or empty. 275 * <tt>MAX_KEY_LENGTH</tt>. 276 * @returns { Promise<boolean> } Promise used to return the result. {@code true} is returned if the 277 * {@link Preferences} object contains a value matching the specified key; {@code false} is returned otherwise. 278 * @throws { BusinessError } 401 - Parameter error. Possible causes: 279 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 280 * <br>3. Parameter verification failed. 281 * @throws { BusinessError } 15500000 - Inner error. 282 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 283 * @atomicservice 284 * @since 12 285 */ 286 has(key: string): Promise<boolean>; 287 288 /** 289 * Checks whether the {@link Preferences} instance contains a value matching the specified key. 290 * This API returns the result synchronously. 291 * 292 * @param { string } key - Indicates the key of the value to check. It cannot be {@code null} or empty. 293 * <tt>MAX_KEY_LENGTH</tt>. 294 * @returns { boolean } {@code true} is returned if the {@link Preferences} object contains a value matching 295 * the specified key; {@code false} is returned otherwise. 296 * @throws { BusinessError } 401 - Parameter error. Possible causes: 297 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 298 * <br>3. Parameter verification failed. 299 * @throws { BusinessError } 15500000 - Inner error. 300 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 301 * @atomicservice 302 * @since 12 303 */ 304 hasSync(key: string): boolean; 305 306 /** 307 * Sets an lang.ISendable value for the key in the {@link Preferences} object. 308 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the file. 309 * 310 * @param { string } key - Indicates the key of the preferences to set. It cannot be {@code null} or empty. 311 * <tt>MAX_KEY_LENGTH</tt>. 312 * @param { lang.ISendable } value - Indicates the value of the preferences. 313 * <tt>MAX_VALUE_LENGTH</tt>. 314 * @returns { Promise<void> } Promise that returns no value. 315 * @throws { BusinessError } 401 - Parameter error. Possible causes: 316 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 317 * <br>3. Parameter verification failed. 318 * @throws { BusinessError } 15500000 - Inner error. 319 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 320 * @atomicservice 321 * @since 12 322 */ 323 put(key: string, value: lang.ISendable): Promise<void>; 324 325 /** 326 * Sets an lang.ISendable value for the key in the {@link Preferences} object. 327 * This API returns the result synchronously. 328 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the file. 329 * 330 * @param { string } key - Indicates the key of the preferences to set. It cannot be {@code null} or empty. 331 * <tt>MAX_KEY_LENGTH</tt>. 332 * @param { lang.ISendable } value - Indicates the value of the preferences. 333 * <tt>MAX_VALUE_LENGTH</tt>. 334 * @throws { BusinessError } 401 - Parameter error. Possible causes: 335 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 336 * <br>3. Parameter verification failed. 337 * @throws { BusinessError } 15500000 - Inner error. 338 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 339 * @atomicservice 340 * @since 12 341 */ 342 putSync(key: string, value: lang.ISendable): void; 343 344 /** 345 * Deletes the preferences with a specified key from the {@link Preferences} object. 346 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the file. 347 * 348 * @param { string } key - Indicates the key of the preferences to delete. It cannot be {@code null} or empty. 349 * <tt>MAX_KEY_LENGTH</tt>. 350 * @returns { Promise<void> } Promise that returns no value. 351 * @throws { BusinessError } 401 - Parameter error. Possible causes: 352 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 353 * <br>3. Parameter verification failed. 354 * @throws { BusinessError } 15500000 - Inner error. 355 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 356 * @atomicservice 357 * @since 12 358 */ 359 delete(key: string): Promise<void>; 360 361 /** 362 * Deletes the preferences with a specified key from the {@link Preferences} object. This API returns the result 363 * synchronously. 364 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the file. 365 * 366 * @param { string } key - Indicates the key of the preferences to delete. It cannot be {@code null} or empty. 367 * <tt>MAX_KEY_LENGTH</tt>. 368 * @throws { BusinessError } 401 - Parameter error. Possible causes: 369 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 370 * <br>3. Parameter verification failed. 371 * @throws { BusinessError } 15500000 - Inner error. 372 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 373 * @atomicservice 374 * @since 12 375 */ 376 deleteSync(key: string): void; 377 378 /** 379 * Clears all preferences from the {@link Preferences} object. 380 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the file. 381 * 382 * @returns { Promise<void> } Promise that returns no value. 383 * @throws { BusinessError } 15500000 - Inner error. 384 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 385 * @atomicservice 386 * @since 12 387 */ 388 clear(): Promise<void>; 389 390 /** 391 * Clears all preferences from the {@link Preferences} object. This API returns the result synchronously. 392 * <p>You can call the {@link #flush} method to save the {@link Preferences} object to the file. 393 * 394 * @throws { BusinessError } 15500000 - Inner error. 395 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 396 * @atomicservice 397 * @since 12 398 */ 399 clearSync(): void; 400 401 /** 402 * Flushes the {@link Preferences} object to the file. 403 * 404 * @returns { Promise<void> } Promise that returns no value. 405 * @throws { BusinessError } 15500000 - Inner error. 406 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 407 * @atomicservice 408 * @since 12 409 */ 410 flush(): Promise<void>; 411 412 /** 413 * Flushes the {@link Preferences} object to the file. 414 * 415 * @throws { BusinessError } 15500000 - Inner error. 416 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 417 * @atomicservice 418 * @since 14 419 */ 420 flushSync(): void; 421 422 /** 423 * Registers an observer to listen for the change of a {@link Preferences} object. 424 * 425 * @param { 'change' } type - Indicates the type of the event to observe. 426 * @param { Callback<string> } callback - Indicates the callback used to return the preferences changes. 427 * @throws { BusinessError } 401 - Parameter error. Possible causes: 428 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 429 * <br>3. Parameter verification failed. 430 * @throws { BusinessError } 15500000 - Inner error. 431 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 432 * @atomicservice 433 * @since 12 434 */ 435 on(type: 'change', callback: Callback<string>): void; 436 437 /** 438 * Registers an observer to listen for the change of a {@link Preferences} object in multiple processes. 439 * 440 * @param { 'multiProcessChange' } type - Indicates the type of the event to observe. 441 * @param { Callback<string> } callback - Indicates the callback used to return the preferences changed 442 * in multiple processes. 443 * @throws { BusinessError } 401 - Parameter error. Possible causes: 444 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 445 * <br>3. Parameter verification failed. 446 * @throws { BusinessError } 15500000 - Inner error. 447 * @throws { BusinessError } 15500019 - Failed to obtain the subscription service. 448 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 449 * @atomicservice 450 * @since 12 451 */ 452 on(type: 'multiProcessChange', callback: Callback<string>): void; 453 454 /** 455 * Registers an observer to listen for changes to the {@link Preferences} object. 456 * 457 * @param { 'dataChange' } type - Indicates the type of the event to observe. 458 * @param { Array<string> } keys - Indicates one or more keys to listen for. 459 * @param { Callback<lang.ISendable> } callback - Indicates the callback used to return the data change. 460 * @throws { BusinessError } 401 - Parameter error. Possible causes: 461 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 462 * <br>3. Parameter verification failed. 463 * @throws { BusinessError } 15500000 - Inner error. 464 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 465 * @atomicservice 466 * @since 12 467 */ 468 on(type: 'dataChange', keys: Array<string>, callback: Callback<lang.ISendable>): void; 469 470 /** 471 * Unregisters an observer used to listen for changes to the {@link Preferences} object. 472 * 473 * @param { 'change' } type - Indicates the event type. 474 * @param { Callback<string> } callback - Indicates the callback to unregister. 475 * @throws { BusinessError } 401 - Parameter error. Possible causes: 476 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 477 * <br>3. Parameter verification failed. 478 * @throws { BusinessError } 15500000 - Inner error. 479 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 480 * @atomicservice 481 * @since 12 482 */ 483 off(type: 'change', callback?: Callback<string>): void; 484 485 /** 486 * Unregisters an observer used to listen for the preferences changed in multiple processes. 487 * 488 * @param { 'multiProcessChange' } type - Indicates the event type. 489 * @param { Callback<string> } callback - Indicates the callback to unregister. 490 * @throws { BusinessError } 401 - Parameter error. Possible causes: 491 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 492 * <br>3. Parameter verification failed. 493 * @throws { BusinessError } 15500000 - Inner error. 494 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 495 * @atomicservice 496 * @since 12 497 */ 498 off(type: 'multiProcessChange', callback?: Callback<string>): void; 499 500 /** 501 * Unregisters an observer for changes to the {@ link Preferences} object. 502 * 503 * @param { 'dataChange' } type - Indicates the event type. 504 * @param { Array<string> } keys - Indicates the data whose changes are not observed. 505 * @param { Callback<lang.ISendable> } callback - Indicates the callback to unregister. 506 * @throws { BusinessError } 401 - Parameter error. Possible causes: 507 * <br>1. Mandatory parameters are left unspecified; <br>2. Incorrect parameter types; 508 * <br>3. Parameter verification failed. 509 * @throws { BusinessError } 15500000 - Inner error. 510 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 511 * @atomicservice 512 * @since 12 513 */ 514 off(type: 'dataChange', keys: Array<string>, callback?: Callback<lang.ISendable>): void; 515 } 516} 517 518export default sendablePreferences; 519