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