@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';

Constraints

Only HTTP requests are supported. HTTPS requests are not supported.

The download server must support the HTTP HEAD method so that the size of the data to download can be obtained through Content-length. Otherwise, the download task fails. If this is the case, you can check the failure cause through on('fail')7+.

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 error codes that may be returned by on('fail')7+/off('fail')7+/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 causes of download pause that may be 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 download task status codes that may be 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 an upload event. 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
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

uploadTask.on('progress', function callback(uploadedSize, totalSize) {
    console.info("upload totalSize:" + totalSize + "  uploadedSize:" + uploadedSize);
}
);

on('headerReceive')7+

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

Subscribes to an upload event. 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
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

uploadTask.on('headerReceive', function callback(headers){   
    console.info("upOnHeader headers:" + JSON.stringify(headers));
}
);

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

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

Subscribes to an upload event. 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
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

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

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

off('progress')

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

Unsubscribes from an upload event. 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
type string Yes Type of the event to unsubscribe from. The value is 'progress' (upload progress).
callback function No 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

uploadTask.off('progress', function callback(uploadedSize, totalSize) {
    console.info('uploadedSize: ' + uploadedSize, 'totalSize: ' + totalSize);
}
);

off('headerReceive')7+

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

Unsubscribes from an upload event. 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
type string Yes Type of the event to unsubscribe from. The value is 'headerReceive' (response header).
callback function No Callback for the HTTP Response Header event.

Parameters of the callback function

Name Type Mandatory Description
header object Yes HTTP Response Header.

Example

uploadTask.off('headerReceive', function callback(headers) {
    console.info("upOnHeader headers:" + JSON.stringify(headers));
}
);

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

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

Unsubscribes from an upload event. 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
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.

Parameters of the callback function

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

Example

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

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

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 a download event. 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
type string Yes Type of the event to subscribe to. The value is 'progress' (download progress).
callback function Yes Callback for the download progress event.

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

downloadTask.on('progress', function download_callback(receivedSize, totalSize) {
    console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
}
);

off('progress')

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

Unsubscribes from a download event. 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
type string Yes Type of the event to unsubscribe from. The value is 'progress' (download progress).
callback function No Callback for the download progress event.

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

downloadTask .off('progress', function download_callback(receivedSize, totalSize) {
    console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
}
);

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

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

Subscribes to a download event. 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
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

downloadTask.on('complete', function callback() {
    console.info('Download task completed.');
}
);

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

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

Unsubscribes from a download event. 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
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

downloadTask.off('complete', function callback() {
    console.info('Download task completed.');
}
);

on('fail')7+

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

Subscribes to the download task failure event. 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
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

downloadTask.on('fail', function callBack(err) {
    console.info('Download task failed. Cause:' + err);
}
);

off('fail')7+

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

Unsubscribes from the download task failure event. 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
type string Yes Type of the event to unsubscribe from. The value is 'fail' (download failure).
callback function No 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

downloadTask.off('fail', function callBack(err) {
    console.info('Download task failed. Cause:' + err);
} 
);

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.
- true: allowed
- false: not allowed
enableRoaming boolean No Whether download is allowed on a roaming network.
- true: allowed
- false: not allowed
description string No Description of the download session.
filePath7+ string No Path where the downloaded file is stored.
- filePath:'/data/storage/el2/base/haps/entry/files/test.txt': Save the file to an absolute path.
- 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.
- NETWORK_MOBILE: 0x00000001
- NETWORK_WIFI: 0x00010000
title string No Download task name.
background9+ boolean No Whether to enable the background task notification. When this parameter is enabled, the download status is displayed in the notification panel.

DownloadInfo7+

Defines the download task information, which is the callback parameter of the query(deprecated) API.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.MiscServices.Download

Name Type Mandatory Description
downloadId number Yes ID of the downloaded file.
failedReason number No 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 No 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 Download task name.
downloadTotalBytes number Yes Total size of the files to download, in bytes.
description string Yes Description of the file to download.
downloadedBytes number Yes Size of the files downloaded, in bytes.