# @ohos.filemanagement.userFileManager (User Data Management)
The **userFileManager** module provides user data management capabilities, including accessing and modifying user media data (audio and video clips, images, and files).
> **NOTE**
>
> - 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.
> - The APIs provided by this module are system APIs.
## Modules to Import
```ts
import userFileManager from '@ohos.filemanagement.userFileManager';
```
## userFileManager.getUserFileMgr
getUserFileMgr(context: Context): UserFileManager
Obtains a **UserFileManager** instance. This instance can be used to access and modify user media data (such as audio and video clips, images, and files).
**Model restriction**: This API can be used only in the stage model.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------- | ---- | -------------------------- |
| context | [Context](js-apis-inner-app-context.md) | Yes | Context of the ability instance.|
**Return value**
| Type | Description |
| ----------------------------- | :---- |
| [UserFileManager](#userfilemanager) | **UserFileManager** instance obtained.|
**Example**
```ts
// The userFileManager 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 mgr is not defined.
const context = getContext(this);
let mgr = userFileManager.getUserFileMgr(context);
```
## UserFileManager
### getPhotoAssets
getPhotoAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<FileAsset>>): void;
Obtains image and video assets. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets. |
| callback | AsyncCallback<[FetchResult](#fetchresult)<[FileAsset](#fileasset)>> | Yes | Callback invoked to return the image and video assets obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getPhotoAssets');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
mgr.getPhotoAssets(fetchOptions, async (err, fetchResult) => {
if (fetchResult != undefined) {
console.info('fetchResult success');
let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) {
console.info('fileAsset.displayName : ' + fileAsset.displayName);
}
} else {
console.error('fetchResult fail' + err);
}
});
}
```
### getPhotoAssets
getPhotoAssets(options: FetchOptions): Promise<FetchResult<FileAsset>>;
Obtains image and video assets. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------- | ---- | ---------------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<[FetchResult](#fetchresult)<[FileAsset](#fileasset)>> | Promise used to return the image and video assets obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getPhotoAssets');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
try {
let fetchResult = await mgr.getPhotoAssets(fetchOptions);
if (fetchResult != undefined) {
console.info('fetchResult success');
let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) {
console.info('fileAsset.displayName :' + fileAsset.displayName);
}
}
} catch (err) {
console.error('getPhotoAssets failed, message = ', err);
}
}
```
### createPhotoAsset
createPhotoAsset(displayName: string, albumUri: string, callback: AsyncCallback<FileAsset>): void;
Creates an image or video asset with the specified file name and URI. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| displayName | string | Yes | File name of the image or video to create. |
| albumUri | string | Yes | URI of the album where the image or video is located. |
| callback | AsyncCallback<[FileAsset](#fileasset)> | Yes | Callback invoked to return the image or video created.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type displayName or albumUri is not string. |
| 14000001 | if type displayName invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('createPhotoAssetDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
predicates: predicates
};
let albums = await mgr.getPhotoAlbums(fetchOptions);
let album = await albums.getFirstObject();
let testFileName = 'testFile' + Date.now() + '.jpg';
mgr.createPhotoAsset(testFileName, album.albumUri, (err, fileAsset) => {
if (fileAsset != undefined) {
console.info('createPhotoAsset file displayName' + fileAsset.displayName);
console.info('createPhotoAsset successfully');
} else {
console.error('createPhotoAsset failed, message = ', err);
}
});
}
```
### createPhotoAsset
createPhotoAsset(displayName: string, callback: AsyncCallback<FileAsset>): void;
Creates an image or video asset with the specified file name. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| displayName | string | Yes | File name of the image or video to create. |
| callback | AsyncCallback<[FileAsset](#fileasset)> | Yes | Callback invoked to return the image or video created.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type displayName is not string. |
| 14000001 | if type displayName invalid. |
**Example**
```ts
async function example() {
console.info('createPhotoAssetDemo');
let testFileName = 'testFile' + Date.now() + '.jpg';
mgr.createPhotoAsset(testFileName, (err, fileAsset) => {
if (fileAsset != undefined) {
console.info('createPhotoAsset file displayName' + fileAsset.displayName);
console.info('createPhotoAsset successfully');
} else {
console.error('createPhotoAsset failed, message = ', err);
}
});
}
```
### createPhotoAsset
createPhotoAsset(displayName: string, albumUri?: string): Promise<FileAsset>;
Creates an image or video asset with the specified file name and URI. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| displayName | string | Yes | File name of the image or video to create. |
| albumUri | string | No | URI of the album where the image or video is located. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<[FileAsset](#fileasset)> | Promise used to return the created image and video asset.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type displayName or albumUri is not string. |
**Example**
```ts
async function example() {
console.info('createPhotoAssetDemo');
try {
let testFileName = 'testFile' + Date.now() + '.jpg';
let fileAsset = await mgr.createPhotoAsset(testFileName);
console.info('createPhotoAsset file displayName' + fileAsset.displayName);
console.info('createPhotoAsset successfully');
} catch (err) {
console.error('createPhotoAsset failed, message = ', err);
}
}
```
### createPhotoAsset
createPhotoAsset(displayName: string, createOption: PhotoCreateOptions, callback: AsyncCallback<FileAsset>): void;
Creates an image or video asset with the specified file name and options. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| displayName | string | Yes | File name of the image or video to create. |
| createOption | [PhotoCreateOptions](#photocreateoptions10) | Yes | Options for creating an image or video asset. |
| callback | AsyncCallback<[FileAsset](#fileasset)> | Yes | Callback invoked to return the image or video created.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type displayName is not string. |
| 14000001 | if type displayName invalid. |
**Example**
```ts
async function example() {
console.info('createPhotoAssetDemo');
let testFileName = 'testFile' + Date.now() + '.jpg';
let createOption = {
subType: userFileManager.PhotoSubType.DEFAULT
}
mgr.createPhotoAsset(testFileName, createOption, (err, fileAsset) => {
if (fileAsset != undefined) {
console.info('createPhotoAsset file displayName' + fileAsset.displayName);
console.info('createPhotoAsset successfully');
} else {
console.error('createPhotoAsset failed, message = ', err);
}
});
}
```
### createPhotoAsset
createPhotoAsset(displayName: string, createOption: PhotoCreateOptions): Promise<FileAsset>;
Creates an image or video asset with the specified file name and options. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| displayName | string | Yes | File name of the image or video to create. |
| createOption | [PhotoCreateOptions](#photocreateoptions10) | Yes | Options for creating an image or video asset. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<[FileAsset](#fileasset)> | Promise used to return the created image and video asset.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type displayName is not string. |
**Example**
```ts
async function example() {
console.info('createPhotoAssetDemo');
try {
let testFileName = 'testFile' + Date.now() + '.jpg';
let createOption = {
subType: userFileManager.PhotoSubType.DEFAULT
}
let fileAsset = await mgr.createPhotoAsset(testFileName, createOption);
console.info('createPhotoAsset file displayName' + fileAsset.displayName);
console.info('createPhotoAsset successfully');
} catch (err) {
console.error('createPhotoAsset failed, message = ', err);
}
}
```
### createAudioAsset10+
createAudioAsset(displayName: string, callback: AsyncCallback<FileAsset>): void;
Creates an audio asset. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_AUDIO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| displayName | string | Yes | File name of the audio asset to create. |
| callback | AsyncCallback<[FileAsset](#fileasset)> | Yes | Callback invoked to return the created audio asset.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type displayName is not string. |
| 14000001 | if type displayName invalid. |
**Example**
```ts
async function example() {
console.info('createAudioAssetDemo');
let testFileName = 'testFile' + Date.now() + '.mp3';
mgr.createAudioAsset(testFileName, (err, fileAsset) => {
if (fileAsset != undefined) {
console.info('createAudioAsset file displayName' + fileAsset.displayName);
console.info('createAudioAsset successfully');
} else {
console.error('createAudioAsset failed, message = ', err);
}
});
}
```
### createAudioAsset10+
createAudioAsset(displayName: string): Promise<FileAsset>;
Creates an audio asset. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_AUDIO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| displayName | string | Yes | File name of the audio asset to create. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<[FileAsset](#fileasset)> | Promise used to return the created audio asset.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type displayName is not string. |
**Example**
```ts
async function example() {
console.info('createAudioAssetDemo');
try {
let testFileName = 'testFile' + Date.now() + '.mp3';
let fileAsset = await mgr.createAudioAsset(testFileName);
console.info('createAudioAsset file displayName' + fileAsset.displayName);
console.info('createAudioAsset successfully');
} catch (err) {
console.error('createAudioAsset failed, message = ', err);
}
}
```
### createAlbum10+
createAlbum(name: string, callback: AsyncCallback<Album>): void;
Creates an album. This API uses an asynchronous callback to return the result.
The album name must meet the following requirements:
- The album name is a string of 1 to 255 characters.
- The album name cannot contain any of the following characters:
.. \ / : * ? " ' ` < > | { } [ ]
- The album name is case-insensitive.
- Duplicate album names are not allowed.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| name | string | Yes | Name of the album to create. |
| callback | AsyncCallback<[Album](#album)> | Yes | Callback invoked to return the created album instance.|
**Example**
```ts
async function example() {
console.info('createAlbumDemo');
let albumName = 'newAlbumName' + new Date().getTime();
mgr.createAlbum(albumName, (err, album) => {
if (err) {
console.error('createAlbumCallback failed with err: ' + err);
return;
}
console.info('createAlbumCallback successfully, album: ' + album.albumName + ' album uri: ' + album.albumUri);
});
}
```
### createAlbum10+
createAlbum(name: string): Promise<Album>;
Creates an album. This API uses a promise to return the result.
The album name must meet the following requirements:
- The album name is a string of 1 to 255 characters.
- The album name cannot contain any of the following characters:
.. \ / : * ? " ' ` < > | { } [ ]
- The album name is case-insensitive.
- Duplicate album names are not allowed.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| name | string | Yes | Name of the album to create. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<[Album](#album)> | Promise used to return the created album instance.|
**Example**
```ts
async function example() {
console.info('createAlbumDemo');
let albumName = 'newAlbumName' + new Date().getTime();
mgr.createAlbum(albumName).then((album) => {
console.info('createAlbumPromise successfully, album: ' + album.albumName + ' album uri: ' + album.albumUri);
}).catch((err) => {
console.error('createAlbumPromise failed with err: ' + err);
});
}
```
### deleteAlbums10+
deleteAlbums(albums: Array<Album>, callback: AsyncCallback<void>): void;
Deletes albums. This API uses an asynchronous callback to return the result.
Ensure that the albums to be deleted exist. Only user albums can be deleted.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| albums | Array<[Album](#album)> | Yes | Albums to delete. |
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
// Delete the album named newAlbumName.
console.info('deleteAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo('album_name', 'newAlbumName');
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions);
let album = await fetchResult.getFirstObject();
mgr.deleteAlbums([album], (err) => {
if (err) {
console.error('deletePhotoAlbumsCallback failed with err: ' + err);
return;
}
console.info('deletePhotoAlbumsCallback successfully');
});
fetchResult.close();
}
```
### deleteAlbums10+
deleteAlbums(albums: Array<Album>): Promise<void>;
Deletes albums. This API uses a promise to return the result.
Ensure that the albums to be deleted exist. Only user albums can be deleted.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| albums | Array<[Album](#album)> | Yes | Albums to delete. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
// Delete the album named newAlbumName.
console.info('deleteAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo('album_name', 'newAlbumName');
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions);
let album = await fetchResult.getFirstObject();
mgr.deleteAlbums([album]).then(() => {
console.info('deletePhotoAlbumsPromise successfully');
}).catch((err) => {
console.error('deletePhotoAlbumsPromise failed with err: ' + err);
});
fetchResult.close();
}
```
### getAlbums10+
getAlbums(type: AlbumType, subType: AlbumSubType, options: FetchOptions, callback: AsyncCallback<FetchResult<Album>>): void;
Obtain albums based on the specified options and album type. This API uses an asynchronous callback to return the result.
Before the operation, ensure that the albums to obtain exist.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| type | [AlbumType](#albumtype10) | Yes | Type of the album to obtain. |
| subType | [AlbumSubType](#albumsubtype10) | Yes | Subtype of the album. |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the albums. |
| callback | AsyncCallback<[FetchResult](#fetchresult)<[Album](#album)>> | Yes | Callback invoked to return the result.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOption. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
// Obtain the album named newAlbumName.
console.info('getAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo('album_name', 'newAlbumName');
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions, async (err, fetchResult) => {
if (err) {
console.error('getAlbumsCallback failed with err: ' + err);
return;
}
if (fetchResult == undefined) {
console.error('getAlbumsCallback fetchResult is undefined');
return;
}
let album = await fetchResult.getFirstObject();
console.info('getAlbumsCallback successfully, albumName: ' + album.albumName);
fetchResult.close();
});
}
```
### getAlbums10+
getAlbums(type: AlbumType, subType: AlbumSubType, callback: AsyncCallback<FetchResult<Album>>): void;
Obtains albums by type. This API uses an asynchronous callback to return the result.
Before the operation, ensure that the albums to obtain exist.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| type | [AlbumType](#albumtype10) | Yes | Type of the album to obtain. |
| subType | [AlbumSubType](#albumsubtype10) | Yes | Subtype of the album. |
| callback | AsyncCallback<[FetchResult](#fetchresult)<[Album](#album)>> | Yes | Callback invoked to return the result.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOption. |
**Example**
```ts
async function example() {
// Obtain the system album VIDEO, which is preset by default.
console.info('getAlbumsDemo');
mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.VIDEO, async (err, fetchResult) => {
if (err) {
console.error('getAlbumsCallback failed with err: ' + err);
return;
}
if (fetchResult == undefined) {
console.error('getAlbumsCallback fetchResult is undefined');
return;
}
let album = await fetchResult.getFirstObject();
console.info('getAlbumsCallback successfully, albumUri: ' + album.albumUri);
fetchResult.close();
});
}
```
### getAlbums10+
getAlbums(type: AlbumType, subType: AlbumSubType, options?: FetchOptions): Promise<FetchResult<Album>>;
Obtain albums based on the specified options and album type. This API uses a promise to return the result.
Before the operation, ensure that the albums to obtain exist.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| type | [AlbumType](#albumtype10) | Yes | Type of the album to obtain. |
| subType | [AlbumSubType](#albumsubtype10) | Yes | Subtype of the album. |
| options | [FetchOptions](#fetchoptions) | No | Options for fetching the albums. If this parameter is not specified, the albums are obtained based on the album type by default. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<[FetchResult](#fetchresult)<[Album](#album)>> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOption. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
// Obtain the album named newAlbumName.
console.info('getAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo('album_name', 'newAlbumName');
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions).then( async (fetchResult) => {
if (fetchResult == undefined) {
console.error('getAlbumsPromise fetchResult is undefined');
return;
}
let album = await fetchResult.getFirstObject();
console.info('getAlbumsPromise successfully, albumName: ' + album.albumName);
fetchResult.close();
}).catch((err) => {
console.error('getAlbumsPromise failed with err: ' + err);
});
}
```
### getPhotoAlbums
getPhotoAlbums(options: AlbumFetchOptions, callback: AsyncCallback<FetchResult<Album>>): void;
Obtains image and video albums. This API uses an asynchronous callback to return the result.
This API will be deprecated. Use [getAlbums10+](#getalbums10) instead.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| options | [AlbumFetchOptions](#albumfetchoptions) | Yes | Options for fetching the albums. |
| callback | AsyncCallback<[FetchResult](#fetchresult)<[Album](#album)>> | Yes | Callback invoked to return the image and video albums obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not AlbumFetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getPhotoAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = {
predicates: predicates
};
mgr.getPhotoAlbums(albumFetchOptions, (err, fetchResult) => {
if (fetchResult != undefined) {
console.info('albums.count = ' + fetchResult.getCount());
fetchResult.getFirstObject((err, album) => {
if (album != undefined) {
console.info('first album.albumName = ' + album.albumName);
} else {
console.error('album is undefined, err = ', err);
}
});
} else {
console.error('getPhotoAlbums fail, message = ', err);
}
});
}
```
### getPhotoAlbums
getPhotoAlbums(options: AlbumFetchOptions): Promise<FetchResult<Album>>;
Obtains image and video albums. This API uses a promise to return the result.
This API will be deprecated. Use [getAlbums10+](#getalbums10) instead.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| options | [AlbumFetchOptions](#albumfetchoptions) | Yes | Options for fetching the albums. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<[FetchResult](#fetchresult)<[Album](#album)>> | Promise used to return the image and video albums obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not AlbumFetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getPhotoAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = {
predicates: predicates
};
try {
let fetchResult = await mgr.getPhotoAlbums(albumFetchOptions);
console.info('album.count = ' + fetchResult.getCount());
const album = await fetchResult.getFirstObject();
console.info('first album.albumName = ' + album.albumName);
} catch (err) {
console.error('getPhotoAlbums fail, message = ' + err);
}
}
```
### getPrivateAlbum
getPrivateAlbum(type: PrivateAlbumType, callback: AsyncCallback<FetchResult<PrivateAlbum>>): void;
Obtains the system album. This API uses an asynchronous callback to return the result.
This API will be deprecated. Use [getAlbums10+](#getalbums10) instead.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| type | [PrivateAlbumType](#privatealbumtype) | Yes | Type of the system album to obtain. |
| callback | AsyncCallback<[FetchResult](#fetchresult)<[PrivateAlbum](#privatealbum)>> | Yes | Callback invoked to return the album obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type type is not PrivateAlbumType. |
**Example**
```ts
async function example() {
console.info('getPrivateAlbumDemo');
mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH, async (err, fetchResult) => {
if (fetchResult != undefined) {
let trashAlbum = await fetchResult.getFirstObject();
console.info('first album.albumName = ' + trashAlbum.albumName);
} else {
console.error('getPrivateAlbum failed. message = ', err);
}
});
}
```
### getPrivateAlbum
getPrivateAlbum(type: PrivateAlbumType): Promise<FetchResult<PrivateAlbum>>;
Obtains the system album. This API uses a promise to return the result.
This API will be deprecated. Use [getAlbums10+](#getalbums10) instead.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| type | [PrivateAlbumType](#privatealbumtype) | Yes | Type of the system album to obtain. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<[FetchResult](#fetchresult)<[PrivateAlbum](#privatealbum)>> | Promise used to return the system album obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type type is not PrivateAlbumType. |
**Example**
```ts
async function example() {
console.info('getPrivateAlbumDemo');
try {
let fetchResult = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
let trashAlbum = await fetchResult.getFirstObject();
console.info('first album.albumName = ' + trashAlbum.albumName);
} catch (err) {
console.error('getPrivateAlbum failed. message = ', err);
}
}
```
### getAudioAssets
getAudioAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<FileAsset>>): void;
Obtains audio assets. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_AUDIO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the audio assets. |
| callback | AsyncCallback<[FetchResult](#fetchresult)<[FileAsset](#fileasset)>> | Yes | Callback invoked to return the audio assets obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getAudioAssets');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
mgr.getAudioAssets(fetchOptions, async (err, fetchResult) => {
if (fetchResult != undefined) {
console.info('fetchFileResult success');
let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) {
console.info('fileAsset.displayName :' + fileAsset.displayName);
}
} else {
console.error('fetchFileResult fail' + err);
}
});
}
```
### getAudioAssets
getAudioAssets(options: FetchOptions): Promise<FetchResult<FileAsset>>;
Obtains audio assets. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_AUDIO
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the audio assets. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise<[FetchResult](#fetchresult)<[FileAsset](#fileasset)>> | Promise used to return the audio assets obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getAudioAssets');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
try {
var fetchResult = await mgr.getAudioAssets(fetchOptions);
} catch (err) {
console.error('getAudioAssets failed, message = ', err);
}
if (fetchResult != undefined) {
console.info('fetchFileResult success');
let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) {
console.info('fileAsset.displayName :' + fileAsset.displayName);
}
}
}
```
### delete
delete(uri: string, callback: AsyncCallback<void>): void;
Deletes a media file. This API uses an asynchronous callback to return the result. The deleted file is moved to the recycle bin.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | URI of the media file.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type uri is not string. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('deleteAssetDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
try {
const fetchResult = await mgr.getPhotoAssets(fetchOptions);
var asset = await fetchResult.getFirstObject();
} catch (err) {
console.info('fetch failed, message =', err);
}
if (asset == undefined) {
console.error('asset not exist');
return;
}
mgr.delete(asset.uri, (err) => {
if (err == undefined) {
console.info('delete successfully');
} else {
console.error('delete failed with error: ' + err);
}
});
}
```
### delete
delete(uri: string): Promise<void>;
Deletes a media file. This API uses a promise to return the result. The deleted file is moved to the recycle bin.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | URI of the media file.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise<void>| Promise that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type uri is not string. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('deleteDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
try {
const fetchResult = await mgr.getPhotoAssets(fetchOptions);
var asset = await fetchResult.getFirstObject();
} catch (err) {
console.info('fetch failed, message =', err);
}
if (asset == undefined) {
console.error('asset not exist');
return;
}
try {
await mgr.delete(asset.uri);
console.info('delete successfully');
} catch (err) {
console.error('delete failed with error: ' + err);
}
}
```
### getActivePeers
getActivePeers(callback: AsyncCallback<Array<PeerInfo>>): void;
Obtains information about online peer devices. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.DistributedCore
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------- | ---- | ------------ |
| callback | AsyncCallback<Array<[PeerInfo](#peerinfo)>> | Yes | Callback invoked to return a list of online peer devices.|
**Example**
```ts
async function example() {
console.info('getActivePeersDemo');
mgr.getActivePeers((err, devicesInfo) => {
if (devicesInfo != undefined) {
console.log('getActivePeers succeed.');
for (let i = 0; i < devicesInfo.length; i++) {
console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId);
}
} else {
console.error('getActivePeers failed. message = ', err);
}
});
}
```
### getActivePeers
getActivePeers(): Promise<Array<PeerInfo>>;
Obtains information about online peer devices. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.DistributedCore
**Return value**
| Type | Description |
| --------------------------- | ----------------------------- |
| Promise<Array<[PeerInfo](#peerinfo)>> | Promise used to return a list of online peer devices.|
**Example**
```ts
async function example() {
console.info('getActivePeersDemo');
try {
var devicesInfo = await mgr.getActivePeers();
} catch (err) {
console.error('getActivePeers failed. message = ', err);
}
if (devicesInfo != undefined) {
console.log('getActivePeers succeed.');
for (let i = 0; i < devicesInfo.length; i++) {
console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId);
}
} else {
console.error('get distributed fail');
}
}
```
### getAllPeers
getAllPeers(callback: AsyncCallback<Array<PeerInfo>>): void;
Obtains information about all peer devices. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.DistributedCore
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------- | ---- | ------------ |
| callback | AsyncCallback<Array<[PeerInfo](#peerinfo)>> | Yes | Callback invoked to return the peer device information obtained.|
**Example**
```ts
async function example() {
console.info('getAllPeersDemo');
mgr.getAllPeers((err, devicesInfo) => {
if (devicesInfo != undefined) {
console.log('getAllPeers succeed.');
for (let i = 0; i < devicesInfo.length; i++) {
console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId);
}
} else {
console.error('getAllPeers failed. message = ', err);
}
});
}
```
### getAllPeers
getAllPeers(): Promise<Array<PeerInfo>>;
Obtains information about all peer devices. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.DistributedCore
**Return value**
| Type | Description |
| --------------------------- | ----------------------------- |
| Promise<Array<[PeerInfo](#peerinfo)>> | Promise used to return the information obtained.|
**Example**
```ts
async function example() {
console.info('getAllPeersDemo');
try {
var devicesInfo = await mgr.getAllPeers();
} catch (err) {
console.error('getAllPeers failed. message = ', err);
}
if (devicesInfo != undefined) {
console.log('getAllPeers succeed.');
for (let i = 0; i < devicesInfo.length; i++) {
console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId);
}
} else {
console.error('get distributed fail');
}
}
```
### getPhotoIndex10+
getPhotoIndex(photoUri: string, albumUri: string, options: FetchOptions, callback: AsyncCallback<number>): void
Obtains the index of an image or video in an album. This API uses an asynchronous callback to return the result.
**System API**: This is a system API.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| photoUri | string | Yes | URI of the media asset whose index is to be obtained.|
| albumUri | string | Yes | Album URI, which can be an empty string. If it is an empty string, all the media assets in the Gallery are obtained by default. |
| options | [FetchOptions](#fetchoptions) | Yes | Fetch options. Only one search condition or sorting mode must be set in **predicates**. If no value is set or multiple search conditions or sorting modes are set, the API cannot be called successfully. |
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| AsyncCallback<number>| Callback invoked to return the index obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcodes/errorcode-universal.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 401 | if parameter is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('getPhotoIndexDemo');
let predicatesForGetAsset = new dataSharePredicates.DataSharePredicates();
let fetchOp = {
fetchColumns: [],
predicates: predicatesForGetAsset
};
// Obtain the uri of the album
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.FAVORITE, fetchOp);
let album = await albumFetchResult.getFirstObject();
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.orderByAsc(userFileManager.ImageVideoKey.DATE_MODIFIED);
let fetchOptions = {
fetchColumns: [userFileManager.ImageVideoKey.DATE_MODIFIED],
predicates: predicates
};
let photoFetchResult = await album.getPhotoAssets(fetchOptions);
let expectIndex = 1;
// Obtain the uri of the second file
let photoAsset = await photoFetchResult.getPositionObject(expectIndex);
mgr.getPhotoIndex(photoAsset.uri, album.albumUri, fetchOptions, (err, index) => {
if (err == undefined) {
console.info(`getPhotoIndex successfully and index is : ${index}`);
} else {
console.info(`getPhotoIndex failed;`);
}
});
} catch (error) {
console.info(`getPhotoIndex failed; error: ${error}`);
}
}
```
### getPhotoIndex10+
getPhotoIndex(photoUri: string, albumUri: string, options: FetchOptions): Promise<number>
Obtains the index of an image or video in an 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.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| photoUri | string | Yes | URI of the media asset whose index is to be obtained.|
| albumUri | string | Yes | Album URI, which can be an empty string. If it is an empty string, all the media assets in the Gallery are obtained by default. |
| options | [FetchOptions](#fetchoptions) | Yes | Fetch options. Only one search condition or sorting mode must be set in **predicates**. If no value is set or multiple search conditions or sorting modes are set, the API cannot be called successfully. |
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise<number>| Promise used to return the index obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcodes/errorcode-universal.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 401 | if parameter is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('getPhotoIndexDemo');
let predicatesForGetAsset = new dataSharePredicates.DataSharePredicates();
let fetchOp = {
fetchColumns: [],
predicates: predicatesForGetAsset
};
// Obtain the uri of the album
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.FAVORITE, fetchOp);
let album = await albumFetchResult.getFirstObject();
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.orderByAsc(userFileManager.ImageVideoKey.DATE_MODIFIED);
let fetchOptions = {
fetchColumns: [userFileManager.ImageVideoKey.DATE_MODIFIED],
predicates: predicates
};
let photoFetchResult = await album.getPhotoAssets(fetchOptions);
let expectIndex = 1;
// Obtain the uri of the second file
let photoAsset = await photoFetchResult.getPositionObject(expectIndex);
mgr.getPhotoIndex(photoAsset.uri, album.albumUri, fetchOptions).then((index) => {
console.info(`getPhotoIndex successfully and index is : ${index}`);
}).catch((err) => {
console.info(`getPhotoIndex failed; error: ${err}`);
});
} catch (error) {
console.info(`getPhotoIndex failed; error: ${error}`);
}
}
```
### release
release(callback: AsyncCallback<void>): void
Releases this **UserFileManager** instance. This API uses an asynchronous callback to return the result.
Call this API when the APIs in the **UserFileManager** instance are no longer used.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | -------------------- |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.|
**Example**
```ts
async function example() {
console.info('releaseDemo');
mgr.release((err) => {
if (err != undefined) {
console.error('release failed. message = ', err);
} else {
console.info('release ok.');
}
});
}
```
### release
release(): Promise<void>
Releases this **UserFileManager** instance. This API uses a promise to return the result.
Call this API when the APIs in the **UserFileManager** instance are no longer used.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| ------------------- | --------------------------------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
async function example() {
console.info('releaseDemo');
try {
await mgr.release();
console.info('release ok.');
} catch (err) {
console.error('release failed. message = ', err);
}
}
```
### on10+
on(uri: string, forSubUri: boolean, callback: Callback<ChangeData>) : void
Registers a listener for the specified URI.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------------------------------------- | ---- | ------------------------------------------------------------ |
| uri | string | Yes | URI of the file asset or album, or [DefaultChangeUri](#defaultchangeuri10).|
| forSubUri | boolean | Yes | Whether to perform fuzzy listening.
If **uri** is the URI of an album, the value **true** means to listen for the changes of the files in the album; the value **false** means to listen for the changes of the album.
If **uri** is the URI of a file asset, there is no difference between **true** and **false** for **forSubUri**.
If **uri** is **DefaultChangeUri**, **forSubUri** must be set to **true**. If **forSubUri** is **false**, the URI cannot be found and no message can be received.|
| callback | Callback<[ChangeData](#changedata10)> | Yes | Callback invoked to return [ChangeData](#changedata10).
**NOTE**: Different callbacks can be registered for a URI. You can use [off10+](#off10) to disable the specified callback or all callbacks for the URI.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if parameter is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('onDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOptions);
let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) {
console.info('fileAsset.displayName : ' + fileAsset.displayName);
}
let onCallback1 = (changeData) => {
console.info('onCallback1 success, changData: ' + JSON.stringify(changeData));
//file had changed, do something
}
let onCallback2 = (changeData) => {
console.info('onCallback2 success, changData: ' + JSON.stringify(changeData));
// File changed. Do something.
}
// Register onCallback1.
mgr.on(fileAsset.uri, false, onCallback1);
// Register onCallback2.
mgr.on(fileAsset.uri, false, onCallback2);
fileAsset.favorite(true, (err) => {
if (err == undefined) {
console.info('favorite successfully');
} else {
console.error('favorite failed with error:' + err);
}
});
}
```
### off10+
off(uri: string, callback?: Callback<ChangeData>): void
Unregisters the listener for the specified URI. Multiple callbacks can be registered for a URI for listening. You can use this API to unregister the specified callbacks or all callbacks.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ |
| uri | string | Yes | URI of the file asset or album, or [DefaultChangeUri](#defaultchangeuri10).|
| callback | Callback<[ChangeData](#changedata10)> | No | Callback registered by [on10+](#on10). If this parameter is not specified, all listener callbacks registered for the URI will be unregistered.
**NOTE**: The specified callback will not be invoked.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if parameter is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('offDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOptions);
let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) {
console.info('fileAsset.displayName : ' + fileAsset.displayName);
}
let onCallback1 = (changeData) => {
console.info('onCallback1 on');
}
let onCallback2 = (changeData) => {
console.info('onCallback2 on');
}
// Register onCallback1.
mgr.on(fileAsset.uri, false, onCallback1);
// Register onCallback2.
mgr.on(fileAsset.uri, false, onCallback2);
// Disable the listening of onCallback1.
mgr.off(fileAsset.uri, onCallback1);
fileAsset.favorite(true, (err) => {
if (err == undefined) {
console.info('favorite successfully');
} else {
console.error('favorite failed with error:' + err);
}
});
}
```
### on
on(type: ChangeEvent, callback: Callback<void>): void
Subscribes to changes of the file management library. This API uses a callback to return the result.
This API will be deprecated. Use [on10+](#on10) instead.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.
**deviceChange** indicates the device change.
**albumChange** indicates the album change.
**imageChange** indicates the image change.
**audioChange** indicates the audio file change.
**videoChange** indicates the video file change.
**remoteFileChange** indicates the file change on the registered device.|
| callback | Callback<void> | Yes | Callback that returns no value. |
**Example**
```ts
async function example() {
console.info('onDemo');
let count = 0;
mgr.on('imageChange', () => {
count++;
// Image file changed. Do something.
});
try {
let testFileName = 'testFile' + Date.now() + '.jpg';
let fileAsset = await mgr.createPhotoAsset(testFileName);
console.info('createPhotoAsset file displayName' + fileAsset.displayName);
console.info('createPhotoAsset successfully');
} catch (err) {
console.error('createPhotoAsset failed, message = ' + err);
}
// Sleep 1s.
if (count > 0) {
console.info('onDemo success');
} else {
console.error('onDemo fail');
}
mgr.off('imageChange', () => {
// Unsubscription succeeds.
});
}
```
### off
off(type: ChangeEvent, callback?: Callback<void>): void
Unsubscribes from changes of the file management library. This API uses a callback to return the result.
This API will be deprecated. Use [off10+](#off10) instead.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.
**deviceChange** indicates the device change.
**albumChange** indicates the album change.
**imageChange** indicates the image change.
**audioChange** indicates the audio file change.
**videoChange** indicates the video file change.
**remoteFileChange** indicates the change of the file on a registered device.|
| callback | Callback<void> | No | Callback that returns no value. |
**Example**
```ts
async function example() {
console.info('offDemo');
let count = 0;
mgr.on('imageChange', () => {
count++;
// Image file changed. Do something.
});
mgr.off('imageChange', () => {
// Unsubscription succeeds.
});
try {
let testFileName = 'testFile' + Date.now() + '.jpg';
let fileAsset = await mgr.createPhotoAsset(testFileName);
console.info('createPhotoAsset file displayName' + fileAsset.displayName);
console.info('createPhotoAsset successfully');
} catch (err) {
console.error('createPhotoAsset failed, message = ' + err);
}
// Sleep 1s.
if (count == 0) {
console.info('offDemo success');
} else {
console.error('offDemo fail');
}
}
```
## FileAsset
Provides APIs for encapsulating file asset attributes.
### Attributes
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Readable| Writable| Description |
| ------------------------- | ------------------------ | ---- | ---- | ------------------------------------------------------ |
| uri | string | Yes | No | File asset URI, for example, **file://media/Photo/1/IMG_datetime_0001/displayName.jpg**. |
| fileType | [FileType](#filetype) | Yes | No | Type of the file. |
| displayName | string | Yes | Yes | File name, including the file name extension, to display. |
### get
get(member: string): MemberType;
Obtains the value of a **FileAsset** parameter.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------------------------- | ---- | ----- |
| member | string | Yes | Name of the parameter, for example, **ImageVideoKey.URI**.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('fileAssetGetDemo');
try {
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: ['title'],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fileAsset = await fetchResult.getFirstObject();
let title = userFileManager.ImageVideoKey.TITLE;
let fileAssetTitle = fileAsset.get(title.toString());
console.info('fileAsset Get fileAssetTitle = ', fileAssetTitle);
} catch (err) {
console.error('release failed. message = ', err);
}
}
```
### set
set(member: string, value: string): void;
Sets a **FileAsset** parameter.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------------------------- | ---- | ----- |
| member | string | Yes | Name of the parameter, for example, **ImageVideoKey.URI**.|
| value | string | Yes | Value to set. Only the value of **ImageVideoKey.DISPLAY_NAME** can be changed.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('fileAssetSetDemo');
try {
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fileAsset = await fetchResult.getFirstObject();
let displayName = userFileManager.ImageVideoKey.DISPLAY_NAME.toString();
fileAsset.set(displayName, 'newDisplayName1');
} catch (err) {
console.error('release failed. message = ', err);
}
}
```
### commitModify
commitModify(callback: AsyncCallback<void>): void
Commits the modification on the file metadata to the database. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------------------------- | ---- | ----- |
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('commitModifyDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fileAsset = await fetchResult.getFirstObject();
let displayName = userFileManager.ImageVideoKey.DISPLAY_NAME.toString();
let fileAssetDisplayName = fileAsset.get(displayName);
console.info('fileAsset get fileAssetDisplayName = ', fileAssetDisplayName);
fileAsset.set(displayName, 'newDisplayName2');
fileAsset.commitModify((err) => {
if (err == undefined) {
let newFileAssetDisplayName = fileAsset.get(displayName);
console.info('fileAsset get newFileAssetDisplayName = ', newFileAssetDisplayName);
} else {
console.error('commitModify failed, message =', err);
}
});
}
```
### commitModify
commitModify(): Promise<void>
Commits the modification on the file metadata to the database. This API uses a promise to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| ------------------- | ---------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('commitModifyDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fileAsset = await fetchResult.getFirstObject();
let displayName = userFileManager.ImageVideoKey.DISPLAY_NAME.toString();
let fileAssetDisplayName = fileAsset.get(displayName);
console.info('fileAsset get fileAssetDisplayName = ', fileAssetDisplayName);
fileAsset.set(displayName, 'newDisplayName3');
try {
await fileAsset.commitModify();
let newFileAssetDisplayName = fileAsset.get(displayName);
console.info('fileAsset get newFileAssetDisplayName = ', newFileAssetDisplayName);
} catch (err) {
console.error('release failed. message = ', err);
}
}
```
### open
open(mode: string, callback: AsyncCallback<number>): void
Opens this file asset. This API uses an asynchronous callback to return the result.
**NOTE**
The write operations are mutually exclusive. After a write operation is complete, you must call **close** to release the resource.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.READ_AUDIO, ohos.permission.WRITE_IMAGEVIDEO, or ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | --------------------------- | ---- | ----------------------------------- |
| mode | string | Yes | File open mode, which can be **r** (read-only), **w** (write-only), or **rw** (read-write).|
| callback | AsyncCallback<number> | Yes | Callback invoked to return the file descriptor of the file opened. |
**Example**
```ts
async function example() {
console.info('openDemo');
let testFileName = 'testFile' + Date.now() + '.jpg';
const fileAsset = await mgr.createPhotoAsset(testFileName);
fileAsset.open('rw', (err, fd) => {
if (fd != undefined) {
console.info('File fd' + fd);
fileAsset.close(fd);
} else {
console.error('File err' + err);
}
});
}
```
### open
open(mode: string): Promise<number>
Opens this file asset. This API uses a promise to return the result.
**NOTE**
The write operations are mutually exclusive. After a write operation is complete, you must call **close** to release the resource.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.READ_AUDIO, ohos.permission.WRITE_IMAGEVIDEO, or ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| ---- | ------ | ---- | ----------------------------------- |
| mode | string | Yes | File open mode, which can be **r** (read-only), **w** (write-only), or **rw** (read-write).|
**Return value**
| Type | Description |
| --------------------- | ------------- |
| Promise<number> | Promise used to return the file descriptor of the file opened.|
**Example**
```ts
async function example() {
console.info('openDemo');
try {
let testFileName = 'testFile' + Date.now() + '.jpg';
const fileAsset = await mgr.createPhotoAsset(testFileName);
let fd = await fileAsset.open('rw');
if (fd != undefined) {
console.info('File fd' + fd);
fileAsset.close(fd);
} else {
console.error(' open File fail');
}
} catch (err) {
console.error('open Demo err' + err);
}
}
```
### close
close(fd: number, callback: AsyncCallback<void>): void
Closes a file asset. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------------------------- | ---- | ----- |
| fd | number | Yes | File descriptor of the file to close.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('closeDemo');
try {
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const fileAsset = await fetchResult.getFirstObject();
let fd = await fileAsset.open('rw');
console.info('file fd', fd);
fileAsset.close(fd, (err) => {
if (err == undefined) {
console.info('asset close succeed.');
} else {
console.error('close failed, message = ' + err);
}
});
} catch (err) {
console.error('close failed, message = ' + err);
}
}
```
### close
close(fd: number): Promise<void>
Closes a file asset. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| ---- | ------ | ---- | ----- |
| fd | number | Yes | File descriptor of the file to close.|
**Return value**
| Type | Description |
| ------------------- | ---------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('closeDemo');
try {
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject();
let fd = await asset.open('rw');
console.info('file fd', fd);
await asset.close(fd);
console.info('asset close succeed.');
} catch (err) {
console.error('close failed, message = ' + err);
}
}
```
### getThumbnail
getThumbnail(callback: AsyncCallback<image.PixelMap>): void
Obtains the thumbnail of this file asset. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO or ohos.permission.READ_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ----------------------------------- | ---- | ---------------- |
| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes | Callback invoked to return the PixelMap of the thumbnail.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getThumbnailDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject();
console.info('asset displayName = ', asset.displayName);
asset.getThumbnail((err, pixelMap) => {
if (err == undefined) {
console.info('getThumbnail successful ' + pixelMap);
} else {
console.error('getThumbnail fail', err);
}
});
}
```
### getThumbnail
getThumbnail(size: image.Size, callback: AsyncCallback<image.PixelMap>): void
Obtains the file thumbnail of the given size. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO or ohos.permission.READ_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ----------------------------------- | ---- | ---------------- |
| size | [image.Size](js-apis-image.md#size) | Yes | Size of the thumbnail. |
| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes | Callback invoked to return the PixelMap of the thumbnail.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getThumbnailDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let size = { width: 720, height: 720 };
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject();
console.info('asset displayName = ', asset.displayName);
asset.getThumbnail(size, (err, pixelMap) => {
if (err == undefined) {
console.info('getThumbnail successful ' + pixelMap);
} else {
console.error('getThumbnail fail', err);
}
});
}
```
### getThumbnail
getThumbnail(size?: image.Size): Promise<image.PixelMap>
Obtains the file thumbnail of the given size. This API uses a promise to return the result.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO or ohos.permission.READ_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| ---- | -------------- | ---- | ----- |
| size | [image.Size](js-apis-image.md#size) | No | Size of the thumbnail.|
**Return value**
| Type | Description |
| ----------------------------- | --------------------- |
| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return the PixelMap of the thumbnail.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getThumbnailDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let size = { width: 720, height: 720 };
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject();
console.info('asset displayName = ', asset.displayName);
asset.getThumbnail(size).then((pixelMap) => {
console.info('getThumbnail successful ' + pixelMap);
}).catch((err) => {
console.error('getThumbnail fail' + err);
});
}
```
### favorite
favorite(isFavorite: boolean, callback: AsyncCallback<void>): void
Favorites or unfavorites this file asset. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ------------------------- | ---- | ---------------------------------- |
| isFavorite | boolean | Yes | Operation to perform. The value **true** means to favorite the file asset, and **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('favoriteDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject();
asset.favorite(true, (err) => {
if (err == undefined) {
console.info('favorite successfully');
} else {
console.error('favorite failed with error:' + err);
}
});
}
```
### favorite
favorite(isFavorite: boolean): Promise<void>
Favorites or unfavorites this file asset. This API uses a promise to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ------- | ---- | ---------------------------------- |
| isFavorite | boolean | Yes | Operation to perform. The value **true** means to favorite the file asset, and **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ---------- |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('favoriteDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject();
asset.favorite(true).then(function () {
console.info('favorite successfully');
}).catch(function (err) {
console.error('favorite failed with error:' + err);
});
}
```
### setHidden10+
setHidden(hiddenState: boolean, callback: AsyncCallback<void>): void
Sets this file asset to hidden state. This API uses an asynchronous callback to return the result.
The private files set to hidden state are located in the private album (in hidden state) and are not open to third-party applications. After obtaining private files from the private album, users can set **hiddenState** to **false** to remove them from the private album.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ------------------------- | ---- | ---------------------------------- |
| hiddenState | boolean | Yes | Whether to set a file to hidden state. The value **true** means to hide the file; the value **false** means the opposite.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value. |
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md) and [Universal Error Codes](../errorcodes/errorcode-universal.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 202 | Called by non-system application. |
| 13900020 | if parameter is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('setHiddenDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject();
asset.setHidden(true, (err) => {
if (err == undefined) {
console.info('setHidden successfully');
} else {
console.error('setHidden failed with error:' + err);
}
});
}
```
### setHidden10+
setHidden(hiddenState: boolean): Promise<void>
Sets this file asset to hidden state. This API uses a promise to return the result.
The private files set to hidden state are located in the private album (in hidden state) and are not open to third-party applications. After obtaining private files from the private album, users can set **hiddenState** to **false** to remove them from the private album.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ------- | ---- | ---------------------------------- |
| hiddenState | boolean | Yes | Whether to set a file to hidden state. The value **true** means to hide the file; the value **false** means the opposite.|
**Return value**
| Type | Description |
| ------------------- | ---------- |
| Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md) and [Universal Error Codes](../errorcodes/errorcode-universal.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 202 | Called by non-system application. |
| 13900020 | if parameter is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
// Restore a file from a hidden album. Before the operation, ensure that the file exists in the hidden album.
console.info('setHiddenDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let albumList = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.HIDDEN);
const album = await albumList.getFirstObject();
let fetchResult = await album.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject();
asset.setHidden(false).then(() => {
console.info('setHidden successfully');
}).catch((err) => {
console.error('setHidden failed with error:' + err);
});
}
```
### getExif10+
getExif(): Promise<string>
Obtains a JSON string consisting of the exchangeable image file format (EXIF) tags of this JPG image. This API uses a promise to return the result.
**CAUTION**
This API returns a JSON string consisting of EXIF tags. The complete EXIF information consists of **all_exif** and **ImageVideoKey.USER_COMMENT**. These two fields must be passed in via **fetchColumns**.
**System API**: This is a system API.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise<string> | Promise used to return the JSON string obtained.|
**Supported EXIF tags**
For details about the EXIF tags, see [image.PropertyKey](js-apis-image.md#propertykey7).
| Key Value | Description |
| --------------------------------------- | ----------------- |
| BitsPerSample | Number of bits per pixel.|
| Orientation | Image orientation.|
| ImageLength | Image length.|
| ImageWidth | Image width.|
| GPSLatitude | GPS latitude of the image.|
| GPSLongitude | GPS longitude of the image.|
| GPSLatitudeRef | Longitude reference, for example, W or E.|
| GPSLongitudeRef | Latitude reference, for example, N or S.|
| DateTimeOriginal | Shooting time.|
| ExposureTime | Exposure time.|
| SceneType | Shooting scene type.|
| ISOSpeedRatings | ISO sensitivity or speed.|
| FNumber | f-number.|
| DateTime | Date and time when the image was last modified.|
| GPSTimeStamp | GPS timestamp.|
| GPSDateStamp | GPS date stamp.|
| ImageDescription | Image description.|
| Make | Camera vendor.|
| Model | Model.|
| PhotoMode | Photo mode.|
| SensitivityType | Sensitivity type.|
| StandardOutputSensitivity | Standard output sensitivity.|
| RecommendedExposureIndex | Recommended exposure index.|
| ApertureValue | Aperture value.|
| MeteringMode | Metering mode.|
| LightSource | Light source.|
| Flash | Flash status.|
| FocalLength | Focal length.|
| UserComment | User comment.|
| PixelXDimension | Pixel X dimension.|
| PixelYDimension | Pixel Y dimension.|
| WhiteBalance | White balance.|
| FocalLengthIn35mmFilm | Focal length in 35 mm film.|
| ExposureBiasValue | Exposure compensation.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('getExifDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.isNotNull('all_exif')
let fetchOptions = {
fetchColumns: ['all_exif', userFileManager.ImageVideoKey.USER_COMMENT],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOptions);
let fileAsset = await fetchResult.getFirstObject();
console.info('getExifDemo fileAsset displayName: ' + JSON.stringify(fileAsset.displayName));
let exifMessage = await fileAsset.getExif();
let userCommentKey = 'UserComment';
let userComment = JSON.stringify(JSON.parse(exifMessage), [userCommentKey]);
console.info('getExifDemo userComment: ' + JSON.stringify(userComment));
fetchResult.close();
} catch (err) {
console.error('getExifDemoCallback failed with error: ' + err);
}
}
```
### getExif10+
getExif(callback: AsyncCallback<string>): void
Obtains a JSON string consisting of the EXIF tags of this JPG image. This API uses an asynchronous callback to return the result.
**CAUTION**
This API returns a JSON string consisting of EXIF tags. The complete EXIF information consists of **all_exif** and **ImageVideoKey.USER_COMMENT**. These two fields must be passed in via **fetchColumns**.
**System API**: This is a system API.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback<string> | Yes | Callback invoked to return the JSON string obtained.|
**Supported EXIF tags**
For details about the EXIF tags, see [image.PropertyKey](js-apis-image.md#propertykey7).
| Key Value | Description |
| --------------------------------------- | ----------------- |
| BitsPerSample | Number of bits per pixel.|
| Orientation | Image orientation.|
| ImageLength | Image length.|
| ImageWidth | Image width.|
| GPSLatitude | GPS latitude of the image.|
| GPSLongitude | GPS longitude of the image.|
| GPSLatitudeRef | Longitude reference, for example, W or E.|
| GPSLongitudeRef | Latitude reference, for example, N or S.|
| DateTimeOriginal | Shooting time.|
| ExposureTime | Exposure time.|
| SceneType | Shooting scene type.|
| ISOSpeedRatings | ISO sensitivity or speed.|
| FNumber | f-number.|
| DateTime | Date and time when the image was last modified.|
| GPSTimeStamp | GPS timestamp.|
| GPSDateStamp | GPS date stamp.|
| ImageDescription | Image description.|
| Make | Camera vendor.|
| Model | Model.|
| PhotoMode | Photo mode.|
| SensitivityType | Sensitivity type.|
| StandardOutputSensitivity | Standard output sensitivity.|
| RecommendedExposureIndex | Recommended exposure index.|
| ApertureValue | Aperture value.|
| MeteringMode | Metering mode.|
| LightSource | Light source.|
| Flash | Flash status.|
| FocalLength | Focal length.|
| UserComment | User comment.|
| PixelXDimension | Pixel X dimension.|
| PixelYDimension | Pixel Y dimension.|
| WhiteBalance | White balance.|
| FocalLengthIn35mmFilm | Focal length in 35 mm film.|
| ExposureBiasValue | Exposure compensation.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('getExifDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.isNotNull('all_exif')
let fetchOptions = {
fetchColumns: ['all_exif', userFileManager.ImageVideoKey.USER_COMMENT],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOptions);
let fileAsset = await fetchResult.getFirstObject();
console.info('getExifDemo fileAsset displayName: ' + JSON.stringify(fileAsset.displayName));
let userCommentKey = 'UserComment';
fileAsset.getExif((err, exifMessage) => {
if (exifMessage != undefined) {
let userComment = JSON.stringify(JSON.parse(exifMessage), [userCommentKey]);
console.info('getExifDemo userComment: ' + JSON.stringify(userComment));
} else {
console.error('getExif failed, message = ', err);
}
});
fetchResult.close();
} catch (err) {
console.error('getExifDemoCallback failed with error: ' + err);
}
}
```
### setUserComment10+
setUserComment(userComment: string): Promise<void>
Sets user comment information of an image or video. This API uses a promise to return the result.
**NOTE**
This API can be used to modify the comment information of only images or videos.
**System API**: This is a system API.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| userComment | string | Yes | User comment information to set, which cannot exceed 140 characters.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
|Promise<void> | Promise that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('setUserCommentDemo')
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOptions);
let fileAsset = await fetchResult.getFirstObject();
let userComment = 'test_set_user_comment';
await fileAsset.setUserComment(userComment);
} catch (err) {
console.error('setUserCommentDemoCallback failed with error: ' + err);
}
}
```
### setUserComment10+
setUserComment(userComment: string, callback: AsyncCallback<void>): void
Sets user comment information of an image or video. This API uses an asynchronous callback to return the result.
**NOTE**
This API can be used to modify the comment information of only images or videos.
**System API**: This is a system API.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| userComment | string | Yes | User comment information to set, which cannot exceed 140 characters.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('setUserCommentDemo')
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOptions);
let fileAsset = await fetchResult.getFirstObject();
let userComment = 'test_set_user_comment';
fileAsset.setUserComment(userComment, (err) => {
if (err === undefined) {
console.info('setUserComment successfully');
} else {
console.error('setUserComment failed with error: ' + err);
}
});
} catch (err) {
console.error('setUserCommentDemoCallback failed with error: ' + err);
}
}
```
## FetchResult
Provides APIs to manage the file retrieval result.
### getCount
getCount(): number
Obtains the total number of files in the result set.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| ------ | -------- |
| number | Returns the total number of files obtained.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getCountDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const fetchCount = fetchResult.getCount();
console.info('fetchCount = ', fetchCount);
}
```
### isAfterLast
isAfterLast(): boolean
Checks whether the cursor is in the last row of the result set.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| ------- | ---------------------------------- |
| boolean | Returns **true** if the cursor is in the last row of the result set; returns **false** otherwise.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
const fetchCount = fetchResult.getCount();
console.info('count:' + fetchCount);
let fileAsset = await fetchResult.getLastObject();
if (fetchResult.isAfterLast()) {
console.info('fileAsset isAfterLast displayName = ', fileAsset.displayName);
} else {
console.info('fileAsset not isAfterLast ');
}
}
```
### close
close(): void
Releases and invalidates this **FetchFileResult** instance. After this instance is released, the APIs in this instance cannot be invoked.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('fetchResultCloseDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
try {
let fetchResult = await mgr.getPhotoAssets(fetchOption);
await fetchResult.close();
console.info('close succeed.');
} catch (err) {
console.error('close fail. message = ' + err);
}
}
```
### getFirstObject
getFirstObject(callback: AsyncCallback<T>): void
Obtains the first file asset in the result set. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | ------------------------------------------- |
| callback | AsyncCallback<T> | Yes | Callback invoked to return the first file asset.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getFirstObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
fetchResult.getFirstObject((err, fileAsset) => {
if (fileAsset != undefined) {
console.info('fileAsset displayName: ', fileAsset.displayName);
} else {
console.error('fileAsset failed with err:' + err);
}
});
}
```
### getFirstObject
getFirstObject(): Promise<T>
Obtains the first file asset in the result set. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| --------------------------------------- | -------------------------- |
| Promise<T> | Promise used to return the first object in the result set.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getFirstObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fileAsset = await fetchResult.getFirstObject();
console.info('fileAsset displayName: ', fileAsset.displayName);
}
```
### getNextObject
getNextObject(callback: AsyncCallback<T>): void
Obtains the next file asset in the result set. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | --------------------------------------------- | ---- | ----------------------------------------- |
| callbacke | AsyncCallback<T> | Yes | Callback invoked to return the next file asset.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getNextObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
await fetchResult.getFirstObject();
if (fetchResult.isAfterLast()) {
fetchResult.getNextObject((err, fileAsset) => {
if (fileAsset != undefined) {
console.info('fileAsset displayName: ', fileAsset.displayName);
} else {
console.error('fileAsset failed with err: ' + err);
}
});
}
}
```
### getNextObject
getNextObject(): Promise<T>
Obtains the next file asset in the result set. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise<T> | Promise used to return the next object in the result set.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getNextObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
await fetchResult.getFirstObject();
if (fetchResult.isAfterLast()) {
let fileAsset = await fetchResult.getNextObject();
console.info('fileAsset displayName: ', fileAsset.displayName);
}
}
```
### getLastObject
getLastObject(callback: AsyncCallback<T>): void
Obtains the last file asset in the result set. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | --------------------------- |
| callback | AsyncCallback<T> | Yes | Callback invoked to return the last file asset obtained.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getLastObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
fetchResult.getLastObject((err, fileAsset) => {
if (fileAsset != undefined) {
console.info('fileAsset displayName: ', fileAsset.displayName);
} else {
console.error('fileAsset failed with err: ' + err);
}
});
}
```
### getLastObject
getLastObject(): Promise<T>
Obtains the last file asset in the result set. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise<T> | Promise used to return the last object in the result set.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getLastObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fileAsset = await fetchResult.getLastObject();
console.info('fileAsset displayName: ', fileAsset.displayName);
}
```
### getPositionObject
getPositionObject(index: number, callback: AsyncCallback<T>): void
Obtains a file asset with the specified index in the result set. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ------------------ |
| index | number | Yes | Index of the file asset to obtain. The value starts from **0**. |
| callback | AsyncCallback<T> | Yes | Callback invoked to return the file asset obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type index is not number. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getPositionObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
fetchResult.getPositionObject(0, (err, fileAsset) => {
if (fileAsset != undefined) {
console.info('fileAsset displayName: ', fileAsset.displayName);
} else {
console.error('fileAsset failed with err: ' + err);
}
});
}
```
### getPositionObject
getPositionObject(index: number): Promise<T>
Obtains a file asset with the specified index in the result set. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ------ | ---- | -------------- |
| index | number | Yes | Index of the file asset to obtain. The value starts from **0**.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise<T> | Promise used to return the file asset obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type index is not number. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getPositionObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fileAsset = await fetchResult.getPositionObject(0);
console.info('fileAsset displayName: ', fileAsset.displayName);
}
```
### getAllObject10+
getAllObject(callback: AsyncCallback<Array<T>>): void
Obtains all the file assets in the result set. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | ------------------------------------------- |
| callback | AsyncCallback<Array<T>> | Yes | Callback invoked to return an array of all file assets in the result set.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getAllObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
fetchResult.getAllObject((err, fileAssetList) => {
if (fileAssetList != undefined) {
console.info('fileAssetList length: ', fileAssetList.length);
} else {
console.error('fileAssetList failed with err:' + err);
}
});
}
```
### getAllObject10+
getAllObject(): Promise<Array<T>>
Obtains all the file assets in the result set. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| --------------------------------------- | -------------------------- |
| Promise<Array<T>> | Promise used to return an array of all file assets in the result set.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('getAllObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fileAssetList = await fetchResult.getAllObject();
console.info('fileAssetList length: ', fileAssetList.length);
}
```
## Album
Provides APIs to manage albums.
### Attributes
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Readable | Writable | Description |
| ------------ | ------ | ---- | ---- | ------- |
| albumType10+ | [AlbumType]( #albumtype10) | Yes | No | Type of the album. |
| albumSubType10+ | [AlbumSubType]( #albumsubtype10) | Yes | No | Subtype of the album. |
| albumName | string | Yes | Yes for a user album; no for a system album. | Name of the album. |
| albumUri | string | Yes | No | URI of the album. |
| count | number | Yes | No | Number of files in the album.|
| coverUri | string | Yes | Yes for a user album; no for a system album. | URI of the cover file of the album.|
### getPhotoAssets
getPhotoAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<FileAsset>>): void;
Obtains image and video assets. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets.|
| callback | AsyncCallback<[FetchResult](#fetchresult)<[FileAsset](#fileasset)>> | Yes | Callback invoked to return the image and video assets obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('albumGetFileAssetsDemoCallback');
let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = {
predicates: predicates
};
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
const albumList = await mgr.getPhotoAlbums(albumFetchOptions);
const album = await albumList.getFirstObject();
album.getPhotoAssets(fetchOption, (err, albumFetchResult) => {
if (albumFetchResult != undefined) {
console.info('album getPhotoAssets successfully, getCount: ' + albumFetchResult.getCount());
} else {
console.error('album getPhotoAssets failed with error: ' + err);
}
});
}
```
### getPhotoAssets
getPhotoAssets(options: FetchOptions): Promise<FetchResult<FileAsset>>;
Obtains image and video assets. This API uses a promise to return the result.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise<[FetchResult](#fetchresult)<[FileAsset](#fileasset)>> | Promise used to return the image and video assets obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('albumGetFileAssetsDemoPromise');
let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = {
predicates: predicates
};
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
const albumList = await mgr.getPhotoAlbums(albumFetchOptions);
const album = await albumList.getFirstObject();
album.getPhotoAssets(fetchOption).then((albumFetchResult) => {
console.info('album getFileAssets successfully, getCount: ' + albumFetchResult.getCount());
}).catch((err) => {
console.error('album getFileAssets failed with error: ' + err);
});
}
```
### commitModify
commitModify(callback: AsyncCallback<void>): void;
Commits the modification on the album attributes to the database. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('albumCommitModifyDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = {
predicates: predicates
};
const albumList = await mgr.getPhotoAlbums(albumFetchOptions);
const album = await albumList.getFirstObject();
album.albumName = 'hello';
album.commitModify((err) => {
if (err != undefined) {
console.error('commitModify failed with error: ' + err);
} else {
console.info('commitModify successfully');
}
});
}
```
### commitModify
commitModify(): Promise<void>;
Commits the modification on the album attributes to the database. This API uses a promise to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| ------------------- | ------------ |
| Promise<void> | Promise that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('albumCommitModifyDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = {
predicates: predicates
};
try {
var albumList = await mgr.getPhotoAlbums(albumFetchOptions);
} catch (err) {
console.error('getPhotoAlbums failed. message = ', err);
}
const album = await albumList.getFirstObject();
album.albumName = 'hello';
album.commitModify().then(() => {
console.info('commitModify successfully');
}).catch((err) => {
console.error('commitModify failed with error: ' + err);
});
}
```
### addPhotoAssets10+
addPhotoAssets(assets: Array<FileAsset>, callback: AsyncCallback<void>): void;
Adds image and video assets to an album. Before the operation, ensure that the image and video assets to add and the album exist. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array<[FileAsset](#fileasset)> | Yes | Array of the image and video assets to add.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if PhotoAssets is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('addPhotoAssetsDemoCallback');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
let album = await albumFetchResult.getFirstObject();
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let asset = await fetchResult.getFirstObject();
album.addPhotoAssets([asset], (err) => {
if (err === undefined) {
console.info('album addPhotoAssets successfully');
} else {
console.error('album addPhotoAssets failed with error: ' + err);
}
});
} catch (err) {
console.error('addPhotoAssetsDemoCallback failed with error: ' + err);
}
}
```
### addPhotoAssets10+
addPhotoAssets(assets: Array<FileAsset>): Promise<void>;
Adds image and video assets to an album. Before the operation, ensure that the image and video assets to add and the album exist. This API uses a promise to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array<[FileAsset](#fileasset)> | Yes | Array of the image and video assets to add.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
|Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if PhotoAssets is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('addPhotoAssetsDemoPromise');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
let album = await albumFetchResult.getFirstObject();
let fetchResult = await mgr.getPhotoAssets(fetchOption);
let asset = await fetchResult.getFirstObject();
album.addPhotoAssets([asset]).then(() => {
console.info('album addPhotoAssets successfully');
}).catch((err) => {
console.error('album addPhotoAssets failed with error: ' + err);
});
} catch (err) {
console.error('addPhotoAssetsDemoPromise failed with error: ' + err);
}
}
```
### removePhotoAssets10+
removePhotoAssets(assets: Array<FileAsset>, callback: AsyncCallback<void>): void;
Removes image and video assets from an album. The album and file resources must exist. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array<[FileAsset](#fileasset)> | Yes | Array of the image and video assets to remove.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if PhotoAssets is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('removePhotoAssetsDemoCallback');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
let album = await albumFetchResult.getFirstObject();
let fetchResult = await album.getPhotoAssets(fetchOption);
let asset = await fetchResult.getFirstObject();
album.removePhotoAssets([asset], (err) => {
if (err === undefined) {
console.info('album removePhotoAssets successfully');
} else {
console.error('album removePhotoAssets failed with error: ' + err);
}
});
} catch (err) {
console.error('removePhotoAssetsDemoCallback failed with error: ' + err);
}
}
```
### removePhotoAssets10+
removePhotoAssets(assets: Array<FileAsset>): Promise<void>;
Removes image and video assets from an album. The album and file resources must exist. This API uses a promise to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array<[FileAsset](#fileasset)> | Yes | Array of the image and video assets to remove.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
|Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if PhotoAssets is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('removePhotoAssetsDemoPromise');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
let album = await albumFetchResult.getFirstObject();
let fetchResult = await album.getPhotoAssets(fetchOption);
let asset = await fetchResult.getFirstObject();
album.removePhotoAssets([asset]).then(() => {
console.info('album removePhotoAssets successfully');
}).catch((err) => {
console.error('album removePhotoAssets failed with error: ' + err);
});
} catch (err) {
console.error('removePhotoAssetsDemoPromise failed with error: ' + err);
}
}
```
### recoverPhotoAssets10+
recoverPhotoAssets(assets: Array<FileAsset>, callback: AsyncCallback<void>): void;
Recovers image or video assets from the recycle bin. Before the operation, ensure that the image or video assets exist in the recycle bin. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array<[FileAsset](#fileasset)> | Yes | Array of the image or video assets to recover.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if PhotoAssets is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('recoverPhotoAssetsDemoCallback');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
let album = await albumFetchResult.getFirstObject();
let fetchResult = await album.getPhotoAssets(fetchOption);
let asset = await fetchResult.getFirstObject();
album.recoverPhotoAssets([asset], (err) => {
if (err === undefined) {
console.info('album recoverPhotoAssets successfully');
} else {
console.error('album recoverPhotoAssets failed with error: ' + err);
}
});
} catch (err) {
console.error('recoverPhotoAssetsDemoCallback failed with error: ' + err);
}
}
```
### recoverPhotoAssets10+
recoverPhotoAssets(assets: Array<FileAsset>): Promise<void>;
Recovers image or video assets from the recycle bin. Before the operation, ensure that the image or video assets exist in the recycle bin. This API uses a promise to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array<[FileAsset](#fileasset)> | Yes | Array of the image or video assets to recover.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
|Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if PhotoAssets is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('recoverPhotoAssetsDemoPromise');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
let album = await albumFetchResult.getFirstObject();
let fetchResult = await album.getPhotoAssets(fetchOption);
let asset = await fetchResult.getFirstObject();
album.recoverPhotoAssets([asset]).then(() => {
console.info('album recoverPhotoAssets successfully');
}).catch((err) => {
console.error('album recoverPhotoAssets failed with error: ' + err);
});
} catch (err) {
console.error('recoverPhotoAssetsDemoPromise failed with error: ' + err);
}
}
```
### deletePhotoAssets10+
deletePhotoAssets(assets: Array<FileAsset>, callback: AsyncCallback<void>): void;
Deletes image or video assets from the recycle bin. Before the operation, ensure that the image or video assets exist in the recycle bin. This API uses an asynchronous callback to return the result.
**CAUTION**: This operation is irreversible. The file assets deleted cannot be restored. Exercise caution when performing this operation.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array<[FileAsset](#fileasset)> | Yes | Array of the image or video assets to delete.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if PhotoAssets is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('deletePhotoAssetsDemoCallback');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
let album = await albumFetchResult.getFirstObject();
let fetchResult = await album.getPhotoAssets(fetchOption);
let asset = await fetchResult.getFirstObject();
album.deletePhotoAssets([asset], (err) => {
if (err === undefined) {
console.info('album deletePhotoAssets successfully');
} else {
console.error('album deletePhotoAssets failed with error: ' + err);
}
});
} catch (err) {
console.error('deletePhotoAssetsDemoCallback failed with error: ' + err);
}
}
```
### deletePhotoAssets10+
deletePhotoAssets(assets: Array<FileAsset>): Promise<void>;
Deletes image or video assets from the recycle bin. Before the operation, ensure that the image or video assets exist in the recycle bin. This API uses a promise to return the result.
**CAUTION**: This operation is irreversible. The file assets deleted cannot be restored. Exercise caution when performing this operation.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array<[FileAsset](#fileasset)> | Yes | Array of the image or video assets to delete.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
|Promise<void> | Promise that returns no value.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if PhotoAssets is invalid. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
try {
console.info('deletePhotoAssetsDemoPromise');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
let album = await albumFetchResult.getFirstObject();
let fetchResult = await album.getPhotoAssets(fetchOption);
let asset = await fetchResult.getFirstObject();
album.deletePhotoAssets([asset]).then(() => {
console.info('album deletePhotoAssets successfully');
}).catch((err) => {
console.error('album deletePhotoAssets failed with error: ' + err);
});
} catch (err) {
console.error('deletePhotoAssetsDemoPromise failed with error: ' + err);
}
}
```
## PrivateAlbum
Provides APIs for managing the system albums.
This API will be discarded. Use [Album](#album) instead.
### Attributes
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Readable | Writable | Description |
| ------------ | ------ | ---- | ---- | ------- |
| albumName | string | Yes | Yes | Name of the album. |
| albumUri | string | Yes | No | URI of the album. |
| dateModified | number | Yes | No | Date when the album was last modified. |
| count | number | Yes | No | Number of files in the album.|
| coverUri | string | Yes | No | URI of the cover file of the album.|
### getPhotoAssets
getPhotoAssets(options: FetchOptions, callback: AsyncCallback<FetchResult<FileAsset>>): void;
Obtains image and video assets from a system album. This API uses an asynchronous callback to return the result.
This API will be deprecated. Use [Album.getPhotoAssets](#getphotoassets-2) instead.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets.|
| callback | AsyncCallback<[FetchResult](#fetchresult)<[FileAsset](#fileasset)>> | Yes | Callback invoked to return the image and video assets obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('privateAlbumGetFileAssetsDemoCallback');
let albumList = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
const trashAlbum = await albumList.getFirstObject();
trashAlbum.getPhotoAssets(fetchOption, (err, fetchResult) => {
if (fetchResult != undefined) {
let count = fetchResult.getCount();
console.info('fetchResult.count = ', count);
} else {
console.error('getFileAssets failed, message = ', err);
}
});
}
```
### getPhotoAssets
getPhotoAssets(options: FetchOptions): Promise<FetchResult<FileAsset>>;
Obtains image and video assets from a system album. This API uses a promise to return the result.
This API will be deprecated. Use [Album.getPhotoAssets](#getphotoassets-3) instead.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise:[FetchResult](#fetchresult)<[FileAsset](#fileasset)>| Promise used to return the image and video assets obtained.|
**Error codes**
For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type options is not FetchOptions. |
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('privateAlbumGetFileAssetsDemoPromise');
let albumList = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
const trashAlbum = await albumList.getFirstObject();
let fetchResult = await trashAlbum.getPhotoAssets(fetchOption);
let count = fetchResult.getCount();
console.info('fetchResult.count = ', count);
}
```
### delete
delete(uri: string, callback: AsyncCallback<void>): void;
Deletes files from a system album.
This API will be deprecated. Use [Album.deletePhotoAssets](#deletephotoassets10) instead.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | URI of the album.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('privateAlbumDeleteCallback');
let albumList = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
const trashAlbum = await albumList.getFirstObject();
let fetchResult = await trashAlbum.getPhotoAssets(fetchOption);
const fileAsset = await fetchResult.getFirstObject();
let deleteFileUri = fileAsset.uri;
trashAlbum.delete(deleteFileUri, (err) => {
if (err != undefined) {
console.error('trashAlbum.delete failed, message = ', err);
} else {
console.info('trashAlbum.delete successfully');
}
});
}
```
### delete
delete(uri: string): Promise<void>;
Deletes files from a system album.
This API will be deprecated. Use [Album.deletePhotoAssets](#deletephotoassets10) instead.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | URI of the album.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise<void>| Promise that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('privateAlbumDeleteDemoPromise');
let albumList = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
const trashAlbum = await albumList.getFirstObject();
let fetchResult = await trashAlbum.getPhotoAssets(fetchOption);
const fileAsset = await fetchResult.getFirstObject();
let deleteFileUri = fileAsset.uri;
trashAlbum.delete(deleteFileUri).then(() => {
console.info('trashAlbum.delete successfully');
}).catch((err) => {
console.error('trashAlbum.delete failed, message = ', err);
});
}
```
### recover
recover(uri: string, callback: AsyncCallback<void>): void;
Recovers files in a system album.
This API will be deprecated. Use [Album.recoverPhotoAssets](#recoverphotoassets10) instead.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | URI of the album.|
| callback | AsyncCallback<void> | Yes | Callback that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('privateAlbumRecoverDemoCallback');
let albumList = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
const trashAlbum = await albumList.getFirstObject();
let fetchResult = await trashAlbum.getPhotoAssets(fetchOption);
const fileAsset = await fetchResult.getFirstObject();
let recoverFileUri = fileAsset.uri;
trashAlbum.recover(recoverFileUri, (err) => {
if (err != undefined) {
console.error('trashAlbum.recover failed, message = ', err);
} else {
console.info('trashAlbum.recover successfully');
}
});
}
```
### recover
recover(uri: string): Promise<void>;
Recovers files in a system album.
This API will be deprecated. Use [Album.recoverPhotoAssets](#recoverphotoassets10) instead.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | URI of the album.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
| Promise<void>| Promise that returns no value.|
**Example**
```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() {
console.info('privateAlbumRecoverDemoPromise');
let albumList = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
const trashAlbum = await albumList.getFirstObject();
let fetchResult = await trashAlbum.getPhotoAssets(fetchOption);
const fileAsset = await fetchResult.getFirstObject();
let recoverFileUri = fileAsset.uri;
trashAlbum.recover(recoverFileUri).then(() => {
console.info('trashAlbum.recover successfully');
}).catch((err) => {
console.error('trashAlbum.recover failed, message = ', err);
});
}
```
## MemberType
Enumerates the member types.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type| Readable | Writable | Description |
| ----- | ---- | ---- | ---- | ---- |
| number | number | Yes| Yes| The member is a number.|
| string | string | Yes| Yes| The member is a string.|
| boolean | boolean | Yes| Yes| The member is a Boolean value.|
## ChangeEvent
Enumerates the type of changes to observe.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type| Readable | Writable | Description|
| ----- | ---- | ---- | ---- | ---- |
| deviceChange | string | Yes| Yes| Device change.|
| albumChange | string | Yes| Yes| Album change.|
| imageChange | string | Yes| Yes| Image change.|
| audioChange | string | Yes| Yes| Audio change.|
| videoChange | string | Yes| Yes| Video change.|
| remoteFileChange | string | Yes| Yes| Remote file change.|
## PeerInfo
Defines information about a registered device.
**System capability**: SystemCapability.FileManagement.UserFileManager.DistributedCore
| Name | Type | Readable| Writable| Description |
| ---------- | -------------------------- | ---- | ---- | ---------------- |
| deviceName | string | Yes | No | Name of the registered device. |
| networkId | string | Yes | No | Network ID of the registered device.|
| isOnline | boolean | Yes | No | Whether the registered device is online. |
## FileType
Enumerates media file types.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value| Description|
| ----- | ---- | ---- |
| IMAGE | 1 | Image.|
| VIDEO | 2 | Video.|
| AUDIO | 3 | Audio.|
## PhotoSubType10+
Enumerates the [FileAsset](#fileasset) types.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value| Description|
| ----- | ---- | ---- |
| DEFAULT | 0 | Default (photo) type.|
| SCREENSHOT | 1 | Screenshots and screen recording files.|
| CAMERA | 2 | Photos and videos taken by a camera.|
## PositionType10+
Enumerates the file location.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value| Description|
| ----- | ---- | ---- |
| LOCAL | 1 | Stored only on a local device.|
| CLOUD | 2 | Stored only on the cloud.|
| BOTH | 3 | Stored both on a local device and the cloud.|
## AlbumType10+
Enumerates the album types.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value| Description|
| ----- | ---- | ---- |
| USER | 0 | User album.|
| SYSTEM | 1024 | System album.|
## AlbumSubType10+
Enumerate the album subtypes.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value| Description|
| ----- | ---- | ---- |
| USER_GENERIC | 1 | User album.|
| FAVORITE | 1025 | Favorites.|
| VIDEO | 1026 | Video album.|
| HIDDEN | 1027 | Hidden album.|
| TRASH | 1028 | Recycle bin.|
| SCREENSHOT | 1029 | Album for screenshots and screen recording files.|
| CAMERA | 1030 | Album for photos and videos taken by the camera.|
| ANY | 2147483647 | Any album.|
## PrivateAlbumType
Enumerates the system album types.
This API will be deprecated. Use [AlbumType](#albumtype10) and [AlbumSubType](#albumsubtype10) instead.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value| Description |
| ----- | ---- | ---- |
| TYPE_FAVORITE | 0 | Favorites.|
| TYPE_TRASH | 1 | Recycle bin.|
## AudioKey
Defines the key information about an audio file.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value | Description |
| ------------- | ------------------- | ---------------------------------------------------------- |
| URI | uri | URI of the file. |
| DISPLAY_NAME | display_name | File name displayed. |
| DATE_ADDED | date_added | Date when the file was added. The value is the number of seconds elapsed since the Epoch time. |
| DATE_MODIFIED | date_modified | Date when the file content (not the file name) was last modified. The value is the number of seconds elapsed since the Epoch time.|
| TITLE | title | Title in the file. |
| ARTIST | artist | Author of the file. |
| AUDIOALBUM | audio_album | Audio album. |
| DURATION | duration | Duration, in ms. |
| FAVORITE | favorite | Whether the file is added to favorites. |
## ImageVideoKey
Defines the key information about an image or video file.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value | Description |
| ------------- | ------------------- | ---------------------------------------------------------- |
| URI | uri | URI of the file. |
| FILE_TYPE | file_type | Type of the file. |
| DISPLAY_NAME | display_name | File name displayed. |
| DATE_ADDED | date_added | Date when the file was added. The value is the number of seconds elapsed since the Epoch time. |
| DATE_MODIFIED | date_modified | Date when the file content (not the file name) was last modified. The value is the number of seconds elapsed since the Epoch time.|
| TITLE | title | Title of the file. |
| DURATION | duration | Duration, in ms. |
| WIDTH | width | Image width, in pixels. |
| HEIGHT | height | Image height, in pixels. |
| DATE_TAKEN | date_taken | Date when the file (photo) was taken. The value is the number of seconds elapsed since the Epoch time. |
| ORIENTATION | orientation | Orientation of the image file. |
| FAVORITE | favorite | Whether the file is added to favorites. |
| POSITION10+ | position | File location type. |
| DATE_TRASHED10+ | date_trashed | Date when the file was deleted. The value is the number of seconds between the time when the file is deleted and January 1, 1970. |
| HIDDEN10+ | hidden | Whether the file is hidden. |
| CAMERA_SHOT_KEY10+ | camera_shot_key | Key for the Untra Snamshot feature, which allows the camera to take photos or record videos with the screen off. (This parameter is available only for the system camera, and the key value is defined by the system camera.) |
| USER_COMMENT10+ | user_comment | User comment information. |
## AlbumKey
Defines the key album information.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value | Description |
| ------------- | ------------------- | ---------------------------------------------------------- |
| URI | uri | URI of the album. |
| FILE_TYPE | file_type | Type of the file. |
| ALBUM_NAME | album_name | Name of the album. |
| DATE_ADDED | date_added | Date when the album was added. The value is the number of seconds elapsed since the Epoch time. |
| DATE_MODIFIED | date_modified | Date when the album file content (not the album name) was last modified. The value is the number of seconds elapsed since the Epoch time.|
## PhotoCreateOptions10+
Options for creating an image or video asset.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Mandatory| Description |
| ---------------------- | ------------------- | ---- | ------------------------------------------------ |
| subType | [PhotoSubType](#photosubtype10) | No | Subtype of the image or video. |
| cameraShotKey | string | No | Key for the Untra Snamshot feature, which allows the camera to take photos or record videos with the screen off. (This parameter is available only for the system camera, and the key value is defined by the system camera.) |
## FetchOptions
Defines the options for fetching media files.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Readable| Writable| Description |
| ---------------------- | ------------------- | ---- |---- | ------------------------------------------------ |
| fetchColumns | Array<string> | Yes | Yes | Column names used for retrieval. If this parameter is left empty, the media files are fetched by URI, name, and file type by default. The specific field names are subject to the definition of the search object. Example:
fetchColumns: ['uri', 'title']|
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md) | Yes | Yes | Predicates that specify the fetch criteria.|
## AlbumFetchOptions
Defines the options for fetching an album.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Readable| Writable| Description |
| ---------------------- | ------------------- | ---- |---- | ------------------------------------------------ |
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md) | Yes | Yes | Predicates that specify the fetch criteria.|
## ChangeData10+
Defines the return value of the listener callback.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Readable| Writable| Description |
| ------- | --------------------------- | ---- | ---- | ------------------------------------------------------------ |
| type | [NotifyType](#notifytype10) | Yes | No | Notification type. |
| uris | Array<string> | Yes | No | Array of all file asset or album URIs with the same [NotifyType](#notifytype10).|
| subUris | Array<string> | Yes | No | URIs of the changed files in the album. |
## NotifyType10+
Enumerates the notification event types.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value | Description |
| ------------------------- | ---- | -------------------------------- |
| NOTIFY_ADD | 0 | A file asset or album is added. |
| NOTIFY_UPDATE | 1 | A file asset or album is updated. |
| NOTIFY_REMOVE | 2 | A file asset or album is removed. |
| NOTIFY_ALBUM_ADD_ASSET | 3 | A file asset is added to the album.|
| NOTIFY_ALBUM_REMOVE_ASSET | 4 | A file asset is removed from the album.|
## DefaultChangeUri10+
Enumerates the **DefaultChangeUri** subtypes.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value | Description |
| ----------------- | ----------------------- | ------------------------------------------------------------ |
| DEFAULT_PHOTO_URI | file://media/Photo | Default **PhotoAsset** URI. The **PhotoAsset** change notifications are received based on this parameter and **forSubUri{true}**.|
| DEFAULT_ALBUM_URI | file://media/PhotoAlbum | Default album URI. Album change notifications are received based on this parameter and **forSubUri{true}**. |
| DEFAULT_AUDIO_URI | file://media/Audio | Default **AudioAsset** URI. The **AudioAsset** change notifications are received based on this parameter and **forSubUri{true}**.|