1# @ohos.request (Upload and Download) (System API) 2 3The **request** module provides applications with basic upload, download, and background transmission agent capabilities. 4 5> **NOTE** 6> 7> 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. 8> 9> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.request](js-apis-request.md). 10 11 12## Modules to Import 13 14 15```js 16import { request } from '@kit.BasicServicesKit'; 17``` 18 19 20## Filter<sup>10+</sup> 21 22Defines the filter criteria. 23 24**System capability**: SystemCapability.Request.FileTransferAgent 25 26| Name| Type| Mandatory| Description| 27| -------- | -------- | -------- | -------- | 28| bundle | string | No| Bundle name of the application.<br>**System API**: This is a system API.| 29 30 31## TaskInfo<sup>10+</sup> 32 33Defines the data structure of the task information for query. The fields available vary depending on the query types: common query and system query. 34 35**System capability**: SystemCapability.Request.FileTransferAgent 36 37| Name| Type| Mandatory| Description| 38| -------- | -------- | -------- | -------- | 39| uid | string | No| UID of the application. It is only available for query by system applications.<br>**System API**: This is a system API.| 40| bundle | string | No| Bundle name of the application. It is only available for query by system applications.<br>**System API**: This is a system API.| 41 42 43 44## request.agent.query<sup>10+</sup> 45 46query(id: string, callback: AsyncCallback<TaskInfo>): void 47 48Queries a task details based on the task ID. This API uses an asynchronous callback to return the result. 49 50**Required permissions**: ohos.permission.DOWNLOAD_SESSION_MANAGER or ohos.permission.UPLOAD_SESSION_MANAGER 51 52**System capability**: SystemCapability.Request.FileTransferAgent 53 54**System API**: This is a system API. 55 56**Parameters** 57 58| Name| Type | Mandatory| Description| 59|----------------------------------------------| -------- | -------- | -------- | 60| id | string | Yes| Task ID.| 61| callback | AsyncCallback<[TaskInfo](#taskinfo10)> | Yes| Callback used to return task details.| 62 63**Error codes** 64 65For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Upload and Download Error Codes](errorcode-request.md). 66 67| ID| Error Message| 68| -------- | -------- | 69| 201 | permission denied. | 70| 202 | permission verification failed, application which is not a system application uses system API. | 71| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. | 72| 13400003 | task service ability error. | 73| 21900006 | task not found. | 74 75**Example** 76 77 ```ts 78 import { BusinessError } from '@kit.BasicServicesKit'; 79 80 request.agent.query("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 81 if (err) { 82 console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`); 83 return; 84 } 85 console.info(`Succeeded in querying the upload task. Result: ${taskInfo.uid}`); 86 }); 87 ``` 88 89 90## request.agent.query<sup>10+</sup> 91 92query(id: string): Promise<TaskInfo> 93 94Queries a task details based on the task ID. This API uses a promise to return the result. 95 96**Required permissions**: ohos.permission.DOWNLOAD_SESSION_MANAGER or ohos.permission.UPLOAD_SESSION_MANAGER 97 98**System capability**: SystemCapability.Request.FileTransferAgent 99 100**System API**: This is a system API. 101 102**Parameters** 103 104| Name| Type| Mandatory| Description| 105| -------- | -------- | -------- | -------- | 106| id | string | Yes| Task ID.| 107 108**Return value** 109 110| Type | Description | 111|----------------------------------------| ------------------------- | 112| Promise<[TaskInfo](#taskinfo10)> | Promise Promise used to return task details.| 113 114**Error codes** 115 116For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Upload and Download Error Codes](errorcode-request.md). 117 118| ID| Error Message| 119| -------- | -------- | 120| 201 | permission denied. | 121| 202 | permission verification failed, application which is not a system application uses system API. | 122| 401 | parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. | 123| 13400003 | task service ability error. | 124| 21900006 | task not found. | 125 126**Example** 127 128 ```ts 129 import { BusinessError } from '@kit.BasicServicesKit'; 130 131 request.agent.query("123456").then((taskInfo: request.agent.TaskInfo) => { 132 console.info(`Succeeded in querying the upload task. Result: ${taskInfo.uid}`); 133 }).catch((err: BusinessError) => { 134 console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`); 135 }); 136 ``` 137