提交 0d826407 编写于 作者: A Annie_wang

update docs

Signed-off-by: NAnnie_wang <annie.wangli@huawei.com>
上级 05cd3ae9
...@@ -62,6 +62,14 @@ Obtains image and video assets. This API uses an asynchronous callback to return ...@@ -62,6 +62,14 @@ Obtains image and video assets. This API uses an asynchronous callback to return
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets. | | options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets. |
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | Yes | Callback invoked to return the image and video assets obtained.| | callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | 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** **Example**
```ts ```ts
...@@ -80,7 +88,7 @@ async function example() { ...@@ -80,7 +88,7 @@ async function example() {
console.info('fetchResult success'); console.info('fetchResult success');
let fileAsset = await fetchResult.getFirstObject(); let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) { if (fileAsset != undefined) {
console.info("fileAsset.displayName : " + fileAsset.displayName); console.info('fileAsset.displayName : ' + fileAsset.displayName);
} }
} else { } else {
console.error('fetchResult fail' + err); console.error('fetchResult fail' + err);
...@@ -111,6 +119,14 @@ Obtains image and video assets. This API uses a promise to return the result. ...@@ -111,6 +119,14 @@ Obtains image and video assets. This API uses a promise to return the result.
| --------------------------- | -------------- | | --------------------------- | -------------- |
| Promise&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | Promise used to return the image and video assets obtained.| | Promise&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | 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** **Example**
```ts ```ts
...@@ -129,7 +145,7 @@ async function example() { ...@@ -129,7 +145,7 @@ async function example() {
console.info('fetchResult success'); console.info('fetchResult success');
let fileAsset = await fetchResult.getFirstObject(); let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) { if (fileAsset != undefined) {
console.info("fileAsset.displayName :" + fileAsset.displayName); console.info('fileAsset.displayName :' + fileAsset.displayName);
} }
} }
} catch (err) { } catch (err) {
...@@ -137,12 +153,11 @@ async function example() { ...@@ -137,12 +153,11 @@ async function example() {
} }
} }
``` ```
### createPhotoAsset ### createPhotoAsset
createPhotoAsset(displayName: string, albumUri: string, callback: AsyncCallback&lt;FileAsset&gt;): void; createPhotoAsset(displayName: string, albumUri: string, callback: AsyncCallback&lt;FileAsset&gt;): void;
Creates an image or video asset. This API uses an asynchronous callback to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
...@@ -156,6 +171,15 @@ Creates an image or video asset. This API uses an asynchronous callback to retur ...@@ -156,6 +171,15 @@ Creates an image or video asset. This API uses an asynchronous callback to retur
| albumUri | string | Yes | URI of the album where the image or video is located. | | albumUri | string | Yes | URI of the album where the image or video is located. |
| callback | AsyncCallback&lt;[FileAsset](#fileasset)&gt; | Yes | Callback invoked to return the image or video created.| | callback | AsyncCallback&lt;[FileAsset](#fileasset)&gt; | 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** **Example**
```ts ```ts
...@@ -169,7 +193,7 @@ async function example() { ...@@ -169,7 +193,7 @@ async function example() {
}; };
let albums = await mgr.getPhotoAlbums(fetchOptions); let albums = await mgr.getPhotoAlbums(fetchOptions);
let album = await albums.getFirstObject(); let album = await albums.getFirstObject();
let testFileName = "testFile" + Date.now() + ".jpg"; let testFileName = 'testFile' + Date.now() + '.jpg';
mgr.createPhotoAsset(testFileName, album.albumUri, (err, fileAsset) => { mgr.createPhotoAsset(testFileName, album.albumUri, (err, fileAsset) => {
if (fileAsset != undefined) { if (fileAsset != undefined) {
console.info('createPhotoAsset file displayName' + fileAsset.displayName); console.info('createPhotoAsset file displayName' + fileAsset.displayName);
...@@ -185,7 +209,7 @@ async function example() { ...@@ -185,7 +209,7 @@ async function example() {
createPhotoAsset(displayName: string, callback: AsyncCallback&lt;FileAsset&gt;): void; createPhotoAsset(displayName: string, callback: AsyncCallback&lt;FileAsset&gt;): void;
Creates an image or video asset. This API uses an asynchronous callback to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
...@@ -198,12 +222,21 @@ Creates an image or video asset. This API uses an asynchronous callback to retur ...@@ -198,12 +222,21 @@ Creates an image or video asset. This API uses an asynchronous callback to retur
| displayName | string | Yes | File name of the image or video to create. | | displayName | string | Yes | File name of the image or video to create. |
| callback | AsyncCallback&lt;[FileAsset](#fileasset)&gt; | Yes | Callback invoked to return the image or video created.| | callback | AsyncCallback&lt;[FileAsset](#fileasset)&gt; | 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** **Example**
```ts ```ts
async function example() { async function example() {
console.info('createPhotoAssetDemo'); console.info('createPhotoAssetDemo');
let testFileName = "testFile" + Date.now() + ".jpg"; let testFileName = 'testFile' + Date.now() + '.jpg';
mgr.createPhotoAsset(testFileName, (err, fileAsset) => { mgr.createPhotoAsset(testFileName, (err, fileAsset) => {
if (fileAsset != undefined) { if (fileAsset != undefined) {
console.info('createPhotoAsset file displayName' + fileAsset.displayName); console.info('createPhotoAsset file displayName' + fileAsset.displayName);
...@@ -219,7 +252,7 @@ async function example() { ...@@ -219,7 +252,7 @@ async function example() {
createPhotoAsset(displayName: string, albumUri?: string): Promise&lt;FileAsset&gt;; createPhotoAsset(displayName: string, albumUri?: string): Promise&lt;FileAsset&gt;;
Creates an image or video asset. This API uses a promise to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
...@@ -236,7 +269,15 @@ Creates an image or video asset. This API uses a promise to return the result. ...@@ -236,7 +269,15 @@ Creates an image or video asset. This API uses a promise to return the result.
| Type | Description | | Type | Description |
| --------------------------- | -------------- | | --------------------------- | -------------- |
| Promise&lt;[FileAsset](#fileasset)&gt; | Promise used to return the image or video created.| | Promise&lt;[FileAsset](#fileasset)&gt; | 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** **Example**
...@@ -244,7 +285,7 @@ Creates an image or video asset. This API uses a promise to return the result. ...@@ -244,7 +285,7 @@ Creates an image or video asset. This API uses a promise to return the result.
async function example() { async function example() {
console.info('createPhotoAssetDemo'); console.info('createPhotoAssetDemo');
try { try {
let testFileName = "testFile" + Date.now() + ".jpg"; let testFileName = 'testFile' + Date.now() + '.jpg';
let fileAsset = await mgr.createPhotoAsset(testFileName); let fileAsset = await mgr.createPhotoAsset(testFileName);
console.info('createPhotoAsset file displayName' + fileAsset.displayName); console.info('createPhotoAsset file displayName' + fileAsset.displayName);
console.info('createPhotoAsset successfully'); console.info('createPhotoAsset successfully');
...@@ -254,10 +295,197 @@ async function example() { ...@@ -254,10 +295,197 @@ async function example() {
} }
``` ```
### createPhotoAsset
createPhotoAsset(displayName: string, createOption: PhotoCreateOptions, callback: AsyncCallback&lt;FileAsset&gt;): 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&lt;[FileAsset](#fileasset)&gt; | 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&lt;FileAsset&gt;;
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&lt;[FileAsset](#fileasset)&gt; | 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);
}
}
```
### createAudioAsset<sup>10+</sup>
createAudioAsset(displayName: string, callback: AsyncCallback&lt;FileAsset&gt;): 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&lt;[FileAsset](#fileasset)&gt; | 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);
}
});
}
```
### createAudioAsset<sup>10+</sup>
createAudioAsset(displayName: string): Promise&lt;FileAsset&gt;;
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&lt;[FileAsset](#fileasset)&gt; | 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);
}
}
```
### getPhotoAlbums ### getPhotoAlbums
getPhotoAlbums(options: AlbumFetchOptions, callback: AsyncCallback&lt;FetchResult&lt;Album&gt;&gt;): void; getPhotoAlbums(options: AlbumFetchOptions, callback: AsyncCallback&lt;FetchResult&lt;Album&gt;&gt;): void;
Obtains image and video albums. This API uses an asynchronous callback to return the result. Obtains image and video albums. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
...@@ -269,7 +497,15 @@ Obtains image and video albums. This API uses an asynchronous callback to return ...@@ -269,7 +497,15 @@ Obtains image and video albums. This API uses an asynchronous callback to return
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- | | -------- | ------------------------ | ---- | ------------------------- |
| options | [AlbumFetchOptions](#albumfetchoptions) | Yes | Options for fetching the albums. | | options | [AlbumFetchOptions](#albumfetchoptions) | Yes | Options for fetching the albums. |
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[Album](#album)&gt;&gt; | Yes | Callback invoked to return the albums obtained.| | callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[Album](#album)&gt;&gt; | 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** **Example**
...@@ -320,7 +556,15 @@ Obtains image and video albums. This API uses a promise to return the result. ...@@ -320,7 +556,15 @@ Obtains image and video albums. This API uses a promise to return the result.
| Type | Description | | Type | Description |
| --------------------------- | -------------- | | --------------------------- | -------------- |
| Promise&lt;[FetchResult](#fetchresult)&lt;[Album](#album)&gt;&gt; | Promise used to return the albums obtained.| | Promise&lt;[FetchResult](#fetchresult)&lt;[Album](#album)&gt;&gt; | 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** **Example**
...@@ -344,93 +588,105 @@ async function example() { ...@@ -344,93 +588,105 @@ async function example() {
} }
``` ```
### getPrivateAlbum ### createAlbum<sup>10+</sup>
getPrivateAlbum(type: PrivateAlbumType, callback: AsyncCallback&lt;FetchResult&lt;PrivateAlbum&gt;&gt;): void; createAlbum(name: string, callback: AsyncCallback&lt;Album&gt;): void;
Obtains the system album. This API uses an asynchronous callback to return the result. 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:<br>.. \ / : * ? " ' ` < > | { } [ ]
- The album name is case-insensitive.
- Duplicate album names are not allowed.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO **Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- | | -------- | ------------------------ | ---- | ------------------------- |
| type | [PrivateAlbumType](#privatealbumtype) | Yes | Type of the album to obtain. | | name | string | Yes | Name of the album to create. |
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[PrivateAlbum](#privatealbum)&gt;&gt; | Yes | Callback invoked to return the album obtained.| | callback | AsyncCallback&lt;[Album](#album)&gt; | Yes | Callback invoked to return the created album instance.|
**Example** **Example**
```ts ```ts
async function example() { async function example() {
console.info('getPrivateAlbumDemo'); console.info('createAlbumDemo');
mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH, async (err, fetchResult) => { let albumName = 'newAlbumName' + new Date().getTime();
if (fetchResult != undefined) { mgr.createAlbum(albumName, (err, album) => {
let trashAlbum = await fetchResult.getFirstObject(); if (err) {
console.info('first album.albumName = ' + trashAlbum.albumName); console.error('createAlbumCallback failed with err: ' + err);
} else { return;
console.error('getPrivateAlbum failed. message = ', err);
} }
console.info('createAlbumCallback successfully, album: ' + album.albumName + ' album uri: ' + album.albumUri);
}); });
} }
``` ```
### getPrivateAlbum ### createAlbum<sup>10+</sup>
getPrivateAlbum(type: PrivateAlbumType): Promise&lt;FetchResult&lt;PrivateAlbum&gt;&gt;; createAlbum(name: string): Promise&lt;Album&gt;;
Creates an album. This API uses a promise to return the result.
Obtains the system 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:<br>.. \ / : * ? " ' ` < > | { } [ ]
- The album name is case-insensitive.
- Duplicate album names are not allowed.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO **Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- | | -------- | ------------------------ | ---- | ------------------------- |
| type | [PrivateAlbumType](#privatealbumtype) | Yes | Type of the album to obtain. | | name | string | Yes | Name of the album to create. |
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------------- | -------------- | | --------------------------- | -------------- |
| Promise&lt;[FetchResult](#fetchresult)&lt;[PrivateAlbum](#privatealbum)&gt;&gt; | Promise used to return the album obtained.| | Promise&lt;[Album](#album)&gt; | Promise used to return the created album instance.|
**Example** **Example**
```ts ```ts
async function example() { async function example() {
console.info('getPrivateAlbumDemo'); console.info('createAlbumDemo');
try { let albumName = 'newAlbumName' + new Date().getTime();
let fetchResult = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH); mgr.createAlbum(albumName).then((album) => {
let trashAlbum = await fetchResult.getFirstObject(); console.info('createAlbumPromise successfully, album: ' + album.albumName + ' album uri: ' + album.albumUri);
console.info('first album.albumName = ' + trashAlbum.albumName); }).catch((err) => {
} catch (err) { console.error('createAlbumPromise failed with err: ' + err);
console.error('getPrivateAlbum failed. message = ', err); });
}
} }
``` ```
### getAudioAssets ### deleteAlbums<sup>10+</sup>
getAudioAssets(options: FetchOptions, callback: AsyncCallback&lt;FetchResult&lt;FileAsset&gt;&gt;): void; deleteAlbums(albums: Array&lt;Album&gt;, callback: AsyncCallback&lt;void&gt;): void;
Obtains audio assets. This API uses an asynchronous callback to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_AUDIO **Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- | | -------- | ------------------------ | ---- | ------------------------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the audio assets. | | albums | Array&lt;[Album](#album)&gt; | Yes | Albums to delete. |
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | Yes | Callback invoked to return the audio assets obtained.| | callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.|
**Example** **Example**
...@@ -438,48 +694,50 @@ Obtains audio assets. This API uses an asynchronous callback to return the resul ...@@ -438,48 +694,50 @@ Obtains audio assets. This API uses an asynchronous callback to return the resul
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getAudioAssets'); // Delete the album named newAlbumName.
console.info('deleteAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo('album_name', 'newAlbumName');
let fetchOptions = { let fetchOptions = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions);
mgr.getAudioAssets(fetchOptions, async (err, fetchResult) => { let album = await fetchResult.getFirstObject();
if (fetchResult != undefined) { mgr.deleteAlbums([album], (err) => {
console.info('fetchFileResult success'); if (err) {
let fileAsset = await fetchResult.getFirstObject(); console.error('deletePhotoAlbumsCallback failed with err: ' + err);
if (fileAsset != undefined) { return;
console.info("fileAsset.displayName :" + fileAsset.displayName);
}
} else {
console.error('fetchFileResult fail' + err);
} }
console.info('deletePhotoAlbumsCallback successfully');
}); });
fetchResult.close();
} }
``` ```
### getAudioAssets ### deleteAlbums<sup>10+</sup>
getAudioAssets(options: FetchOptions): Promise&lt;FetchResult&lt;FileAsset&gt;&gt;; deleteAlbums(albums: Array&lt;Album&gt;): Promise&lt;void&gt;;
Obtains audio assets. This API uses a promise to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_AUDIO **Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ------------------------- | | -------- | ------------------------ | ---- | ------------------------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the audio assets. | | albums | Array&lt;[Album](#album)&gt; | Yes | Albums to delete. |
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------------- | -------------- | | --------------------------- | -------------- |
| Promise&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | Promise used to return the audio assets obtained.| | Promise&lt;void&gt; | Promise that returns no value.|
**Example** **Example**
...@@ -487,44 +745,53 @@ Obtains audio assets. This API uses a promise to return the result. ...@@ -487,44 +745,53 @@ Obtains audio assets. This API uses a promise to return the result.
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getAudioAssets'); // Delete the album named newAlbumName.
console.info('deleteAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo('album_name', 'newAlbumName');
let fetchOptions = { let fetchOptions = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
try { let fetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions);
var fetchResult = await mgr.getAudioAssets(fetchOptions); let album = await fetchResult.getFirstObject();
} catch (err) { mgr.deleteAlbums([album]).then(() => {
console.error('getAudioAssets failed, message = ', err); console.info('deletePhotoAlbumsPromise successfully');
} }).catch((err) => {
console.error('deletePhotoAlbumsPromise failed with err: ' + err);
if (fetchResult != undefined) { });
console.info('fetchFileResult success'); fetchResult.close();
let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) {
console.info("fileAsset.displayName :" + fileAsset.displayName);
}
}
} }
``` ```
### delete ### getAlbums<sup>10+</sup>
delete(uri: string, callback: AsyncCallback&lt;void&gt;): void; getAlbums(type: AlbumType, subType: AlbumSubType, options: FetchOptions, callback: AsyncCallback&lt;FetchResult&lt;Album&gt;&gt;): void;
Deletes a media file. This API uses an asynchronous callback to return the result. The deleted file is moved to the recycle bin. Obtain albums based on the specified options and album type. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO Before the operation, ensure that the albums to obtain exist.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- | | -------- | ------------------------ | ---- | ------------------------- |
| uri | string | Yes | URI of the media file to delete.| | type | [AlbumType](#albumtype10) | Yes | Type of the album to obtain. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.| | subType | [AlbumSubType](#albumsubtype10) | Yes | Subtype of the album. |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the albums. |
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[Album](#album)&gt;&gt; | 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** **Example**
...@@ -532,54 +799,113 @@ Deletes a media file. This API uses an asynchronous callback to return the resul ...@@ -532,54 +799,113 @@ Deletes a media file. This API uses an asynchronous callback to return the resul
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('deleteAssetDemo'); // Obtain the album named newAlbumName.
console.info('getAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo('album_name', 'newAlbumName');
let fetchOptions = { let fetchOptions = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
try { mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions, async (err, fetchResult) => {
const fetchResult = await mgr.getPhotoAssets(fetchOptions); if (err) {
var asset = await fetchResult.getFirstObject(); console.error('getAlbumsCallback failed with err: ' + err);
} catch (err) { return;
console.info('fetch failed, message =', err); }
} if (fetchResult == undefined) {
console.error('getAlbumsCallback fetchResult is undefined');
if (asset == undefined) { return;
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);
} }
let album = await fetchResult.getFirstObject();
console.info('getAlbumsCallback successfully, albumName: ' + album.albumName);
fetchResult.close();
}); });
} }
``` ```
### delete ### getAlbums<sup>10+</sup>
delete(uri: string): Promise&lt;void&gt;; getAlbums(type: AlbumType, subType: AlbumSubType, callback: AsyncCallback&lt;FetchResult&lt;Album&gt;&gt;): void;
Deletes a media file. This API uses a promise to return the result. The deleted file is moved to the recycle bin. Obtains albums by type. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO Before the operation, ensure that the albums to obtain exist.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- | | -------- | ------------------------ | ---- | ------------------------- |
| uri | string | Yes | URI of the media file to delete.| | type | [AlbumType](#albumtype10) | Yes | Type of the album to obtain. |
| subType | [AlbumSubType](#albumsubtype10) | Yes | Subtype of the album. |
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[Album](#album)&gt;&gt; | 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();
});
}
```
### getAlbums<sup>10+</sup>
getAlbums(type: AlbumType, subType: AlbumSubType, options?: FetchOptions): Promise&lt;FetchResult&lt;Album&gt;&gt;;
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** **Return value**
| Type | Description | | Type | Description |
| --------------------------------------- | ----------------- | | --------------------------- | -------------- |
| Promise&lt;void&gt;| Promise that returns no value.| | Promise&lt;[FetchResult](#fetchresult)&lt;[Album](#album)&gt;&gt; | 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** **Example**
...@@ -587,211 +913,528 @@ Deletes a media file. This API uses a promise to return the result. The deleted ...@@ -587,211 +913,528 @@ Deletes a media file. This API uses a promise to return the result. The deleted
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('deleteDemo'); // Obtain the album named newAlbumName.
console.info('getAlbumsDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo('album_name', 'newAlbumName');
let fetchOptions = { let fetchOptions = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
try { mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC, fetchOptions).then( async (fetchResult) => {
const fetchResult = await mgr.getPhotoAssets(fetchOptions); if (fetchResult == undefined) {
var asset = await fetchResult.getFirstObject(); console.error('getAlbumsPromise fetchResult is undefined');
} catch (err) { return;
console.info('fetch failed, message =', err); }
} let album = await fetchResult.getFirstObject();
console.info('getAlbumsPromise successfully, albumName: ' + album.albumName);
if (asset == undefined) { fetchResult.close();
console.error('asset not exist'); }).catch((err) => {
return; console.error('getAlbumsPromise failed with err: ' + err);
} });
try {
await mgr.delete(asset.uri);
console.info("delete successfully");
} catch (err) {
console.error("delete failed with error: " + err);
}
} }
``` ```
### on ### getPrivateAlbum
on(type: ChangeEvent, callback: Callback&lt;void&gt;): void getPrivateAlbum(type: PrivateAlbumType, callback: AsyncCallback&lt;FetchResult&lt;PrivateAlbum&gt;&gt;): void;
Subscribes to changes of the file management library. This API uses a callback to return the result. Obtains the system album. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ | | -------- | ------------------------ | ---- | ------------------------- |
| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.<br>**deviceChange** indicates the device change.<br>**albumChange** indicates the album change.<br>**imageChange** indicates the image change.<br>**audioChange** indicates the audio file change.<br>**videoChange** indicates the video file change.<br>**remoteFileChange** indicates the file change on the registered device.| | type | [PrivateAlbumType](#privatealbumtype) | Yes | Type of the system album to obtain. |
| callback | Callback&lt;void&gt; | Yes | Callback that returns no value. | | callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[PrivateAlbum](#privatealbum)&gt;&gt; | 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** **Example**
```ts ```ts
async function example() { async function example() {
console.info('onDemo'); console.info('getPrivateAlbumDemo');
let count = 0; mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH, async (err, fetchResult) => {
mgr.on('imageChange', () => { if (fetchResult != undefined) {
count++; let trashAlbum = await fetchResult.getFirstObject();
// Image file changed. Do something. console.info('first album.albumName = ' + trashAlbum.albumName);
}); } else {
try { console.error('getPrivateAlbum failed. message = ', err);
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 ### getPrivateAlbum
off(type: ChangeEvent, callback?: Callback&lt;void&gt;): void getPrivateAlbum(type: PrivateAlbumType): Promise&lt;FetchResult&lt;PrivateAlbum&gt;&gt;;
Unsubscribes from changes of the file management library. This API uses a callback to return the result. Obtains the system album. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ | | -------- | ------------------------ | ---- | ------------------------- |
| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.<br>**deviceChange** indicates the device change.<br>**albumChange** indicates the album change.<br>**imageChange** indicates the image change.<br>**audioChange** indicates the audio file change.<br>**videoChange** indicates the video file change.<br>**remoteFileChange** indicates the file change on the registered device.| | type | [PrivateAlbumType](#privatealbumtype) | Yes | Type of the system album to obtain. |
| callback | Callback&lt;void&gt; | No | Callback that returns no value. |
**Return value**
| Type | Description |
| --------------------------- | -------------- |
| Promise&lt;[FetchResult](#fetchresult)&lt;[PrivateAlbum](#privatealbum)&gt;&gt; | 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** **Example**
```ts ```ts
async function example() { async function example() {
console.info('offDemo'); console.info('getPrivateAlbumDemo');
let count = 0;
mgr.on('imageChange', () => {
count++;
// Image file changed. Do something.
});
mgr.off('imageChange', () => {
// Unsubscription succeeds.
});
try { try {
let testFileName = "testFile" + Date.now() + ".jpg"; let fetchResult = await mgr.getPrivateAlbum(userFileManager.PrivateAlbumType.TYPE_TRASH);
let fileAsset = await mgr.createPhotoAsset(testFileName); let trashAlbum = await fetchResult.getFirstObject();
console.info('createPhotoAsset file displayName' + fileAsset.displayName); console.info('first album.albumName = ' + trashAlbum.albumName);
console.info('createPhotoAsset successfully');
} catch (err) { } catch (err) {
console.error('createPhotoAsset failed, message = ' + err); console.error('getPrivateAlbum failed. message = ', err);
}
//sleep 1s
if (count == 0) {
console.info("offDemo success");
} else {
console.error("offDemo fail");
} }
} }
``` ```
### getActivePeers ### getAudioAssets
getActivePeers(callback: AsyncCallback&lt;Array&lt;PeerInfo&gt;&gt;): void; getAudioAssets(options: FetchOptions, callback: AsyncCallback&lt;FetchResult&lt;FileAsset&gt;&gt;): void;
Obtains information about online peer devices. This API uses an asynchronous callback to return the result. Obtains audio assets. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.DistributedCore **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_AUDIO
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------------- | ---- | ------------ | | -------- | ------------------------ | ---- | ------------------------- |
| callback | AsyncCallback&lt;Array&lt;[PeerInfo](#peerinfo)&gt;&gt; | Yes | Callback invoked to return the online peer device list.| | options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the audio assets. |
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | 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** **Example**
```ts ```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getActivePeersDemo'); console.info('getAudioAssets');
mgr.getActivePeers((err, devicesInfo) => { let predicates = new dataSharePredicates.DataSharePredicates();
if (devicesInfo != undefined) { let fetchOptions = {
console.log('getActivePeers succeed.'); fetchColumns: [],
for (let i = 0; i < devicesInfo.length; i++) { predicates: predicates
console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId); };
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 { } else {
console.error('getActivePeers failed. message = ', err); console.error('fetchFileResult fail' + err);
} }
}); });
} }
``` ```
### getActivePeers ### getAudioAssets
getActivePeers(): Promise&lt;Array&lt;PeerInfo&gt;&gt;; getAudioAssets(options: FetchOptions): Promise&lt;FetchResult&lt;FileAsset&gt;&gt;;
Obtains information about online peer devices. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.DistributedCore 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** **Return value**
| Type | Description | | Type | Description |
| --------------------------- | ----------------------------- | | --------------------------- | -------------- |
| Promise&lt;Array&lt;[PeerInfo](#peerinfo)&gt;&gt; | Promise used to return the online device list.| | Promise&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | 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** **Example**
```ts ```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getActivePeersDemo'); console.info('getAudioAssets');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOptions = {
fetchColumns: [],
predicates: predicates
};
try { try {
var devicesInfo = await mgr.getActivePeers(); var fetchResult = await mgr.getAudioAssets(fetchOptions);
} catch (err) { } catch (err) {
console.error('getActivePeers failed. message = ', err); console.error('getAudioAssets failed, message = ', err);
} }
if (devicesInfo != undefined) {
console.log('getActivePeers succeed.'); if (fetchResult != undefined) {
for (let i = 0; i < devicesInfo.length; i++) { console.info('fetchFileResult success');
console.info('get distributed info ' + devicesInfo[i].deviceName + devicesInfo[i].networkId); let fileAsset = await fetchResult.getFirstObject();
if (fileAsset != undefined) {
console.info('fileAsset.displayName :' + fileAsset.displayName);
} }
} else {
console.error('get distributed fail');
} }
} }
``` ```
### getAllPeers ### delete
getAllPeers(callback: AsyncCallback&lt;Array&lt;PeerInfo&gt;&gt;): void; delete(uri: string, callback: AsyncCallback&lt;void&gt;): void;
Obtains information about all peer devices. This API uses an asynchronous callback to return the result. Deletes a media file. This API uses an asynchronous callback to return the result. The deleted file is moved to the recycle bin.
**System capability**: SystemCapability.FileManagement.UserFileManager.DistributedCore **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** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------------- | ---- | ------------ | | -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback&lt;Array&lt;[PeerInfo](#peerinfo)&gt;&gt; | Yes | Callback invoked to return the online peer device list.| | uri | string | Yes | URI of the media file.|
| callback | AsyncCallback&lt;void&gt; | 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** **Example**
```ts ```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getAllPeersDemo'); console.info('deleteAssetDemo');
mgr.getAllPeers((err, devicesInfo) => { 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&lt;void&gt;;
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&lt;void&gt;| 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);
}
}
```
### on
on(type: ChangeEvent, callback: Callback&lt;void&gt;): void
Subscribes to changes of the file management library. This API uses a callback to return the result.
This API will be deprecated. Use [on<sup>10+</sup>](#on10) instead.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.<br>**deviceChange** indicates the device change.<br>**albumChange** indicates the album change.<br>**imageChange** indicates the image change.<br>**audioChange** indicates the audio file change.<br>**videoChange** indicates the video file change.<br>**remoteFileChange** indicates the file change on the registered device.|
| callback | Callback&lt;void&gt; | 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&lt;void&gt;): void
Unsubscribes from changes of the file management library. This API uses a callback to return the result.
This API will be deprecated. Use [off<sup>10+</sup>](#off10) instead.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.<br>**deviceChange** indicates the device change.<br>**albumChange** indicates the album change.<br>**imageChange** indicates the image change.<br>**audioChange** indicates the audio file change.<br>**videoChange** indicates the video file change.<br>**remoteFileChange** indicates the change of the file on a registered device.|
| callback | Callback&lt;void&gt; | 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');
}
}
```
### getActivePeers
getActivePeers(callback: AsyncCallback&lt;Array&lt;PeerInfo&gt;&gt;): 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&lt;Array&lt;[PeerInfo](#peerinfo)&gt;&gt; | 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&lt;Array&lt;PeerInfo&gt;&gt;;
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&lt;Array&lt;[PeerInfo](#peerinfo)&gt;&gt; | 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&lt;Array&lt;PeerInfo&gt;&gt;): 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&lt;Array&lt;[PeerInfo](#peerinfo)&gt;&gt; | Yes | Callback invoked to return the information obtained.|
**Example**
```ts
async function example() {
console.info('getAllPeersDemo');
mgr.getAllPeers((err, devicesInfo) => {
if (devicesInfo != undefined) { if (devicesInfo != undefined) {
console.log('getAllPeers succeed.'); console.log('getAllPeers succeed.');
for (let i = 0; i < devicesInfo.length; i++) { for (let i = 0; i < devicesInfo.length; i++) {
...@@ -816,7 +1459,7 @@ Obtains information about all peer devices. This API uses a promise to return th ...@@ -816,7 +1459,7 @@ Obtains information about all peer devices. This API uses a promise to return th
| Type | Description | | Type | Description |
| --------------------------- | ----------------------------- | | --------------------------- | ----------------------------- |
| Promise&lt;Array&lt;[PeerInfo](#peerinfo)&gt;&gt; | Promise used to return the peer device list.| | Promise&lt;Array&lt;[PeerInfo](#peerinfo)&gt;&gt; | Promise used to return the information obtained.|
**Example** **Example**
...@@ -852,7 +1495,7 @@ Call this API when the APIs in the **UserFileManager** instance are no longer us ...@@ -852,7 +1495,7 @@ Call this API when the APIs in the **UserFileManager** instance are no longer us
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | -------------------- | | -------- | ------------------------- | ---- | -------------------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.| | callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result.|
**Example** **Example**
...@@ -898,20 +1541,145 @@ async function example() { ...@@ -898,20 +1541,145 @@ async function example() {
} }
``` ```
## FileAsset ### on<sup>10+</sup>
Provides APIs for encapsulating file asset attributes. on(uri: string, forSubUri: boolean, callback: Callback&lt;ChangeData&gt;) : void
### Attributes Enables listening for the specified URI. This API uses a callback to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Readable| Writable| Description | **Parameters**
| ------------------------- | ------------------------ | ---- | ---- | ------------------------------------------------------ |
| uri | string | Yes | No | File asset URI, for example, **dataability:///media/image/2**. | | Name | Type | Mandatory| Description |
| fileType | [FileType](#filetype) | Yes | No | Type of the file. | | --------- | ------------------------------------------- | ---- | ------------------------------------------------------------ |
| displayName | string | Yes | Yes | File name, including the file name extension, to display. | | uri | string | Yes | URI of the file asset or album, or [DefaultChangeUri](#defaultchangeuri10).|
| forSubUri | boolean | Yes | Whether to perform fuzzy listening.<br>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. <br>If **uri** is the URI of a file asset, there is no difference between **true** and **false** for **forSubUri**.<br>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&lt;[ChangeData](#changedata10)&gt; | Yes | Callback invoked to return [ChangeData](#changedata10). <br>**NOTE**: Different callbacks can be registered for a URI. You can use [off<sup>10+</sup>](#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);
}
});
}
```
### off<sup>10+</sup>
off(uri: string, callback?: Callback&lt;ChangeData&gt;): void
Disables listening for the specified URI. Multiple callbacks can be registered for a URI for listening. You can use **off()** to disable the listening of 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&lt;[ChangeData](#changedata10)&gt; | No | Callback registered by [on<sup>10+</sup>](#on10). If this parameter is not specified, all callbacks registered for the URI will be unregistered. <br>**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);
}
});
}
```
## 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/image/2**. |
| fileType | [FileType](#filetype) | Yes | No | Type of the file. |
| displayName | string | Yes | Yes | File name, including the file name extension, to display. |
### get ### get
...@@ -925,7 +1693,7 @@ Obtains the value of a **FileAsset** parameter. ...@@ -925,7 +1693,7 @@ Obtains the value of a **FileAsset** parameter.
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | ------------------------- | ---- | ----- | | -------- | ------------------------- | ---- | ----- |
| member | string | Yes | Name of the parameter to obtain, for example, **ImageVideoKey.URI**.| | member | string | Yes | Name of the parameter, for example, **ImageVideoKey.URI**.|
**Example** **Example**
...@@ -937,7 +1705,7 @@ async function example() { ...@@ -937,7 +1705,7 @@ async function example() {
try { try {
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: ['title'],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fetchResult = await mgr.getPhotoAssets(fetchOption);
...@@ -951,20 +1719,497 @@ async function example() { ...@@ -951,20 +1719,497 @@ async function example() {
} }
``` ```
### set ### 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&lt;void&gt;): 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&lt;void&gt; | 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&lt;void&gt;
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&lt;void&gt; | 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&lt;number&gt;): void
Opens this file asset. This API uses an asynchronous callback to return the result.
**NOTE**<br>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&lt;number&gt; | 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&lt;number&gt;
Opens this file asset. This API uses a promise to return the result.
**NOTE**<br>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&lt;number&gt; | 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&lt;void&gt;): 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&lt;void&gt; | 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&lt;void&gt;
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&lt;void&gt; | 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&lt;image.PixelMap&gt;): 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&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | 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&lt;image.PixelMap&gt;): 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&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | 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&lt;image.PixelMap&gt;
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&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | 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&lt;void&gt;): 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&lt;void&gt; | 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
set(member: string, value: string): void; favorite(isFavorite: boolean): Promise&lt;void&gt;
Sets a **FileAsset** parameter. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | ------------------------- | ---- | ----- | | ---------- | ------- | ---- | ---------------------------------- |
| member | string | Yes | Name of the parameter to set, for example, **ImageVideoKey.URI**.| | isFavorite | boolean | Yes | Operation to perform. The value **true** means to favorite the file asset, and **false** means the opposite.|
| value | string | Yes | Value to set. Only the value of **ImageVideoKey.TITLE** can be changed.|
**Return value**
| Type | Description |
| ------------------- | ---------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Example** **Example**
...@@ -972,38 +2217,49 @@ Sets a **FileAsset** parameter. ...@@ -972,38 +2217,49 @@ Sets a **FileAsset** parameter.
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('fileAssetSetDemo'); console.info('favoriteDemo');
try { let predicates = new dataSharePredicates.DataSharePredicates();
let predicates = new dataSharePredicates.DataSharePredicates(); let fetchOption = {
let fetchOption = { fetchColumns: [],
fetchColumns: [], predicates: predicates
predicates: predicates };
}; let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fetchResult = await mgr.getPhotoAssets(fetchOption); const asset = await fetchResult.getFirstObject();
let fileAsset = await fetchResult.getFirstObject(); asset.favorite(true).then(function () {
let title = userFileManager.ImageVideoKey.TITLE; console.info('favorite successfully');
fileAsset.set(title.toString(), "newTitle"); }).catch(function (err) {
} catch (err) { console.error('favorite failed with error:' + err);
console.error('release failed. message = ', err); });
}
} }
``` ```
### commitModify ### setHidden<sup>10+</sup>
commitModify(callback: AsyncCallback&lt;void&gt;): void setHidden(hiddenState: boolean, callback: AsyncCallback&lt;void&gt;): void
Commits the modification on the file metadata to the database. This API uses an asynchronous callback to return the result. Sets this file asset to hidden state. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | ------------------------- | ---- | ----- | | ---------- | ------------------------- | ---- | ---------------------------------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.| | 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&lt;void&gt; | 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** **Example**
...@@ -1011,169 +2267,198 @@ Commits the modification on the file metadata to the database. This API uses an ...@@ -1011,169 +2267,198 @@ Commits the modification on the file metadata to the database. This API uses an
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('commitModifyDemo'); console.info('setHiddenDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fileAsset = await fetchResult.getFirstObject(); const asset = await fetchResult.getFirstObject();
let title = userFileManager.ImageVideoKey.TITLE; asset.setHidden(true, (err) => {
let fileAssetTitle = fileAsset.get(title.toString());
console.info('fileAsset Get fileAssetTitle = ', fileAssetTitle);
fileAsset.set(title.toString(), "newTitle");
fileAsset.commitModify((err) => {
if (err == undefined) { if (err == undefined) {
let newFileAssetTitle = fileAsset.get(title.toString()); console.info('setHidden successfully');
console.info('fileAsset Get newFileAssetTitle = ', newFileAssetTitle);
} else { } else {
console.error('commitModify failed, message =', err); console.error('setHidden failed with error:' + err);
} }
}); });
} }
``` ```
### commitModify ### setHidden<sup>10+</sup>
commitModify(): Promise&lt;void&gt; setHidden(hiddenState: boolean): Promise&lt;void&gt;
Commits the modification on the file metadata to the database. This API uses a promise to return the result. Sets this file asset to hidden state. This API uses a promise to return the result.
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO 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 **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** **Return value**
| Type | Description | | Type | Description |
| ------------------- | ---------- | | ------------------- | ---------- |
| Promise&lt;void&gt; | Promise that returns no value.| | Promise&lt;void&gt; | Promise that returns no value.|
**Example** **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 ```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('commitModifyDemo'); // 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 predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let albumList = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.HIDDEN);
let fileAsset = await fetchResult.getFirstObject(); const album = await albumList.getFirstObject();
let title = userFileManager.ImageVideoKey.TITLE; let fetchResult = await album.getPhotoAssets(fetchOption);
let fileAssetTitle = fileAsset.get(title.toString()); const asset = await fetchResult.getFirstObject();
console.info('fileAsset Get fileAssetTitle = ', fileAssetTitle); asset.setHidden(false).then(() => {
fileAsset.set(title.toString(), "newTitle"); console.info('setHidden successfully');
try { }).catch((err) => {
await fileAsset.commitModify(); console.error('setHidden failed with error:' + err);
let newFileAssetTitle = fileAsset.get(title.toString()); });
console.info('fileAsset Get newFileAssetTitle = ', newFileAssetTitle);
} catch (err) {
console.error('release failed. message = ', err);
}
} }
``` ```
### open ## FetchResult
open(mode: string, callback: AsyncCallback&lt;number&gt;): void Provides APIs to manage the file retrieval result.
Opens this file asset. This API uses an asynchronous callback to return the result. ### getCount
**NOTE**<br>The write operations are mutually exclusive. After a write operation is complete, you must call **close** to release the resource. getCount(): number
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.READ_AUDIO, ohos.permission.WRITE_IMAGEVIDEO, or ohos.permission.WRITE_AUDIO Obtains the total number of files in the result set.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Return value**
| Name | Type | Mandatory | Description | | Type | Description |
| -------- | --------------------------- | ---- | ----------------------------------- | | ------ | -------- |
| mode | string | Yes | File open mode, which can be **r** (read-only), **w** (write-only), or **rw** (read-write).| | number | Returns the total number of files obtained.|
| callback | AsyncCallback&lt;number&gt; | Yes | Callback invoked to return the file descriptor. |
**Example** **Example**
```ts ```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('openDemo'); console.info('getCountDemo');
let testFileName = "testFile" + Date.now() + ".jpg"; let predicates = new dataSharePredicates.DataSharePredicates();
const fileAsset = await mgr.createPhotoAsset(testFileName); let fetchOption = {
fileAsset.open('rw', (err, fd) => { fetchColumns: [],
if (fd != undefined) { predicates: predicates
console.info('File fd' + fd); };
fileAsset.close(fd); let fetchResult = await mgr.getPhotoAssets(fetchOption);
} else { const fetchCount = fetchResult.getCount();
console.error('File err' + err); console.info('fetchCount = ', fetchCount);
}
});
} }
``` ```
### open ### isAfterLast
open(mode: string): Promise&lt;number&gt; isAfterLast(): boolean
Opens this file asset. This API uses a promise to return the result. Checks whether the cursor is in the last row of the result set.
**NOTE**<br>The write operations are mutually exclusive. After a write operation is complete, you must call **close** to release the resource. **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.READ_AUDIO, ohos.permission.WRITE_IMAGEVIDEO, or ohos.permission.WRITE_AUDIO **Return value**
**System capability**: SystemCapability.FileManagement.UserFileManager.Core | Type | Description |
| ------- | ---------------------------------- |
| boolean | Returns **true** if the cursor is in the last row of the result set; returns **false** otherwise.|
**Parameters** **Example**
| Name | Type | Mandatory | Description | ```ts
| ---- | ------ | ---- | ----------------------------------- | import dataSharePredicates from '@ohos.data.dataSharePredicates';
| mode | string | Yes | File open mode, which can be **r** (read-only), **w** (write-only), or **rw** (read-write).|
**Return value** 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 ');
}
}
```
| Type | Description | ### close
| --------------------- | ------------- |
| Promise&lt;number&gt; | Promise used to return the file descriptor.| 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** **Example**
```ts ```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('openDemo'); console.info('fetchResultCloseDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = {
fetchColumns: [],
predicates: predicates
};
try { try {
let testFileName = "testFile" + Date.now() + ".jpg"; let fetchResult = await mgr.getPhotoAssets(fetchOption);
const fileAsset = await mgr.createPhotoAsset(testFileName); await fetchResult.close();
let fd = await fileAsset.open('rw'); console.info('close succeed.');
if (fd != undefined) {
console.info('File fd' + fd);
fileAsset.close(fd);
} else {
console.error(' open File fail');
}
} catch (err) { } catch (err) {
console.error('open Demo err' + err); console.error('close fail. message = ' + err);
} }
} }
``` ```
### close ### getFirstObject
close(fd: number, callback: AsyncCallback&lt;void&gt;): void getFirstObject(callback: AsyncCallback&lt;T&gt;): void
Closes this file asset. This API uses an asynchronous callback to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ----- | | -------- | --------------------------------------------- | ---- | ------------------------------------------- |
| fd | number | Yes | File descriptor.| | callback | AsyncCallback&lt;T&gt; | Yes | Callback invoked to return the first file asset.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.|
**Example** **Example**
...@@ -1181,49 +2466,36 @@ Closes this file asset. This API uses an asynchronous callback to return the res ...@@ -1181,49 +2466,36 @@ Closes this file asset. This API uses an asynchronous callback to return the res
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('closeDemo'); console.info('getFirstObjectDemo');
try { let predicates = new dataSharePredicates.DataSharePredicates();
let predicates = new dataSharePredicates.DataSharePredicates(); let fetchOption = {
let fetchOption = { fetchColumns: [],
fetchColumns: [], predicates: predicates
predicates: predicates };
}; let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fetchResult = await mgr.getPhotoAssets(fetchOption); fetchResult.getFirstObject((err, fileAsset) => {
const fileAsset = await fetchResult.getFirstObject(); if (fileAsset != undefined) {
let fd = await fileAsset.open('rw'); console.info('fileAsset displayName: ', fileAsset.displayName);
console.info('file fd', fd); } else {
fileAsset.close(fd, (err) => { console.error('fileAsset failed with err:' + 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 ### getFirstObject
close(fd: number): Promise&lt;void&gt; getFirstObject(): Promise&lt;T&gt;
Closes this file asset. This API uses a promise to return the result. Obtains the first file asset in the result set. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory | Description |
| ---- | ------ | ---- | ----- |
| fd | number | Yes | File descriptor.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------------------- | ---------- | | --------------------------------------- | -------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.| | Promise&lt;T&gt; | Promise used to return the first object in the result set.|
**Example** **Example**
...@@ -1231,40 +2503,31 @@ Closes this file asset. This API uses a promise to return the result. ...@@ -1231,40 +2503,31 @@ Closes this file asset. This API uses a promise to return the result.
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('closeDemo'); console.info('getFirstObjectDemo');
try { let predicates = new dataSharePredicates.DataSharePredicates();
let predicates = new dataSharePredicates.DataSharePredicates(); let fetchOption = {
let fetchOption = { fetchColumns: [],
fetchColumns: [], predicates: predicates
predicates: predicates };
}; let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fileAsset = await fetchResult.getFirstObject();
const asset = await fetchResult.getFirstObject(); console.info('fileAsset displayName: ', fileAsset.displayName);
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 ### getNextObject
getThumbnail(callback: AsyncCallback&lt;image.PixelMap&gt;): void
Obtains the thumbnail of this file asset. This API uses an asynchronous callback to return the result. getNextObject(callback: AsyncCallback&lt;T&gt;): void
**Required permissions**: ohos.permission.READ_IMAGEVIDEO or ohos.permission.READ_AUDIO 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| -------- | ----------------------------------- | ---- | ---------------- | | --------- | --------------------------------------------- | ---- | ----------------------------------------- |
| callback | AsyncCallback&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | Yes | Callback invoked to return the pixel map of the thumbnail.| | callbacke | AsyncCallback&lt;T&gt; | Yes | Callback invoked to return the next file asset.|
**Example** **Example**
...@@ -1272,41 +2535,39 @@ Obtains the thumbnail of this file asset. This API uses an asynchronous callback ...@@ -1272,41 +2535,39 @@ Obtains the thumbnail of this file asset. This API uses an asynchronous callback
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getThumbnailDemo'); console.info('getNextObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject(); await fetchResult.getFirstObject();
console.info('asset displayName = ', asset.displayName); if (fetchResult.isAfterLast()) {
asset.getThumbnail((err, pixelMap) => { fetchResult.getNextObject((err, fileAsset) => {
if (err == undefined) { if (fileAsset != undefined) {
console.info('getThumbnail successful ' + pixelMap); console.info('fileAsset displayName: ', fileAsset.displayName);
} else { } else {
console.error('getThumbnail fail', err); console.error('fileAsset failed with err: ' + err);
} }
}); });
}
} }
``` ```
### getThumbnail ### getNextObject
getThumbnail(size: image.Size, callback: AsyncCallback&lt;image.PixelMap&gt;): void
Obtains the file thumbnail of the given size. This API uses an asynchronous callback to return the result. getNextObject(): Promise&lt;T&gt;
**Required permissions**: ohos.permission.READ_IMAGEVIDEO or ohos.permission.READ_AUDIO Obtains the next file asset in the result set. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Return value**
| Name | Type | Mandatory | Description | | Type | Description |
| -------- | ----------------------------------- | ---- | ---------------- | | --------------------------------------- | ----------------- |
| size | [image.Size](js-apis-image.md#size) | Yes | Size of the thumbnail to obtain. | | Promise&lt;T&gt; | Promise used to return the next object in the result set.|
| callback | AsyncCallback&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | Yes | Callback invoked to return the pixel map of the thumbnail.|
**Example** **Example**
...@@ -1314,47 +2575,34 @@ Obtains the file thumbnail of the given size. This API uses an asynchronous call ...@@ -1314,47 +2575,34 @@ Obtains the file thumbnail of the given size. This API uses an asynchronous call
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getThumbnailDemo'); console.info('getNextObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let size = { width: 720, height: 720 };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject(); await fetchResult.getFirstObject();
console.info('asset displayName = ', asset.displayName); if (fetchResult.isAfterLast()) {
asset.getThumbnail(size, (err, pixelMap) => { let fileAsset = await fetchResult.getNextObject();
if (err == undefined) { console.info('fileAsset displayName: ', fileAsset.displayName);
console.info('getThumbnail successful ' + pixelMap); }
} else {
console.error('getThumbnail fail', err);
}
});
} }
``` ```
### getThumbnail ### getLastObject
getThumbnail(size?: image.Size): Promise&lt;image.PixelMap&gt;
Obtains the file thumbnail of the given size. This API uses a promise to return the result. getLastObject(callback: AsyncCallback&lt;T&gt;): void
**Required permissions**: ohos.permission.READ_IMAGEVIDEO or ohos.permission.READ_AUDIO 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| ---- | -------------- | ---- | ----- | | -------- | --------------------------------------------- | ---- | --------------------------- |
| size | [image.Size](js-apis-image.md#size) | No | Size of the thumbnail to obtain.| | callback | AsyncCallback&lt;T&gt; | Yes | Callback invoked to return the last file asset obtained.|
**Return value**
| Type | Description |
| ----------------------------- | --------------------- |
| Promise&lt;[image.PixelMap](js-apis-image.md#pixelmap7)&gt; | Promise used to return the pixel map of the thumbnail.|
**Example** **Example**
...@@ -1362,40 +2610,36 @@ Obtains the file thumbnail of the given size. This API uses a promise to return ...@@ -1362,40 +2610,36 @@ Obtains the file thumbnail of the given size. This API uses a promise to return
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getThumbnailDemo'); console.info('getLastObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let size = { width: 720, height: 720 };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject(); fetchResult.getLastObject((err, fileAsset) => {
console.info('asset displayName = ', asset.displayName); if (fileAsset != undefined) {
asset.getThumbnail(size).then((pixelMap) => { console.info('fileAsset displayName: ', fileAsset.displayName);
console.info('getThumbnail successful ' + pixelMap); } else {
}).catch((err) => { console.error('fileAsset failed with err: ' + err);
console.error('getThumbnail fail' + err); }
}); });
} }
``` ```
### favorite ### getLastObject
favorite(isFavorite: boolean, callback: AsyncCallback&lt;void&gt;): void
Favorites or unfavorites this file asset. This API uses an asynchronous callback to return the result. getLastObject(): Promise&lt;T&gt;
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO Obtains the last file asset in the result set. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Return value**
| Name | Type | Mandatory | Description | | Type | Description |
| ---------- | ------------------------- | ---- | ---------------------------------- | | --------------------------------------- | ----------------- |
| isFavorite | boolean | Yes | Operation to perform. The value **true** means to favorite the file asset, and **false** means the opposite.| | Promise&lt;T&gt; | Promise used to return the last object in the result set.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value. |
**Example** **Example**
...@@ -1403,45 +2647,40 @@ Favorites or unfavorites this file asset. This API uses an asynchronous callback ...@@ -1403,45 +2647,40 @@ Favorites or unfavorites this file asset. This API uses an asynchronous callback
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('favoriteDemo'); console.info('getLastObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject(); let fileAsset = await fetchResult.getLastObject();
asset.favorite(true, (err) => { console.info('fileAsset displayName: ', fileAsset.displayName);
if (err == undefined) {
console.info("favorite successfully");
} else {
console.error("favorite failed with error:" + err);
}
});
} }
``` ```
### favorite ### getPositionObject
favorite(isFavorite: boolean): Promise&lt;void&gt;
Favorites or unfavorites this file asset. This API uses a promise to return the result. getPositionObject(index: number, callback: AsyncCallback&lt;T&gt;): void
**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.WRITE_AUDIO 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ---------- | ------- | ---- | ---------------------------------- | | -------- | ---------------------------------------- | ---- | ------------------ |
| isFavorite | boolean | Yes | Operation to perform. The value **true** means to favorite the file asset, and **false** means the opposite.| | index | number | Yes | Index of the file asset to obtain. The value starts from **0**. |
| callback | AsyncCallback&lt;T&gt; | Yes | Callback invoked to return the file asset obtained.|
**Return value** **Error codes**
| Type | Description | For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
| ------------------- | ---------- |
| Promise&lt;void&gt; | Promise that returns no value.| | ID| Error Message|
| -------- | ---------------------------------------- |
| 13900020 | if type index is not number. |
**Example** **Example**
...@@ -1449,39 +2688,50 @@ Favorites or unfavorites this file asset. This API uses a promise to return the ...@@ -1449,39 +2688,50 @@ Favorites or unfavorites this file asset. This API uses a promise to return the
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('favoriteDemo'); console.info('getPositionObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fetchResult = await mgr.getPhotoAssets(fetchOption);
const asset = await fetchResult.getFirstObject(); fetchResult.getPositionObject(0, (err, fileAsset) => {
asset.favorite(true).then(function () { if (fileAsset != undefined) {
console.info("favorite successfully"); console.info('fileAsset displayName: ', fileAsset.displayName);
}).catch(function (err) { } else {
console.error("favorite failed with error:" + err); console.error('fileAsset failed with err: ' + err);
}
}); });
} }
``` ```
## FetchResult ### getPositionObject
Provides APIs to manage the file retrieval result. getPositionObject(index: number): Promise&lt;T&gt;
### getCount Obtains a file asset with the specified index in the result set. This API uses a promise to return the result.
getCount(): number **System capability**: SystemCapability.FileManagement.UserFileManager.Core
Obtains the total number of files in the result set. **Parameters**
**System capability**: SystemCapability.FileManagement.UserFileManager.Core | Name | Type | Mandatory | Description |
| ----- | ------ | ---- | -------------- |
| index | number | Yes | Index of the file asset to obtain. The value starts from **0**.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------ | -------- | | --------------------------------------- | ----------------- |
| number | Total number of files.| | Promise&lt;T&gt; | 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** **Example**
...@@ -1489,31 +2739,31 @@ Obtains the total number of files in the result set. ...@@ -1489,31 +2739,31 @@ Obtains the total number of files in the result set.
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getCountDemo'); console.info('getPositionObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fetchResult = await mgr.getPhotoAssets(fetchOption);
const fetchCount = fetchResult.getCount(); let fileAsset = await fetchResult.getPositionObject(0);
console.info('fetchCount = ', fetchCount); console.info('fileAsset displayName: ', fileAsset.displayName);
} }
``` ```
### isAfterLast ### getAllObject<sup>10+</sup>
isAfterLast(): boolean getAllObject(callback: AsyncCallback&lt;Array&lt;T&gt;&gt;): void
Checks whether the cursor is in the last row of the result set. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value** **Parameters**
| Type | Description | | Name | Type | Mandatory| Description |
| ------- | ---------------------------------- | | -------- | --------------------------------------------- | ---- | ------------------------------------------- |
| boolean | Returns **true** if the cursor is in the last row of the result set; returns **false** otherwise.| | callback | AsyncCallback&lt;Array&lt;T&gt;&gt; | Yes | Callback invoked to return an array of all file assets in the result set.|
**Example** **Example**
...@@ -1521,66 +2771,96 @@ Checks whether the cursor is in the last row of the result set. ...@@ -1521,66 +2771,96 @@ Checks whether the cursor is in the last row of the result set.
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getAllObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fetchResult = await mgr.getPhotoAssets(fetchOption);
const fetchCount = fetchResult.getCount(); fetchResult.getAllObject((err, fileAssetList) => {
console.info('count:' + fetchCount); if (fileAssetList != undefined) {
let fileAsset = await fetchResult.getLastObject(); console.info('fileAssetList length: ', fileAssetList.length);
if (!fetchResult.isAfterLast()) { } else {
console.info('fileAsset isAfterLast displayName = ', fileAsset.displayName); console.error('fileAssetList failed with err:' + err);
} else { }
console.info('fileAsset not isAfterLast '); });
}
} }
``` ```
### close ### getAllObject<sup>10+</sup>
close(): void getAllObject(): Promise&lt;Array&lt;T&gt;&gt;
Releases and invalidates this **FetchFileResult** instance. After this instance is released, the APIs in this instance cannot be invoked. Obtains all the file assets in the result set. This API uses a promise to return the result.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value**
| Type | Description |
| --------------------------------------- | -------------------------- |
| Promise&lt;Array&lt;T&gt;&gt; | Promise used to return an array of all file assets in the result set.|
**Example** **Example**
```ts ```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('fetchResultCloseDemo'); console.info('getAllObjectDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
try { let fetchResult = await mgr.getPhotoAssets(fetchOption);
let fetchResult = await mgr.getPhotoAssets(fetchOption); let fileAssetList = await fetchResult.getAllObject();
await fetchResult.close(); console.info('fileAssetList length: ', fileAssetList.length);
console.info('close succeed.');
} catch (err) {
console.error('close fail. message = ' + err);
}
} }
``` ```
### getFirstObject ## Album
getFirstObject(callback: AsyncCallback&lt;T&gt;): void Provides APIs to manage albums.
Obtains the first file asset in the result set. This API uses an asynchronous callback to return the result. ### Attributes
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Readable | Writable | Description |
| ------------ | ------ | ---- | ---- | ------- |
| albumType<sup>10+</sup> | [AlbumType]( #albumtype10) | Yes | No | Type of the album. |
| albumSubType<sup>10+</sup> | [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&lt;FetchResult&lt;FileAsset&gt;&gt;): 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | ------------------------------------------- | | -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback&lt;T&gt; | Yes | Callback invoked to return the first file asset.| | options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets.|
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | 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** **Example**
...@@ -1588,36 +2868,57 @@ Obtains the first file asset in the result set. This API uses an asynchronous ca ...@@ -1588,36 +2868,57 @@ Obtains the first file asset in the result set. This API uses an asynchronous ca
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getFirstObjectDemo'); console.info('albumGetFileAssetsDemoCallback');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = {
predicates: predicates
};
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); const albumList = await mgr.getPhotoAlbums(albumFetchOptions);
fetchResult.getFirstObject((err, fileAsset) => { const album = await albumList.getFirstObject();
if (fileAsset != undefined) { album.getPhotoAssets(fetchOption, (err, albumFetchResult) => {
console.info('fileAsset displayName: ', fileAsset.displayName); if (albumFetchResult != undefined) {
console.info('album getPhotoAssets successfully, getCount: ' + albumFetchResult.getCount());
} else { } else {
console.error("fileAsset failed with err:" + err); console.error('album getPhotoAssets failed with error: ' + err);
} }
}); });
} }
``` ```
### getFirstObject ### getPhotoAssets
getFirstObject(): Promise&lt;T&gt; getPhotoAssets(options: FetchOptions): Promise&lt;FetchResult&lt;FileAsset&gt;&gt;;
Obtains the first file asset in the result set. This API uses a promise to return the result. 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 **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** **Return value**
| Type | Description | | Type | Description |
| --------------------------------------- | -------------------------- | | --------------------------------------- | ----------------- |
| Promise&lt;T&gt; | Promise used to return the first file asset.| | Promise&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | 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** **Example**
...@@ -1625,31 +2926,41 @@ Obtains the first file asset in the result set. This API uses a promise to retur ...@@ -1625,31 +2926,41 @@ Obtains the first file asset in the result set. This API uses a promise to retur
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getFirstObjectDemo'); console.info('albumGetFileAssetsDemoPromise');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = {
predicates: predicates
};
let fetchOption = { let fetchOption = {
fetchColumns: [], fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); const albumList = await mgr.getPhotoAlbums(albumFetchOptions);
let fileAsset = await fetchResult.getFirstObject(); const album = await albumList.getFirstObject();
console.info('fileAsset displayName: ', fileAsset.displayName); album.getPhotoAssets(fetchOption).then((albumFetchResult) => {
console.info('album getFileAssets successfully, getCount: ' + albumFetchResult.getCount());
}).catch((err) => {
console.error('album getFileAssets failed with error: ' + err);
});
} }
``` ```
### getNextObject ### commitModify
getNextObject(callback: AsyncCallback&lt;T&gt;): void commitModify(callback: AsyncCallback&lt;void&gt;): void;
Obtains the next file asset in the result set. This API uses an asynchronous callback to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| --------- | --------------------------------------------- | ---- | ----------------------------------------- | | -------- | ------------------------- | ---- | ---------- |
| callbacke | AsyncCallback&lt;T&gt; | Yes | Callback invoked to return the next file asset.| | callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.|
**Example** **Example**
...@@ -1657,39 +2968,39 @@ Obtains the next file asset in the result set. This API uses an asynchronous cal ...@@ -1657,39 +2968,39 @@ Obtains the next file asset in the result set. This API uses an asynchronous cal
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getNextObjectDemo'); console.info('albumCommitModifyDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let albumFetchOptions = {
fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); const albumList = await mgr.getPhotoAlbums(albumFetchOptions);
await fetchResult.getFirstObject(); const album = await albumList.getFirstObject();
if (fetchResult.isAfterLast()) { album.albumName = 'hello';
fetchResult.getNextObject((err, fileAsset) => { album.commitModify((err) => {
if (fileAsset != undefined) { if (err != undefined) {
console.info('fileAsset displayName: ', fileAsset.displayName); console.error('commitModify failed with error: ' + err);
} else { } else {
console.error("fileAsset failed with err: " + err); console.info('commitModify successfully');
} }
}); });
}
} }
``` ```
### getNextObject ### commitModify
getNextObject(): Promise&lt;T&gt; commitModify(): Promise&lt;void&gt;;
Obtains the next file asset in the result set. This API uses a promise to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------------------------- | ----------------- | | ------------------- | ------------ |
| Promise&lt;T&gt; | Promise used to return the next file asset obtained.| | Promise&lt;void&gt; | Promise that returns no value.|
**Example** **Example**
...@@ -1697,34 +3008,50 @@ Obtains the next file asset in the result set. This API uses a promise to return ...@@ -1697,34 +3008,50 @@ Obtains the next file asset in the result set. This API uses a promise to return
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getNextObjectDemo'); console.info('albumCommitModifyDemo');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let fetchOption = { let albumFetchOptions = {
fetchColumns: [],
predicates: predicates predicates: predicates
}; };
let fetchResult = await mgr.getPhotoAssets(fetchOption); try {
await fetchResult.getFirstObject(); var albumList = await mgr.getPhotoAlbums(albumFetchOptions);
if (fetchResult.isAfterLast()) { } catch (err) {
let fileAsset = await fetchResult.getNextObject(); console.error('getPhotoAlbums failed. message = ', err);
console.info('fileAsset displayName: ', fileAsset.displayName);
} }
const album = await albumList.getFirstObject();
album.albumName = 'hello';
album.commitModify().then(() => {
console.info('commitModify successfully');
}).catch((err) => {
console.error('commitModify failed with error: ' + err);
});
} }
``` ```
### getLastObject ### addPhotoAssets<sup>10+</sup>
getLastObject(callback: AsyncCallback&lt;T&gt;): void addPhotoAssets(assets: Array&lt;FileAsset&gt;, callback: AsyncCallback&lt;void&gt;): void;
Obtains the last file asset in the result set. This API uses an asynchronous callback to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | --------------------------- | | -------- | ------------------------- | ---- | ---------- |
| callback | AsyncCallback&lt;T&gt; | Yes | Callback invoked to return the last file asset obtained.| | assets | Array&lt;[FileAsset](#fileasset)&gt; | Yes | Array of the image and video assets to add.|
| callback | AsyncCallback&lt;void&gt; | 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** **Example**
...@@ -1732,36 +3059,59 @@ Obtains the last file asset in the result set. This API uses an asynchronous cal ...@@ -1732,36 +3059,59 @@ Obtains the last file asset in the result set. This API uses an asynchronous cal
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getLastObjectDemo'); try {
let predicates = new dataSharePredicates.DataSharePredicates(); console.info('addPhotoAssetsDemoCallback');
let fetchOption = { let predicates = new dataSharePredicates.DataSharePredicates();
fetchColumns: [], let fetchOption = {
predicates: predicates fetchColumns: [],
}; predicates: predicates
let fetchResult = await mgr.getPhotoAssets(fetchOption); };
fetchResult.getLastObject((err, fileAsset) => { let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
if (fileAsset != undefined) { let album = await albumFetchResult.getFirstObject();
console.info('fileAsset displayName: ', fileAsset.displayName); let fetchResult = await mgr.getPhotoAssets(fetchOption);
} else { let asset = await fetchResult.getFirstObject();
console.error("fileAsset failed with err: " + err); 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);
}
} }
``` ```
### getLastObject ### addPhotoAssets<sup>10+</sup>
getLastObject(): Promise&lt;T&gt; addPhotoAssets(assets: Array&lt;FileAsset&gt;): Promise&lt;void&gt;;
Obtains the last file asset in the result set. This API uses a promise to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array&lt;[FileAsset](#fileasset)&gt; | Yes | Array of the image and video assets to add.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------------------------- | ----------------- | | --------------------------------------- | ----------------- |
| Promise&lt;T&gt; | Promise used to return the last file asset obtained.| |Promise&lt;void&gt; | 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** **Example**
...@@ -1769,32 +3119,52 @@ Obtains the last file asset in the result set. This API uses a promise to return ...@@ -1769,32 +3119,52 @@ Obtains the last file asset in the result set. This API uses a promise to return
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getLastObjectDemo'); try {
let predicates = new dataSharePredicates.DataSharePredicates(); console.info('addPhotoAssetsDemoPromise');
let fetchOption = { let predicates = new dataSharePredicates.DataSharePredicates();
fetchColumns: [], let fetchOption = {
predicates: predicates fetchColumns: [],
}; predicates: predicates
let fetchResult = await mgr.getPhotoAssets(fetchOption); };
let fileAsset = await fetchResult.getLastObject(); let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
console.info('fileAsset displayName: ', fileAsset.displayName); 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);
}
} }
``` ```
### getPositionObject ### removePhotoAssets<sup>10+</sup>
getPositionObject(index: number, callback: AsyncCallback&lt;T&gt;): void removePhotoAssets(assets: Array&lt;FileAsset&gt;, callback: AsyncCallback&lt;void&gt;): void;
Obtains a file asset with the specified index in the result set. This API uses an asynchronous callback to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| -------- | ---------------------------------------- | ---- | ------------------ | | -------- | ------------------------- | ---- | ---------- |
| index | number | Yes | Index of the file asset to obtain. The value starts from **0**. | | assets | Array&lt;[FileAsset](#fileasset)&gt; | Yes | Array of the image and video assets to remove.|
| callback | AsyncCallback&lt;T&gt; | Yes | Callback invoked to return the file asset obtained.| | callback | AsyncCallback&lt;void&gt; | 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** **Example**
...@@ -1802,42 +3172,59 @@ Obtains a file asset with the specified index in the result set. This API uses a ...@@ -1802,42 +3172,59 @@ Obtains a file asset with the specified index in the result set. This API uses a
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getPositionObjectDemo'); try {
let predicates = new dataSharePredicates.DataSharePredicates(); console.info('removePhotoAssetsDemoCallback');
let fetchOption = { let predicates = new dataSharePredicates.DataSharePredicates();
fetchColumns: [], let fetchOption = {
predicates: predicates fetchColumns: [],
}; predicates: predicates
let fetchResult = await mgr.getPhotoAssets(fetchOption); };
fetchResult.getPositionObject(0, (err, fileAsset) => { let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
if (fileAsset != undefined) { let album = await albumFetchResult.getFirstObject();
console.info('fileAsset displayName: ', fileAsset.displayName); let fetchResult = await album.getPhotoAssets(fetchOption);
} else { let asset = await fetchResult.getFirstObject();
console.error("fileAsset failed with err: " + err); 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);
}
} }
``` ```
### getPositionObject ### removePhotoAssets<sup>10+</sup>
getPositionObject(index: number): Promise&lt;T&gt; removePhotoAssets(assets: Array&lt;FileAsset&gt;): Promise&lt;void&gt;;
Obtains a file asset with the specified index in the result set. This API uses a promise to return the result. 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 **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| ----- | ------ | ---- | -------------- | | -------- | ------------------------- | ---- | ---------- |
| index | number | Yes | Index of the file asset to obtain. The value starts from **0**.| | assets | Array&lt;[FileAsset](#fileasset)&gt; | Yes | Array of the image and video assets to remove.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------------------------- | ----------------- | | --------------------------------------- | ----------------- |
| Promise&lt;T&gt; | Promise used to return the file asset obtained.| |Promise&lt;void&gt; | 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** **Example**
...@@ -1845,41 +3232,35 @@ Obtains a file asset with the specified index in the result set. This API uses a ...@@ -1845,41 +3232,35 @@ Obtains a file asset with the specified index in the result set. This API uses a
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('getPositionObjectDemo'); try {
let predicates = new dataSharePredicates.DataSharePredicates(); console.info('removePhotoAssetsDemoPromise');
let fetchOption = { let predicates = new dataSharePredicates.DataSharePredicates();
fetchColumns: [], let fetchOption = {
predicates: predicates fetchColumns: [],
}; predicates: predicates
let fetchResult = await mgr.getPhotoAssets(fetchOption); };
let fileAsset = await fetchResult.getPositionObject(0); let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.USER, userFileManager.AlbumSubType.USER_GENERIC);
console.info('fileAsset displayName: ', fileAsset.displayName); 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);
}
} }
``` ```
## Album ### recoverPhotoAssets<sup>10+</sup>
Provides APIs to manage albums.
### Attributes
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Type | Readable | Writable | Description |
| ------------ | ------ | ---- | ---- | ------- |
| albumName | string | Yes | Yes | Album name. |
| albumUri | string | Yes | No | Album URI. |
| 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&lt;FetchResult&lt;FileAsset&gt;&gt;): void; recoverPhotoAssets(assets: Array&lt;FileAsset&gt;, callback: AsyncCallback&lt;void&gt;): void;
Obtains image and video assets. This API uses an asynchronous callback to return the result. 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.READ_IMAGEVIDEO **Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
...@@ -1887,8 +3268,16 @@ Obtains image and video assets. This API uses an asynchronous callback to return ...@@ -1887,8 +3268,16 @@ Obtains image and video assets. This API uses an asynchronous callback to return
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- | | -------- | ------------------------- | ---- | ---------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets.| | assets | Array&lt;[FileAsset](#fileasset)&gt; | Yes | Array of the image or video assets to recover.|
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | Yes | Callback invoked to return the image and video assets obtained.| | callback | AsyncCallback&lt;void&gt; | 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** **Example**
...@@ -1896,35 +3285,37 @@ Obtains image and video assets. This API uses an asynchronous callback to return ...@@ -1896,35 +3285,37 @@ Obtains image and video assets. This API uses an asynchronous callback to return
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('albumGetFileAssetsDemoCallback'); try {
console.info('recoverPhotoAssetsDemoCallback');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = { let fetchOption = {
predicates: predicates fetchColumns: [],
}; predicates: predicates
let fetchOption = { };
fetchColumns: [], let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
predicates: predicates let album = await albumFetchResult.getFirstObject();
}; let fetchResult = await album.getPhotoAssets(fetchOption);
const albumList = await mgr.getPhotoAlbums(albumFetchOptions); let asset = await fetchResult.getFirstObject();
const album = await albumList.getFirstObject(); album.recoverPhotoAssets([asset], (err) => {
album.getPhotoAssets(fetchOption, (err, albumFetchResult) => { if (err === undefined) {
if (albumFetchResult != undefined) { console.info('album recoverPhotoAssets successfully');
console.info("album getPhotoAssets successfully, getCount: " + albumFetchResult.getCount()); } else {
} else { console.error('album recoverPhotoAssets failed with error: ' + err);
console.error("album getPhotoAssets failed with error: " + err); }
} });
}); } catch (err) {
console.error('recoverPhotoAssetsDemoCallback failed with error: ' + err);
}
} }
``` ```
### getPhotoAssets ### recoverPhotoAssets<sup>10+</sup>
getPhotoAssets(options: FetchOptions): Promise&lt;FetchResult&lt;FileAsset&gt;&gt;; recoverPhotoAssets(assets: Array&lt;FileAsset&gt;): Promise&lt;void&gt;;
Obtains image and video assets. This API uses a promise to return the result. 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.READ_IMAGEVIDEO **Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
...@@ -1932,8 +3323,21 @@ Obtains image and video assets. This API uses a promise to return the result. ...@@ -1932,8 +3323,21 @@ Obtains image and video assets. This API uses a promise to return the result.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- | | -------- | ------------------------- | ---- | ---------- |
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets.| | assets | Array&lt;[FileAsset](#fileasset)&gt; | Yes | Array of the image or video assets to recover.|
| Promise | [FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt; | Yes | Promise used to return the image and video assets obtained.|
**Return value**
| Type | Description |
| --------------------------------------- | ----------------- |
|Promise&lt;void&gt; | 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** **Example**
...@@ -1941,31 +3345,35 @@ Obtains image and video assets. This API uses a promise to return the result. ...@@ -1941,31 +3345,35 @@ Obtains image and video assets. This API uses a promise to return the result.
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('albumGetFileAssetsDemoPromise'); try {
console.info('recoverPhotoAssetsDemoPromise');
let predicates = new dataSharePredicates.DataSharePredicates(); let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = { let fetchOption = {
predicates: predicates fetchColumns: [],
}; predicates: predicates
let fetchOption = { };
fetchColumns: [], let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
predicates: predicates let album = await albumFetchResult.getFirstObject();
}; let fetchResult = await album.getPhotoAssets(fetchOption);
const albumList = await mgr.getPhotoAlbums(albumFetchOptions); let asset = await fetchResult.getFirstObject();
const album = await albumList.getFirstObject(); album.recoverPhotoAssets([asset]).then(() => {
album.getPhotoAssets(fetchOption).then((albumFetchResult) => { console.info('album recoverPhotoAssets successfully');
console.info("album getFileAssets successfully, getCount: " + albumFetchResult.getCount()); }).catch((err) => {
}).catch((err) => { console.error('album recoverPhotoAssets failed with error: ' + err);
console.error("album getFileAssets failed with error: " + err); });
}); } catch (err) {
console.error('recoverPhotoAssetsDemoPromise failed with error: ' + err);
}
} }
``` ```
### commitModify ### deletePhotoAssets<sup>10+</sup>
commitModify(callback: AsyncCallback&lt;void&gt;): void; deletePhotoAssets(assets: Array&lt;FileAsset&gt;, callback: AsyncCallback&lt;void&gt;): void;
Commits the modification on the album attributes to the database. This API uses an asynchronous callback to return the result. 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 **Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
...@@ -1975,47 +3383,78 @@ Commits the modification on the album attributes to the database. This API uses ...@@ -1975,47 +3383,78 @@ Commits the modification on the album attributes to the database. This API uses
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- | | -------- | ------------------------- | ---- | ---------- |
| assets | Array&lt;[FileAsset](#fileasset)&gt; | Yes | Array of the image or video assets to delete.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.| | callback | AsyncCallback&lt;void&gt; | 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** **Example**
```ts ```ts
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('albumCommitModifyDemo'); try {
let predicates = new dataSharePredicates.DataSharePredicates(); console.info('deletePhotoAssetsDemoCallback');
let albumFetchOptions = { let predicates = new dataSharePredicates.DataSharePredicates();
predicates: predicates let fetchOption = {
}; fetchColumns: [],
const albumList = await mgr.getPhotoAlbums(albumFetchOptions); predicates: predicates
const album = await albumList.getFirstObject(); };
album.albumName = 'hello'; let albumFetchResult = await mgr.getAlbums(userFileManager.AlbumType.SYSTEM, userFileManager.AlbumSubType.TRASH);
album.commitModify((err) => { let album = await albumFetchResult.getFirstObject();
if (err != undefined) { let fetchResult = await album.getPhotoAssets(fetchOption);
console.error("commitModify failed with error: " + err); let asset = await fetchResult.getFirstObject();
} else { album.deletePhotoAssets([asset], (err) => {
console.info("commitModify successfully"); 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);
}
} }
``` ```
### commitModify ### deletePhotoAssets<sup>10+</sup>
commitModify(): Promise&lt;void&gt;; deletePhotoAssets(assets: Array&lt;FileAsset&gt;): Promise&lt;void&gt;;
Commits the modification on the album attributes to the database. This API uses a promise to return the result. 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 **Required permissions**: ohos.permission.WRITE_IMAGEVIDEO
**System capability**: SystemCapability.FileManagement.UserFileManager.Core **System capability**: SystemCapability.FileManagement.UserFileManager.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- |
| assets | Array&lt;[FileAsset](#fileasset)&gt; | Yes | Array of the image or video assets to delete.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------------------- | ------------ | | --------------------------------------- | ----------------- |
| Promise&lt;void&gt; | Promise that returns no value.| |Promise&lt;void&gt; | 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** **Example**
...@@ -2023,23 +3462,25 @@ Commits the modification on the album attributes to the database. This API uses ...@@ -2023,23 +3462,25 @@ Commits the modification on the album attributes to the database. This API uses
import dataSharePredicates from '@ohos.data.dataSharePredicates'; import dataSharePredicates from '@ohos.data.dataSharePredicates';
async function example() { async function example() {
console.info('albumCommitModifyDemo');
let predicates = new dataSharePredicates.DataSharePredicates();
let albumFetchOptions = {
predicates: predicates
};
try { try {
var albumList = await mgr.getPhotoAlbums(albumFetchOptions); 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) { } catch (err) {
console.error('getPhotoAlbums failed. message = ', err); console.error('deletePhotoAssetsDemoPromise failed with error: ' + 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);
});
} }
``` ```
...@@ -2053,11 +3494,11 @@ Provides APIs for managing the system albums. ...@@ -2053,11 +3494,11 @@ Provides APIs for managing the system albums.
| Name | Type | Readable | Writable | Description | | Name | Type | Readable | Writable | Description |
| ------------ | ------ | ---- | ---- | ------- | | ------------ | ------ | ---- | ---- | ------- |
| albumName | string | Yes | Yes | Album name. | | albumName | string | Yes | Yes | Name of the album. |
| albumUri | string | Yes | No | Album URI. | | albumUri | string | Yes | No | URI of the album. |
| dateModified | number | Yes | No | Date when the album was last modified. | | dateModified | number | Yes | No | Date when the album was last modified. |
| count | number | Yes | No | Number of files in the album.| | count | number | Yes | No | Number of files in the album.|
| coverUri | string | Yes | No | URI of the cover file of the album. | coverUri | string | Yes | No | URI of the cover file of the album.|
### getPhotoAssets ### getPhotoAssets
...@@ -2076,6 +3517,14 @@ Obtains image and video assets from a system album. This API uses an asynchronou ...@@ -2076,6 +3517,14 @@ Obtains image and video assets from a system album. This API uses an asynchronou
| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets.| | options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the image and video assets.|
| callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | Yes | Callback invoked to return the image and video assets obtained.| | callback | AsyncCallback&lt;[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;&gt; | 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** **Example**
```ts ```ts
...@@ -2124,6 +3573,14 @@ Obtains image and video assets from a system album. This API uses a promise to r ...@@ -2124,6 +3573,14 @@ Obtains image and video assets from a system album. This API uses a promise to r
| --------------------------------------- | ----------------- | | --------------------------------------- | ----------------- |
| Promise:[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;| Promise used to return the image and video assets obtained.| | Promise:[FetchResult](#fetchresult)&lt;[FileAsset](#fileasset)&gt;| 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** **Example**
```ts ```ts
...@@ -2158,7 +3615,7 @@ Deletes files from a system album. ...@@ -2158,7 +3615,7 @@ Deletes files from a system album.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- | | -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | Album URI.| | uri | string | Yes | URI of the album.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.| | callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.|
**Example** **Example**
...@@ -2202,7 +3659,7 @@ Deletes files from a system album. ...@@ -2202,7 +3659,7 @@ Deletes files from a system album.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- | | -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | Album URI.| | uri | string | Yes | URI of the album.|
**Return value** **Return value**
...@@ -2249,7 +3706,7 @@ Recovers files in a system album. ...@@ -2249,7 +3706,7 @@ Recovers files in a system album.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- | | -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | Album URI.| | uri | string | Yes | URI of the album.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.| | callback | AsyncCallback&lt;void&gt; | Yes | Callback that returns no value.|
**Example** **Example**
...@@ -2293,7 +3750,7 @@ Recovers files in a system album. ...@@ -2293,7 +3750,7 @@ Recovers files in a system album.
| Name | Type | Mandatory| Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------- | | -------- | ------------------------- | ---- | ---------- |
| uri | string | Yes | Album URI.| | uri | string | Yes | URI of the album.|
**Return value** **Return value**
...@@ -2346,12 +3803,12 @@ Enumerates the type of changes to observe. ...@@ -2346,12 +3803,12 @@ Enumerates the type of changes to observe.
| Name | Type| Readable | Writable | Description| | Name | Type| Readable | Writable | Description|
| ----- | ---- | ---- | ---- | ---- | | ----- | ---- | ---- | ---- | ---- |
| deviceChange | string | Yes| Yes| Device.| | deviceChange | string | Yes| Yes| Device change.|
| albumChange | string | Yes| Yes| Album.| | albumChange | string | Yes| Yes| Album change.|
| imageChange | string | Yes| Yes| Image.| | imageChange | string | Yes| Yes| Image change.|
| audioChange | string | Yes| Yes| Audio.| | audioChange | string | Yes| Yes| Audio change.|
| videoChange | string | Yes| Yes| Video.| | videoChange | string | Yes| Yes| Video change.|
| remoteFileChange | string | Yes| Yes| Remote file.| | remoteFileChange | string | Yes| Yes| Remote file change.|
## PeerInfo ## PeerInfo
...@@ -2377,6 +3834,58 @@ Enumerates media file types. ...@@ -2377,6 +3834,58 @@ Enumerates media file types.
| VIDEO | 2 | Video.| | VIDEO | 2 | Video.|
| AUDIO | 3 | Audio.| | AUDIO | 3 | Audio.|
## PhotoSubType<sup>10+</sup>
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.|
## PositionType<sup>10+</sup>
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.|
## AlbumType<sup>10+</sup>
Enumerates the album types.
**System capability**: SystemCapability.FileManagement.UserFileManager.Core
| Name | Value| Description|
| ----- | ---- | ---- |
| USER | 0 | User album.|
| SYSTEM | 1024 | System album.|
## AlbumSubType<sup>10+</sup>
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 ## PrivateAlbumType
Enumerates the system album types. Enumerates the system album types.
...@@ -2396,7 +3905,7 @@ Defines the key information about an audio file. ...@@ -2396,7 +3905,7 @@ Defines the key information about an audio file.
| Name | Value | Description | | Name | Value | Description |
| ------------- | ------------------- | ---------------------------------------------------------- | | ------------- | ------------------- | ---------------------------------------------------------- |
| URI | uri | File URI. | | URI | uri | URI of the file. |
| DISPLAY_NAME | display_name | File name displayed. | | 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_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.| | 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.|
...@@ -2414,18 +3923,21 @@ Defines the key information about an image or video file. ...@@ -2414,18 +3923,21 @@ Defines the key information about an image or video file.
| Name | Value | Description | | Name | Value | Description |
| ------------- | ------------------- | ---------------------------------------------------------- | | ------------- | ------------------- | ---------------------------------------------------------- |
| URI | uri | File URI. | | URI | uri | URI of the file. |
| FILE_TYPE | file_type | Type of the file. | | FILE_TYPE | file_type | Type of the file. |
| DISPLAY_NAME | display_name | File name displayed. | | 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_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.| | 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. | | TITLE | title | Title of the file. |
| DURATION | duration | Duration, in ms. | | DURATION | duration | Duration, in ms. |
| WIDTH | width | Image width, in pixels. | | WIDTH | width | Image width, in pixels. |
| HEIGHT | height | Image height, 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. | | 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. | | ORIENTATION | orientation | Orientation of the image file. |
| FAVORITE | favorite | Whether the file is added to favorites. | | FAVORITE | favorite | Whether the file is added to favorites. |
| POSITION<sup>10+</sup> | position | File location type. |
| DATE_TRASHED<sup>10+</sup> | 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. |
| HIDDEN<sup>10+</sup> | hidden | Whether the file is hidden. |
## AlbumKey ## AlbumKey
...@@ -2435,11 +3947,21 @@ Defines the key album information. ...@@ -2435,11 +3947,21 @@ Defines the key album information.
| Name | Value | Description | | Name | Value | Description |
| ------------- | ------------------- | ---------------------------------------------------------- | | ------------- | ------------------- | ---------------------------------------------------------- |
| URI | uri | Album URI. | | URI | uri | URI of the album. |
| FILE_TYPE | file_type | Type of the file. | | FILE_TYPE | file_type | Type of the file. |
| ALBUM_NAME | album_name | Name of the album. | | ALBUM_NAME | album_name | Name of the album. |
| DATE_ADDED | date_added | Date when the file was added. The value is the number of seconds elapsed since the Epoch time. | | 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 file content (not the file name) was last modified. 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.|
## PhotoCreateOptions<sup>10+</sup>
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. |
## FetchOptions ## FetchOptions
...@@ -2449,7 +3971,7 @@ Defines the options for fetching media files. ...@@ -2449,7 +3971,7 @@ Defines the options for fetching media files.
| Name | Type | Readable| Writable| Description | | Name | Type | Readable| Writable| Description |
| ---------------------- | ------------------- | ---- |---- | ------------------------------------------------ | | ---------------------- | ------------------- | ---- |---- | ------------------------------------------------ |
| fetchColumns | Array&lt;string&gt; | Yes | Yes | Columns to fetch. If this parameter is left empty, data is fetched by URI, name, and file type by default. For example,<br>**fetchColumns: "uri"**.| | fetchColumns | Array&lt;string&gt; | 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:<br>fetchColumns: ['uri', 'title']|
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md) | Yes | Yes | Predicates that specify the fetch criteria.| | predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md) | Yes | Yes | Predicates that specify the fetch criteria.|
## AlbumFetchOptions ## AlbumFetchOptions
...@@ -2461,3 +3983,41 @@ Defines the options for fetching an album. ...@@ -2461,3 +3983,41 @@ Defines the options for fetching an album.
| Name | Type | Readable| Writable| Description | | Name | Type | Readable| Writable| Description |
| ---------------------- | ------------------- | ---- |---- | ------------------------------------------------ | | ---------------------- | ------------------- | ---- |---- | ------------------------------------------------ |
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md) | Yes | Yes | Predicates that specify the fetch criteria.| | predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md) | Yes | Yes | Predicates that specify the fetch criteria.|
## ChangeData<sup>10+</sup>
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&lt;string&gt; | Yes | No | Array of all file asset or album URIs with the same [NotifyType](#notifytype10).|
| subUris | Array&lt;string&gt; | Yes | No | URIs of the changed files in the album. |
## NotifyType<sup>10+</sup>
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.|
## DefaultChangeUri<sup>10+</sup>
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}**.|
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册