1# @ohos.fileshare (File Sharing) 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 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 38## PolicyErrorResult<sup>11+</sup> 39 40Represents the detailed permission policy error information, which can be used when **persistPermission**, **revokePermission**, **activatePermission**, or **deactivatePermission** throws an error. 41 42**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 43 44| Name | Type | Description | 45|---------|--------------------------------------|-------------------| 46| uri | string | URI of the file, on which the permission fails to be granted or activated. | 47| code | [PolicyErrorCode](#policyerrorcode11) | Error code.| 48| message | string | Cause of the error. | 49 50## PolicyInfo<sup>11+</sup> 51 52Represents a permission policy, that is, a policy for granting or activating the permission on a file. 53 54**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 55 56| Name | Type | Mandatory | Description | 57|---------------| ---------|-----|---------------------------------------------------------------------------------------------------------------------------------------------------| 58| uri | string | Yes | URI of the file. | 59| operationMode | number | Yes | Mode for accessing 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 and write permissions on the file. | 60 61## fileShare.persistPermission<sup>11+</sup> 62 63persistPermission(policies: Array<PolicyInfo>): Promise<void> 64 65Persists the permissions granted to multiple files or folders. This API uses a promise to return the result.<br>This API is available only to certain devices. 66 67**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 68 69**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 70 71**Parameters** 72 73| Name| Type | Mandatory| Description | 74| -------- |---------------------------------------| -------- |-------------------------| 75| policies| Array<[PolicyInfo](#policyinfo11)> | Yes| Permissions to persist. | 76 77**Return value** 78 79| Type| Description| 80| -------- | -------- | 81| Promise<void> | Promise that returns no value.| 82 83**Error codes** 84 85For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 86If 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. 87 88| ID | Error Message | 89|----------| --------- | 90| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 91| 401 | Parameter error. | 92| 801 | Capability not supported. | 93| 13900001 | Operation not permitted. | 94| 13900042 | Unknown error | 95 96**Example** 97 98 ```ts 99 import { BusinessError } from '@ohos.base'; 100 import picker from '@ohos.file.picker'; 101 102 async function persistPermissionExample() { 103 try { 104 let DocumentSelectOptions = new picker.DocumentSelectOptions(); 105 let documentPicker = new picker.DocumentViewPicker(); 106 let uris = await documentPicker.select(DocumentSelectOptions); 107 let policyInfo: fileShare.PolicyInfo = { 108 uri: uris[0], 109 operationMode: fileShare.OperationMode.READ_MODE, 110 }; 111 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 112 fileShare.persistPermission(policies).then(() => { 113 console.info("persistPermission successfully"); 114 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 115 console.info("persistPermission failed with error message: " + err.message + ", error code: " + err.code); 116 if (err.code == 13900001 && err.data) { 117 for (let i = 0; i < err.data.length; i++) { 118 console.log("error code : " + JSON.stringify(err.data[i].code)); 119 console.log("error uri : " + JSON.stringify(err.data[i].uri)); 120 console.log("error reason : " + JSON.stringify(err.data[i].message)); 121 } 122 } 123 }); 124 } catch (error) { 125 let err: BusinessError = error as BusinessError; 126 console.error('persistPermission failed with err: ' + JSON.stringify(err)); 127 } 128 } 129 ``` 130 131## fileShare.revokePermission<sup>11+</sup> 132 133revokePermission(policies: Array<PolicyInfo>): Promise<void> 134 135Revokes permissions from multiple files or folders. This API uses a promise to return the result.<br>This API is available only to certain devices. 136 137**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 138 139**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 140 141**Parameters** 142 143| Name| Type | Mandatory| Description | 144| -------- |--------------------| -------- |-------------------------| 145| policies| Array<[PolicyInfo](#policyinfo11)> | Yes| Permissions to revoke. | 146 147**Return value** 148 149| Type| Description| 150| -------- | -------- | 151| Promise<void> | Promise that returns no value.| 152 153**Error codes** 154 155For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 156If 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. 157 158| ID | Error Message | 159|----------| --------- | 160| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 161| 401 | Parameter error. | 162| 801 | Capability not supported. | 163| 13900001 | Operation not permitted. | 164| 13900042 | Unknown error | 165 166**Example** 167 168 ```ts 169 import { BusinessError } from '@ohos.base'; 170 import picker from '@ohos.file.picker'; 171 172 async function revokePermissionExample() { 173 try { 174 let DocumentSelectOptions = new picker.DocumentSelectOptions(); 175 let documentPicker = new picker.DocumentViewPicker(); 176 let uris = await documentPicker.select(DocumentSelectOptions); 177 let policyInfo: fileShare.PolicyInfo = { 178 uri: uris[0], 179 operationMode: fileShare.OperationMode.READ_MODE, 180 }; 181 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 182 fileShare.revokePermission(policies).then(() => { 183 console.info("revokePermission successfully"); 184 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 185 console.info("revokePermission failed with error message: " + err.message + ", error code: " + err.code); 186 if (err.code == 13900001 && err.data) { 187 for (let i = 0; i < err.data.length; i++) { 188 console.log("error code : " + JSON.stringify(err.data[i].code)); 189 console.log("error uri : " + JSON.stringify(err.data[i].uri)); 190 console.log("error reason : " + JSON.stringify(err.data[i].message)); 191 } 192 } 193 }); 194 } catch (error) { 195 let err: BusinessError = error as BusinessError; 196 console.error('revokePermission failed with err: ' + JSON.stringify(err)); 197 } 198 } 199 ``` 200 201## fileShare.activatePermission<sup>11+</sup> 202 203activatePermission(policies: Array<PolicyInfo>): Promise<void> 204 205Activates 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 certain devices. 206 207**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 208 209**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 210 211**Parameters** 212 213| Name| Type| Mandatory| Description | 214| -------- | -------- | -------- |-------------------------| 215| policies| Array<[PolicyInfo](#policyinfo11)> | Yes| Permissions to activate. | 216 217**Return value** 218 219| Type| Description| 220| -------- | -------- | 221| Promise<void> | Promise that returns no value.| 222 223**Error codes** 224 225For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 226If 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. 227 228| ID | Error Message | 229|----------| --------- | 230| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 231| 401 | Parameter error. | 232| 801 | Capability not supported. | 233| 13900001 | Operation not permitted. | 234| 13900042 | Unknown error | 235 236**Example** 237 238 ```ts 239 import { BusinessError } from '@ohos.base'; 240 import picker from '@ohos.file.picker'; 241 242 async function activatePermissionExample() { 243 try { 244 let uri = "file://docs/storage/Users/username/tmp.txt"; 245 let policyInfo: fileShare.PolicyInfo = { 246 uri: uri, 247 operationMode: fileShare.OperationMode.READ_MODE, 248 }; 249 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 250 fileShare.activatePermission(policies).then(() => { 251 console.info("activatePermission successfully"); 252 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 253 console.info("activatePermission failed with error message: " + err.message + ", error code: " + err.code); 254 if (err.code == 13900001 && err.data) { 255 for (let i = 0; i < err.data.length; i++) { 256 console.log("error code : " + JSON.stringify(err.data[i].code)); 257 console.log("error uri : " + JSON.stringify(err.data[i].uri)); 258 console.log("error reason : " + JSON.stringify(err.data[i].message)); 259 } 260 } 261 }); 262 } catch (error) { 263 let err: BusinessError = error as BusinessError; 264 console.error('activatePermission failed with err: ' + JSON.stringify(err)); 265 } 266 } 267 ``` 268 269## fileShare.deactivatePermission<sup>11+</sup> 270 271deactivatePermission(policies: Array<PolicyInfo>): Promise<void> 272 273Deactivates the permissions on multiple files or folders. This API uses a promise to return the result. <br>This API is available only to certain devices. 274 275**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 276 277**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 278 279**Parameters** 280 281| Name| Type| Mandatory| Description | 282| -------- | -------- | -------- |-------------------------| 283| policies| Array<[PolicyInfo](#policyinfo11)> | Yes| Permissions to deactivate. | 284 285**Return value** 286 287| Type| Description| 288| -------- | -------- | 289| Promise<void> | Promise that returns no value.| 290 291**Error codes** 292 293For details about the error codes, see [File Management Error Codes](errorcode-filemanagement.md). 294If 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. 295 296| ID | Error Message | 297|----------| --------- | 298| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 299| 401 | Parameter error. | 300| 801 | Capability not supported. | 301| 13900001 | Operation not permitted. | 302| 13900042 | Unknown error | 303 304**Example** 305 306 ```ts 307 import { BusinessError } from '@ohos.base'; 308 import picker from '@ohos.file.picker'; 309 310 async function deactivatePermissionExample() { 311 try { 312 let uri = "file://docs/storage/Users/username/tmp.txt"; 313 let policyInfo: fileShare.PolicyInfo = { 314 uri: uri, 315 operationMode: fileShare.OperationMode.READ_MODE, 316 }; 317 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 318 fileShare.deactivatePermission(policies).then(() => { 319 console.info("deactivatePermission successfully"); 320 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 321 console.info("deactivatePermission failed with error message: " + err.message + ", error code: " + err.code); 322 if (err.code == 13900001 && err.data) { 323 for (let i = 0; i < err.data.length; i++) { 324 console.log("error code : " + JSON.stringify(err.data[i].code)); 325 console.log("error uri : " + JSON.stringify(err.data[i].uri)); 326 console.log("error reason : " + JSON.stringify(err.data[i].message)); 327 } 328 } 329 }); 330 } catch (error) { 331 let err: BusinessError = error as BusinessError; 332 console.error('deactivatePermission failed with err: ' + JSON.stringify(err)); 333 } 334 } 335 ``` 336