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