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