• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.fileshare (File Sharing) (System API)
2
3The **fileShare** module provides APIs for granting the access permissions on a user file to another application based on the file Uniform Resource Identifier (URI). Then, the authorized application can access the file by using the [@ohos.file.fs](js-apis-file-fs.md) APIs.
4
5> **NOTE**
6>
7> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.fileshare](js-apis-fileShare-sys.md).
9
10## Modules to Import
11
12```ts
13import  { fileShare } from '@kit.CoreFileKit';
14```
15
16## fileShare.grantUriPermission
17
18grantUriPermission(uri: string, bundleName: string, flag: wantConstant.Flags, callback: AsyncCallback<void>): void
19
20Grants the permissions on a user file to an application. This API uses an asynchronous callback to return the result.
21
22**Required permissions**: ohos.permission.WRITE_MEDIA
23
24**System API**: This is a system API.
25
26**System capability**: SystemCapability.FileManagement.AppFileService
27
28**Parameters**
29
30| Name| Type| Mandatory| Description|
31| ------ |---------| ---- |-----------|
32| uri   | string| Yes  | URI of the file under user directory.|
33| bundleName   | string| Yes  | Application to be granted with the permissions.  |
34| flag   | [wantConstant.Flags](../apis-ability-kit/js-apis-app-ability-wantConstant.md#flags) | Yes  | Permissions to grant.    |
35 | callback | AsyncCallback<void>| Yes   | Callback used to return the result.|
36
37**Error codes**
38
39For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md).
40
41| ID| Error Message|
42| ------ | ------- |
43| 201 | Permission verification failed. |
44| 202 | The caller is not a system application. |
45| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
46| 143000001 | IPC error. |
47
48**Example**
49
50  ```ts
51  import { wantConstant } from '@kit.AbilityKit';
52  import { BusinessError } from '@kit.BasicServicesKit';
53  let uri: string = 'file://docs/storage/Users/currentUser/Document/1.txt';  // You are advised to use the system API to generate a URI using fileUri.getUriFromPath("Sandbox path");
54  let bundleName: string = 'com.demo.test';
55  try {
56    fileShare.grantUriPermission(uri, bundleName, wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION |
57      wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION, (err: BusinessError) => {
58      if (err) {
59        console.error("grantUriPermission failed with error: " + JSON.stringify(err));
60        return;
61      }
62      console.info("grantUriPermission success!");
63    });
64  } catch (err) {
65    let error: BusinessError = err as BusinessError;
66    console.error("grantUriPermission failed with error:" + JSON.stringify(error));
67  }
68  ```
69
70## fileShare.grantUriPermission
71
72grantUriPermission(uri: string, bundleName: string, flag: wantConstant.Flags): Promise<void>
73
74Grants the permissions on a user file to an application. This API uses a promise to return the result.
75
76**Required permissions**: ohos.permission.WRITE_MEDIA
77
78**System API**: This is a system API.
79
80**System capability**: SystemCapability.FileManagement.AppFileService
81
82**Parameters**
83
84| Name| Type| Mandatory| Description       |
85| ------ |-------| ---- |-----------|
86| uri   | string| Yes  | URI of the file under user directory.|
87| bundleName   | string| Yes  | Application to be granted with the permissions.  |
88| flag   | [wantConstant.Flags](../apis-ability-kit/js-apis-app-ability-wantConstant.md#flags) | Yes  | Permissions to grant.    |
89
90**Return value**
91
92  | Type                          | Description        |
93  | ---------- | ---------- |
94  | Promise<void> | Promise that returns no value.|
95
96**Error codes**
97
98For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md).
99
100| ID| Error Message|
101| ------- | ---------- |
102| 201 | Permission verification failed. |
103| 202 | The caller is not a system application. |
104| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
105| 143000001 | IPC error. |
106
107**Example**
108
109  ```ts
110  import { wantConstant } from '@kit.AbilityKit';
111  import { BusinessError } from '@kit.BasicServicesKit';
112  let uri: string = 'file://docs/storage/Users/currentUser/Document/1.txt'; // You are advised to use the system API fileUri.getUriFromPath("Sandbox path") to generate a URI.;
113  let bundleName: string = 'com.demo.test';
114  try {
115    fileShare.grantUriPermission(uri, bundleName, wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION |
116      wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION).then(() => {
117      console.info("grantUriPermission success!");
118    }).catch((error: BusinessError) => {
119      console.error("grantUriPermission failed with error:" + JSON.stringify(error));
120    });
121  } catch (err) {
122    let error: BusinessError = err as BusinessError;
123    console.error("grantUriPermission failed with error:" + JSON.stringify(error));
124  }
125  ```
126
127## fileShare.checkPathPermission<sup>15+</sup>
128
129checkPathPermission(tokenID: number, policies: Array&lt;PathPolicyInfo&gt;, policyType: PolicyType): Promise&lt;Array&lt;boolean&gt;&gt;
130
131Checks whether the selected files or folders have temporary or persistent permissions. This API uses a promise to return the result.
132
133**Required permission**: ohos.permission.CHECK_SANDBOX_POLICY
134
135**System API**: This is a system API.
136
137**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization
138
139**Parameters**
140
141| Name| Type| Mandatory| Description|
142| -------- |-------| -------- |----------|
143| tokenID| number | Yes| Application token ID, which is the value of **accessTokenId** in [ApplicationInfo](../apis-ability-kit/js-apis-bundleManager-applicationInfo.md).|
144| policies| Array&lt;[PathPolicyInfo](js-apis-fileShare.md#pathpolicyinfo15)> | Yes| Array of permission policies. The maximum number of policies is 500.|
145| policyType| [PolicyType](js-apis-fileShare.md#policytype15) | Yes| Policy type to check, which can be a temporary or persistent permission.|
146
147**Return value**
148
149|Type|Description|
150| ------ | ------ |
151| Promise&lt;Array&lt;boolean&gt;&gt; | Promise used to return the result. The value **true** means that a policy type is used. Otherwise, **false** is returned.|
152
153**Error codes**
154
155For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md).
156
157| ID   | Error Message      |
158|----------| --------- |
159| 201      | Permission verification failed, usually the result returned by VerifyAccessToken.|
160| 202      | The caller is not a system application.|
161| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
162| 801      | Capability not supported. |
163
164**Example**
165
166  ```ts
167  import { BusinessError } from '@ohos.base';
168  import fileshare from '@ohos.fileshare';
169
170  async function checkPersistentPermissionExample() {
171    try {
172      let pathPolicyInfo1: fileshare.PathPolicyInfo = {
173        path: "/storage/Users/currentUser/Documents/1.txt",
174        operationMode: fileshare.OperationMode.READ_MODE,
175      }
176      let pathPolicyInfo2: fileshare.PathPolicyInfo = {
177        path: "/storage/Users/currentUser/Desktop/2.txt",
178        operationMode: fileshare.OperationMode.READ_MODE,
179      }
180
181      let policies: Array<fileshare.PathPolicyInfo> = [pathPolicyInfo1, pathPolicyInfo2];
182      let policyType: fileshare.PolicyType = fileshare.PolicyType.PERSISTENT_TYPE;
183      let tokenid = 537688848; // Use bundleManager.getApplicationInfo() to obtain the token ID for a system application, and use bundleManager.getBundleInfoForSelf() to obtain the token ID for a non-system application.
184
185      fileshare.checkPathPermission(tokenid, policies, policyType).then((result:Array<boolean>) => {
186        for (let x of result) {
187          console.info('check permission result is', x);
188        }
189      })
190      console.info("checkPathPermission finish");
191    }
192    catch (error) {
193      console.info(error.code + 'checkPathPermission error' + error.message);
194    }
195  }
196  ```
197