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