@ohos.request (Upload and Download)

The request module provides applications with basic upload, download, and background transmission agent capabilities.

NOTE

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

Modules to Import

import request from '@ohos.request';

Constants

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Network Types

You can set networkType in DownloadConfig to specify the network type for the download service.

Name Type Value Description
NETWORK_MOBILE number 0x00000001 Whether download is allowed on a mobile network.
NETWORK_WIFI number 0x00010000 Whether download is allowed on a WLAN.

Download Error Codes

The table below lists the values of err in the callback of on('fail')7+ and the values of failedReason returned by getTaskInfo9+.

Name Type Value Description
ERROR_CANNOT_RESUME7+ number 0 Failure to resume the download due to network errors.
ERROR_DEVICE_NOT_FOUND7+ number 1 Failure to find a storage device such as a memory card.
ERROR_FILE_ALREADY_EXISTS7+ number 2 Failure to download the file because it already exists.
ERROR_FILE_ERROR7+ number 3 File operation failure.
ERROR_HTTP_DATA_ERROR7+ number 4 HTTP transmission failure.
ERROR_INSUFFICIENT_SPACE7+ number 5 Insufficient storage space.
ERROR_TOO_MANY_REDIRECTS7+ number 6 Error caused by too many network redirections.
ERROR_UNHANDLED_HTTP_CODE7+ number 7 Unidentified HTTP code.
ERROR_UNKNOWN7+ number 8 Unknown error.
ERROR_OFFLINE9+ number 9 No network connection.
ERROR_UNSUPPORTED_NETWORK_TYPE9+ number 10 Network type mismatch.

Causes of Download Pause

The table below lists the values of pausedReason returned by getTaskInfo9+.

Name Type Value Description
PAUSED_QUEUED_FOR_WIFI7+ number 0 Download paused and queuing for a WLAN connection, because the file size exceeds the maximum value allowed by a mobile network session.
PAUSED_WAITING_FOR_NETWORK7+ number 1 Download paused due to a network connection problem, for example, network disconnection.
PAUSED_WAITING_TO_RETRY7+ number 2 Download paused and then retried.
PAUSED_BY_USER9+ number 3 The user paused the session.
PAUSED_UNKNOWN7+ number 4 Download paused due to unknown reasons.

Download Task Status Codes

The table below lists the values of status returned by getTaskInfo9+.

Name Type Value Description
SESSION_SUCCESSFUL7+ number 0 Successful download.
SESSION_RUNNING7+ number 1 Download in progress.
SESSION_PENDING7+ number 2 Download pending.
SESSION_PAUSED7+ number 3 Download paused.
SESSION_FAILED7+ number 4 Download failure without retry.

request.uploadFile9+

uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask>

Uploads files. This API uses a promise to return the result. You can use on('complete'|'fail')9+ to obtain the upload error information.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
context BaseContext Yes Application-based context.
config UploadConfig Yes Upload configurations.

Return value

Type Description
Promise<UploadTask> Promise used to return the UploadTask object.

Error codes For details about the error codes, see Upload and Download Error Codes.

ID Error Message
13400002 bad file path.

Example

let uploadTask;
let uploadConfig = {
  url: 'https://patch',
  header: { key1: "value1", key2: "value2" },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
try {
  request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => {
    uploadTask = data;
  }).catch((err) => {
      console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
  });
} catch (err) {
  console.error('err.code : ' + err.code + ', err.message : ' + err.message);
}

request.uploadFile9+

uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void

Uploads files. This API uses an asynchronous callback to return the result. You can use on('complete'|'fail')9+ to obtain the upload error information.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
context BaseContext Yes Application-based context.
config UploadConfig Yes Upload configurations.
callback AsyncCallback<UploadTask> Yes Callback used to return the UploadTask object.

Error codes For details about the error codes, see Upload and Download Error Codes.

ID Error Message
13400002 bad file path.

Example

let uploadTask;
let uploadConfig = {
  url: 'https://patch',
  header: { key1: "value1", key2: "value2" },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
try {
  request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => {
    if (err) {
        console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
        return;
    }
    uploadTask = data;
  });
} catch (err) {
  console.error('err.code : ' + err.code + ', err.message : ' + err.message);
}

request.upload(deprecated)

upload(config: UploadConfig): Promise<UploadTask>

Uploads files. This API uses a promise to return the result.

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

NOTE

This API is deprecated since API version 9. You are advised to use request.uploadFile9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
config UploadConfig Yes Upload configurations.

Return value

Type Description
Promise<UploadTask> Promise used to return the UploadTask object.

Example

let uploadTask;
let uploadConfig = {
  url: 'https://patch',
  header: { key1: "value1", key2: "value2" },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
request.upload(uploadConfig).then((data) => {
    uploadTask = data;
}).catch((err) => {
    console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
})

request.upload(deprecated)

upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void

Uploads files. This API uses an asynchronous callback to return the result.

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

NOTE

This API is deprecated since API version 9. You are advised to use request.uploadFile9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
config UploadConfig Yes Upload configurations.
callback AsyncCallback<UploadTask> Yes Callback used to return the UploadTask object.

Example

let uploadTask;
let uploadConfig = {
  url: 'https://patch',
  header: { key1: "value1", key2: "value2" },
  method: "POST",
  files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
  data: [{ name: "name123", value: "123" }],
};
request.upload(uploadConfig, (err, data) => {
    if (err) {
        console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
        return;
    }
    uploadTask = data;
});

UploadTask

Implements file uploads. Before using any APIs of this class, you must obtain an UploadTask object.

on('progress')

on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void

Subscribes to upload progress events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
type string Yes Type of the event to subscribe to. The value is 'progress' (upload progress).
callback function Yes Callback for the upload progress event.

Parameters of the callback function

Name Type Mandatory Description
uploadedSize number Yes Size of the uploaded files, in bits.
totalSize number Yes Total size of the files to upload, in bits.

Example

let upProgressCallback = (uploadedSize, totalSize) => {
    console.info("upload totalSize:" + totalSize + "  uploadedSize:" + uploadedSize);
};
uploadTask.on('progress', upProgressCallback);

on('headerReceive')7+

on(type: 'headerReceive', callback: (header: object) => void): void

Subscribes to HTTP header events for an upload task. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
type string Yes Type of the event to subscribe to. The value is 'headerReceive' (response header).
callback function Yes Callback for the HTTP Response Header event.

Parameters of the callback function

Name Type Mandatory Description
header object Yes HTTP Response Header.

Example

let headerCallback = (headers) => {
    console.info("upOnHeader headers:" + JSON.stringify(headers));
};
uploadTask.on('headerReceive', headerCallback);

on('complete' | 'fail')9+

on(type:'complete' | 'fail', callback: Callback<Array<TaskState>>): void;

Subscribes to upload completion or failure events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
type string Yes Type of the event to subscribe to. The value 'complete' means the upload completion event, and 'fail' means the upload failure event.
callback Callback<Array<TaskState>> Yes Callback used to return the result.

Parameters of the callback function

Name Type Mandatory Description
taskstates Array<TaskState> Yes Upload result.

Example

let upCompleteCallback = (taskStates) => {
  for (let i = 0; i < taskStates.length; i++ ) {
      console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i]));
  }
};
uploadTask.on('complete', upCompleteCallback);

let upFailCallback = (taskStates) => {
  for (let i = 0; i < taskStates.length; i++ ) {
    console.info("upOnFail taskState:" + JSON.stringify(taskStates[i]));
  }
};
uploadTask.on('fail', upFailCallback);

off('progress')

off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void

Unsubscribes from upload progress events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
type string Yes Type of the event to unsubscribe from. The value is 'progress' (upload progress).
callback function No Callback used to return the result.
uploadedSize: size of the uploaded files, in bits.
totalSize: Total size of the files to upload, in bits.

Example

let upProgressCallback = (uploadedSize, totalSize) => {
    console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
};
uploadTask.off('progress', upProgressCallback);

off('headerReceive')7+

off(type: 'headerReceive', callback?: (header: object) => void): void

Unsubscribes from HTTP header events for an upload task. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
type string Yes Type of the event to unsubscribe from. The value is 'headerReceive' (response header).
callback function No Callback used to return the result.
header: HTTP response header.

Example

let headerCallback = (header) => {
    console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`);
};
uploadTask.off('headerReceive', headerCallback);

off('complete' | 'fail')9+

off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void;

Unsubscribes from upload completion or failure events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
type string Yes Type of the event to subscribe to. The value 'complete' means the upload completion event, and 'fail' means the upload failure event.
callback Callback<Array<TaskState>> No Callback used to return the result.
taskstates: upload task result.

Example

let upCompleteCallback = (taskStates) => {
  console.info('Upload delete complete notification.');
  for (let i = 0; i < taskStates.length; i++ ) {
      console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
uploadTask.off('complete', upCompleteCallback);

let upFailCallback = (taskStates) => {
  console.info('Upload delete fail notification.');
  for (let i = 0; i < taskStates.length; i++ ) {
    console.info('taskState:' + JSON.stringify(taskStates[i]));
  }
};
uploadTask.off('fail', upFailCallback);

delete9+

delete(): Promise<boolean>

Deletes this upload task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Return value

Type Description
Promise<boolean> Promise used to return the task removal result. It returns true if the operation is successful and returns false otherwise.

Example

uploadTask.delete().then((result) => {
    if (result) {
        console.info('Upload task removed successfully. ');
    } else {
        console.error('Failed to remove the upload task. ');
    }
}).catch((err) => {
    console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
});

delete9+

delete(callback: AsyncCallback<boolean>): void

Deletes this upload task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the result.

Example

uploadTask.delete((err, result) => {
    if (err) {
        console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
        return;
    }
    if (result) {
        console.info('Upload task removed successfully.');
    } else {
        console.error('Failed to remove the upload task.');
    }
});

remove(deprecated)

remove(): Promise<boolean>

Removes this upload task. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use delete9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Return value

Type Description
Promise<boolean> Promise used to return the task removal result. It returns true if the operation is successful and returns false otherwise.

Example

uploadTask.remove().then((result) => {
    if (result) {
        console.info('Upload task removed successfully. ');
    } else {
        console.error('Failed to remove the upload task. ');
    }
}).catch((err) => {
    console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
});

remove(deprecated)

remove(callback: AsyncCallback<boolean>): void

Removes this upload task. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use delete9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the result.

Example

uploadTask.remove((err, result) => {
    if (err) {
        console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err));
        return;
    }
    if (result) {
        console.info('Upload task removed successfully.');
    } else {
        console.error('Failed to remove the upload task.');
    }
});

UploadConfig

Describes the configuration for an upload task.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Name Type Mandatory Description
url string Yes Resource URL.
header Object Yes HTTP or HTTPS header added to an upload request.
method string Yes Request method, which can be 'POST' or 'PUT'. The default value is 'POST'.
files Array<File> Yes List of files to upload, which is submitted through multipart/form-data.
data Array<RequestData> Yes Form data in the request body.

TaskState9+

Implements a TaskState object, which is the callback parameter of the on('complete' | 'fail')9+ and off('complete' | 'fail')9+ APIs.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Upload

Name Type Mandatory Description
path string Yes File path.
responseCode number Yes Return value of an upload task.
message string Yes Description of the upload task result.

File

Describes the list of files in UploadConfig.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Name Type Mandatory Description
filename string Yes File name in the header when multipart is used.
name string Yes Name of a form item when multipart is used. The default value is file.
uri string Yes Local path for storing files.
Only the internal protocol type is supported. In the value, internal://cache/ is mandatory. Example:
internal://cache/path/to/file.txt
type string Yes Type of the file content. By default, the type is obtained based on the extension of the file name or URI.

RequestData

Describes the form data in UploadConfig.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Name Type Mandatory Description
name string Yes Name of a form element.
value string Yes Value of a form element.

request.downloadFile9+

downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask>

Downloads files. This API uses a promise to return the result. You can use on('complete'|'pause'|'remove')7+ to obtain the download task state, which can be completed, paused, or removed. You can also use on('fail')7+ to obtain the task download error information.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
context BaseContext Yes Application-based context.
config DownloadConfig Yes Download configurations.

Return value

Type Description
Promise<DownloadTask> Promise used to return the result.

Error codes For details about the error codes, see Upload and Download Error Codes.

ID Error Message
13400001 file operation error.
13400002 bad file path.
13400003 task manager service error.

Example

let downloadTask;
try {
  request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => {
      downloadTask = data;
  }).catch((err) => {
      console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
  })
} catch (err) {
  console.error('err.code : ' + err.code + ', err.message : ' + err.message);
}

request.downloadFile9+

downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void;

Downloads files. This API uses an asynchronous callback to return the result. You can use on('complete'|'pause'|'remove')7+ to obtain the download task state, which can be completed, paused, or removed. You can also use on('fail')7+ to obtain the task download error information.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
context BaseContext Yes Application-based context.
config DownloadConfig Yes Download configurations.
callback AsyncCallback<DownloadTask> Yes Callback used to return the result.

Error codes For details about the error codes, see Upload and Download Error Codes.

ID Error Message
13400001 file operation error.
13400002 bad file path.
13400003 task manager service error.

Example

let downloadTask;
try {
  request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', 
  filePath: 'xxx/xxxxx.hap'}, (err, data) => {
      if (err) {
          console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
          return;
      }
      downloadTask = data;
  });
} catch (err) {
  console.error('err.code : ' + err.code + ', err.message : ' + err.message);
}

request.download(deprecated)

download(config: DownloadConfig): Promise<DownloadTask>

Downloads files. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use request.downloadFile9+.

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

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
config DownloadConfig Yes Download configurations.

Return value

Type Description
Promise<DownloadTask> Promise used to return the result.

Example

let downloadTask;
request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => {
    downloadTask = data;
}).catch((err) => {
    console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
})

request.download(deprecated)

download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void

Downloads files. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use request.downloadFile9+.

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

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
config DownloadConfig Yes Download configurations.
callback AsyncCallback<DownloadTask> Yes Callback used to return the result.

Example

let downloadTask;
request.download({ url: 'https://xxxx/xxxxx.hap', 
filePath: 'xxx/xxxxx.hap'}, (err, data) => {
    if (err) {
        console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
        return;
    }
    downloadTask = data;
});

DownloadTask

Implements file downloads.

on('progress')

on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void

Subscribes to download progress events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
type string Yes Type of the event to subscribe to. The value is 'progress' (download progress).
callback function Yes Callback used to return the result.

Parameters of the callback function

Name Type Mandatory Description
receivedSize number Yes Size of the downloaded files, in bits.
totalSize number Yes Total size of the files to download, in bits.

Example

let progresCallback = (receivedSize, totalSize) => {
    console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
};
downloadTask.on('progress', progresCallback);

off('progress')

off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void

Unsubscribes from download progress events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
type string Yes Type of the event to unsubscribe from. The value is 'progress' (download progress).
callback function No Callback used to return the result.
receivedSize: size of the downloaded files.
totalSize: total size of the files to download.

Example

let progresCallback = (receivedSize, totalSize) => {
    console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize);
};
downloadTask.off('progress', progresCallback);

on('complete'|'pause'|'remove')7+

on(type: 'complete'|'pause'|'remove', callback:() => void): void

Subscribes to download events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
type string Yes Type of the event to subscribe to.
- 'complete': download task completion event.
- 'pause': download task pause event.
- 'remove': download task removal event.
callback function Yes Callback used to return the result.

Example

let completeCallback = () => {
    console.info('Download task completed.');
};
downloadTask.on('complete', completeCallback);

let pauseCallback = () => {
    console.info('Download task pause.');
};
downloadTask.on('pause', pauseCallback);

let removeCallback = () => {
    console.info('Download task remove.');
};
downloadTask.on('remove', removeCallback);

off('complete'|'pause'|'remove')7+

off(type: 'complete'|'pause'|'remove', callback?:() => void): void

Unsubscribes from download events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
type string Yes Type of the event to unsubscribe from.
- 'complete': download task completion event.
- 'pause': download task pause event.
- 'remove': download task removal event.
callback function No Callback used to return the result.

Example

let completeCallback = () => {
    console.info('Download delete complete notification.');
};
downloadTask.off('complete', completeCallback);

let pauseCallback = () => {
    console.info('Download delete pause notification.');
};
downloadTask.off('pause', pauseCallback);

let removeCallback = () => {
    console.info('Download delete remove notification.');
};
downloadTask.off('remove', removeCallback);

on('fail')7+

on(type: 'fail', callback: (err: number) => void): void

Subscribes to download failure events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
type string Yes Type of the event to subscribe to. The value is 'fail' (download failure).
callback function Yes Callback for the download task failure event.

Parameters of the callback function

Name Type Mandatory Description
err number Yes Error code of the download failure. For details about the error codes, see Download Error Codes.

Example

let failCallback = (err) => {
    console.info('Download task failed. Cause:' + err);
};
downloadTask.on('fail', failCallback);

off('fail')7+

off(type: 'fail', callback?: (err: number) => void): void

Unsubscribes from download failure events. This API uses a callback to return the result synchronously.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
type string Yes Type of the event to unsubscribe from. The value is 'fail' (download failure).
callback function No Callback used to return the result.
err: error code of the download failure.

Example

let failCallback = (err) => {
    console.info(`Download delete fail notification. err: ${err.message}`);
};
downloadTask.off('fail', failCallback);

delete9+

delete(): Promise<boolean>

Removes this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<boolean> Promise used to return the task removal result.

Example

downloadTask.delete().then((result) => {
    if (result) {
        console.info('Download task removed.');
    } else {
        console.error('Failed to remove the download task.');
    }
}).catch ((err) => {
    console.error('Failed to remove the download task.');
});

delete9+

delete(callback: AsyncCallback<boolean>): void

Deletes this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the task deletion result.

Example

downloadTask.delete((err, result)=>{
    if(err) {
        console.error('Failed to remove the download task.');
        return;
    } 
    if (result) {
        console.info('Download task removed.');
    } else {
        console.error('Failed to remove the download task.');
    } 
});

getTaskInfo9+

getTaskInfo(): Promise<DownloadInfo>

Obtains the information about this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<DownloadInfo> Promise used to return the download task information.

Example

downloadTask.getTaskInfo().then((downloadInfo) => {    
    console.info('Download task queried. Data:' + JSON.stringify(downloadInfo))
}) .catch((err) => {
    console.error('Failed to query the download task. Cause:' + err)
});

getTaskInfo9+

getTaskInfo(callback: AsyncCallback<DownloadInfo>): void

Obtains the information about this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<DownloadInfo> Yes Callback used to return the download task information.

Example

downloadTask.getTaskInfo((err, downloadInfo)=>{
    if(err) {
        console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
    } else {
        console.info('download query success. data:'+ JSON.stringify(downloadInfo));
    }
});

getTaskMimeType9+

getTaskMimeType(): Promise<string>

Obtains the MimeType of this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<string> Promise used to return the MimeType of the download task.

Example

downloadTask.getTaskMimeType().then((data) => {    
    console.info('Download task queried. Data:' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err))
});

getTaskMimeType9+

getTaskMimeType(callback: AsyncCallback<string>): void;

Obtains the MimeType of this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<string> Yes Callback used to return the MimeType of the download task.

Example

downloadTask.getTaskMimeType((err, data)=>{
    if(err) {
        console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
    } else {
        console.info('Download task queried. data:' + JSON.stringify(data));
    }
});

suspend9+

suspend(): Promise<boolean>

Pauses this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<boolean> Promise used to return the download task pause result.

Example

downloadTask.suspend().then((result) => {    
    if (result) {
         console.info('Download task paused. ');
    } else {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
    }
}).catch((err) => {
    console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
});

suspend9+

suspend(callback: AsyncCallback<boolean>): void

Pauses this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the result.

Example

downloadTask.suspend((err, result)=>{
    if(err) {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
        return;
    }
    if (result) {
         console.info('Download task paused. ');
    } else {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
    }
});

restore9+

restore(): Promise<boolean>

Resumes this download task. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<boolean> Promise used to return the result.

Example

downloadTask.restore().then((result) => {
    if (result) {
        console.info('Download task resumed.')
    } else {
        console.error('Failed to resume the download task. ');
    }
    console.info('Download task resumed.')
}).catch((err) => {
    console.error('Failed to resume the download task. Cause:' + err);
});

restore9+

restore(callback: AsyncCallback<boolean>): void

Resumes this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the result.

Example

downloadTask.restore((err, result)=>{
    if (err) {
        console.error('Failed to resume the download task. Cause:' + err);
        return;
    } 
    if (result) {
        console.info('Download task resumed.');
    } else {
        console.error('Failed to resume the download task.');
    }
});

remove(deprecated)

remove(): Promise<boolean>

Removes this download task. This API uses a promise to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use delete9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<boolean> Promise used to return the task removal result.

Example

downloadTask.remove().then((result) => {
    if (result) {
        console.info('Download task removed.');
    } else {
        console.error('Failed to remove the download task.');
    }
}).catch ((err) => {
    console.error('Failed to remove the download task.');
});

remove(deprecated)

remove(callback: AsyncCallback<boolean>): void

Removes this download task. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 9. You are advised to use delete9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the task removal result.

Example

downloadTask.remove((err, result)=>{
    if(err) {
        console.error('Failed to remove the download task.');
        return;
    } 
    if (result) {
        console.info('Download task removed.');
    } else {
        console.error('Failed to remove the download task.');
    } 
});

query(deprecated)

query(): Promise<DownloadInfo>

Queries this download task. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use getTaskInfo9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<DownloadInfo> Promise used to return the download task information.

Example

downloadTask.query().then((downloadInfo) => {    
    console.info('Download task queried. Data:' + JSON.stringify(downloadInfo))
}) .catch((err) => {
    console.error('Failed to query the download task. Cause:' + err)
});

query(deprecated)

query(callback: AsyncCallback<DownloadInfo>): void

Queries this download task. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use getTaskInfo9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<DownloadInfo> Yes Callback used to return the download task information.

Example

downloadTask.query((err, downloadInfo)=>{
    if(err) {
        console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
    } else {
        console.info('download query success. data:'+ JSON.stringify(downloadInfo));
    }
});

queryMimeType(deprecated)

queryMimeType(): Promise<string>

Queries the MimeType of this download task. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use getTaskMimeType9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<string> Promise used to return the MimeType of the download task.

Example

downloadTask.queryMimeType().then((data) => {    
    console.info('Download task queried. Data:' + JSON.stringify(data));
}).catch((err) => {
    console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err))
});

queryMimeType(deprecated)

queryMimeType(callback: AsyncCallback<string>): void;

Queries the MimeType of this download task. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use getTaskMimeType9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<string> Yes Callback used to return the MimeType of the download task.

Example

downloadTask.queryMimeType((err, data)=>{
    if(err) {
        console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err));
    } else {
        console.info('Download task queried. data:' + JSON.stringify(data));
    }
});

pause(deprecated)

pause(): Promise<void>

Pauses this download task. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use suspend9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<void> Promise used to return the download task pause result.

Example

downloadTask.pause().then((result) => {    
    if (result) {
         console.info('Download task paused. ');
    } else {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
    }
}).catch((err) => {
    console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
});

pause(deprecated)

pause(callback: AsyncCallback<void>): void

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use suspend9+.

Pauses this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result.

Example

downloadTask.pause((err, result)=>{
    if(err) {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(err));
        return;
    }
    if (result) {
         console.info('Download task paused. ');
    } else {
        console.error('Failed to pause the download task. Cause:' + JSON.stringify(result));
    }
});

resume(deprecated)

resume(): Promise<void>

Resumes this download task. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use restore9+.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Return value

Type Description
Promise<void> Promise used to return the result.

Example

downloadTask.resume().then((result) => {
    if (result) {
        console.info('Download task resumed.')
    } else {
        console.error('Failed to resume the download task. ');
    }
    console.info('Download task resumed.')
}).catch((err) => {
    console.error('Failed to resume the download task. Cause:' + err);
});

resume(deprecated)

resume(callback: AsyncCallback<void>): void

NOTE

This API is supported since API version 7 and is deprecated since API version 9. You are advised to use restore9+.

Resumes this download task. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result.

Example

downloadTask.resume((err, result)=>{
    if (err) {
        console.error('Failed to resume the download task. Cause:' + err);
        return;
    } 
    if (result) {
        console.info('Download task resumed.');
    } else {
        console.error('Failed to resume the download task.');
    }
});

DownloadConfig

Defines the download task configuration.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Name Type Mandatory Description
url string Yes Resource URL.
header Object No HTTPS flag header to be included in the download request.
The X-TLS-Version parameter in header specifies the TLS version to be used. If this parameter is not set, the CURL_SSLVERSION_TLSv1_2 version is used. Available options are as follows:
CURL_SSLVERSION_TLSv1_0
CURL_SSLVERSION_TLSv1_1
CURL_SSLVERSION_TLSv1_2
CURL_SSLVERSION_TLSv1_3
The X-Cipher-List parameter in header specifies the cipher suite list to be used. If this parameter is not specified, the secure cipher suite list is used. Available options are as follows:
- The TLS 1.2 cipher suite list includes the following ciphers:
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,TLS_DSS_RSA_WITH_AES_256_GCM_SHA384,
TLS_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_AES_128_GCM_SHA256,
TLS_DHE_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256,
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256,
TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_ECDHE_PSK_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_CCM,
TLS_DHE_RSA_WITH_AES_256_CCM,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
TLS_PSK_WITH_AES_256_CCM,TLS_DHE_PSK_WITH_AES_128_CCM,
TLS_DHE_PSK_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_AES_128_CCM,
TLS_ECDHE_ECDSA_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
- The TLS 1.3 cipher suite list includes the following ciphers:
TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_CCM_SHA256
- The TLS 1.3 cipher suite list adds the Chinese national cryptographic algorithm:
TLS_SM4_GCM_SM3,TLS_SM4_CCM_SM3
enableMetered boolean No Whether download is allowed on a metered connection. The default value is false. In general cases, a mobile data connection is metered, while a Wi-Fi connection is not.
- true: allowed
- false: not allowed
enableRoaming boolean No Whether download is allowed on a roaming network. The default value is false.
- true: allowed
- false: not allowed
description string No Description of the download session.
filePath7+ string No Path where the downloaded file is stored.
- In the FA model, use context to obtain the cache directory of the application, for example, **${featureAbility.getContext().getFilesDir()}/test.txt*, and store the file in this directory.
- In the stage model, use AbilityContext to obtain the file path, for example, **${globalThis.abilityContext.tempDir}/test.txt*, and store the file in this path.
networkType number No Network type allowed for download. The default value is NETWORK_MOBILE and NETWORK_WIFI.
- NETWORK_MOBILE: 0x00000001
- NETWORK_WIFI: 0x00010000
title string No Download task name.
background9+ boolean No Whether to enable background task notification so that the download status is displayed in the notification panel. The default value is false.

DownloadInfo7+

Defines the download task information, which is the callback parameter of the getTaskInfo9+ API.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Name Type Mandatory Description
downloadId number Yes ID of the download task.
failedReason number Yes Cause of the download failure. The value can be any constant in Download Error Codes.
fileName string Yes Name of the downloaded file.
filePath string Yes URI of the saved file.
pausedReason number Yes Cause of download pause. The value can be any constant in Causes of Download Pause.
status number Yes Download task status code. The value can be any constant in Download Task Status Codes.
targetURI string Yes URI of the downloaded file.
downloadTitle string Yes Name of the download task.
downloadTotalBytes number Yes Total size of the files to download, in bytes.
description string Yes Description of the download task.
downloadedBytes number Yes Size of the files downloaded, in bytes.