@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 upload task. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400002 | bad file path. |
Example
let uploadTask: request.UploadTask;
let uploadConfig: request.UploadConfig = {
url: 'http://www.example.com', // Replace the example with the actual server address.
header: { 'Accept': '*/*' },
method: "POST",
files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
data: [{ name: "name123", value: "123" }],
};
try {
request.uploadFile(getContext(), uploadConfig).then((data: request.UploadTask) => {
uploadTask = data;
}).catch((err: BusinessError) => {
console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
});
} catch (err) {
console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`);
}
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
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: request.UploadTask;
let uploadConfig: request.UploadConfig = {
url: 'http://www.example.com', // Replace the example with the actual server address.
header: { 'Accept': '*/*' },
method: "POST",
files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
data: [{ name: "name123", value: "123" }],
};
try {
request.uploadFile(getContext(), uploadConfig, (err: BusinessError, data: request.UploadTask) => {
if (err) {
console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`);
return;
}
uploadTask = data;
});
} catch (err) {
console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`);
}
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
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+ instead.
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 upload task. |
Example
let uploadTask;
let uploadConfig = {
url: 'http://www.example.com', // Replace the example with the actual server address.
header: { 'Accept': '*/*' },
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. Code: ${err.code}, message: ${err.message}`);
})
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+ instead.
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: 'http://www.example.com', // Replace the example with the actual server address.
header: { 'Accept': '*/*' },
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. Code: ${err.code}, message: ${err.message}`);
return;
}
uploadTask = data;
});
UploadTask
Implements file uploads. Before using any APIs of this class, you must obtain an UploadTask object through request.uploadFile9+ in promise mode or request.uploadFile9+ in callback mode.
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 asynchronously.
NOTE
To maintain a balance between power consumption and performance, this API cannot be called when the application is running in the background.
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 bytes. |
totalSize | number | Yes | Total size of the files to upload, in bytes. |
Example
let upProgressCallback = (uploadedSize: number, totalSize: number) => {
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 the upload task. This API uses a callback to return the result asynchronously.
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: object) => {
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 asynchronously.
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: Array<request.TaskState>) => {
for (let i = 0; i < taskStates.length; i++) {
console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i]));
}
};
uploadTask.on('complete', upCompleteCallback);
let upFailCallback = (taskStates: Array<request.TaskState>) => {
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.
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 to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. uploadedSize: size of the uploaded files, in B. totalSize: Total size of the files to upload, in B. |
Example
let upProgressCallback1 = (uploadedSize: number, totalSize: number) => {
console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
};
let upProgressCallback2 = (uploadedSize: number, totalSize: number) => {
console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize);
};
uploadTask.on('progress', upProgressCallback1);
uploadTask.on('progress', upProgressCallback2);
// Unsubscribe from upProgressCallback1.
uploadTask.off('progress', upProgressCallback1);
// Unsubscribe from all callbacks of upload progress events.
uploadTask.off('progress');
off('headerReceive')7+
off(type: 'headerReceive', callback?: (header: object) => void): void
This interface is used to unsubscribe from the HTTP header event of an upload task.
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 to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Example
let headerCallback1 = (header: object) => {
console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`);
};
let headerCallback2 = (header: object) => {
console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`);
};
uploadTask.on('headerReceive', headerCallback1);
uploadTask.on('headerReceive', headerCallback2);
// Unsubscribe from headerCallback1.
uploadTask.off('headerReceive', headerCallback1);
// Unsubscribe from all callbacks of the HTTP header events for the upload task.
uploadTask.off('headerReceive');
off('complete' | 'fail')9+
off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void;
Unsubscribes from upload completion or failure events.
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 to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Example
let upCompleteCallback1 = (taskStates: Array<request.TaskState>) => {
console.info('Upload delete complete notification.');
for (let i = 0; i < taskStates.length; i++) {
console.info('taskState:' + JSON.stringify(taskStates[i]));
}
};
let upCompleteCallback2 = (taskStates: Array<request.TaskState>) => {
console.info('Upload delete complete notification.');
for (let i = 0; i < taskStates.length; i++) {
console.info('taskState:' + JSON.stringify(taskStates[i]));
}
};
uploadTask.on('complete', upCompleteCallback1);
uploadTask.on('complete', upCompleteCallback2);
// Unsubscribe from headerCallback1.
uploadTask.off('complete', upCompleteCallback1);
// Unsubscribe from all callbacks of the upload completion events.
uploadTask.off('complete');
let upFailCallback1 = (taskStates: Array<request.TaskState>) => {
console.info('Upload delete fail notification.');
for (let i = 0; i < taskStates.length; i++) {
console.info('taskState:' + JSON.stringify(taskStates[i]));
}
};
let upFailCallback2 = (taskStates: Array<request.TaskState>) => {
console.info('Upload delete fail notification.');
for (let i = 0; i < taskStates.length; i++) {
console.info('taskState:' + JSON.stringify(taskStates[i]));
}
};
uploadTask.on('fail', upFailCallback1);
uploadTask.on('fail', upFailCallback2);
// Unsubscribe from headerCallback1.
uploadTask.off('fail', upFailCallback1);
// Unsubscribe from all callbacks of the upload failure events.
uploadTask.off('fail');
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 result. The value true indicates that the operation is successful, and the value false indicates the opposite. |
Example
uploadTask.delete().then((result: boolean) => {
console.info('Succeeded in deleting the upload task.');
}).catch((err: BusinessError) => {
console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`);
});
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. The value true indicates that the operation is successful, and the value false indicates the opposite. |
Example
uploadTask.delete((err: BusinessError, result: boolean) => {
if (err) {
console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in deleting 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+ instead.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.MiscServices.Upload
Return value
Type | Description |
---|---|
Promise<boolean> | Promise used to return the result. The value true indicates that the operation is successful, and the value false indicates the opposite. |
Example
uploadTask.remove().then((result) => {
console.info('Succeeded in removing the upload task.');
}).catch((err) => {
console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
});
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+ instead.
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. The value true indicates that the operation is successful, and the value false indicates the opposite. |
Example
uploadTask.remove((err, result) => {
if (err) {
console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
return;
}
if (result) {
console.info('Succeeded in removing the upload task.');
} else {
console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`);
}
});
UploadConfig6+
Describes the configuration of 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'. |
index11+ | number | No | Path index of the task. The default value is 0. |
begins11+ | number | No | File start point to read when the task begins. The default value is 0. The value is a closed interval. |
ends11+ | number | No | File start point to read when the task ends. The default value is -1. The value is a closed interval. |
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. The value 0 means that the task is successful, and other values means that the task fails. For details about the task result, see message. |
message | string | Yes | Description of the upload task result. |
File
Defines the file list in UploadConfig6+.
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 is currently supported. internal://cache/ is the private directory of the application and 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
Defines the form data in UploadConfig6+.
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 configuration. |
Return value
Type | Description |
---|---|
Promise<DownloadTask> | Promise used to return the download task. |
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 service ability error. |
Example
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
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 configuration. |
callback | AsyncCallback<DownloadTask> | Yes | Callback used to return the download task. |
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 service ability error. |
Example
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), {
url: 'https://xxxx/xxxxx.hap',
filePath: 'xxx/xxxxx.hap'
}, (err: BusinessError, data: request.DownloadTask) => {
if (err) {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
return;
}
let downloadTask: request.DownloadTask = data;
});
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
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+ instead.
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 configuration. |
Return value
Type | Description |
---|---|
Promise<DownloadTask> | Promise used to return the download task. |
Example
let downloadTask;
request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => {
downloadTask = data;
}).catch((err) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
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+ instead.
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 configuration. |
callback | AsyncCallback<DownloadTask> | Yes | Callback used to return the download task. |
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. Code: ${err.code}, message: ${err.message}`);
return;
}
downloadTask = data;
});
DownloadTask
Implements file downloads. Before using any APIs of this class, you must obtain a DownloadTask object through request.downloadFile9+ in promise mode or request.downloadFile9+ in callback mode.
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 asynchronously.
NOTE
To maintain a balance between power consumption and performance, this API cannot be called when the application is running in the background.
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 bytes. |
totalSize | number | Yes | Total size of the files to download, in bytes. |
Example
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
let progressCallback = (receivedSize: number, totalSize: number) => {
console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize);
};
downloadTask.on('progress', progressCallback);
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
off('progress')
off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void
Unsubscribes from download progress events.
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 to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. receivedSize: size of the downloaded files. totalSize: total size of the files to download. |
Example
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
let progressCallback1 = (receivedSize: number, totalSize: number) => {
console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize);
};
let progressCallback2 = (receivedSize: number, totalSize: number) => {
console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize);
};
downloadTask.on('progress', progressCallback1);
downloadTask.on('progress', progressCallback2);
// Unsubscribe from progressCallback1.
downloadTask.off('progress', progressCallback1);
// Unsubscribe from all callbacks of download progress events.
downloadTask.off('progress');
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
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 asynchronously.
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
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
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);
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
off('complete'|'pause'|'remove')7+
off(type: 'complete'|'pause'|'remove', callback?:() => void): void
Unsubscribes from download events.
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 to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Example
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
let completeCallback1 = () => {
console.info('Download delete complete notification.');
};
let completeCallback2 = () => {
console.info('Download delete complete notification.');
};
downloadTask.on('complete', completeCallback1);
downloadTask.on('complete', completeCallback2);
// Unsubscribe from completeCallback1.
downloadTask.off('complete', completeCallback1);
// Unsubscribe from all callbacks of the download completion events.
downloadTask.off('complete');
let pauseCallback1 = () => {
console.info('Download delete pause notification.');
};
let pauseCallback2 = () => {
console.info('Download delete pause notification.');
};
downloadTask.on('pause', pauseCallback1);
downloadTask.on('pause', pauseCallback2);
// Unsubscribe from pauseCallback1.
downloadTask.off('pause', pauseCallback1);
// Unsubscribe from all callbacks of the download pause events.
downloadTask.off('pause');
let removeCallback1 = () => {
console.info('Download delete remove notification.');
};
let removeCallback2 = () => {
console.info('Download delete remove notification.');
};
downloadTask.on('remove', removeCallback1);
downloadTask.on('remove', removeCallback2);
// Unsubscribe from removeCallback1.
downloadTask.off('remove', removeCallback1);
// Unsubscribe from all callbacks of the download removal events.
downloadTask.off('remove');
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
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 asynchronously.
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
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
let failCallback = (err: number) => {
console.error(`Failed to download the task. Code: ${err}`);
};
downloadTask.on('fail', failCallback);
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
off('fail')7+
off(type: 'fail', callback?: (err: number) => void): void
Unsubscribes from download failure events.
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 to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Example
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
let failCallback1 = (err: number) => {
console.error(`Failed to download the task. Code: ${err}`);
};
let failCallback2 = (err: number) => {
console.error(`Failed to download the task. Code: ${err}`);
};
downloadTask.on('fail', failCallback1);
downloadTask.on('fail', failCallback2);
// Unsubscribe from failCallback1.
downloadTask.off('fail', failCallback1);
// Unsubscribe from all callbacks of the download failure events.
downloadTask.off('fail');
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
delete9+
delete(): Promise<boolean>
Deletes 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. The value true indicates that the operation is successful, and the value false indicates the opposite. |
Example
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.delete().then((result: boolean) => {
console.info('Succeeded in removing the download task.');
}).catch((err: BusinessError) => {
console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
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 result. The value true indicates that the operation is successful, and the value false indicates the opposite. |
Example
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.delete((err: BusinessError, result: boolean) => {
if (err) {
console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in removing the download task.');
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
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
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.getTaskInfo().then((downloadInfo: request.DownloadInfo) => {
console.info('Succeeded in querying the download task')
}).catch((err: BusinessError) => {
console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`)
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(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
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.getTaskInfo((err: BusinessError, downloadInfo: request.DownloadInfo) => {
if (err) {
console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
} else {
console.info('Succeeded in querying the download mimeType');
}
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
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
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.getTaskMimeType().then((data: string) => {
console.info('Succeeded in querying the download MimeType');
}).catch((err: BusinessError) => {
console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`)
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${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
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.getTaskMimeType((err: BusinessError, data: string) => {
if (err) {
console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`);
} else {
console.info('Succeeded in querying the download mimeType');
}
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
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 result. |
Example
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.suspend().then((result: boolean) => {
console.info('Succeeded in pausing the download task.');
}).catch((err: BusinessError) => {
console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${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
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.suspend((err: BusinessError, result: boolean) => {
if (err) {
console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in pausing the download task.');
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
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
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.restore().then((result: boolean) => {
console.info('Succeeded in resuming the download task.')
}).catch((err: BusinessError) => {
console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(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
import { BusinessError } from '@ohos.base';
try {
request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => {
let downloadTask: request.DownloadTask = data;
downloadTask.restore((err: BusinessError, result: boolean) => {
if (err) {
console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in resuming the download task.');
});
}).catch((err: BusinessError) => {
console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`);
})
} catch (err) {
console.error(`Failed to request the download. err: ${JSON.stringify(err)}`);
}
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+ instead.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.MiscServices.Download
Return value
Type | Description |
---|---|
Promise<boolean> | Promise used to return the result. |
Example
downloadTask.remove().then((result) => {
console.info('Succeeded in removing the download task.');
}).catch ((err) => {
console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
});
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+ instead.
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.remove((err, result)=>{
if(err) {
console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in removing 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+ instead.
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('Succeeded in querying the download task.')
}) .catch((err) => {
console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`)
});
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+ instead.
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. Code: ${err.code}, message: ${err.message}`);
} else {
console.info('Succeeded in querying the download task.');
}
});
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+ instead.
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('Succeeded in querying the download MimeType.');
}).catch((err) => {
console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`)
});
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+ instead.
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. Code: ${err.code}, message: ${err.message}`);
} else {
console.info('Succeeded in querying the download mimeType.');
}
});
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+ instead.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.MiscServices.Download
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
downloadTask.pause().then((result) => {
console.info('Succeeded in pausing the download task.');
}).catch((err) => {
console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`);
});
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+ instead.
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. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in pausing the download task.');
});
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+ instead.
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) => {
console.info('Succeeded in resuming the download task.')
}).catch((err) => {
console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`);
});
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+ instead.
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. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info('Succeeded in resuming 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 application storage path. - In the stage model, use AbilityContext to obtain the application storage path. |
networkType | number | No | Network type allowed for the 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. |
Action10+
Defines action options.
System capability: SystemCapability.Request.FileTransferAgent
Name | Value | Description |
---|---|---|
DOWNLOAD | 0 | Download. |
UPLOAD | 1 | Upload. |
Mode10+
Defines mode options.
After an application is switched to the background for a period of time, background tasks are not affected but foreground tasks will fail or pause.
System capability: SystemCapability.Request.FileTransferAgent
Name | Value | Description |
---|---|---|
BACKGROUND | 0 | Background task. |
FOREGROUND | 1 | Foreground task. |
Network10+
Defines network options.
If the network does not meet the preset conditions, the tasks that have not been executed will await for execution, and the tasks that are being executed will fail or pause.
System capability: SystemCapability.Request.FileTransferAgent
Name | Value | Description |
---|---|---|
ANY | 0 | Network of any type. |
WIFI | 1 | Wi-Fi network. |
CELLULAR | 2 | Cellular data network. |
BroadcastEvent11+
Defines a custom system event. You can use a common event API to obtain the event. The upload and download SA has the ohos.permission.SEND_TASK_COMPLETE_EVENT permission. You can configure the level-2 configuration file to which the metadata of an event points to intercept other event senders.
You can use the CommonEventData type to transmit data related to common events. The members in CommonEventData are different from those described in CommonEventData. Specifically, CommonEventData.code indicates the task status, which is 0x40 COMPLETE or 0x41 FAILED, and CommonEventData.data indicates the task ID.
For details about event configuration information, see Subscribing to Common Events in Static Mode.
System capability: SystemCapability.Request.FileTransferAgent
Name | Value | Description |
---|---|---|
COMPLETE | 'ohos.request.event.COMPLETE' | Task completion event. |
FileSpec10+
Provides the file information of a table item.
System capability: SystemCapability.Request.FileTransferAgent
Name | Type | Mandatory | Description |
---|---|---|---|
path | string | Yes | Relative path in the cache folder of the invoker. |
mimeType | string | No | MIME type of the file, which is obtained from the file name. |
filename | string | No | File name. The default value is obtained from the file path. |
extras | Object | No | Additional information of the file. |
FormItem10+
Describes the form item of a task.
System capability: SystemCapability.Request.FileTransferAgent
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Form parameter name. |
value | string | FileSpec | Array<FileSpec> | Yes | Form parameter value. |
Config10+
Provides the configuration information of an upload or download task.
System capability: SystemCapability.Request.FileTransferAgent
Name | Type | Mandatory | Description |
---|---|---|---|
action | Action | Yes | Task action. - UPLOAD - DOWNLOAD |
url | string | Yes | Resource URL. The value contains a maximum of 2048 characters. |
title | string | No | Task title. The value contains a maximum of 256 characters. The default value is upload or download in lowercase. Set the value to that of action. |
description | string | No | Task description. The value contains a maximum of 1024 characters. The default value is a null string. |
mode | Mode | No | Task mode. The default mode is background. |
overwrite | boolean | No | Whether to overwrite an existing file during the download. The default value is false. - true: Overwrite the existing file. - false: Do not overwrite the existing file. In this case, the download fails. |
method | string | No | Standard HTTP method for the task. The value can be GET, POST, or PUT, which is case-insensitive. - If the task is an upload, use PUT or POST. The default value is PUT. - If the task is a download, use GET or POST. The default value is GET. |
headers | object | No | HTTP headers to be included in the task. - If the task is an upload, the default Content-Type is multipart/form-data. - If the task is a download, the default Content-Type is application/json. |
data | string | Array<FormItem> | No | Task data. - If the task is a download, the value is a string, typically in JSON format (an object will be converted to a JSON string); the default value is null. - If the task is an upload, the value is Array<FormItem>; the default value is null. |
saveas | string | No | Path for storing downloaded files. The options are as follows: - Relative path in the cache folder of the invoker, for example, "./xxx/yyy/zzz.html" and "xxx/yyy/zzz.html". - URI (applicable when the application has the permission to access the URI), for example, "datashare://bundle/xxx/yyy/zzz.html". This option is not supported currently. The default value is a relative path in the cache folder of the application. |
network | Network | No | Network used for the task. The default value is ANY (Wi-Fi or cellular). |
metered | boolean | No | Whether the task is allowed on a metered connection. The default value is false. - true: task allowed on a metered connection. - false: task not allowed on a metered connection. |
roaming | boolean | No | Whether the task is allowed on a roaming network. The default value is true. - true: task allowed on a roaming network. - false: task not allowed on a roaming network. |
retry | boolean | No | Whether automatic retry is enabled for the task. This parameter is only applicable to background tasks. The default value is true. - true: automatic retry enabled for the task. - -false: automatic retry not enabled for the task. |
redirect | boolean | No | Whether redirection is allowed. The default value is true. - true: redirection allowed. - false: redirection not allowed. |
index | number | No | Path index of the task. It is usually used for resumable downloads. The default value is 0. |
begins | number | No | File start point of the task. It is usually used for resumable downloads. The default value is 0. The value is a closed interval. - If the task is a download, the value is obtained by sending an HTTP range request to read the start position when the server starts to download files. - If the task is an upload, the value is obtained at the beginning of the upload. |
ends | number | No | File end point of the task. It is usually used for resumable downloads. The default value is -1. The value is a closed interval. - If the task is a download, the value is obtained by sending an HTTP range request to read the end position when the server starts to download files. - If the task is an upload, the value is obtained at the end of the upload. |
gauge | boolean | No | Whether to send progress notifications. This parameter applies only to background tasks. The default value is false. - false: Progress notifications are not sent. This means that a notification is sent only to indicate the result of the total task. - true: Progress notifications are sent to indicate the result of each file. |
precise | boolean | No | - If this parameter is set to true, the task fails when the file size cannot be obtained. - If this parameter is set to false, the task continues when the file size is set to -1. The default value is false. |
token | string | No | Token of the task. If the task has a token configured, this token is required for query of the task. The value contains 8 to 2048 bytes. This parameter is left empty by default. |
priority11+ | number | No | Priority of the task. For tasks in the same mode, a smaller value indicates a higher priority. Default value: 0 |
extras | object | No | Additional information of the task. This parameter is left empty by default. |
State10+
Defines the current task status.
System capability: SystemCapability.Request.FileTransferAgent
Name | Value | Description |
---|---|---|
INITIALIZED | 0x00 | The task is initialized based on the configuration specified in Config. |
WAITING | 0x10 | The task lacks resources for running or the resources for retries do not match the network status. |
RUNNING | 0x20 | The task is being executed. |
RETRYING | 0x21 | The task has failed at least once and is being executed again. |
PAUSED | 0x30 | The task is suspended and will be resumed later. |
STOPPED | 0x31 | The task is stopped. |
COMPLETED | 0x40 | The task is complete. |
FAILED | 0x41 | The task fails. |
REMOVED | 0x50 | The task is removed. |
Progress10+
Describes the data structure of the task progress.
System capability: SystemCapability.Request.FileTransferAgent
Name | Type | Mandatory | Description |
---|---|---|---|
state | State | Yes | Current task status. |
index | number | Yes | Index of the file that is being processed in the task. |
processed | number | Yes | Size of processed data in the current file in the task, in bytes. |
sizes | Array<number> | Yes | Size of files in the task, in bytes. |
extras | object | No | Extra information of the task, for example, the header and body of the response from the server. |
Faults10+
Defines the cause of a task failure.
System capability: SystemCapability.Request.FileTransferAgent
Name | Value | Description |
---|---|---|
OTHERS | 0xFF | Other fault. |
DISCONNECTED | 0x00 | Network disconnection. |
TIMEOUT | 0x10 | Timeout. |
PROTOCOL | 0x20 | Protocol error, for example, an internal server error (500) or a data range that cannot be processed (416). |
FSIO | 0x40 | File system I/O error, for example, an error that occurs during the open, search, read, write, or close operation. |
Filter10+
Defines the filter criteria.
System capability: SystemCapability.Request.FileTransferAgent
Name | Type | Mandatory | Description |
---|---|---|---|
before | number | No | Unix timestamp of the end time, in milliseconds. The default value is the invoking time. |
after | number | No | Unix timestamp of the start time, in milliseconds. The default value is the invoking time minus 24 hours. |
state | State | No | Task state. |
action | Action | No | Task action. - UPLOAD - DOWNLOAD |
mode | Mode | No | Task mode. - FOREGROUND: foreground task. - BACKGROUND: background task. - No value: All tasks are queried. |
TaskInfo10+
Defines the data structure of the task information for query. The fields available vary depending on the query type.
System capability: SystemCapability.Request.FileTransferAgent
Name | Type | Mandatory | Description |
---|---|---|---|
saveas | string | No | Path for storing downloaded files. The options are as follows: - Relative path in the cache folder of the invoker, for example, "./xxx/yyy/zzz.html" and "xxx/yyy/zzz.html". - URI (applicable when the application has the permission to access the URI), for example, "datashare://bundle/xxx/yyy/zzz.html". This option is not supported currently. The default value is a relative path in the cache folder of the application. |
url | string | No | Task URL. It can be obtained through request.agent.show10+ or request.agent.touch10+. |
data | string | Array<FormItem> | No | Task value. It can be obtained through request.agent.show10+ or request.agent.touch10+. |
tid | string | Yes | Task ID. |
title | string | Yes | Task title. |
description | string | Yes | Task description. |
action | Action | Yes | Task action. - UPLOAD - DOWNLOAD |
mode | Mode | Yes | Task mode. - FOREGROUND: foreground task. - BACKGROUND: background task. |
priority11+ | number | No | Task priority. The priority of a foreground task is higher than that of a background task. For tasks in the same mode, a smaller value indicates a higher priority. |
mimeType | string | Yes | MIME type in the task configuration. |
progress | Progress | Yes | Task progress. |
gauge | boolean | Yes | Whether to send progress notifications. This parameter applies only to background tasks. |
ctime | number | Yes | Unix timestamp when the task is created, in milliseconds. The value is generated by the system of the current device. Note: When request.agent.search10+ is used for query, this value must be within the range of [after,before] for the task ID to be obtained. For details about before and after, see Filter. |
mtime | number | Yes | Unix timestamp when the task state changes, in milliseconds. The value is generated by the system of the current device. |
retry | boolean | Yes | Whether automatic retry is enabled for the task. This parameter applies only to background tasks. |
tries | number | Yes | Number of retries of the task. |
faults | Faults | Yes | Failure cause of the task. - OTHERS: other fault. - DISCONNECT: network disconnection. - TIMEOUT: timeout. - PROTOCOL: protocol error. - FSIO: file system I/O error. |
reason | string | Yes | Reason why the task is waiting, failed, stopped, or paused. |
extras | string | No | Extra information of the task |
Task10+
Implements an upload or download task. Before using this API, you must obtain a Task object, from a promise through request.agent.create10+ or from a callback through request.agent.create10+.
Attributes
Task attributes include the task ID and task configuration.
System capability: SystemCapability.Request.FileTransferAgent
Name | Type | Mandatory | Description |
---|---|---|---|
tid | string | Yes | Task ID, which is unique in the system and is automatically generated by the system. |
config | Config | Yes | Task configuration. |
on('progress')10+
on(event: 'progress', callback: (progress: Progress) => void): void
Subscribes to task progress changes. This API uses a callback to return the result asynchronously.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'progress', indicating the task progress. |
callback | function | Yes | Callback used to return the data structure of the task progress. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
21900005 | task mode error. |
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOnTest",
value: {
filename: "taskOnTest.avi",
mimeType: "application/octet-stream",
path: "./taskOnTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOnTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
console.info('upload task progress.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('progress', createOnCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
on('completed')10+
on(event: 'completed', callback: (progress: Progress) => void): void
Subscribes to task completion events. This API uses a callback to return the result asynchronously.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'completed', indicating task completion. |
callback | function | Yes | Callback used to return the data structure of the task progress. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
21900005 | task mode error. |
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOnTest",
value: {
filename: "taskOnTest.avi",
mimeType: "application/octet-stream",
path: "./taskOnTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOnTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
console.info('upload task completed.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('completed', createOnCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
on('failed')10+
on(event: 'failed', callback: (progress: Progress) => void): void
Subscribes to task failure events. This API uses a callback to return the result asynchronously.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'failed', indicating task failure. |
callback | function | Yes | Callback used to return the data structure of the task progress. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
21900005 | task mode error. |
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOnTest",
value: {
filename: "taskOnTest.avi",
mimeType: "application/octet-stream",
path: "./taskOnTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOnTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
console.info('upload task failed.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('failed', createOnCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
on('pause')11+
on(event: 'pause', callback: (progress: Progress) => void): void
Subscribes to task pause events. This API uses a callback to return the result asynchronously.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'pause', indicating task pause. |
callback | function | Yes | Callback used to return the data structure of the task progress. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOnTest",
value: {
filename: "taskOnTest.avi",
mimeType: "application/octet-stream",
path: "./taskOnTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOnTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
console.info('upload task pause.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('pause', createOnCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
on('resume')11+
on(event: 'resume', callback: (progress: Progress) => void): void
Subscribes to task resume events. This API uses a callback to return the result asynchronously.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'resume', indicating task resume. |
callback | function | Yes | Callback used to return the data structure of the task progress. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOnTest",
value: {
filename: "taskOnTest.avi",
mimeType: "application/octet-stream",
path: "./taskOnTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOnTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
console.info('upload task resume.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('resume', createOnCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
on('remove')11+
on(event: 'remove', callback: (progress: Progress) => void): void
Subscribes to task removal events. This API uses a callback to return the result asynchronously.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'remove', indicating task removal. |
callback | function | Yes | Callback used to return the data structure of the task progress. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOnTest",
value: {
filename: "taskOnTest.avi",
mimeType: "application/octet-stream",
path: "./taskOnTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOnTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOnCallback = (progress: request.agent.Progress) => {
console.info('upload task remove.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('remove', createOnCallback);
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
off('progress')10+
off(event: 'progress', callback?: (progress: Progress) => void): void
Unsubscribes from task progress events.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'progress', indicating the task progress. |
callback | function | No | Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
21900005 | task mode error. |
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOffTest",
value: {
filename: "taskOffTest.avi",
mimeType: "application/octet-stream",
path: "./taskOffTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOffTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
console.info('upload task progress.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
console.info('upload task progress.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('progress', createOffCallback1);
task.on('progress', createOffCallback2);
// Unsubscribe from createOffCallback1.
task.off('progress', createOffCallback1);
// Unsubscribe from all callbacks of task progress changes.
task.off('progress');
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
off('completed')10+
off(event: 'completed', callback?: (progress: Progress) => void): void
Unsubscribes from task completion events.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'completed', indicating task completion. |
callback | function | No | Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
21900005 | task mode error. |
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOffTest",
value: {
filename: "taskOffTest.avi",
mimeType: "application/octet-stream",
path: "./taskOffTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOffTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
console.info('upload task completed.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
console.info('upload task completed.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('completed', createOffCallback1);
task.on('completed', createOffCallback2);
// Unsubscribe from createOffCallback1.
task.off('completed', createOffCallback1);
// Unsubscribe from all callbacks of the task completion events.
task.off('completed');
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
off('failed')10+
off(event: 'failed', callback?: (progress: Progress) => void): void
Unsubscribes from task failure events.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'failed', indicating task failure. |
callback | function | No | Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
21900005 | task mode error. |
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOffTest",
value: {
filename: "taskOffTest.avi",
mimeType: "application/octet-stream",
path: "./taskOffTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOffTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
console.info('upload task failed.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
console.info('upload task failed.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('failed', createOffCallback1);
task.on('failed', createOffCallback2);
// Unsubscribe from createOffCallback1.
task.off('failed', createOffCallback1);
// Unsubscribe from all callbacks of the task failure events.
task.off('failed');
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
off('pause')11+
off(event: 'pause', callback?: (progress: Progress) => void): void
Unsubscribes from the foreground task pause event.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'pause', indicating task pause. |
callback | function | No | Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOffTest",
value: {
filename: "taskOffTest.avi",
mimeType: "application/octet-stream",
path: "./taskOffTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOffTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
console.info('upload task pause.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
console.info('upload task pause.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('pause', createOffCallback1);
task.on('pause', createOffCallback2);
// Unsubscribe from createOffCallback1.
task.off('pause', createOffCallback1);
// Unsubscribe from all callbacks of the foreground task pause event.
task.off('pause');
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
off('resume')11+
off(event: 'resume', callback?: (progress: Progress) => void): void
Unsubscribes from the foreground task resume event.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'resume', indicating task resume. |
callback | function | No | Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOffTest",
value: {
filename: "taskOffTest.avi",
mimeType: "application/octet-stream",
path: "./taskOffTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOffTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
console.info('upload task resume.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
console.info('upload task resume.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('resume', createOffCallback1);
task.on('resume', createOffCallback2);
// Unsubscribe from createOffCallback1.
task.off('resume', createOffCallback1);
// Unsubscribe from all callbacks of the foreground task resume event.
task.off('resume');
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
off('remove')11+
off(event: 'remove', callback?: (progress: Progress) => void): void
Unsubscribes from the task removal event.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Type of the event to subscribe to. The value is 'remove', indicating task removal. |
callback | function | No | Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
Example
let attachments: Array<request.agent.FormItem> = [{
name: "taskOffTest",
value: {
filename: "taskOffTest.avi",
mimeType: "application/octet-stream",
path: "./taskOffTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'taskOffTest',
description: 'Sample code for event listening',
mode: request.agent.Mode.FOREGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
let createOffCallback1 = (progress: request.agent.Progress) => {
console.info('upload task remove.');
};
let createOffCallback2 = (progress: request.agent.Progress) => {
console.info('upload task remove.');
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.on('remove', createOffCallback1);
task.on('remove', createOffCallback2);
// Unsubscribe from createOffCallback1.
task.off('remove', createOffCallback1);
// Unsubscribe from all callbacks of the task removal event.
task.off('remove');
console.info(`Succeeded in creating a upload task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
start10+
start(callback: AsyncCallback<void>): void
Starts this task. This API cannot be used to start an initialized task. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | function | Yes | Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900007 | task state error. |
Example
let config: request.agent.Config = {
action: request.agent.Action.DOWNLOAD,
url: 'http://127.0.0.1',
title: 'taskStartTest',
description: 'Sample code for start the download task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "GET",
data: "",
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.start((err: BusinessError) => {
if (err) {
console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in starting a download task.`);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
start10+
start(): Promise<void>
Starts this task. This API cannot be used to start an initialized task. This API uses a promise to return the result.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.Request.FileTransferAgent
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900007 | task state error. |
Example
let config: request.agent.Config = {
action: request.agent.Action.DOWNLOAD,
url: 'http://127.0.0.1',
title: 'taskStartTest',
description: 'Sample code for start the download task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "GET",
data: "",
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.start().then(() => {
console.info(`Succeeded in starting a download task.`);
}).catch((err: BusinessError) => {
console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
pause10+
pause(callback: AsyncCallback<void>): void
Pauses this task. This API can be used to pause a background task that is waiting, running, or retrying. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | function | Yes | Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900005 | task mode error. |
21900007 | task state error. |
Example
let config: request.agent.Config = {
action: request.agent.Action.DOWNLOAD,
url: 'http://127.0.0.1',
title: 'taskPauseTest',
description: 'Sample code for pause the download task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "GET",
data: "",
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.pause((err: BusinessError) => {
if (err) {
console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in pausing a download task. `);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
The error code 21900005 task mode error is removed from API version 11.
pause10+
pause(): Promise<void>
Pauses this task. This API can be used to pause a background task that is waiting, running, or retrying. This API uses a promise to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900005 | task mode error. |
21900007 | task state error. |
Example
let config: request.agent.Config = {
action: request.agent.Action.DOWNLOAD,
url: 'http://127.0.0.1',
title: 'taskPauseTest',
description: 'Sample code for pause the download task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "GET",
data: "",
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.pause().then(() => {
console.info(`Succeeded in pausing a download task. `);
}).catch((err: BusinessError) => {
console.error(`Failed to pause the upload task, Code: ${err.code}, message: ${err.message}`);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
The error code 21900005 task mode error is removed from API version 11.
resume10+
resume(callback: AsyncCallback<void>): void
Resumes this task. This API can be used to resume a paused background task. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | function | Yes | Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900005 | task mode error. |
21900007 | task state error. |
Example
let config: request.agent.Config = {
action: request.agent.Action.DOWNLOAD,
url: 'http://127.0.0.1',
title: 'taskResumeTest',
description: 'Sample code for resume the download task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "GET",
data: "",
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.resume((err: BusinessError) => {
if (err) {
console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in resuming a download task. `);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
The error code 21900005 task mode error is removed from API version 11.
resume10+
resume(): Promise<void>
Resumes this task. This API can be used to resume a paused background task. This API uses a promise to return the result.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.Request.FileTransferAgent
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900005 | task mode error. |
21900007 | task state error. |
Example
let config: request.agent.Config = {
action: request.agent.Action.DOWNLOAD,
url: 'http://127.0.0.1',
title: 'taskResumeTest',
description: 'Sample code for resume the download task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "GET",
data: "",
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.resume().then(() => {
console.info(`Succeeded in resuming a download task. `);
}).catch((err: BusinessError) => {
console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
The error code 21900005 task mode error is removed from API version 11.
stop10+
stop(callback: AsyncCallback<void>): void
Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | function | Yes | Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900007 | task state error. |
Example
let config: request.agent.Config = {
action: request.agent.Action.DOWNLOAD,
url: 'http://127.0.0.1',
title: 'taskStopTest',
description: 'Sample code for stop the download task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "GET",
data: "",
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.stop((err: BusinessError) => {
if (err) {
console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in stopping a download task. `);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
stop10+
stop(): Promise<void>
Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses a promise to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900007 | task state error. |
Example
let config: request.agent.Config = {
action: request.agent.Action.DOWNLOAD,
url: 'http://127.0.0.1',
title: 'taskStopTest',
description: 'Sample code for stop the download task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "GET",
data: "",
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
task.stop().then(() => {
console.info(`Succeeded in stopping a download task. `);
}).catch((err: BusinessError) => {
console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`);
});
console.info(`Succeeded in creating a download task. result: ${task.tid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
request.agent.create10+
create(context: BaseContext, config: Config, callback: AsyncCallback<Task>): void
Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 unfinished tasks. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
config | Config | Yes | Task configuration. |
context | BaseContext | Yes | Application-based context. |
callback | AsyncCallback<Task> | Yes | Callback used to return the configuration about the created task. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400001 | file operation error. |
13400003 | task service ability error. |
21900004 | application task queue full error. |
21900005 | task mode error. |
Example
let attachments: Array<request.agent.FormItem> = [{
name: "createTest",
value: {
filename: "createTest.avi",
mimeType: "application/octet-stream",
path: "./createTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'createTest',
description: 'Sample code for create task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config, (err: BusinessError, task: request.agent.Task) => {
if (err) {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in creating a download task. result: ${task.config}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
request.agent.create10+
create(context: BaseContext, config: Config): Promise<Task>
Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 unfinished tasks. This API uses a promise to return the result.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
context | BaseContext | Yes | Application-based context. |
config | Config | Yes | Task configuration. |
Return value
Type | Description |
---|---|
Promise<Task> | Promise used to return the configuration about the created task. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400001 | file operation error. |
13400003 | task service ability error. |
21900004 | application task queue full error. |
21900005 | task mode error. |
Example
let attachments: Array<request.agent.FormItem> = [{
name: "createTest",
value: {
filename: "createTest.avi",
mimeType: "application/octet-stream",
path: "./createTest.avi",
}
}];
let config: request.agent.Config = {
action: request.agent.Action.UPLOAD,
url: 'http://127.0.0.1',
title: 'createTest',
description: 'Sample code for create task',
mode: request.agent.Mode.BACKGROUND,
overwrite: false,
method: "PUT",
data: attachments,
saveas: "./",
network: request.agent.Network.CELLULAR,
metered: false,
roaming: true,
retry: true,
redirect: true,
index: 0,
begins: 0,
ends: -1,
gauge: false,
precise: false,
token: "it is a secret"
};
request.agent.create(getContext(), config).then((task: request.agent.Task) => {
console.info(`Succeeded in creating a download task. result: ${task.config}`);
}).catch((err) => {
console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`);
});
NOTE
For details about how to obtain the context in the example, see Obtaining the Context of UIAbility.
request.agent.getTask11+
getTask(context: BaseContext, id: string, token?: string): Promise<Task>
Obtains task information based on the task ID. This API uses a promise to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
context | BaseContext | Yes | Application-based context. |
id | string | Yes | Task ID. |
token | string | No | Token for task query. |
Return value
Type | Description |
---|---|
Promise<Task> | Promise used to return the configuration about the created task. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900006 | task not found error. |
Example
request.agent.getTask(context, "123456").then((task: request.agent.Task) => {
console.info(`Succeeded in querying a upload task. result: ${task.uid}`);
}).catch((err: BusinessError) => {
console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`);
});
request.agent.remove10+
remove(id: string, callback: AsyncCallback<void>): void
Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | Task ID. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900006 | task not found error. |
Example
request.agent.remove("123456", (err: BusinessError) => {
if (err) {
console.error(`Failed to removing a download task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in creating a download task.`);
});
request.agent.remove10+
remove(id: string): Promise<void>
Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses a promise to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | Task ID. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900006 | task not found error. |
Example
request.agent.remove("123456").then(() => {
console.info(`Succeeded in removing a download task. `);
}).catch((err: BusinessError) => {
console.error(`Failed to remove a download task, Code: ${err.code}, message: ${err.message}`);
});
request.agent.show10+
show(id: string, callback: AsyncCallback<TaskInfo>): void
Queries a task details based on the task ID. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | Task ID. |
callback | AsyncCallback<TaskInfo> | Yes | Callback used to return task details. |
Error codes For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900006 | task not found error. |
Example
request.agent.show("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => {
if (err) {
console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in showing a upload task.`);
});
request.agent.show10+
show(id: string): Promise<TaskInfo>
Queries a task details based on the task ID. This API uses a promise to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | Task ID. |
Return value
Type | Description |
---|---|
Promise<TaskInfo> | Promise Promise used to return task details. |
Error codes For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900006 | task not found error. |
Example
request.agent.show("123456").then((taskInfo: request.agent.TaskInfo) => {
console.info(`Succeeded in showing a upload task.`);
}).catch((err: BusinessError) => {
console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`);
});
request.agent.touch10+
touch(id: string, token: string, callback: AsyncCallback<TaskInfo>): void
Queries the task details based on the task ID and token. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | Task ID. |
token | string | Yes | Token for task query. |
callback | AsyncCallback<TaskInfo> | Yes | Callback used to return task details. |
Error codes For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900006 | task not found error. |
Example
request.agent.touch("123456", "token", (err: BusinessError, taskInfo: request.agent.TaskInfo) => {
if (err) {
console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Succeeded in touching a upload task.`);
});
request.agent.touch10+
touch(id: string, token: string): Promise<TaskInfo>
Queries the task details based on the task ID and token. This API uses a promise to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | string | Yes | Task ID. |
token | string | Yes | Token for task query. |
Return value
Type | Description |
---|---|
Promise<TaskInfo> | Promise Promise used to return task details. |
Error codes For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
21900006 | task not found error. |
Example
request.agent.touch("123456", "token").then((taskInfo: request.agent.TaskInfo) => {
console.info(`Succeeded in touching a upload task. `);
}).catch((err: BusinessError) => {
console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`);
});
request.agent.search10+
search(callback: AsyncCallback<Array<string>>): void
Searches for task IDs based on Filter. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<Array<string>> | Yes | Callback used to return task ID matches. |
Error codes For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
Example
request.agent.search((err: BusinessError, data: Array<string>) => {
if (err) {
console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Upload task search succeeded. `);
});
request.agent.search10+
search(filter: Filter, callback: AsyncCallback<Array<string>>): void
Searches for task IDs based on Filter. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
filter | Filter | Yes | Filter criteria. |
callback | AsyncCallback<Array<string>> | Yes | Callback used to return task ID matches. |
Error codes For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
Example
let filter: request.agent.Filter = {
bundle: "com.example.myapplication",
action: request.agent.Action.UPLOAD,
mode: request.agent.Mode.BACKGROUND
}
request.agent.search(filter, (err: BusinessError, data: Array<string>) => {
if (err) {
console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`);
return;
}
console.info(`Upload task search succeeded. `);
});
request.agent.search10+
search(filter?: Filter): Promise<Array<string>>
Searches for task IDs based on Filter. This API uses a promise to return the result.
System capability: SystemCapability.Request.FileTransferAgent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
filter | Filter | No | Filter criteria. |
Return value
Type | Description |
---|---|
Promise<Array<string>> | Promise Promise used to return task ID matches. |
Error codes For details about the error codes, see Upload and Download Error Codes.
ID | Error Message |
---|---|
13400003 | task service ability error. |
Example
let filter: request.agent.Filter = {
bundle: "com.example.myapplication",
action: request.agent.Action.UPLOAD,
mode: request.agent.Mode.BACKGROUND
}
request.agent.search(filter).then((data: Array<string>) => {
console.info(`Upload task search succeeded. `);
}).catch((err: BusinessError) => {
console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`);
});