@ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object) (System API)

The module provides APIs for album management, including creating an album and accessing and modifying media data in an album, based on a Sendable object.

NOTE

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.

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).

Modules to Import

import { sendablePhotoAccessHelper } from '@kit.MediaLibraryKit';

sendablePhotoAccessHelper.getPhotoAccessHelper¹⁹⁺

getPhotoAccessHelper(context: Context, userId: number): PhotoAccessHelper

Obtains a PhotoAccessHelper instance for the specified user, letting you access and modify media files in an album.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Context of the ability instance.
userId	number	Yes	ID of the user.

Return value

Type	Description
PhotoAccessHelper	PhotoAccessHelper instance obtained.

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

ID	Error Message
201	Permission denied.
202	Called by non-system application.
13900020	Invalid argument.

Example

// 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.
// Obtain the context from the component and ensure that the return value of this.getUiContext().getHostContext() is UIAbilityContext.
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  build() {
    Row() {
      Button("example").onClick(async () => {
        let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
        // 101 indicates the user ID of another user space.
        let phAccessHelper = sendablePhotoAccessHelper.getPhotoAccessHelper(context, 101);
      }).width('100%')
    }
    .height('90%')
  }
}

PhotoAccessHelper

createAsset

createAsset(displayName: string): Promise<PhotoAsset>

Creates an asset with the specified file name. This API uses a promise to return the result.

The file name must meet the following requirements:

A valid file name must include a base name and a supported image or video extension.
The total length of the file name must be between 1 and 255 characters.
The base name must not contain any invalid characters.
Starting from API version 18, the following characters are considered invalid: \ / : * ? " < > |
For API versions 10 to 17, the following characters are considered invalid: . .. \ / : * ? " ' ` < > | { } [ ]

System API: This is a system API.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
displayName	string	Yes	File name of the asset to create.

Return value

Type	Description
Promise<PhotoAsset>	Promise used to return the created asset.

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

ID	Error Message
201	Permission denied.
202	Called by non-system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900020	Invalid argument.
14000001	Invalid display name.
14000011	Internal system error

Example

For details about how to create a phAccessHelper instance, see the example provided in @ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object).

async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) {
  console.info('createAssetDemo');
  try {
    let testFileName: string = 'testFile' + Date.now() + '.jpg';
    let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await phAccessHelper.createAsset(testFileName);
    console.info('createAsset file displayName' + photoAsset.displayName);
    console.info('createAsset successfully');
  } catch (err) {
    console.error(`createAsset failed, error: ${err.code}, ${err.message}`);
  }
}

createAsset

createAsset(displayName: string, options: photoAccessHelper.PhotoCreateOptions): Promise<PhotoAsset>

Creates an asset with the specified file name and options. This API uses a promise to return the result.

The file name must meet the following requirements:

A valid file name must include a base name and a supported image or video extension.
The total length of the file name must be between 1 and 255 characters.
The base name must not contain any invalid characters.
Starting from API version 18, the following characters are considered invalid: \ / : * ? " < > |
For API versions 10 to 17, the following characters are considered invalid: . .. \ / : * ? " ' ` < > | { } [ ]

System API: This is a system API.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Required permissions: ohos.permission.WRITE_IMAGEVIDEO

Parameters

Name	Type	Mandatory	Description
displayName	string	Yes	File name of the asset to create.
options	photoAccessHelper.PhotoCreateOptions	Yes	Options for creating the asset.

Return value

Type	Description
Promise<PhotoAsset>	Promise used to return the created asset.

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

ID	Error Message
201	Permission denied.
202	Called by non-system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
13900020	Invalid argument.
14000001	Invalid display name.
14000011	Internal system error

Example

For details about how to create a phAccessHelper instance, see the example provided in @ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object).

async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) {
  console.info('createAssetDemo');
  try {
    let testFileName:string = 'testFile' + Date.now() + '.jpg';
    let createOption: photoAccessHelper.PhotoCreateOptions = {
      subtype: photoAccessHelper.PhotoSubtype.DEFAULT
    }
    let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await phAccessHelper.createAsset(testFileName, createOption);
    console.info('createAsset file displayName' + photoAsset.displayName);
    console.info('createAsset successfully');
  } catch (err) {
    console.error(`createAsset failed, error: ${err.code}, ${err.message}`);
  }
}

getHiddenAlbums

getHiddenAlbums(mode: HiddenPhotosDisplayMode, options?: FetchOptions): Promise<FetchResult<Album>>

Obtains hidden albums based on the specified display mode and retrieval options. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.READ_IMAGEVIDEO and ohos.permission.MANAGE_PRIVATE_PHOTOS

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Name	Type	Mandatory	Description
mode	HiddenPhotosDisplayMode	Yes	Display mode of hidden albums.
options	FetchOptions	No	Options for retrieving the albums. If this parameter is not specified, the albums are retrieved based on the display mode.

Return value

Type	Description
Promise<FetchResult<Album>>	Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

ID	Error Message
201	Permission verification failed, usually the result returned by VerifyAccessToken.
202	Permission verification failed, application which is not a system application uses system API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error.

Example

For details about how to create a phAccessHelper instance, see the example provided in @ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object).

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

// Obtain the preset hidden album.
async function getSysHiddenAlbum(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) {
  console.info('getSysHiddenAlbumDemo');
  phAccessHelper.getHiddenAlbums(photoAccessHelper.HiddenPhotosDisplayMode.ASSETS_MODE)
    .then( async (fetchResult) => {
      if (fetchResult === undefined) {
        console.error('getSysHiddenAlbumPromise fetchResult is undefined');
        return;
      }
      let hiddenAlbum: sendablePhotoAccessHelper.Album = await fetchResult.getFirstObject();
      console.info('getAlbumsPromise successfully, albumUri: ' + hiddenAlbum.albumUri);
      fetchResult.close();
    }).catch((err: BusinessError) => {
      console.error(`getSysHiddenAlbumPromise failed with err: ${err.code}, ${err.message}`);
    });
}

// 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.
async function getHiddenAlbumsView(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) {
  console.info('getHiddenAlbumsViewDemo');
  phAccessHelper.getHiddenAlbums(photoAccessHelper.HiddenPhotosDisplayMode.ALBUMS_MODE).then( async (fetchResult) => {
    if (fetchResult === undefined) {
      console.error('getHiddenAlbumsViewPromise fetchResult is undefined');
      return;
    }
    let albums: Array<sendablePhotoAccessHelper.Album> = await fetchResult.getAllObjects();
    console.info('getHiddenAlbumsViewPromise successfully, albums size: ' + albums.length);

    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOption: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    for (let i = 0; i < albums.length; i++) {
      // Obtain hidden files in the album.
      albums[i].getAssets(fetchOption).then((assetFetchResult) => {
        console.info('album get hidden assets successfully, getCount: ' + assetFetchResult.getCount());
      }).catch((err: BusinessError) => {
        console.error(`album get hidden assets failed with error: ${err.code}, ${err.message}`);
      });
    }
    fetchResult.close();
  }).catch((err: BusinessError) => {
    console.error(`getHiddenAlbumsViewPromise failed with err: ${err.code}, ${err.message}`);
  });
}

getPhotoAssets²⁴⁺

getPhotoAssets(assetsData: photoAccessHelper.ValuesBucket[]): Promise<PhotoAsset[]>

Converts the ValuesBucket record to a PhotoAsset object.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Name	Type	Mandatory	Description
assetsData	photoAccessHelper.ValuesBucket[]	Yes	Array of asset records. Each element in the array contains the column name and value of the asset. The array can contain a maximum of 500 elements. Each element in the array must contain the following asset column information: file_id, data, display_name, media_type, and subtype.

Return value

Type	Description
Promise<PhotoAsset[]>	Promise used to return the PhotoAsset object array (which may be empty).

Error codes

For details about the error codes, see Universal Error Codes and Media Library Error Codes.

ID	Error Message
202	Called by non-system application.
23800151	The scenario parameter verification fails. Possible causes: 1. Invalid value type in ValuesBucket; 2. Missing required column in ValuesBucket; 3. Array size exceeds 500.
23800301	Internal system error. It is recommended to retry and check the logs. Possible causes: 1. Database corrupted; 2. The file system is abnormal; 3. The IPC request timed out.

Example

For details about how to create a phAccessHelper instance, see the example provided in @ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object).

async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper, context: Context) {
  console.info('getPhotoAssets demo');
  let valuesArr: photoAccessHelper.ValuesBucket[] = [];
  let resultSet: photoAccessHelper.ResultSet | undefined = undefined;
  let photoAssetArr: sendablePhotoAccessHelper.PhotoAsset[] = [];
  let QUERY_SQL = 'SELECT file_id,data,display_name,media_type,subtype from Photos limit 100';
  try {
    resultSet = await photoAccessHelper.getPhotoAccessHelper(context).query(QUERY_SQL);
    let index: number = 0;
    while(resultSet && index < resultSet.rowCount){
      resultSet.goToRow(index);
      valuesArr.push(resultSet.getRow());
      index++;
    }
    photoAssetArr = await phAccessHelper.getPhotoAssets(valuesArr);
    console.info('getPhotoAssets successfully');
  } catch (err) {
    console.error(`valuesArr failed: ${err.code}, ${err.message}`);
  }
}

PhotoAsset

Provides APIs for encapsulating file asset attributes.

requestSource

requestSource(): Promise<number>

Opens the source file and returns the FD. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Type	Description
Promise<number>	Promise used to return the FD obtained.

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

ID	Error Message
201	Permission denied.
202	Called by non-system application.
14000011	Internal system error

Example

For details about how to create a phAccessHelper instance, see the example provided in @ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object).

import { dataSharePredicates } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';

async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) {
  try {
    console.info('requestSourcePromiseDemo')
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    let fetchOptions: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
    if (fetchResult === undefined) {
      console.error('requestSourcePromise fetchResult is undefined');
      return;
    }
    let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    let fd = await photoAsset.requestSource();
    console.info('Source fd is ' + fd);
  } catch (err) {
    console.error(`requestSourcePromiseDemo failed with error: ${err.code}, ${err.message}`);
  }
}

getAnalysisData

getAnalysisData(analysisType: AnalysisType): Promise<string>

Obtains analysis data. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.READ_IMAGEVIDEO

Since API version 22, the ohos.permission.MEDIA_LOCATION permission is required when analysisType is set to ANALYSIS_DETAIL_ADDRESS. If the permission is not granted, the universal error code 201 Permission Denied is thrown.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Parameters

Name	Type	Mandatory	Description
analysisType	AnalysisType	Yes	Smart analysis type.

Return value

Type	Description
Promise<string>	Promise used to return the analysis result obtained.

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

ID	Error Message
201	Permission denied.
202	Called by non-system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
14000011	Internal system error

Example

For details about how to create a phAccessHelper instance, see the example provided in @ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object).

import { dataSharePredicates } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';

async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) {
  try {
    console.info('getAnalysisDataDemo')
    let fetchOptions: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: new dataSharePredicates.DataSharePredicates()
    }
    let fetchResult: sendablePhotoAccessHelper.FetchResult<sendablePhotoAccessHelper.PhotoAsset> =
      await phAccessHelper.getAssets(fetchOptions);
    let photoAsset: sendablePhotoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    if (photoAsset != undefined) {
      let analysisData: string = await photoAsset.getAnalysisData(
        photoAccessHelper.AnalysisType.ANALYSIS_OCR);
      console.info('get ocr result: ' + JSON.stringify(analysisData));
    }
    fetchResult.close();
  } catch (err) {
    console.error(`getAnalysisDataDemofailed with error: ${err.code}, ${err.message}`);
  }
}

Album

Provides APIs to manage albums.

getFaceId¹³⁺

getFaceId(): Promise<string>

Obtains the face identifier on the cover of a portrait album or group photo album. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.READ_IMAGEVIDEO

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Return value

Type	Description
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.

Error codes

For details about the error codes, see Universal Error Codes and File Management Error Codes.

ID	Error Message
201	Permission denied.
202	Called by non-system application.
14000011	Internal system error

Example

For details about how to create a phAccessHelper instance, see the example provided in @ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object).

import { dataSharePredicates } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';

async function example(phAccessHelper: sendablePhotoAccessHelper.PhotoAccessHelper) {
  try {
    console.info('getFaceIdDemo');
    let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
    predicates.equalTo("user_display_level", 1);
    let fetchOptions: photoAccessHelper.FetchOptions = {
      fetchColumns: [],
      predicates: predicates
    };
    let fetchResult =
      await phAccessHelper.getAlbums(sendablePhotoAccessHelper.AlbumType.SMART,
        sendablePhotoAccessHelper.AlbumSubtype.PORTRAIT,
        fetchOptions);
    let album = await fetchResult?.getFirstObject();
    let faceId = await album?.getFaceId();
    console.info(`getFaceId successfully, faceId: ${faceId}`);
    fetchResult.close();
  } catch (err) {
    console.error(`getFaceId failed with err: ${err.code}, ${err.message}`);
  }
}

AlbumType

Enumerates the album types.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Name	Value	Description
SMART	4096	Smart analysis album. System API: This is a system API.

AlbumSubtype

Enumerate the album subtypes.

System capability: SystemCapability.FileManagement.PhotoAccessHelper.Core

Name	Value	Description
HIDDEN	1027	Hidden album. System API: This is a system API.
TRASH	1028	Trash. System API: This is a system API.
SCREENSHOT	1029	Album for screenshots and screen recording files. System API: This is a system API.
CAMERA	1030	Album for photos and videos taken by the camera. System API: This is a system API.
SOURCE_GENERIC	2049	Source album. System API: This is a system API.
CLASSIFY	4097	Classified album. System API: This is a system API.
GEOGRAPHY_LOCATION	4099	Geographic location album. System API: This is a system API.
GEOGRAPHY_CITY	4100	City album. System API: This is a system API.
SHOOTING_MODE	4101	Shooting mode album. System API: This is a system API.
PORTRAIT	4102	Portrait album. System API: This is a system API.
GROUP_PHOTO	4103	Group photo album. System API: This is a system API.
HIGHLIGHT	4104	Highlights album. System API: This is a system API.
HIGHLIGHT_SUGGESTIONS	4105	Highlights suggestion album. System API: This is a system API.

@ohos.file.sendablePhotoAccessHelper (Album Management Based on a Sendable Object) (System API)

Modules to Import

sendablePhotoAccessHelper.getPhotoAccessHelper19+

PhotoAccessHelper

createAsset

createAsset

getHiddenAlbums

getPhotoAssets24+

PhotoAsset

requestSource

getAnalysisData

Album

getFaceId13+

AlbumType

AlbumSubtype

sendablePhotoAccessHelper.getPhotoAccessHelper¹⁹⁺

getPhotoAssets²⁴⁺

getFaceId¹³⁺