目录

@ohos.request.cacheDownload (Download and Cache)

The request module provides applications with the basic capabilities of file upload and download and background transfer proxy.

The initial APIs of this module are supported since API version 18. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { cacheDownload } from '@kit.BasicServicesKit';

SslType21+

Enumerates secure communication protocols.

System capability: SystemCapability.Request.FileTransferAgent

Name Value Description
TLS 'TLS' TLS.
TLCP 'TLCP' TLCP.

ErrorCode23+

Enumerates the specific types of returned error code.

System capability: SystemCapability.Request.FileTransferAgent

Name Value Description
OTHERS 0xFF Other types of errors that are not classified.
DNS 0x00 DNS-related errors.
TCP 0x10 TCP-related errors.
SSL 0x20 SSL-related errors.
HTTP 0x30 HTTP-related errors.

CacheStrategy23+

Enumerates cache update strategies.

System capability: SystemCapability.Request.FileTransferAgent

Name Value Description
FORCE 0 Forcibly updates the cache, regardless of whether the cache already exists.
LAZY 1 Updates the cache only when the cache does not exist.

TimeoutOptions

Enumerates the timeout configuration option of a task, including the timeout interval for checking network availability and the timeout interval for completing an HTTP request.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Request.FileTransferAgent

Name Type Read-Only Optional Description
networkCheckTimeout number No Yes

Timeout for checking network availability, in seconds. The default value is 20, the minimum value is 0 (a value of 0 means no network availability check is performed), and the maximum value is 20. An exception is thrown when the value is out of range.

Checking the network requires the permission ohos.permission.GET_NETWORK_INFO. Without the permission, the network check fails until timeout.
httpTotalTimeout number No Yes Timeout for completing an HTTP request, in seconds. The default value is 60, the minimum value is 1, and the maximum value is 4294967

RetryOptions

Enumerates retry options of a task, which is used to set the maximum number of retries.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Request.FileTransferAgent

Name Type Read-Only Optional Description
maxRetryCount number No Yes Maximum number of retries when a task fails. The default value is 1, the minimum value is 0, and the maximum value is 10. An exception is thrown when the value is out of range.

CacheDownloadOptions

Provides configuration options for download and cache, including HTTP options, transmission options, and task options.

System capability: SystemCapability.Request.FileTransferAgent

Name Type Read-Only Optional Description
headers Record<string, string> No Yes Request header used by a download task during HTTP transfer. The default value is empty.
sslType21+ SslType No Yes Secure communication protocol, such as TLS or TLCP. TLS is used by default. Currently, TLS and TLCP do not support two-way authentication.
caPath21+ string No Yes CA certificate path. Currently, only the .pem certificate is supported. The CA certificate preset by the system is used by default.
cacheStrategy23+ CacheStrategy No Yes Cache update strategies, including FORCE or LAZY. The FORCE policy is used by default.
retry RetryOptions No Yes

Retry configuration of a task, used to customize the retry behavior for a single task. Set this option when the retry count needs to be specified separately for the task; if not set, it falls back to the global retry configuration (setGlobalRetryOptions), and then to the default value (maxRetryCount defaults to 1).

Since Version: 26.0.0

Model Constraint: This API can be used only in the stage model.
timeout TimeoutOptions No Yes

Timeout configuration of a task, used to customize the timeout behavior for a single task. Set this option when the network check timeout or HTTP request timeout needs to be specified separately for the task; if not set, it falls back to the global timeout configuration (setGlobalTimeoutOptions), and then to the default values (networkCheckTimeout defaults to 20 and httpTotalTimeout defaults to 60).

Since Version: 26.0.0

Model Constraint: This API can be used only in the stage model.

ResourceInfo20+

Describes the pre-downloaded resource information.

System capability: SystemCapability.Request.FileTransferAgent

Name Type Read-Only Optional Description
size number Yes No Size of a pre-downloaded resource after decompression, in bytes. If the value is a positive integer, the resource is successfully downloaded; if the value is -1, the resource fails to be downloaded.

NetworkInfo20+

Describes the pre-downloaded network information.

System capability: SystemCapability.Request.FileTransferAgent

Name Type Read-Only Optional Description
dnsServers string[] Yes No List of DNS servers used when downloading resources.
ip23+ string Yes Yes IP address of the URL when downloading resources. When DNS resolution fails, the IP is undefined.

PerformanceInfo20+

Describes the pre-downloaded performance information.

System capability: SystemCapability.Request.FileTransferAgent

Name Type Read-Only Optional Description
dnsTime number Yes No Time required from startup to DNS resolution completion, in milliseconds (ms).
connectTime number Yes No Time required from startup to TCP connection completion, in milliseconds (ms).
tlsTime number Yes No Time required from startup to TLS connection completion, in milliseconds (ms).
firstSendTime number Yes No Time taken from startup to sending the first byte, in milliseconds.
firstReceiveTime number Yes No Time taken from startup to receiving the first byte, in milliseconds.
totalTime number Yes No Time taken from startup to request completion, in milliseconds.
redirectTime number Yes No Time taken from startup to redirection completion, in milliseconds.

DownloadInfo20+

Describes the pre-downloaded download information.

System capability: SystemCapability.Request.FileTransferAgent

Name Type Read-Only Optional Description
resource ResourceInfo Yes No Pre-downloaded resource information.
network NetworkInfo Yes No Pre-downloaded network information.
performance PerformanceInfo Yes No Pre-downloaded performance information.

DownloadError23+

Describes the error message returned when a pre-download error occurs.

System capability: SystemCapability.Request.FileTransferAgent

Name Type Read-Only Optional Description
errorCode ErrorCode Yes No Specific error type returned by the pre-download error callback.
message string Yes No Error message. A universal error code or HTTP error code is returned.

cacheDownload.download

download(url: string, options: CacheDownloadOptions): void

Downloads a task from a specified URL. If the transfer is successful, the data is downloaded to the memory cache and file cache.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
url string Yes URL of the target resource. HTTP and HTTPS are supported. The URL length cannot exceed 8192 bytes.
options CacheDownloadOptions Yes Cache download options for the target resource.

Error codes

For details about the error codes, see Universal Error Codes.

Error Code Error Message
201 permission denied.
401 parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

// Provide configuration options for the download task.
let options: cacheDownload.CacheDownloadOptions = {
  headers: { 'Accept': 'application/json' },
  sslType: cacheDownload.SslType.TLS,
  caPath: '/path/to/ca.pem',
  cacheStrategy: cacheDownload.CacheStrategy.FORCE,
  retry: { maxRetryCount: 1 },
  timeout: {
    networkCheckTimeout: 20,
    httpTotalTimeout: 60,
  }
};

try {
  // Download the resource. If the download is successful, the resource will be cached to the specified file in the application memory or sandbox directory.
  cacheDownload.download("https://www.example.com", options);
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.cancel

cancel(url: string): void

Cancels an ongoing download task based on the URL. The saved memory cache and file cache are not affected.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
url string Yes URL of the target resource. HTTP and HTTPS are supported. The URL length cannot exceed 8192 bytes.

Error codes

For details about the error codes, see Universal Error Codes.

Error Code Error Message
401 parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

// Provide configuration options for the download task.
let options: cacheDownload.CacheDownloadOptions = {};

try {
  // Download the resource. If the download is successful, the resource will be cached to the specified file in the application memory or sandbox directory.
  cacheDownload.download("https://www.example.com", options);
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}

// Other service logic is omitted here.

try {
  // Cancel the download task when it is not required. The cached data is not affected.
  cacheDownload.cancel("https://www.example.com");
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to cancel the task. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.setMemoryCacheSize

setMemoryCacheSize(bytes: number): void

Sets the upper limit of the memory cache size for the cacheDownload component.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
bytes number Yes Cache storage limit set. The default value is 0B, the minimum value is 0, and the maximum value does not exceed 1073741824B (that is, 1GB). If bytes is set to 0, all cached memory cache content will be cleared.

Error codes

For details about the error codes, see Universal Error Codes.

Error Code Error Message
401 parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  // Set the upper limit of the memory cache size.
  cacheDownload.setMemoryCacheSize(10 * 1024 * 1024);
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to set memory cache size. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.setFileCacheSize

setFileCacheSize(bytes: number): void

Sets the upper limit of the file cache size for the cacheDownload component.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
bytes number Yes Cache storage limit set. Default value: 104857600B (100MB); minimum value: 0; maximum value: no more than 4294967296B (4GB).

Error codes

For details about the error codes, see Universal Error Codes.

Error Code Error Message
401 parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  // Set the upper limit of the file cache size.
  cacheDownload.setFileCacheSize(100 * 1024 * 1024);
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to set file cache size. err code: ${err.code}, err message: ${err.message}`);
}

​>

  • Network cache files downloaded by the cacheDownload module are stored in the cache directory of the application sandbox.
  • An application can use this API to clear cache files.
  • Do not modify the cache directory and files directly to avoid function exceptions.

cacheDownload.setDownloadInfoListSize20+

setDownloadInfoListSize(size: number): void

Sets the size of the download information list.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
size number Yes Size of the download information list to set. Value range: [0, 8192]. The default value is 0, which means no download information is stored. An exception is thrown when the value is out of range.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  // Set the size of the download information list.
  cacheDownload.setDownloadInfoListSize(2048);
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to set download information list size. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.getDownloadInfo20+

getDownloadInfo(url: string): DownloadInfo | undefined

Obtains the pre-downloaded download information based on the URL. The information is stored in the download information list in the memory and is cleared when the application exits. The pre-download information is stored in the list only after setDownloadInfoListSize is called to set the list size (greater than 0). Otherwise, the default list size is 0, no download information is stored, and getDownloadInfo returns undefined.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
url string Yes URL to query. Supports HTTP and HTTPS. The maximum length is 8192 bytes. An exception is thrown when the length limit is exceeded.

Return value

Type Description
DownloadInfo | undefined Returns the download information of the corresponding URL if the operation is successful; returns undefined if the specified URL does not exist.

Error codes

For details about the error codes, see Universal Error Codes.

Error Code Error Message
201 permission denied.

Example

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  // Set the size of the download information list.
  cacheDownload.setDownloadInfoListSize(2048);
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to set download information list size. err code: ${err.code}, err message: ${err.message}`);
}

// Provide configuration options for the download task.
let options: cacheDownload.CacheDownloadOptions = {};

try {
  // Download the resource. If the download is successful, the resource will be cached to the specified file in the application memory or sandbox directory.
  cacheDownload.download("https://www.example.com", options);
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}

// Other service logic is omitted here.

try {
  // Obtain the download information after the download task is complete.
  let downloadInfo = cacheDownload.getDownloadInfo("https://www.example.com");
  if (downloadInfo == undefined) {
    console.error(`CacheDownload get download info undefined.`);
  } else {
    console.info(`CacheDownload get download info : ${JSON.stringify(downloadInfo)}`);
  }
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to get download info. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.clearMemoryCache23+

clearMemoryCache(): void

Clears this memory cache.

System capability: SystemCapability.Request.FileTransferAgent

Example:

import { cacheDownload } from '@kit.BasicServicesKit';
  
cacheDownload.clearMemoryCache();

cacheDownload.clearFileCache23+

clearFileCache(): void

Clears this file cache.

System capability: SystemCapability.Request.FileTransferAgent

Example:

import { cacheDownload } from '@kit.BasicServicesKit';
  
cacheDownload.clearFileCache();

cacheDownload.onDownloadSuccess23+

onDownloadSuccess(url: string, callback: Callback<void>): void

Subscribes to the pre-download completion event. This API uses an asynchronous callback. It is used together with the offDownloadSuccess() method. When the completion event no longer needs to be received, call offDownloadSuccess() to unsubscribe, so as to avoid unnecessary callback overhead.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
url string Yes URL of the callback to register. Both HTTP and HTTPS are supported. The maximum length of the URL string is 8192 bytes. An exception is thrown when the length limit is exceeded.
callback Callback<void> Yes Callback invoked when the download succeeds. No callback parameter is provided.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  const successCallback = () => {
    console.info("Succeeded in getting callback from cacheDownload");
  };
  // Subscribe to the pre-download completion events. Callback is invoked when the download is complete.
  cacheDownload.onDownloadSuccess("https://www.example.com", successCallback);
  // Download the resource. If the download is successful, the resource will be cached to the specified file in the application memory or sandbox directory.
  cacheDownload.download("https://www.example.com", {});
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.onDownloadError23+

onDownloadError(url: string, callback: Callback<DownloadError>): void

Subscribes to the pre-download error event. This API uses an asynchronous callback. It is used together with the offDownloadError() method. When the error event no longer needs to be received, call offDownloadError() to unsubscribe, so as to avoid unnecessary callback overhead.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
url string Yes URL of the callback to register. Both HTTP and HTTPS are supported. The maximum length of the URL string is 8192 bytes. An exception is thrown when the length limit is exceeded.
callback Callback<DownloadError> Yes Callback used to return the error information about the pre-download.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  const errorCallback = (error: cacheDownload.DownloadError) => {
    console.error(`Error callback from cacheDownload. error code: ${error.errorCode}, error message: ${error.message}`);
  };
  // Subscribe to pre-download error events. When a download error occurs, the callback is invoked to return error information.
  cacheDownload.onDownloadError("https://www.example.com", errorCallback);
  // Download the resource. If the download is successful, the resource will be cached to the specified file in the application memory or sandbox directory.
  cacheDownload.download("https://www.example.com", {});
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.offDownloadSuccess23+

offDownloadSuccess(url: string, callback?: Callback<void>): void

Unsubscribes from the pre-download completion event.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
url string Yes URL for which the callback is to be registered. Both HTTP and HTTPS are supported. The maximum length of the URL string is 8192 bytes. An exception is thrown when the length limit is exceeded.
callback Callback<void> No Callback to unsubscribe. If this parameter is not specified, all completion callbacks under the URL are unsubscribed.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  const successCallback = () => {
    console.info("Succeeded in getting callback from cacheDownload");
  };
  // Subscribe to the pre-download completion events. Callback is invoked when the download is complete.
  cacheDownload.onDownloadSuccess("https://www.example.com", successCallback);
  // Unsubscribe from the pre-download completion events.
  cacheDownload.offDownloadSuccess("https://www.example.com", successCallback);
  // Download the resource. If the download is successful, the resource will be cached to the specified file in the application memory or sandbox directory.
  cacheDownload.download("https://www.example.com", {});
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.offDownloadError23+

offDownloadError(url: string, callback?: Callback<DownloadError>): void

Unsubscribes from the pre-download error event.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
url string Yes URL of the callback to register. It supports HTTP and HTTPS. The maximum length of the URL string is 8192 bytes. An exception is thrown when the length limit is exceeded.
callback Callback<DownloadError> No Callback for the error event to unsubscribe. If this parameter is not specified, all error callbacks under the URL are unsubscribed.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  const errorCallback = (error: cacheDownload.DownloadError) => {
    console.error(`Error callback from cacheDownload. error code: ${error.errorCode}, error message: ${error.message}`);
  };
  // Subscribe to pre-download error events. When a download error occurs, the callback is invoked to return error information.
  cacheDownload.onDownloadError("https://www.example.com", errorCallback);
  // Unsubscribe from the pre-download error events.
  cacheDownload.offDownloadError("https://www.example.com", errorCallback);
  // Download the resource. If the download is successful, the resource will be cached to the specified file in the application memory or sandbox directory.
  cacheDownload.download("https://www.example.com", {});
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.setGlobalRetryOptions

setGlobalRetryOptions(options?: RetryOptions): void

Sets the global retry options of a task. This configuration takes effect when no specific retry configuration is set for a task. The retry configuration priority is as follows: task settings > global settings > default settings.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
options RetryOptions No Task retry configuration, used to customize the retry behavior of global tasks. Pass this parameter when you need to adjust policies such as the global retry count; if it is not passed, the current global retry configuration remains unchanged.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  // Set the maximum number of retries for a task globally.
  cacheDownload.setGlobalRetryOptions({
    maxRetryCount: 1
  });
  cacheDownload.download("https://www.example.com", {});
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}

cacheDownload.setGlobalTimeoutOptions

setGlobalTimeoutOptions(options?: TimeoutOptions): void

Sets the global timeout options of a task. This configuration takes effect when no specific timeout configuration is set for a task. The timeout configuration priority is as follows: task settings > global settings > default settings.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Request.FileTransferAgent

Parameters

Name Type Mandatory Description
options TimeoutOptions No Task timeout configuration, used to customize the timeout behavior of global tasks. Pass this parameter when you need to adjust the global network check timeout or HTTP request timeout; if it is not passed, the current global timeout configuration remains unchanged.

Example:

import { cacheDownload, BusinessError } from '@kit.BasicServicesKit';

try {
  // Set the global timeout options of a task.
  cacheDownload.setGlobalTimeoutOptions({
    networkCheckTimeout: 20,
    httpTotalTimeout: 60,
  });
  cacheDownload.download("https://www.example.com", {});
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to download the resource. err code: ${err.code}, err message: ${err.message}`);
}