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 BasicServicesKit 19 */ 20 21import { BusinessError } from './@ohos.base'; 22 23/** 24 * Cache download capability provider. 25 * 26 * @namespace cacheDownload 27 * @syscap SystemCapability.Request.FileTransferAgent 28 * @since 18 29 */ 30declare namespace cacheDownload { 31 /** 32 * Options of the cache download task. 33 * 34 * @typedef CacheDownloadOptions 35 * @syscap SystemCapability.Request.FileTransferAgent 36 * @since 18 37 */ 38 interface CacheDownloadOptions { 39 /** 40 * HTTP headers added to the cache download request. 41 * 42 * @type { ?Record<string, string> } 43 * @syscap SystemCapability.Request.FileTransferAgent 44 * @since 18 45 */ 46 headers?: Record<string, string>; 47 } 48 49 /** 50 * Resource information of historical cache downloads. 51 * 52 * @typedef ResourceInfo 53 * @syscap SystemCapability.Request.FileTransferAgent 54 * @since 20 55 * @arkts 1.1&1.2 56 */ 57 interface ResourceInfo { 58 /** 59 * The decompressed size of the downloaded resource. 60 * 61 * @type { number } 62 * @readonly 63 * @syscap SystemCapability.Request.FileTransferAgent 64 * @since 20 65 * @arkts 1.1&1.2 66 */ 67 readonly size: number; 68 } 69 70 /** 71 * Network information of historical cache downloads. 72 * 73 * @typedef NetworkInfo 74 * @syscap SystemCapability.Request.FileTransferAgent 75 * @since 20 76 * @arkts 1.1&1.2 77 */ 78 interface NetworkInfo { 79 /** 80 * The DNS server list is used when downloading resources. 81 * 82 * @type { string[] } 83 * @readonly 84 * @syscap SystemCapability.Request.FileTransferAgent 85 * @since 20 86 * @arkts 1.1&1.2 87 */ 88 readonly dnsServers: string[]; 89 } 90 91 /** 92 * Performance information of historical cache downloads. 93 * 94 * @typedef PerformanceInfo 95 * @syscap SystemCapability.Request.FileTransferAgent 96 * @since 20 97 * @arkts 1.1&1.2 98 */ 99 interface PerformanceInfo { 100 /** 101 * Time taken from startup to DNS resolution completion, in milliseconds. 102 * 103 * @type { number } 104 * @readonly 105 * @syscap SystemCapability.Request.FileTransferAgent 106 * @since 20 107 * @arkts 1.1&1.2 108 */ 109 readonly dnsTime: number; 110 /** 111 * Time taken from startup to TCP connection completion, in milliseconds. 112 * 113 * @type { number } 114 * @readonly 115 * @syscap SystemCapability.Request.FileTransferAgent 116 * @since 20 117 * @arkts 1.1&1.2 118 */ 119 readonly connectTime: number; 120 /** 121 * Time taken from startup to TLS connection completion, in milliseconds. 122 * 123 * @type { number } 124 * @readonly 125 * @syscap SystemCapability.Request.FileTransferAgent 126 * @since 20 127 * @arkts 1.1&1.2 128 */ 129 readonly tlsTime: number; 130 /** 131 * Time taken from startup to start sending the first byte, in milliseconds. 132 * 133 * @type { number } 134 * @readonly 135 * @syscap SystemCapability.Request.FileTransferAgent 136 * @since 20 137 * @arkts 1.1&1.2 138 */ 139 readonly firstSendTime: number; 140 /** 141 * Time taken from startup to start receiving the first byte, in milliseconds. 142 * 143 * @type { number } 144 * @readonly 145 * @syscap SystemCapability.Request.FileTransferAgent 146 * @since 20 147 * @arkts 1.1&1.2 148 */ 149 readonly firstReceiveTime: number; 150 /** 151 * Time taken from startup to the completion of the request, in milliseconds. 152 * 153 * @type { number } 154 * @readonly 155 * @syscap SystemCapability.Request.FileTransferAgent 156 * @since 20 157 * @arkts 1.1&1.2 158 */ 159 readonly totalTime: number; 160 /** 161 * Time taken from startup to completion of all redirection steps, in milliseconds. 162 * 163 * @type { number } 164 * @readonly 165 * @syscap SystemCapability.Request.FileTransferAgent 166 * @since 20 167 * @arkts 1.1&1.2 168 */ 169 readonly redirectTime: number; 170 } 171 172 /** 173 * Download information of historical cache downloads. 174 * 175 * @typedef DownloadInfo 176 * @syscap SystemCapability.Request.FileTransferAgent 177 * @since 20 178 * @arkts 1.1&1.2 179 */ 180 interface DownloadInfo { 181 /** 182 * Resource information of historical cache downloads. 183 * 184 * @type { ResourceInfo } 185 * @readonly 186 * @syscap SystemCapability.Request.FileTransferAgent 187 * @since 20 188 * @arkts 1.1&1.2 189 */ 190 readonly resource: ResourceInfo; 191 /** 192 * Network information of historical cache downloads. 193 * 194 * @type { NetworkInfo } 195 * @readonly 196 * @syscap SystemCapability.Request.FileTransferAgent 197 * @since 20 198 * @arkts 1.1&1.2 199 */ 200 readonly network: NetworkInfo; 201 /** 202 * Performance information of historical cache downloads. 203 * 204 * @type { PerformanceInfo } 205 * @readonly 206 * @syscap SystemCapability.Request.FileTransferAgent 207 * @since 20 208 * @arkts 1.1&1.2 209 */ 210 readonly performance: PerformanceInfo; 211 } 212 213 /** 214 * Downloads resources at the specified URL. Resources will be stored in memory cache or files cache. 215 * The maximum size of the specified URL is 8192 bytes. 216 * The maximum size of a single resource after decompression is 20,971,520 bytes(20 MB). 217 * If the decompressed size of the downloaded resource exceeds the limit, it will not be recorded in the cache. 218 * 219 * @permission ohos.permission.INTERNET 220 * @param { string } url - URL of the cache download target. 221 * @param { CacheDownloadOptions } options - Options of the cache download task. 222 * @throws { BusinessError } 201 - permission denied. 223 * @throws { BusinessError } 401 - parameter error. Possible causes: 1. Missing mandatory parameters. 224 * <br>2. Incorrect parameter type. 3. Parameter verification failed. 225 * @syscap SystemCapability.Request.FileTransferAgent 226 * @since 18 227 */ 228 function download(url: string, options: CacheDownloadOptions): void; 229 230 /** 231 * Cancels an ongoing cache download task based on the target URL. 232 * The maximum size of the specified URL is 8192 bytes. 233 * 234 * @param { string } url - URL of the cache download target. 235 * @throws { BusinessError } 401 - parameter error. Possible causes: 1. Missing mandatory parameters. 236 * <br>2. Incorrect parameter type. 3. Parameter verification failed. 237 * @syscap SystemCapability.Request.FileTransferAgent 238 * @since 18 239 */ 240 function cancel(url: string): void; 241 242 /** 243 * Sets the size of the memory cache used to store downloaded content. 244 * The default size is 0 bytes. 245 * The maximum size is 1,073,741,824 bytes(1 GB). 246 * 247 * @param { number } bytes - The maximum amount of data cached in memory, in bytes. 248 * @throws { BusinessError } 401 - parameter error. Possible causes: 1. Missing mandatory parameters. 249 * <br>2. Incorrect parameter type. 3. Parameter verification failed. 250 * @syscap SystemCapability.Request.FileTransferAgent 251 * @since 18 252 */ 253 function setMemoryCacheSize(bytes: number): void; 254 255 /** 256 * Sets the size of the file cache used to store downloaded content. 257 * The default size is 104,857,600 bytes(100 MB). 258 * The maximum size is 4,294,967,296 bytes(4 GB). 259 * 260 * @param { number } bytes - The maximum amount of data cached in files, in bytes. 261 * @throws { BusinessError } 401 - parameter error. Possible causes: 1. Missing mandatory parameters. 262 * <br>2. Incorrect parameter type. 3. Parameter verification failed. 263 * @syscap SystemCapability.Request.FileTransferAgent 264 * @since 18 265 */ 266 function setFileCacheSize(bytes: number): void; 267 268 /** 269 * Gets download information of cache downloads based on URL. 270 * These information are stored in memory and cleared when the application exits. 271 * The maximum size of the specified URL is 8192 bytes. 272 * If the specified URL can be found in the download information list, 273 * return { @link DownloadInfo } of the most recent download. 274 * If the specified URL can not be found in the download information list, return `undefined`. 275 * 276 * @permission ohos.permission.GET_NETWORK_INFO 277 * @param { string } url - URL to be queried. 278 * @returns { DownloadInfo | undefined } the information of the specified cache download or none. 279 * @throws { BusinessError } 201 - permission denied. 280 * @syscap SystemCapability.Request.FileTransferAgent 281 * @since 20 282 * @arkts 1.1&1.2 283 */ 284 function getDownloadInfo(url: string): DownloadInfo | undefined; 285 286 /** 287 * Sets the maximum size of the download information list. 288 * The download information list is used to store download infarmation. 289 * URLs and download information correspond one to one. 290 * Each download will generate a download information. 291 * Under the same URL, only the latest download information will be saved. 292 * The default value of the specified size is 0. It means no download information can be stored. 293 * The maximum value of the specified size is 8192. 294 * 295 * @param { number } size - the size of the download information list. 296 * @syscap SystemCapability.Request.FileTransferAgent 297 * @since 20 298 * @arkts 1.1&1.2 299 */ 300 function setDownloadInfoListSize(size: number): void; 301} 302 303export default cacheDownload;