1# Starting a File Application
2
3## When to Use
4
5You can call [startAbility](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to enable the system to search for an application that can handle the intent of opening a file from installed applications. For example, after downloading a PDF file from a browser, you can call this API to start a file application to open the PDF file. You must set the file URI (specified by [uri](#key-api-parameters)) and type (specified by [type](#key-api-parameters)) and other fields in the request so that the system can identify the file to open. Then the system directly starts an application to open the file or displays a dialog box for users to select an application to open the file.
6
7**Figure 1** Example of opening a file
8
9![](figures/file-open.jpeg)
10
11## Key API Parameters
12
13You can call [startAbility](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to start an installed vertical application to open a file.
14
15**Table 1** Description of [want](../reference/apis-ability-kit/js-apis-app-ability-want.md) in startAbility
16
17| Parameter| Type  | Mandatory| Description                 |
18|----------|--------|----------|---------------------|
19| uri      | string | Yes      | URI of the file to open. This parameter is used together with **type**.<br>The URI format is file:\/\/bundleName\/path.<br>- **file**: indicates a file URI.<br>- *bundleName*: specifies the owner of the file.<br>- *path*: specifies the application sandbox path of the file.|
20| type     | string | No      | MIME type of the file to open, for example, **'text/xml'** and **'image/*'**. For details about the MIME type definition, see https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com.                 |
21| parameters | Record<string, Object>       | No        | Custom parameters that are defined by the system and assigned values by developers as required. For details, see Table 2.        |
22| flags | number | No| Processing mode. For details, see Table 3.                                                                                                                                                                                      |
23
24**Table 2** Description of [parameters](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#wantconstantparams)
25
26
27| Parameter                             | Type   | Description                                                                                                                                                               |
28|---------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
29| ability.params.stream                 | string  | File URIs to be authorized to the target application. This parameter is used when the file to open depends on other files. For example, opening a local HTML file depends on other local resource files. The value must be an array of file URIs of the string type. For details about how to obtain the file URI, see the **uri** parameter in Table 1.|
30| ohos.ability.params.showDefaultPicker | string | Whether to display a dialog box to ask users to select a file opening mode when only one matching application is found.<br>- **false**: The display of the dialog box is determined by the system policy or default application settings.<br>- **true**: Such a dialog box is always displayed. The default value is **false**.                                                                           |
31
32**Table 3** Description of [flags](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#wantconstantflags)
33
34| Parameter                      | Value        | Description                      |
35|--------------------------------|------------|----------------------------|
36| FLAG_AUTH_READ_URI_PERMISSION  | 0x00000001 | Grants the permission to read the URI.|
37| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Grants the permission to write data to the URI.|
38
39## How to Develop
40
41### Procedure for the Caller Application
42
431. Import the required modules.
44
45    ```ts
46    // xxx.ets
47    import { fileUri } from '@kit.CoreFileKit';
48    import { UIAbility, Want, common, wantConstant } from '@kit.AbilityKit';
49    import { BusinessError } from '@kit.BasicServicesKit';
50    ```
51
522. Obtain the [application file paths](application-context-stage.md#obtaining-application-file-paths).
53
54    ```ts
55    // xxx.ets
56    // Assume that the bundle name is com.example.demo.
57    export default class EntryAbility extends UIAbility {
58        onWindowStageCreate(windowStage: window.WindowStage) {
59            // Obtain the application sandbox path of the file.
60            let filePath = this.context.filesDir + '/test1.txt';
61            // Convert the application sandbox path into a URI.
62            let uri = fileUri.getUriFromPath(filePath);
63            // The obtained URI is file://com.example.demo/data/storage/el2/base/files/test.txt.
64        }
65        // ...
66    }
67    ```
68
693. Construct request data.
70
71    ```ts
72    // xxx.ets
73    export default class EntryAbility extends UIAbility {
74        onWindowStageCreate(windowStage: window.WindowStage) {
75            // Obtain the application sandbox path of the file.
76            let filePath = this.context.filesDir + '/test.txt';
77            // Convert the application sandbox path into a URI.
78            let uri = fileUri.getUriFromPath(filePath);
79            // Construct the request data.
80            let want: Want = {
81            uri: uri,
82            type: 'text/plain', // Type of the file to open.
83            // Grant the read and write permissions on the file to the target application.
84            flags: wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION | wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION
85            };
86        }
87        // ...
88    }
89    ```
90
914. Call the API to start the target application.
92    
93    ```ts
94    // xxx.ets
95    export default class EntryAbility extends UIAbility {
96        onWindowStageCreate(windowStage: window.WindowStage) {
97            // Obtain the application sandbox path of the file.
98            let filePath = this.context.filesDir + '/test.txt';
99            // Convert the application sandbox path into a URI.
100            let uri = fileUri.getUriFromPath(filePath);
101            // Construct the request data.
102            let want: Want = {
103            uri: uri,
104            type: 'text/plain', // Type of the file to open.
105            // Grant the read and write permissions on the file to the target application.
106            flags: wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION | wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION
107            };
108            // Call startAbility.
109            this.context.startAbility(want)
110            .then(() => {
111                console.info('Succeed to invoke startAbility.');
112            })
113            .catch((err: BusinessError) => {
114                console.error(`Failed to invoke startAbility, code: ${err.code}, message: ${err.message}`);
115            });
116        }
117        // ...
118    }
119    ```
120
121### Procedure for the Target Application
122
1231. Declare the capability to open files.
124
125    Applications that are able to open files must declare the file opening capability in the [module.json5](../quick-start/module-configuration-file.md) file. The **uris** field indicates the type of the URIs, and the **scheme** field is fixed at **file**. The **type** field indicates the types of files that can be opened. For details, see [MIME Definition](https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com). In the following example, the file type is TXT.
126
127    ```ts
128    {
129    "module": {
130        // ...
131        "abilities": [
132        {
133            // ...
134            "skills": [
135            {
136                "actions": [
137                "ohos.want.action.viewData" // Mandatory. Declare the data processing capability.
138                ],
139                "uris": [
140                {
141                    // Declare the capability of opening local files whose URIs start with file://.
142                    "scheme": "file", // Mandatory. Declare that the scheme type is file.
143                    "type": "text/plain", // Mandatory. Specify the type of file that can be opened.
144                    "linkFeature": "FileOpen" // Mandatory. Specify that the URI is used to open files.
145                }
146                // ...
147                ]
148                // ...
149            }
150            ]
151        }
152        ]
153    }
154    }
155    ```
156
157
1582. Process the file.
159
160    After the target application is started and obtains the URI of the file to open from the [want](../reference/apis-ability-kit/js-apis-app-ability-want.md) information, it opens the file and obtains the corresponding file object for reading and writing.
161
162    ```ts
163    // xxx.ets
164    import fs from '@ohos.file.fs';
165    import { Want } from '@kit.AbilityKit';
166    import { BusinessError } from '@kit.BasicServicesKit';
167
168    export default class EntryAbility extends UIAbility {
169        onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
170            // Obtain the uri field from the want information.
171            let uri = want.uri;
172            if (uri == null || uri == undefined) {
173                console.info('uri is invalid');
174                return;
175            }
176            try {
177                // Perform operations on the URI of the file as required. For example, open the URI to obtain the file object in read/write mode.
178                let file = fs.openSync(uri, fs.OpenMode.READ_WRITE);
179                console.info('Succeed to open file.');
180            } catch (err) {
181                let error: BusinessError = err as BusinessError;
182                console.error(`Failed to open file openSync, code: ${error.code}, message: ${error.message}`);
183            }
184        }
185    }
186    ```
187