1# @ohos.fileshare (File Sharing) 2 3The **fileShare** module provides APIs for granting permissions on a user file to another application based on the file Uniform Resource Identifier (URI). Then, the authorized application can call [@ohos.file.fs](js-apis-file-fs.md) APIs to access the file. 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 9## Modules to Import 10 11```ts 12import fileShare from '@ohos.fileshare'; 13``` 14 15## OperationMode<sup>11+</sup> 16 17Enumerates the permissions on a URI. 18 19**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 20 21| Name | Value | Description | 22| ----- |-----|-----| 23| READ_MODE | 0b1 | Read.| 24| WRITE_MODE | 0b10 | Write.| 25 26## PolicyErrorCode<sup>11+</sup> 27 28Enumerates the error codes for a permission policy. 29 30**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 31 32| Name | Value | Description | 33| ----- |-----|-----------| 34| PERSISTENCE_FORBIDDEN | 1 | The permission on the URI cannot be persisted.| 35| INVALID_MODE | 2 | Invalid mode. | 36| INVALID_PATH | 3 | Invalid path. | 37| PERMISSION_NOT_PERSISTED<sup>12+</sup> | 4 | The permission is not persisted.| 38 39## PolicyErrorResult<sup>11+</sup> 40 41Represents the detailed permission policy error information, which can be used when **persistPermission**, **revokePermission**, **activatePermission**, or **deactivatePermission** throws an error. 42 43**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 44 45| Name | Type | Mandatory| Description | 46|---------|--------------------------------------|-----|-----------------------| 47| uri | string | Yes | URI of the file, on which the permission fails to be granted or activated. | 48| code | [PolicyErrorCode](#policyerrorcode11) | Yes | Error code.| 49| message | string | Yes | Cause of the error. | 50 51## PolicyInfo<sup>11+</sup> 52 53Represents a permission policy, that is, a policy for granting or activating the permission on a file. 54 55**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 56 57| Name | Type | Mandatory | Description | 58|---------------| ---------|-----|---------------------------------------------------------------------------------------------------------------------------------------------------| 59| uri | string | Yes | URI of the file, on which the permission is to be granted or activated. | 60| operationMode | number | Yes | Permissions on the URI. For details, see [OperationMode](#operationmode11).<br>For example, **fileShare.OperationMode.READ_MODE** indicates the read permission on the file.<br>**fileShare.OperationMode.READ_MODE\|fileShare.OperationMode.WRITE_MODE** indicates the read/write permission.| 61 62## fileShare.persistPermission<sup>11+</sup> 63 64persistPermission(policies: Array<PolicyInfo>): Promise<void> 65 66Persists the permissions granted to multiple files or folders. This API uses a promise to return the result.<br>This API is available only to the devices with the required system capability. 67 68**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 69 70**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 71 72**Parameters** 73 74| Name| Type | Mandatory| Description | 75| -------- |---------------------------------------| -------- |-------------------------| 76| policies| Array<[PolicyInfo](#policyinfo11)> | Yes| Array of permission policies. The maximum number of policies is 500.| 77 78**Return value** 79 80| Type| Description| 81| -------- | -------- | 82| Promise<void> | Promise that returns no value.| 83 84**Error codes** 85 86For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 87If the permission persistence of some URIs fails, error code 13900001 will be returned and the **data** field provides error information of these URIs in the Array<[PolicyErrorResult](#policyerrorresult11)> format. 88 89| ID | Error Message | 90|----------| --------- | 91| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 92| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 93| 801 | Capability not supported. | 94| 13900001 | Operation not permitted. | 95| 13900042 | Unknown error | 96 97**Example** 98 99 ```ts 100 import { BusinessError } from '@ohos.base'; 101 import picker from '@ohos.file.picker'; 102 103 async function persistPermissionExample() { 104 try { 105 let DocumentSelectOptions = new picker.DocumentSelectOptions(); 106 let documentPicker = new picker.DocumentViewPicker(); 107 let uris = await documentPicker.select(DocumentSelectOptions); 108 let policyInfo: fileShare.PolicyInfo = { 109 uri: uris[0], 110 operationMode: fileShare.OperationMode.READ_MODE, 111 }; 112 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 113 fileShare.persistPermission(policies).then(() => { 114 console.info("persistPermission successfully"); 115 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 116 console.error("persistPermission failed with error message: " + err.message + ", error code: " + err.code); 117 if (err.code == 13900001 && err.data) { 118 for (let i = 0; i < err.data.length; i++) { 119 console.error("error code : " + JSON.stringify(err.data[i].code)); 120 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 121 console.error("error reason : " + JSON.stringify(err.data[i].message)); 122 } 123 } 124 }); 125 } catch (error) { 126 let err: BusinessError = error as BusinessError; 127 console.error('persistPermission failed with err: ' + JSON.stringify(err)); 128 } 129 } 130 ``` 131 132## fileShare.revokePermission<sup>11+</sup> 133 134revokePermission(policies: Array<PolicyInfo>): Promise<void> 135 136Revokes permissions from multiple files or folders. This API uses a promise to return the result.<br>This API is available only to the devices with the required system capability. 137 138**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 139 140**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 141 142**Parameters** 143 144| Name| Type | Mandatory| Description | 145| -------- |--------------------| -------- |-------------------------| 146| policies| Array<[PolicyInfo](#policyinfo11)> | Yes| Array of permission policies. The maximum number of policies is 500.| 147 148**Return value** 149 150| Type| Description| 151| -------- | -------- | 152| Promise<void> | Promise that returns no value.| 153 154**Error codes** 155 156For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 157If the permission revocation of some URIs fails, error code 13900001 will be returned and the **data** field provides error information of these URIs in the Array<[PolicyErrorResult](#policyerrorresult11)> format. 158 159| ID | Error Message | 160|----------| --------- | 161| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 162| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 163| 801 | Capability not supported. | 164| 13900001 | Operation not permitted. | 165| 13900042 | Unknown error | 166 167**Example** 168 169 ```ts 170 import { BusinessError } from '@ohos.base'; 171 import picker from '@ohos.file.picker'; 172 173 async function revokePermissionExample() { 174 try { 175 let DocumentSelectOptions = new picker.DocumentSelectOptions(); 176 let documentPicker = new picker.DocumentViewPicker(); 177 let uris = await documentPicker.select(DocumentSelectOptions); 178 let policyInfo: fileShare.PolicyInfo = { 179 uri: uris[0], 180 operationMode: fileShare.OperationMode.READ_MODE, 181 }; 182 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 183 fileShare.revokePermission(policies).then(() => { 184 console.info("revokePermission successfully"); 185 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 186 console.error("revokePermission failed with error message: " + err.message + ", error code: " + err.code); 187 if (err.code == 13900001 && err.data) { 188 for (let i = 0; i < err.data.length; i++) { 189 console.error("error code : " + JSON.stringify(err.data[i].code)); 190 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 191 console.error("error reason : " + JSON.stringify(err.data[i].message)); 192 } 193 } 194 }); 195 } catch (error) { 196 let err: BusinessError = error as BusinessError; 197 console.error('revokePermission failed with err: ' + JSON.stringify(err)); 198 } 199 } 200 ``` 201 202## fileShare.activatePermission<sup>11+</sup> 203 204activatePermission(policies: Array<PolicyInfo>): Promise<void> 205 206Activates the permissions that have been persisted on multiple files or folders. This API uses a promise to return the result.<br>This API is available only to the devices with the required system capability. 207 208**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 209 210**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 211 212**Parameters** 213 214| Name| Type| Mandatory| Description | 215| -------- | -------- | -------- |-------------------------| 216| policies| Array<[PolicyInfo](#policyinfo11)> | Yes| Array of permission policies. The maximum number of policies is 500.| 217 218**Return value** 219 220| Type| Description| 221| -------- | -------- | 222| Promise<void> | Promise that returns no value.| 223 224**Error codes** 225 226For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 227If the permission activation of some URIs fails, error code 13900001 will be returned and the **data** field provides error information of these URIs in the Array<[PolicyErrorResult](#policyerrorresult11)> format. 228 229| ID | Error Message | 230|----------| --------- | 231| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 232| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 233| 801 | Capability not supported. | 234| 13900001 | Operation not permitted. | 235| 13900042 | Unknown error | 236 237**Example** 238 239 ```ts 240 import { BusinessError } from '@ohos.base'; 241 import picker from '@ohos.file.picker'; 242 243 async function activatePermissionExample() { 244 try { 245 let uri = "file://docs/storage/Users/username/tmp.txt"; 246 let policyInfo: fileShare.PolicyInfo = { 247 uri: uri, 248 operationMode: fileShare.OperationMode.READ_MODE, 249 }; 250 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 251 fileShare.activatePermission(policies).then(() => { 252 console.info("activatePermission successfully"); 253 }).catch(async (err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 254 console.error("activatePermission failed with error message: " + err.message + ", error code: " + err.code); 255 if (err.code == 13900001 && err.data) { 256 for (let i = 0; i < err.data.length; i++) { 257 console.error("error code : " + JSON.stringify(err.data[i].code)); 258 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 259 console.error("error reason : " + JSON.stringify(err.data[i].message)); 260 if(err.data[i].code == fileShare.PolicyErrorCode.PERMISSION_NOT_PERSISTED){ 261 await fileShare.persistPermission(policies); 262 } 263 } 264 } 265 }); 266 } catch (error) { 267 let err: BusinessError = error as BusinessError; 268 console.error('activatePermission failed with err: ' + JSON.stringify(err)); 269 } 270 } 271 ``` 272 273## fileShare.deactivatePermission<sup>11+</sup> 274 275deactivatePermission(policies: Array<PolicyInfo>): Promise<void> 276 277Deactivates the permissions on multiple files or folders. This API uses a promise to return the result. <br>This API is available only to the devices that have the required system capability. 278 279**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 280 281**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 282 283**Parameters** 284 285| Name| Type| Mandatory| Description | 286| -------- | -------- | -------- |-------------------------| 287| policies| Array<[PolicyInfo](#policyinfo11)> | Yes| Array of permission policies. The maximum number of policies is 500.| 288 289**Return value** 290 291| Type| Description| 292| -------- | -------- | 293| Promise<void> | Promise that returns no value.| 294 295**Error codes** 296 297For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 298If the permission deactivation of some URIs fails, error code 13900001 will be returned and the **data** field provides error information of these URIs in the Array<[PolicyErrorResult](#policyerrorresult11)> format. 299 300| ID | Error Message | 301|----------| --------- | 302| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 303| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 304| 801 | Capability not supported. | 305| 13900001 | Operation not permitted. | 306| 13900042 | Unknown error | 307 308**Example** 309 310 ```ts 311 import { BusinessError } from '@ohos.base'; 312 import picker from '@ohos.file.picker'; 313 314 async function deactivatePermissionExample() { 315 try { 316 let uri = "file://docs/storage/Users/username/tmp.txt"; 317 let policyInfo: fileShare.PolicyInfo = { 318 uri: uri, 319 operationMode: fileShare.OperationMode.READ_MODE, 320 }; 321 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 322 fileShare.deactivatePermission(policies).then(() => { 323 console.info("deactivatePermission successfully"); 324 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 325 console.error("deactivatePermission failed with error message: " + err.message + ", error code: " + err.code); 326 if (err.code == 13900001 && err.data) { 327 for (let i = 0; i < err.data.length; i++) { 328 console.error("error code : " + JSON.stringify(err.data[i].code)); 329 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 330 console.error("error reason : " + JSON.stringify(err.data[i].message)); 331 } 332 } 333 }); 334 } catch (error) { 335 let err: BusinessError = error as BusinessError; 336 console.error('deactivatePermission failed with err: ' + JSON.stringify(err)); 337 } 338 } 339 ``` 340 341## fileShare.checkPersistentPermission<sup>12+</sup> 342 343checkPersistentPermission(policies: Array<PolicyInfo>): Promise<Array<boolean>> 344 345Checks persistent permissions. This API uses a promise to return the result. 346 347**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 348 349**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 350 351**Parameters** 352 353| Name| Type | Mandatory| Description | 354| -------- |---------------------------------------| -------- |-------------------------| 355| policies| Array<[PolicyInfo](#policyinfo11)> | Yes| Array of permission policies. The maximum number of policies is 500.| 356 357**Return value** 358 359| Type | Description | 360| ----------------------------------- | ------------------------------------- | 361| Promise<Array<boolean>> | Promise used to return the result. The value **true** means the permission on the file or folder is persistent; the value **false** means the opposite.| 362 363**Error codes** 364 365For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 366 367| ID | Error Message | 368|----------| --------- | 369| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 370| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 371| 801 | Capability not supported. | 372| 13900042 | Unknown error | 373 374**Example** 375 376 ```ts 377 import { BusinessError } from '@ohos.base'; 378 import picker from '@ohos.file.picker'; 379 380 async function checkPersistentPermissionExample() { 381 try { 382 let documentSelectOptions = new picker.DocumentSelectOptions(); 383 let documentPicker = new picker.DocumentViewPicker(); 384 let uris = await documentPicker.select(documentSelectOptions); 385 let policyInfo: fileShare.PolicyInfo = { 386 uri: uris[0], 387 operationMode: fileShare.OperationMode.READ_MODE, 388 }; 389 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 390 fileShare.checkPersistentPermission(policies).then(async (data) => { 391 let result: Array<boolean> = data; 392 for (let i = 0; i < result.length; i++) { 393 console.log("checkPersistentPermission result: " + JSON.stringify(result[i])); 394 if(!result[i]){ 395 let info: fileShare.PolicyInfo = { 396 uri: policies[i].uri, 397 operationMode: policies[i].operationMode, 398 }; 399 let policy : Array<fileShare.PolicyInfo> = [info]; 400 await fileShare.persistPermission(policy); 401 } 402 } 403 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 404 console.error("checkPersistentPermission failed with error message: " + err.message + ", error code: " + err.code); 405 }); 406 } catch (error) { 407 let err: BusinessError = error as BusinessError; 408 console.error('checkPersistentPermission failed with err: ' + JSON.stringify(err)); 409 } 410 } 411 ``` 412