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