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*/ 15import { AsyncCallback, Callback } from './basic'; 16 17/** 18 * Provides interfaces to obtain and modify storage data. 19 * 20 * @name storage 21 * @since 6 22 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 23 * 24 */ 25declare namespace storage { 26 /** 27 * Obtains a {@link Storage} instance matching a specified storage file name. 28 * 29 * <p>The {@link references} instance loads all data of the storage file and 30 * resides in the memory. You can use removeStorageFromCache to remove the instance from the memory. 31 * 32 * @param path Indicates the path of storage file stored. 33 * @return Returns the {@link Storage} instance matching the specified storage file name. 34 * @throws BusinessError if invoked failed 35 * @since 6 36 */ 37 38 function getStorageSync(path: string): Storage; 39 function getStorage(path: string, callback: AsyncCallback<Storage>): void; 40 function getStorage(path: string): Promise<Storage>; 41 42 /** 43 * Deletes a {@link Storage} instance matching a specified storage file name 44 * from the cache which is performed by removeStorageFromCache and deletes the 45 * storage file. 46 * 47 * <p>When deleting the {@link Storage} instance, you must release all references 48 * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency 49 * will occur. 50 * 51 * @param path Indicates the path of storage file 52 * @throws BusinessError if invoked failed 53 * @since 6 54 */ 55 function deleteStorageSync(path: string): void; 56 function deleteStorage(path: string, callback: AsyncCallback<void>): void; 57 function deleteStorage(path: string): Promise<void>; 58 59 /** 60 * Deletes a {@link Storage} instance matching a specified storage file name 61 * from the cache. 62 * 63 * <p>When deleting the {@link Storage} instance, you must release all references 64 * of the instance. In addition, do not use the instance to perform data operations. Otherwise, data inconsistency 65 * will occur. 66 * 67 * @param path Indicates the path of storage file. 68 * @throws BusinessError if invoked failed 69 * @since 6 70 */ 71 function removeStorageFromCacheSync(path: string): void; 72 function removeStorageFromCache(path: string, callback: AsyncCallback<void>): void; 73 function removeStorageFromCache(path: string): Promise<void>; 74 75 /** 76 * Provides interfaces to obtain and modify storage data. 77 * 78 * <p>The storage data is stored in a file, which matches only one {@link Storage} instance in the memory. 79 * You can use getStorage to obtain the {@link Storage} instance matching 80 * the file that stores storage data, and use emoveStorageFromCache 81 * to remove the {@link Storage} instance from the memory. 82 * 83 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 84 * 85 * @since 6 86 */ 87 interface Storage { 88 /** 89 * Obtains the value of a storage in the int format. 90 * 91 * <p>If the value is {@code null} or not in the int format, the default value is returned. 92 * 93 * @param key Indicates the key of the storage. It cannot be {@code null} or empty. 94 * @param defValue Indicates the default value to return. 95 * @return Returns the value matching the specified key if it is found; returns the default value otherwise. 96 * @throws BusinessError if invoked failed 97 * @since 6 98 */ 99 getSync(key: string, defValue: ValueType): ValueType; 100 get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void; 101 get(key: string, defValue: ValueType): Promise<ValueType>; 102 103 /** 104 * Checks whether the {@link Storage} object contains a storage matching a specified key. 105 * 106 * @param key Indicates the key of the storage to check for. 107 * @return Returns {@code true} if the {@link Storage} object contains a storage with the specified key; 108 * returns {@code false} otherwise. 109 * @throws BusinessError if invoked failed 110 * @since 6 111 */ 112 hasSync(key: string): boolean; 113 has(key: string, callback: AsyncCallback<boolean>): boolean; 114 has(key: string): Promise<boolean>; 115 116 /** 117 * Sets an int value for the key in the {@link Storage} object. 118 * 119 * <p>You can call the {@link #flush} or {@link #flushSync} method to save the {@link Storage} object to the 120 * file. 121 * 122 * @param key Indicates the key of the storage to modify. It cannot be {@code null} or empty. 123 * @param value Indicates the value of the storage. 124 * <tt>MAX_KEY_LENGTH</tt>. 125 * @throws BusinessError if invoked failed 126 * @since 6 127 */ 128 putSync(key: string, value: ValueType): void; 129 put(key: string, value: ValueType, callback: AsyncCallback<void>): void; 130 put(key: string, value: ValueType): Promise<void>; 131 132 /** 133 * Deletes the storage with a specified key from the {@link Storage} object. 134 * 135 * <p>You can call the {@link #flush} method to save the {@link Storage} object to the 136 * file. 137 * 138 * @param key Indicates the key of the storage to delete. It cannot be {@code null} or empty. 139 * <tt>MAX_KEY_LENGTH</tt>. 140 * @throws BusinessError if invoked failed 141 * @since 6 142 */ 143 deleteSync(key: string): void; 144 delete(key: string, callback: AsyncCallback<void>): void; 145 delete(key: string): Promise<void>; 146 147 /** 148 * Clears all storage from the {@link Storage} object. 149 * 150 * <p>You can call the {@link #flush} method to save the {@link Storage} object to the 151 * file. 152 * 153 * @throws BusinessError if invoked failed 154 * @since 6 155 */ 156 clearSync(): void; 157 clear(callback: AsyncCallback<void>): void; 158 clear(): Promise<void>; 159 160 /** 161 * Asynchronously saves the {@link Storage} object to the file. 162 * 163 * @throws BusinessError if invoked failed 164 * @since 6 165 */ 166 flushSync(): void; 167 flush(callback: AsyncCallback<void>): void; 168 flush(): Promise<void>; 169 170 /** 171 * Registers an observer to listen for the change of a {@link Storage} object. 172 * 173 * @param callback Indicates the callback when storage changes. 174 * @throws BusinessError if invoked failed 175 * @since 6 176 */ 177 on(type: 'change', callback: Callback<StorageObserver>): void; 178 179 /** 180 * Unregisters an existing observer. 181 * 182 * @param callback Indicates the registered callback. 183 * @throws BusinessError if invoked failed 184 * @since 6 185 */ 186 off(type: 'change', callback: Callback<StorageObserver>): void; 187 } 188 189 /** 190 * Indicates possible value types 191 */ 192 type ValueType = number | string | boolean; 193 194 /** 195 * Define the change data information object. 196 * 197 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 198 * 199 * @since 6 200 */ 201 interface StorageObserver { 202 /** 203 * Indicates which key changes 204 */ 205 key: string; 206 } 207 208 /** 209 * Indicates the maximum length of a key (80 characters). 210 */ 211 const MAX_KEY_LENGTH: 80; 212 213 /** 214 * Indicates the maximum length of a string (8192 characters). 215 */ 216 const MAX_VALUE_LENGTH: 8192; 217} 218 219export default storage; 220