1# oh_file_share.h 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 9## Overview 10 11Provides APIs for persisting permissions, activating or deactivating persistent permissions, and checking the persistent permissions on files or directories based on their URIs. 12 13**Library**: libohfileshare.so 14 15**System capability**: SystemCapability.FileManagement.AppFileService.FolderAuthorization 16 17**Since**: 12 18 19**Related module**: [fileShare](capi-fileshare.md) 20 21## Summary 22 23### Structs 24 25| Name| typedef Keyword| Description| 26| -- | -- | -- | 27| [FileShare_PolicyErrorResult](capi-fileshare-fileshare-policyerrorresult.md) | FileShare_PolicyErrorResult | Represents the permission policy error result.| 28| [FileShare_PolicyInfo](capi-fileshare-fileshare-policyinfo.md) | FileShare_PolicyInfo | Represents the permission policy information.| 29 30### Enums 31 32| Name| typedef Keyword| Description| 33| -- | -- | -- | 34| [FileShare_OperationMode](#fileshare_operationmode) | FileShare_OperationMode | Enumerates the URI operation mode.| 35| [FileShare_PolicyErrorCode](#fileshare_policyerrorcode) | FileShare_PolicyErrorCode | Enumerates the permission policy error code.| 36 37### Functions 38 39| Name| Description| 40| -- | -- | 41| [FileManagement_ErrCode OH_FileShare_PersistPermission(const FileShare_PolicyInfo *policies, unsigned int policyNum,FileShare_PolicyErrorResult **result, unsigned int *resultNum)](#oh_fileshare_persistpermission) | Persists the permissions on files or directories.| 42| [FileManagement_ErrCode OH_FileShare_RevokePermission(const FileShare_PolicyInfo *policies, unsigned int policyNum,FileShare_PolicyErrorResult **result, unsigned int *resultNum)](#oh_fileshare_revokepermission) | Revokes the permissions from files or directories.| 43| [FileManagement_ErrCode OH_FileShare_ActivatePermission(const FileShare_PolicyInfo *policies, unsigned int policyNum,FileShare_PolicyErrorResult **result, unsigned int *resultNum)](#oh_fileshare_activatepermission) | Activates the persistent permissions on files or directories.| 44| [FileManagement_ErrCode OH_FileShare_DeactivatePermission(const FileShare_PolicyInfo *policies, unsigned int policyNum,FileShare_PolicyErrorResult **result, unsigned int *resultNum)](#oh_fileshare_deactivatepermission) | Deactivates the persistent permissions on files or directories.| 45| [FileManagement_ErrCode OH_FileShare_CheckPersistentPermission(const FileShare_PolicyInfo *policies, unsigned int policyNum, bool **result, unsigned int *resultNum)](#oh_fileshare_checkpersistentpermission) | Checks the persistent permissions on files or directories.| 46| [void OH_FileShare_ReleasePolicyErrorResult(FileShare_PolicyErrorResult *errorResult, unsigned int resultNum)](#oh_fileshare_releasepolicyerrorresult) | Releases the memory, to which **FileShare_PolicyErrorResult** points.| 47 48## Enum Description 49 50### FileShare_OperationMode 51 52``` 53enum FileShare_OperationMode 54``` 55 56**Description** 57 58Enumerates the URI operation mode. 59 60**Since**: 12 61 62| Enum Item| Description| 63| -- | -- | 64| READ_MODE = 1 << 0 | Read.| 65| WRITE_MODE = 1 << 1 | Write.| 66 67### FileShare_PolicyErrorCode 68 69``` 70enum FileShare_PolicyErrorCode 71``` 72 73**Description** 74 75Enumerates the permission policy error code. 76 77**Since**: 12 78 79| Enum Item| Description| 80| -- | -- | 81| PERSISTENCE_FORBIDDEN = 1 | The permission on the URI cannot be persisted.| 82| INVALID_MODE = 2 | Invalid mode.| 83| INVALID_PATH = 3 | Invalid path.| 84| PERMISSION_NOT_PERSISTED = 4 | The permission is not persisted.| 85 86 87## Function Description 88 89### OH_FileShare_PersistPermission() 90 91``` 92FileManagement_ErrCode OH_FileShare_PersistPermission(const FileShare_PolicyInfo *policies, unsigned int policyNum,FileShare_PolicyErrorResult **result, unsigned int *resultNum) 93``` 94 95**Description** 96 97Persists the permissions on files or directories. 98 99**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 100 101**Since**: 12 102 103 104**Parameters** 105 106| Name| Description| 107| -- | -- | 108| [const FileShare_PolicyInfo](capi-fileshare-fileshare-policyinfo.md) *policies | Pointer to a **FileShare_PolicyInfo** instance.| 109| unsigned int policyNum | Number of policies in the **FileShare_PolicyInfo** array.| 110| [FileShare_PolicyErrorResult](capi-fileshare-fileshare-policyerrorresult.md) **result | Double pointer to the **FileShare_PolicyErrorResult** array. Use **OH_FileShare_ReleasePolicyErrorResult()** to release the memory allocated.| 111| unsigned int *resultNum | Pointer to the size of the **FileShare_PolicyErrorResult** array.| 112 113**Returns** 114 115| Type| Description| 116| -- | -- | 117| [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode) | Returns [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode).<br> E_PARAMS 401 - The input parameter is invalid. Possible causes:<br> 1. The **policies**, **result**, or **resultNum** parameter is a null pointer.<br> 2. The value of **policyNum** is **0** or exceeds the maximum length (500).<br> 3. The value of **uri** in the **policies** parameter is empty, the value of **length** is **0**, or the value of **uri** is different from the value of **length**.<br> E_DEVICE_NOT_SUPPORT 801 - The device does not support this API.<br> E_PERMISSION 201 - The permission verification fails.<br> E_ENOMEM 13900011 - The memory allocation or copy fails.<br> E_EPERM 13900001 - The operation is not allowed.<br> E_UNKNOWN_ERROR 13900042 - An unknown internal error occurs. The error is none of the preceding errors.<br> E_NO_ERROR 0 - The API is successfully called.| 118 119### OH_FileShare_RevokePermission() 120 121``` 122FileManagement_ErrCode OH_FileShare_RevokePermission(const FileShare_PolicyInfo *policies, unsigned int policyNum,FileShare_PolicyErrorResult **result, unsigned int *resultNum) 123``` 124 125**Description** 126 127Revokes the permissions from files or directories. 128 129**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 130 131**Since**: 12 132 133 134**Parameters** 135 136| Name| Description| 137| -- | -- | 138| [const FileShare_PolicyInfo](capi-fileshare-fileshare-policyinfo.md) *policies | Pointer to a **FileShare_PolicyInfo** instance.| 139| unsigned int policyNum | Number of policies in the **FileShare_PolicyInfo** array.| 140| [FileShare_PolicyErrorResult](capi-fileshare-fileshare-policyerrorresult.md) **result | Double pointer to the **FileShare_PolicyErrorResult** array. Use **OH_FileShare_ReleasePolicyErrorResult()** to release the memory allocated.| 141| unsigned int *resultNum | Pointer to the size of the **FileShare_PolicyErrorResult** array.| 142 143**Returns** 144 145| Type| Description| 146| -- | -- | 147| [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode) | Returns [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode).<br> E_PARAMS 401 - The input parameter is invalid. Possible causes:<br>1. The **policies**, **result**, or **resultNum** parameter is a null pointer.<br> 2. The value of **policyNum** is **0** or exceeds the maximum length (500).<br>3. The value of **uri** in the **policies** parameter is empty, the value of **length** is **0**, or the value of **uri** is different from the value of **length**.<br> E_DEVICE_NOT_SUPPORT 801 - The device does not support this API.<br> E_PERMISSION 201 - The permission verification fails.<br> E_ENOMEM 13900011 - The memory allocation or copy fails.<br> E_EPERM 13900001 - The operation is not allowed.<br> E_UNKNOWN_ERROR 13900042 - An unknown internal error occurs. The error is none of the preceding errors.<br> E_NO_ERROR - The API is called successfully.| 148 149### OH_FileShare_ActivatePermission() 150 151``` 152FileManagement_ErrCode OH_FileShare_ActivatePermission(const FileShare_PolicyInfo *policies, unsigned int policyNum,FileShare_PolicyErrorResult **result, unsigned int *resultNum) 153``` 154 155**Description** 156 157Activates the persistent permissions on files or directories. 158 159**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 160 161**Since**: 12 162 163 164**Parameters** 165 166| Name| Description| 167| -- | -- | 168| [const FileShare_PolicyInfo](capi-fileshare-fileshare-policyinfo.md) *policies | Pointer to a **FileShare_PolicyInfo** instance.| 169| unsigned int policyNum | Number of policies in the **FileShare_PolicyInfo** array.| 170| [FileShare_PolicyErrorResult](capi-fileshare-fileshare-policyerrorresult.md) **result | Double pointer to the **FileShare_PolicyErrorResult** array. Use **OH_FileShare_ReleasePolicyErrorResult()** to release the memory allocated.| 171| unsigned int *resultNum | Pointer to the size of the **FileShare_PolicyErrorResult** array.| 172 173**Returns** 174 175| Type| Description| 176| -- | -- | 177| [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode) | Returns [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode).<br> E_PARAMS 401 - The input parameter is invalid. Possible causes:<br> 1. The **policies**, **result**, or **resultNum** parameter is a null pointer.<br> 2. The value of **policyNum** is **0** or exceeds the maximum length (500).<br> 3. The value of **uri** in the **policies** parameter is empty, the value of **length** is **0**, or the value of **uri** is different from the value of **length**.<br> E_DEVICE_NOT_SUPPORT 801 - The device does not support this API.<br> E_PERMISSION 201 - The permission verification fails.<br> E_ENOMEM 13900011 - The memory allocation or copy fails.<br> E_EPERM 13900001 - The operation is not allowed.<br> E_UNKNOWN_ERROR 13900042 - An unknown internal error occurs. The error is none of the preceding errors.<br> E_NO_ERROR 0 - The API is successfully called.| 178 179### OH_FileShare_DeactivatePermission() 180 181``` 182FileManagement_ErrCode OH_FileShare_DeactivatePermission(const FileShare_PolicyInfo *policies, unsigned int policyNum,FileShare_PolicyErrorResult **result, unsigned int *resultNum) 183``` 184 185**Description** 186 187Deactivates the persistent permissions on files or directories. 188 189**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 190 191**Since**: 12 192 193 194**Parameters** 195 196| Name| Description| 197| -- | -- | 198| [const FileShare_PolicyInfo](capi-fileshare-fileshare-policyinfo.md) *policies | Pointer to a **FileShare_PolicyInfo** instance.| 199| unsigned int policyNum | Number of policies in the **FileShare_PolicyInfo** array.| 200| [FileShare_PolicyErrorResult](capi-fileshare-fileshare-policyerrorresult.md) **result | Double pointer to the **FileShare_PolicyErrorResult** array. Use **OH_FileShare_ReleasePolicyErrorResult()** to release the memory allocated.| 201| unsigned int *resultNum | Pointer to the size of the **FileShare_PolicyErrorResult** array.| 202 203**Returns** 204 205| Type| Description| 206| -- | -- | 207| [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode) | Returns [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode).<br> E_PARAMS 401 - The input parameter is invalid. Possible causes:<br> 1. The **policies**, **result**, or **resultNum** parameter is a null pointer.<br> 2. The value of **policyNum** is **0** or exceeds the maximum length (500).<br> 3. The value of **uri** in the **policies** parameter is empty, the value of **length** is **0**, or the value of **uri** is different from the value of **length**.<br> E_DEVICE_NOT_SUPPORT 801 - The device does not support this API.<br> E_PERMISSION 201 - The permission verification fails.<br> E_ENOMEM 13900011 - The memory allocation or copy fails.<br> E_EPERM 13900001 - The operation is not allowed.<br> E_UNKNOWN_ERROR 13900042 - An unknown internal error occurs. The error is none of the preceding errors.<br> E_NO_ERROR - The API is called successfully.| 208 209### OH_FileShare_CheckPersistentPermission() 210 211``` 212FileManagement_ErrCode OH_FileShare_CheckPersistentPermission(const FileShare_PolicyInfo *policies, unsigned int policyNum, bool **result, unsigned int *resultNum) 213``` 214 215**Description** 216 217Checks the persistent permissions on files or directories. 218 219**Required permissions**: ohos.permission.FILE_ACCESS_PERSIST 220 221**Since**: 12 222 223 224**Parameters** 225 226| Name| Description| 227| -- | -- | 228| [const FileShare_PolicyInfo](capi-fileshare-fileshare-policyinfo.md) *policies | Pointer to a **FileShare_PolicyInfo** instance.| 229| unsigned int policyNum | Number of policies in the **FileShare_PolicyInfo** array.| 230| bool **result | Double pointer to the check result obtained. You also need to include **malloc.h** and use **free()** to release the memory allocated.| 231| unsigned int *resultNum | Pointer to the size of the check result array.| 232 233**Returns** 234 235| Type| Description| 236| -- | -- | 237| [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode) | Returns [FileManagement_ErrCode](capi-error-code-h.md#filemanagement_errcode).<br> E_PARAMS 401 - The input parameter is invalid. Possible causes:<br> 1. The **policies**, **result**, or **resultNum** parameter is a null pointer.<br> 2. The value of **policyNum** is **0** or exceeds the maximum length (500).<br> 3. The value of **uri** in the **policies** parameter is empty, the value of **length** is **0**, or the value of **uri** is different from the value of **length**.<br> E_DEVICE_NOT_SUPPORT 801 - The device does not support this API.<br> E_PERMISSION 201 - The permission verification fails.<br> E_ENOMEM 13900011 - The memory allocation or copy fails.<br> E_EPERM 13900001 - The operation is not allowed. All URIs carried in **policies** do not meet the specifications, or the path converted from the URI does not exist.<br> E_UNKNOWN_ERROR 13900042 - An unknown internal error occurs. The error is none of the preceding errors.<br> E_NO_ERROR 0 - The API is successfully called.| 238 239### OH_FileShare_ReleasePolicyErrorResult() 240 241``` 242void OH_FileShare_ReleasePolicyErrorResult(FileShare_PolicyErrorResult *errorResult, unsigned int resultNum) 243``` 244 245**Description** 246 247Releases the memory, to which **FileShare_PolicyErrorResult** points. 248 249**Since**: 12 250 251 252**Parameters** 253 254| Name| Description| 255| -- | -- | 256| [FileShare_PolicyErrorResult](capi-fileshare-fileshare-policyerrorresult.md) *errorResult | Pointer to a **FileShare_PolicyErrorResult** instance.| 257| unsigned int resultNum | Size of the **FileShare_PolicyErrorResult** array.| 258