1# @ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object) (System API) 2 3The module provides APIs for album management, including creating an album and accessing and modifying media data in an album, based on a [Sendable](../../arkts-utils/arkts-sendable.md) object. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object)](js-apis-sendablePhotoAccessHelper.md). 9 10## Modules to Import 11 12```ts 13import { sendablePhotoAccessHelper } from '@kit.MediaLibraryKit'; 14``` 15 16## sendablePhotoAccessHelper.getPhotoAccessHelper<sup>19+</sup> 17 18getPhotoAccessHelper(context: Context, userId: number): PhotoAccessHelper 19 20Obtains a PhotoAccessHelper instance for the specified user, letting you access and modify media files in an album. 21 22**Model restriction**: This API can be used only in the stage model. 23 24**System API**: This is a system API. 25 26**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 27 28**Parameters** 29 30| Name | Type | Mandatory| Description | 31| ------- | ------- | ---- | -------------------------- | 32| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Context of the ability instance.| 33| userId | number | Yes | ID of the user.| 34 35**Return value** 36 37| Type | Description | 38| ----------------------------- | :---- | 39| [PhotoAccessHelper](#photoaccesshelper) | PhotoAccessHelper instance obtained.| 40 41**Error codes** 42 43For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 44 45| ID| Error Message| 46| -------- | ---------------------------------------- | 47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 48 49**Example** 50 51```ts 52// The phAccessHelper instance obtained is a global object. It is used by default in subsequent operations. If the code snippet is not added, an error will be reported indicating that phAccessHelper is not defined. 53// Obtain the context from the component and ensure that the return value of this.getUiContext().getHostContext() is UIAbilityContext. 54import { common } from '@kit.AbilityKit'; 55 56@Entry 57@Component 58struct Index { 59 build() { 60 Row() { 61 Button("example").onClick(async () => { 62 let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext; 63 // 101 indicates the user ID of another user space. 64 let phAccessHelper = sendablePhotoAccessHelper.getPhotoAccessHelper(context, 101); 65 }).width('100%') 66 } 67 .height('90%') 68 } 69} 70``` 71 72## PhotoAccessHelper 73 74### createAsset 75 76createAsset(displayName: string): Promise<PhotoAsset> 77 78Creates an asset with the specified file name. This API uses a promise to return the result. 79 80The file name must comply with the following specifications: 81- The file name consists of a valid file name and an image or video file name extension. 82- The file name cannot exceed 255 characters. 83- The file name cannot contain any of the following characters:<br>API version 18 and later: \ / : * ? " < > |<br>API versions 10 to 17: . .. \ / : * ? " ' ` < > | { } [ ] 84 85**System API**: This is a system API. 86 87**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 88 89**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO 90 91**Parameters** 92 93| Name | Type | Mandatory| Description | 94| ----------- | ------ | ---- | -------------------------- | 95| displayName | string | Yes | File name of the asset to create.| 96 97**Return value** 98 99| Type | Description | 100| ---------------------------------------- | --------------------------------------- | 101| Promise<[PhotoAsset](#photoasset)> | Promise used to return the created asset.| 102 103**Error codes** 104 105For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 106 107| ID| Error Message | 108| -------- | ------------------------------------------------------------ | 109| 202 | Called by non-system application. | 110| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 111| 201 | Permission denied. | 112| 13900020 | Invalid argument. | 113| 14000001 | Invalid display name. | 114| 14000011 | Internal system error | 115 116**Example** 117 118For details about how to create a phAccessHelper instance, see the example provided in [@ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object)](js-apis-sendablePhotoAccessHelper.md). 119 120```ts 121async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 122 console.info('createAssetDemo'); 123 try { 124 let testFileName: string = 'testFile' + Date.now() + '.jpg'; 125 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await phAccessHelper.createAsset(testFileName); 126 console.info('createAsset file displayName' + photoAsset.displayName); 127 console.info('createAsset successfully'); 128 } catch (err) { 129 console.error(`createAsset failed, error: ${err.code}, ${err.message}`); 130 } 131} 132``` 133 134### createAsset 135 136createAsset(displayName: string, options: PhotoCreateOptions): Promise<PhotoAsset> 137 138Creates an asset with the specified file name and options. This API uses a promise to return the result. 139 140The file name must comply with the following specifications: 141- The file name consists of a valid file name and an image or video file name extension. 142- The file name cannot exceed 255 characters. 143- The file name cannot contain any of the following characters:<br>API version 18 and later: \ / : * ? " < > |<br>API versions 10 to 17: . .. \ / : * ? " ' ` < > | { } [ ] 144 145**System API**: This is a system API. 146 147**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 148 149**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO 150 151**Parameters** 152 153| Name | Type | Mandatory| Description | 154| ----------- | ------------------------------------------------------------ | ---- | -------------------------- | 155| displayName | string | Yes | File name of the asset to create.| 156| options | [PhotoCreateOptions](js-apis-photoAccessHelper-sys.md#photocreateoptions) | Yes | Options for creating the asset. | 157 158**Return value** 159 160| Type | Description | 161| ---------------------------------------- | --------------------------------------- | 162| Promise<[PhotoAsset](#photoasset)> | Promise used to return the created asset.| 163 164**Error codes** 165 166For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 167 168| ID| Error Message | 169| -------- | ------------------------------------------------------------ | 170| 202 | Called by non-system application. | 171| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 172| 201 | Permission denied. | 173| 13900020 | Invalid argument. | 174| 14000001 | Invalid display name. | 175| 14000011 | Internal system error | 176 177**Example** 178 179For details about how to create a phAccessHelper instance, see the example provided in [@ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object)](js-apis-sendablePhotoAccessHelper.md). 180 181```ts 182async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 183 console.info('createAssetDemo'); 184 try { 185 let testFileName:string = 'testFile' + Date.now() + '.jpg'; 186 let createOption: photoAccessHelper.PhotoCreateOptions = { 187 subtype: photoAccessHelper.PhotoSubtype.DEFAULT 188 } 189 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await phAccessHelper.createAsset(testFileName, createOption); 190 console.info('createAsset file displayName' + photoAsset.displayName); 191 console.info('createAsset successfully'); 192 } catch (err) { 193 console.error(`createAsset failed, error: ${err.code}, ${err.message}`); 194 } 195} 196``` 197 198### getHiddenAlbums 199 200getHiddenAlbums(mode: HiddenPhotosDisplayMode, options?: FetchOptions): Promise<FetchResult<Album>> 201 202Obtains hidden albums based on the specified display mode and retrieval options. This API uses a promise to return the result. 203 204**System API**: This is a system API. 205 206**Required permissions**: ohos.permission.READ_IMAGEVIDEO and ohos.permission.MANAGE_PRIVATE_PHOTOS 207 208**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 209 210**Parameters** 211 212| Name | Type | Mandatory| Description | 213| ------- | ------------------------------------------------------------ | ---- | ---------------------------------------------- | 214| mode | [HiddenPhotosDisplayMode](js-apis-photoAccessHelper-sys.md#hiddenphotosdisplaymode11) | Yes | Display mode of hidden albums. | 215| options | [FetchOptions](arkts-apis-photoAccessHelper-i.md#fetchoptions) | No | Options for retrieving the albums. If this parameter is not specified, the albums are retrieved based on the display mode.| 216 217**Return value** 218 219| Type | Description | 220| ------------------------------------------------------------ | ----------------------------------- | 221| Promise<[FetchResult](arkts-apis-photoAccessHelper-FetchResult.md)<[Album](#album)>> | Promise used to return the result.| 222 223**Error codes** 224 225For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 226 227| ID| Error Message | 228| -------- | ------------------------------------------------------------ | 229| 201 | Permission verification failed, usually the result returned by VerifyAccessToken. | 230| 202 | Permission verification failed, application which is not a system application uses system API. | 231| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 232| 14000011 | Internal system error. | 233 234**Example** 235 236For details about how to create a phAccessHelper instance, see the example provided in [@ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object)](js-apis-sendablePhotoAccessHelper.md). 237 238```ts 239import { dataSharePredicates } from '@kit.ArkData'; 240import { BusinessError } from '@kit.BasicServicesKit'; 241 242// Obtain the preset hidden album. 243async function getSysHiddenAlbum(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 244 console.info('getSysHiddenAlbumDemo'); 245 phAccessHelper.getHiddenAlbums(photoAccessHelper.HiddenPhotosDisplayMode.ASSETS_MODE) 246 .then( async (fetchResult) => { 247 if (fetchResult === undefined) { 248 console.error('getSysHiddenAlbumPromise fetchResult is undefined'); 249 return; 250 } 251 let hiddenAlbum: sendablePhotoAccessHelper.Album = await fetchResult.getFirstObject(); 252 console.info('getAlbumsPromise successfully, albumUri: ' + hiddenAlbum.albumUri); 253 fetchResult.close(); 254 }).catch((err: BusinessError) => { 255 console.error(`getSysHiddenAlbumPromise failed with err: ${err.code}, ${err.message}`); 256 }); 257} 258 259// Obtain the hidden albums displayed by album, that is, the albums with hidden files. Such albums do not include the preset hidden album and the albums in the trash. 260async function getHiddenAlbumsView(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 261 console.info('getHiddenAlbumsViewDemo'); 262 phAccessHelper.getHiddenAlbums(photoAccessHelper.HiddenPhotosDisplayMode.ALBUMS_MODE).then( async (fetchResult) => { 263 if (fetchResult === undefined) { 264 console.error('getHiddenAlbumsViewPromise fetchResult is undefined'); 265 return; 266 } 267 let albums: Array<sendablePhotoAccessHelper.Album> = await fetchResult.getAllObjects(); 268 console.info('getHiddenAlbumsViewPromise successfully, albums size: ' + albums.length); 269 270 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 271 let fetchOption: photoAccessHelper.FetchOptions = { 272 fetchColumns: [], 273 predicates: predicates 274 }; 275 for (let i = 0; i < albums.length; i++) { 276 // Obtain hidden files in the album. 277 albums[i].getAssets(fetchOption).then((assetFetchResult) => { 278 console.info('album get hidden assets successfully, getCount: ' + assetFetchResult.getCount()); 279 }).catch((err: BusinessError) => { 280 console.error(`album get hidden assets failed with error: ${err.code}, ${err.message}`); 281 }); 282 } 283 fetchResult.close(); 284 }).catch((err: BusinessError) => { 285 console.error(`getHiddenAlbumsViewPromise failed with err: ${err.code}, ${err.message}`); 286 }); 287} 288``` 289 290## PhotoAsset 291 292Provides APIs for encapsulating file asset attributes. 293 294### requestSource 295 296requestSource(): Promise<number> 297 298Opens the source file to obtain the file descriptor (FD). This API uses a promise to return the result. 299 300**System API**: This is a system API. 301 302**Required permissions**: ohos.permission.READ_IMAGEVIDEO 303 304**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 305 306**Return value** 307 308| Type | Description | 309| --------------------- | --------------------------- | 310| Promise<number> | Promise used to return the FD obtained.| 311 312**Error codes** 313 314For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 315 316| ID| Error Message | 317| -------- | ------------------------------------------------------------ | 318| 201 | Permission denied. | 319| 202 | Called by non-system application. | 320| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 321| 14000011 | Internal system error | 322 323**Example** 324 325For details about how to create a phAccessHelper instance, see the example provided in [@ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object)](js-apis-sendablePhotoAccessHelper.md). 326 327```ts 328import { dataSharePredicates } from '@kit.ArkData'; 329import { common } from '@kit.AbilityKit'; 330 331async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 332 try { 333 console.info('requsetSourcePromiseDemo') 334 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 335 let fetchOptions: photoAccessHelper.FetchOptions = { 336 fetchColumns: [], 337 predicates: predicates 338 }; 339 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions); 340 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 341 let fd = await photoAsset.requestSource(); 342 console.info('Source fd is ' + fd); 343 } catch (err) { 344 console.error(`requsetSourcePromiseDemo failed with error: ${err.code}, ${err.message}`); 345 } 346} 347``` 348 349### getAnalysisData 350 351getAnalysisData(analysisType: AnalysisType): Promise\<string> 352 353Obtains analysis data. This API uses a promise to return the result. 354 355**System API**: This is a system API. 356 357**Required permissions**: ohos.permission.READ\_IMAGEVIDEO 358 359**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 360 361**Parameters** 362 363| Name | Type | Mandatory| Description | 364| :----------- | :----------------------------------------------------------- | :--- | :----------------------- | 365| analysisType | [AnalysisType](js-apis-photoAccessHelper-sys.md#analysistype11) | Yes | Smart analysis type.| 366 367**Return value** 368 369| Type | Description | 370| :------------------ | :---------------------------------- | 371| Promise<string> | Promise used to return the analysis result obtained.| 372 373**Error codes** 374 375For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 376 377| ID| Error Message | 378| :------- | :----------------------------------------------------------- | 379| 201 | Permission denied. | 380| 202 | Called by non-system application. | 381| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 382| 14000011 | Internal system error | 383 384**Example** 385 386For details about how to create a phAccessHelper instance, see the example provided in [@ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object)](js-apis-sendablePhotoAccessHelper.md). 387 388```ts 389import { dataSharePredicates } from '@kit.ArkData'; 390import { common } from '@kit.AbilityKit'; 391 392async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 393 try { 394 console.info('getAnalysisDataDemo') 395 let fetchOptions: photoAccessHelper.FetchOptions = { 396 fetchColumns: [], 397 predicates: new dataSharePredicates.DataSharePredicates() 398 } 399 let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = 400 await phAccessHelper.getAssets(fetchOptions); 401 let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject(); 402 if (photoAsset != undefined) { 403 let analysisData: string = await photoAsset.getAnalysisData( 404 photoAccessHelper.AnalysisType.ANALYSIS_OCR); 405 console.info('get ocr result: ' + JSON.stringify(analysisData)); 406 } 407 fetchResult.close(); 408 } catch (err) { 409 console.error(`getAnalysisDataDemofailed with error: ${err.code}, ${err.message}`); 410 } 411} 412``` 413 414## Album 415 416Provides APIs to manage albums. 417 418### getFaceId<sup>13+</sup> 419 420getFaceId(): Promise\<string> 421 422Obtains the face identifier on the cover of a portrait album or group photo album. 423 424**System API**: This is a system API. 425 426**Required permissions**: ohos.permission.READ\_IMAGEVIDEO 427 428**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 429 430**Return value** 431 432| Type | Description | 433| :------------------ | :---------------------------------- | 434| Promise<string> | Promise used to return **tag_id** of the portrait album, **group_tag** of the group photo album, or an empty string if no face identifier is found.| 435 436**Error codes** 437 438For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [File Management Error Codes](../apis-core-file-kit/errorcode-filemanagement.md). 439 440| ID| Error Message | 441| :------- | :----------------------------------------------------------- | 442| 201 | Permission denied. | 443| 202 | Called by non-system application. | 444| 14000011 | Internal system error | 445 446**Example** 447 448For details about how to create a phAccessHelper instance, see the example provided in [@ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object)](js-apis-sendablePhotoAccessHelper.md). 449 450```ts 451import { dataSharePredicates } from '@kit.ArkData'; 452import { common } from '@kit.AbilityKit'; 453 454async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) { 455 try { 456 console.info('getFaceIdDemo'); 457 let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 458 predicates.equalTo("user_display_level", 1); 459 let fetchOptions: photoAccessHelper.FetchOptions = { 460 fetchColumns: [], 461 predicates: predicates 462 }; 463 let fetchResult = 464 await phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.SMART, 465 sendablePhotoAccessHelper.AlbumSubtype.PORTRAIT, 466 fetchOptions); 467 let album = await fetchResult?.getFirstObject(); 468 let faceId = await album?.getFaceId(); 469 console.info(`getFaceId successfully, faceId: ${faceId}`); 470 fetchResult.close(); 471 } catch (err) { 472 console.error(`getFaceId failed with err: ${err.code}, ${err.message}`); 473 } 474} 475``` 476 477## AlbumType 478 479Enumerates the album types. 480 481**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 482 483| Name | Value | Description | 484| ----- | ---- | ---------------------------------------------- | 485| SMART | 4096 | Smart analysis album. **System API**: This is a system API.| 486 487## AlbumSubtype 488 489Enumerate the album subtypes. 490 491**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core 492 493| Name | Value | Description | 494| --------------------- | ---- | ---------------------------------------------------------- | 495| HIDDEN | 1027 | Hidden album. <br>**System API**: This is a system API. | 496| TRASH | 1028 | Trash. <br>**System API**: This is a system API. | 497| SCREENSHOT | 1029 | Album for screenshots and screen recording files. <br>**System API**: This is a system API. | 498| CAMERA | 1030 | Album for photos and videos taken by the camera. <br>**System API**: This is a system API.| 499| SOURCE\_GENERIC | 2049 | Source album. <br>**System API**: This is a system API. | 500| CLASSIFY | 4097 | Classified album. <br>**System API**: This is a system API. | 501| GEOGRAPHY\_LOCATION | 4099 | Geographic location album. <br>**System API**: This is a system API. | 502| GEOGRAPHY\_CITY | 4100 | City album. <br>**System API**: This is a system API. | 503| SHOOTING\_MODE | 4101 | Shooting mode album. <br>**System API**: This is a system API. | 504| PORTRAIT | 4102 | Portrait album. <br>**System API**: This is a system API. | 505| GROUP_PHOTO | 4103 | Group photo album. <br>**System API**: This is a system API. | 506| HIGHLIGHT | 4104 | Highlights album. <br>**System API**: This is a system API. | 507| HIGHLIGHT_SUGGESTIONS | 4105 | Highlights suggestion album. <br>**System API**: This is a system API. | 508