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