diff --git a/en/application-dev/reference/apis/js-apis-medialibrary.md b/en/application-dev/reference/apis/js-apis-medialibrary.md new file mode 100644 index 0000000000000000000000000000000000000000..219f699cdd68b377a94846c4aeadb1341c713ece --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-medialibrary.md @@ -0,0 +1,2219 @@ +# Media Library Management + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> This component is supported since API version 6. Updates will be marked with a superscript to indicate their earliest API version. + +## Modules to Import +``` +import mediaLibrary from '@ohos.multimedia.medialibrary'; +``` + +## mediaLibrary.getMediaLibrary + +getMediaLibrary(context: Context): MediaLibrary + +Obtains a **MediaLibrary** instance, which is used to access and modify personal data of users. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | ------------------------------------------------------------ | +| context | Context | Yes | Context of the ability. This parameter is optional for API version 7 and earlier versions, but mandatory for API version 8 and later versions.| + +**Return value** + +| Type | Description | +| ----------------------------- | :--------- | +| [MediaLibrary](#medialibrary) | **MediaLibrary** instance.| + +**Example** + +``` +import featureAbility from '@ohos.ability.featureAbility'; + +var context = featureAbility.getContext() +var media = mediaLibrary.getMediaLibrary(context); +``` +## MediaLibrary + +### getFileAssets8+ + + +getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void + +Obtains file assets (also called files). This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------------------------------- | ---- | --------------------------------- | +| options | [MediaFetchOptions](#mediafetchoptions8) | Yes | Options for fetching the files. | +| callback | AsyncCallback<[FetchFileResult](#fetchfileresult8)> | Yes | Asynchronous callback of **FetchFileResult**.| + +**Example** + +``` +let fileKeyObj = mediaLibrary.FileKey +let imageType = mediaLibrary.MediaType.IMAGE +let imagesfetchOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], +}; +mediaLibrary.getFileAssets(imagesfetchOp, (error, fetchFileResult) => { + if (fetchFileResult != undefined) { + console.info('mediaLibraryTest : ASSET_CALLBACK fetchFileResult success'); + fetchFileResult.getAllObject((err, fileAssetList) => { + if (fileAssetList != undefined) { + fileAssetList.forEach(getAllObjectInfo); + } + }); + } +}); +``` +### getFileAssets8+ + +getFileAssets(options: MediaFetchOptions): Promise<FetchFileResult> + +Obtains file assets. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------------------------------- | ---- | ------------ | +| options | [MediaFetchOptions](#mediafetchoptions8) | Yes | Options for fetching the files.| + +**Return value** + +| Type | Description | +| ------------------------------------ | -------------- | +| [FetchFileResult](#fetchfileresult8) | Result set of the file retrieval operation.| + +**Example** + +``` +let fileKeyObj = mediaLibrary.FileKey +let imageType = mediaLibrary.MediaType.IMAGE +let imagesfetchOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], +}; +mediaLibrary.getFileAssets(imagesfetchOp).then(function(fetchFileResult){ + console.info("getFileAssets successfully:"+ JSON.stringify(dir)); +}).catch(function(err){ + console.info("getFileAssets failed with error:"+ err); +}); +``` + +### on8+ + +on(type: 'deviceChange'|'albumChange'|'imageChange'|'audioChange'|'videoChange'|'fileChange'|'remoteFileChange', callback: Callback<void>): void + +Subscribes to the media library changes. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Media type.
'deviceChange': registered device change
'albumChange': album change
'imageChange': image file change
'audioChange': audio file change
'videoChange': video file change
'fileChange': file change
'remoteFileChange': file change on the registered device| +| callback | callback<void> | Yes | Void callback. | + +**Example** + +``` +mediaLibrary.on('imageChange', () => { + // image file had changed, do something +}) +``` +### off8+ + +off(type: 'deviceChange'|'albumChange'|'imageChange'|'audioChange'|'videoChange'|'fileChange'|'remoteFileChange', callback?: Callback<void>): void + +Unsubscribes from the media library changes. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Media type.
'deviceChange': registered device change
'albumChange': album change
'imageChange': image file change
'audioChange': audio file change
'videoChange': video file change
'fileChange': file change
'remoteFileChange': file change on the registered device| +| callback | callback<void> | No | Void callback. | + +**Example** + +``` +mediaLibrary.off('imageChange', () => { + // stop listening success +}) +``` + +### createAsset 8+ + +createAsset(mediaType: MediaType, displayName: string, relativePath: string, callback: AsyncCallback<FileAsset>): void + +Creates a media asset. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | --------------------------------------- | ---- | ------------------------------------------------------------ | +| mediaType | [MediaType](#mediatype) | Yes | Media type. | +| displayName | string | Yes | Display file name. | +| relativePath | string | Yes | Path for storing the file. You can use [getPublicDirectory](#getpublicdirectory8) to obtain the paths for storing different types of files.| +| callback | AsyncCallback<[FileAsset](#fileasset8)> | Yes | Asynchronous callback for **FileAsset**. | + +**Example** + +``` +async function example() { + // Create an image file in callback mode. + let mediaType = mediaLibrary.MediaType.IMAGE; + let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; + const path = await media.getPublicDirectory(DIR_IMAGE); + mediaLibrary.createAsset(mediaType, 'imageCallBack.jpg', path + 'myPicture/', (err, fileAsset) => { + if (fileAsset != undefined) { + console.info('createAsset successfully, message = ' + err); + } else { + console.info('createAsset failed, message = ' + err); + } + }); +} +``` + +### createAsset8+ + +createAsset(mediaType: MediaType, displayName: string, relativePath: string): Promise<FileAsset> + +Creates a media asset. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ----------------------- | ---- | ------------------------------------------------------------ | +| mediaType | [MediaType](#mediatype) | Yes | Media type. | +| displayName | string | Yes | Display file name. | +| relativePath | string | Yes | Relative path. You can use [getPublicDirectory](#getpublicdirectory8) to obtain the relative path of the level-1 directory of different types of media files.| + +**Return value** + +| Type | Description | +| ------------------------ | ----------------- | +| [FileAsset](#fileasset8) | Media data (FileAsset).| + +**Example** + +``` +async function example() { + // Create an image file in promise mode + let mediaType = mediaLibrary.MediaType.IMAGE; + let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; + const path = await media.getPublicDirectory(DIR_IMAGE); + mediaLibrary.createAsset(mediaType, "image01.jpg", path + 'myPicture/').then (function (asset) { + console.info("createAsset successfully:"+ JSON.stringify(asset)); + }).catch(function(err){ + console.info("createAsset failed with error:"+ err); + }); +} +``` + +### getPublicDirectory8+ + +getPublicDirectory(type: DirectoryType, callback: AsyncCallback<string>): void + +Obtains a public directory. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------- | ---- | ------------------------- | +| type | [DirectoryType](#directorytype) | Yes | Type of the public directory. | +| callback | AsyncCallback<string> | Yes | Callback used to return the public directory.| + +**Example** + +``` +let DIR_CAMERA = mediaLibrary.DirectoryType.DIR_CAMERA; +media.getPublicDirectory(DIR_CAMERA, (err, dicResult) => { + if (dicResult == 'Camera/') { + console.info('mediaLibraryTest : getPublicDirectory passed'); + } else { + console.info('mediaLibraryTest : getPublicDirectory failed'); + } +}); +``` + +### getPublicDirectory8+ + +getPublicDirectory(type: DirectoryType): Promise<string> + +Obtains a public directory. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------------------------------- | ---- | ------------ | +| type | [DirectoryType](#directorytype) | Yes | Type of the public directory.| + +**Return value** + +| Type | Description | +| --------------- | ---------------- | +| Promise | Promise used to return the public directory.| + +**Example** + +``` +async function example() { + let DIR_CAMERA = mediaLibrary.DirectoryType.DIR_CAMERA; + const dicResult = await media.getPublicDirectory(DIR_CAMERA); + if (dicResult == 'Camera/') { + console.info('MediaLibraryTest : getPublicDirectory'); + } else { + console.info('MediaLibraryTest : getPublicDirectory failed'); + } +} +``` + +### getAlbums8+ + +getAlbums(options: MediaFetchOptions, callback: AsyncCallback): void + +Obtains the albums. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------------------------------- | ---- | --------------------------- | +| options | [MediaFetchOptions](#mediafetchoptions8) | Yes | Options for fetching the albums. | +| callback | AsyncCallback<Array<[Album](#album8)>> | Yes | Callback used to return the albums.| + +**Example** + +``` +let AlbumNoArgsfetchOp = { + selections: '', + selectionArgs: [], +}; +mediaLibrary.getAlbums(AlbumNoArgsfetchOp, (err, albumList) => { + if (albumList != undefined) { + const album = albumList[0]; + console.info('album.albumName = ' + album.albumName); + console.info('album.count = ' + album.count); + } else { + console.info('getAlbum fail, message = ' + err); + } +}) +``` + +### getAlbums8+ + +getAlbums(options: MediaFetchOptions): Promise + +Obtains the albums. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------------------------------- | ---- | ------------ | +| options | [MediaFetchOptions](#mediafetchoptions8) | Yes | Options for fetching the albums.| + +**Return value** + +| Type | Description | +| -------------------------------- | ------------- | +| Promise> | Promise used to return the albums.| + +**Example** + +``` +let AlbumNoArgsfetchOp = { + selections: '', + selectionArgs: [], +}; +mediaLibrary.getAlbums(AlbumNoArgsfetchOp).then(function(albumList){ + console.info("getAlbums successfully:"+ JSON.stringify(albumList)); +}).catch(function(err){ + console.info("getAlbums failed with error:"+ err); +}); +``` + +### release8+ + +release(callback: AsyncCallback<void>): void + +Releases this **MediaLibrary** instance. +Call this API when you no longer need to use the APIs in the **MediaLibrary** instance. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | -------------------- | +| callback | AsyncCallback<void> | Yes | Callback used to return the execution result.| + +**Example** + +``` +var media = mediaLibrary.getMediaLibrary(context); +media.release((err) => { + // do something +}); +``` + +### release8+ + +release(): Promise<void> + +Releases this **MediaLibrary** instance. +Call this API when you no longer need to use the APIs in the **MediaLibrary** instance. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| ------------------- | --------------------------------- | +| Promise<void> | Promise used to return the execution result.| + +**Example** + +``` +var media = mediaLibrary.getMediaLibrary(context); +media.release() +``` + +### storeMediaAsset + +storeMediaAsset(option: MediaAssetOption, callback: AsyncCallback<string>): void + +Stores a media asset. This API uses an asynchronous callback to return the URI that stores the media asset. + +This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------- | ---- | ------------------------------------------- | +| option | [MediaAssetOption](#mediaassetoption) | Yes | Media asset option. | +| callback | AsyncCallback<string> | Yes | Callback used to return the URI that stores the media asset.| + +**Example** + + ``` +let option = { + src : "file:///data/data/ohos.xxx.yyy/files/image.png", + mimeType : "image/jpeg", + relativePath : "imageDir/image2/" +}; +mediaLibrary.getMediaLibrary().storeMediaAsset(option, (err, value) => { + if (err) { + console.log("An error occurred when storing the media asset."); + return; + } + console.log("Media asset stored. "); + // Obtain the URI that stores the media asset. +}); + ``` + + +### storeMediaAsset + +storeMediaAsset(option: MediaAssetOption): Promise<string> + +Stores a media asset. This API uses a promise to return the URI that stores the media asset. + +This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------------------------------------- | ---- | -------------- | +| option | [MediaAssetOption](#mediaassetoption) | Yes | Media asset option.| + +**Return value** + +| Type | Description | +| --------------------- | ---------------------------------------------- | +| Promise<string> | Promise used to return the URI that stores the media asset.| + +**Example** + + ``` +let option = { + src : "file:///data/data/ohos.xxx.yyy/files/image.jpg", + mimeType : "image/jpeg", + relativePath : "imageDir/image2/" +}; +mediaLibrary.getMediaLibrary().storeMediaAsset(option).then((value) => { + console.log("Media asset stored."); + // Obtain the URI that stores the media asset. +}).catch((err) => { + console.log("An error occurred when storing the media assets."); +}); + ``` + + +### startImagePreview + +startImagePreview(images: Array<string>, index: number, callback: AsyncCallback<void>): void + +Starts image preview, with the first image to preview specified. This API can be used to preview local images whose URIs start with **dataability://** or online images whose URIs start with **https://**. It uses an asynchronous callback to return the execution result. + +This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | --------------------------------------------------- | +| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **https://** or **dataability://**.| +| index | number | Yes | Index of the first image to preview. | +| callback | AsyncCallback<void> | Yes | Callback used to return the image preview result. If the preview fails, an error message is returned. | + +**Example** + + ``` +let images = [ + "dataability:///media/external/images/media/50", + "dataability:///media/external/images/media/55" +]; +let images = [ + "https://media.xxxx.com/image1.jpg", + "https://media.xxxx.com/image2.jpg" +]; +let index = 1; +mediaLibrary.getMediaLibrary().startImagePreview(images, index, (err) => { + if (err) { + console.log("An error occurred when previewing the images."); + return; + } + console.log("Succeeded in previewing the images."); +}); + ``` + + +### startImagePreview + +startImagePreview(images: Array<string>, callback: AsyncCallback<void>): void + +Starts image preview. This API can be used to preview local images whose URIs start with **dataability://** or online images whose URIs start with **https://**. It uses an asynchronous callback to return the execution result. + +This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | --------------------------------------------------- | +| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **https://** or **dataability://**.| +| callback | AsyncCallback<void> | Yes | Callback used to return the image preview result. If the preview fails, an error message is returned. | + +**Example** + + ``` +let images = [ + "dataability:///media/external/images/media/50", + "dataability:///media/external/images/media/55" +]; +let images = [ + "https://media.xxxx.com/image1.jpg", + "https://media.xxxx.com/image2.jpg" +]; +mediaLibrary.getMediaLibrary().startImagePreview(images, (err) => { + if (err) { + console.log("An error occurred when previewing the images."); + return; + } + console.log("Succeeded in previewing the images."); +}); + ``` + + +### startImagePreview + +startImagePreview(images: Array<string>, index?: number): Promise<void> + +Starts image preview, with the first image to preview specified. This API can be used to preview local images whose URIs start with dataability:// or online images whose URIs start with https://. It uses a promise to return the execution result. + +This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------------------- | ---- | --------------------------------------------------- | +| images | Array<string> | Yes | URIs of the images to preview. The value can start with either **https://** or **dataability://**.| +| index | number | No | Index of the first image to preview. If this parameter is not specified, the default value **0** is used. | + +**Return value** + +| Type | Description | +| ------------------- | ------------------------------------------------------- | +| Promise<void> | Promise used to return the image preview result. If the preview fails, an error message is returned.| + +**Example** + + ``` +let images = [ + "dataability:///media/external/images/media/50", + "dataability:///media/external/images/media/55" +]; +let images = [ + "https://media.xxxx.com/image1.jpg", + "https://media.xxxx.com/image2.jpg" +]; +let index = 1; +mediaLibrary.getMediaLibrary().startImagePreview(images, index).then(() => { + console.log("Succeeded in previewing the images."); +}).catch((err) => { + console.log("An error occurred when previewing the images."); +}); + ``` + + +### startMediaSelect + +startMediaSelect(option: MediaSelectOption, callback: AsyncCallback<Array<string>>): void + +Starts media selection. This API uses an asynchronous callback to return the list of URIs that store the selected media assets. + +This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------- | ---- | ------------------------------------------------------- | +| option | [MediaSelectOption](#mediaselectoption) | Yes | Media selection option. | +| callback | AsyncCallback<Array<string>> | Yes | Callback used to return the list of URIs (starting with **dataability://**) that store the selected media assets.| + +**Example** + + ``` +let option = { + type : "image", + count : 2 +}; +mediaLibrary.getMediaLibrary().startMediaSelect(option, (err, value) => { + if (err) { + console.log("An error occurred when selecting the media asset."); + return; + } + console.log("Media asset selected."); + // Obtain the media selection value. +}); + ``` + + +### startMediaSelect + +startMediaSelect(option: MediaSelectOption): Promise<Array<string>> + +Starts media selection. This API uses a promise to return the list of URIs that store the selected media assets. + +This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | --------------------------------------- | ---- | -------------- | +| option | [MediaSelectOption](#mediaselectoption) | Yes | Media selection option.| + +**Return value** + +| Type | Description | +| ---------------------------------- | ------------------------------------------------------------ | +| Promise<Array<string>> | Promise used to return the list of URIs (starting with **dataability://**) that store the selected media assets.| + +**Example** + + ``` +let option = { + type : "image", + count : 2 +}; +mediaLibrary.getMediaLibrary().startMediaSelect(option).then((value) => { + console.log("Media asset selected."); + // Obtain the media selection value. +}).catch((err) => { + console.log("An error occurred when selecting the media assets."); +}); + + ``` + +## FileAsset8+ + +Provides APIs for encapsulating file asset attributes. + +### Attributes + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +| Name | Type | Readable| Writable| Description | +| ------------ | ----------------------- | ---- | ---- | ------------------------------------------------------ | +| id | number | Yes | No | File asset ID. | +| uri | string | Yes | No | File asset URI, for example, dataability:///media/image/2. | +| mimeType | string | Yes | No | Extended file attributes. | +| mediaType | [MediaType](#mediatype) | Yes | No | Media type. | +| displayName | string | Yes | Yes | Display file name, including the file name extension. | +| title | string | Yes | Yes | Title in the file. | +| relativePath | string | Yes | Yes | Relative public directory of the file. | +| parent | number | Yes | No | Parent directory ID. | +| size | number | Yes | No | File size, in bytes. | +| dateAdded | number | Yes | No | Date when the file was added. (The value is the number of seconds elapsed since the Epoch time.) | +| dateModified | number | Yes | No | Date when the file was modified. (The value is the number of seconds elapsed since the Epoch time.) | +| dateTaken | number | Yes | No | Date when the file (photo) was taken. (The value is the number of seconds elapsed since the Epoch time.) | +| artist | string | Yes | No | Artist of the file. | +| audioAlbum | string | Yes | No | Audio album. | +| width | number | Yes | No | Image width, in pixels. | +| height | number | Yes | No | Image height, in pixels. | +| orientation | number | Yes | Yes | Image display direction (clockwise rotation angle, for example, 0, 90, or 180, in degrees).| +| duration | number | Yes | No | Duration, in seconds. | +| albumId | number | Yes | No | ID of the album to which the file belongs. | +| albumUri | string | Yes | No | URI of the album to which the file belongs. | +| albumName | string | Yes | No | Name of the album to which the file belongs. | + + +### isDirectory8+ + +isDirectory(callback: AsyncCallback<boolean>): void + +Checks whether this file asset is a directory. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ----------------------------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return whether the file asset is a directory.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.isDirectory((err, isDirectory) => { + // do something + }); +} +``` + +### isDirectory8+ + +isDirectory():Promise<boolean> + +Checks whether this file asset is a directory. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| ---------------------- | ---------------------------------------- | +| Promise<boolean> | Promise used to return whether the file asset is a directory.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.isDirectory().then(function(isDirectory){ + console.info("isDirectory result:"+ isDirectory); + }).catch(function(err){ + console.info("isDirectory failed with error:"+ err); + }); +} +``` + +### commitModify8+ + +commitModify(callback: AsyncCallback<void>): void + +Commits the modification of this file asset to the database. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Void callback.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.title = 'newtitle'; + asset.commitModify(() => { + console.info('commitModify success'); + }); +} +``` + +### commitModify8+ + +commitModify(): Promise<void> + +Commits the modification of this file asset to the database. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| ------------------- | ------------- | +| Promise<void> | Void promise.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.title = 'newtitle'; + asset.commitModify(); +} +``` + +### open8+ + +open(mode: string, callback: AsyncCallback<number>): void + +Opens this file asset. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA (when **mode** is set to **r**) and ohos.permission.WRITE_MEDIA (when **mode** is set to **w**) + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------- | ---- | -------------------------------------------------------- | +| mode | string | Yes | Mode of opening the file, for example, **r** (read-only), **w** (write-only), and **rw** (read-write).| +| callback | AsyncCallback<number> | Yes | Callback used to return the file handle. | + +**Example** + +``` +async function example() { + let mediaType = mediaLibrary.MediaType.IMAGE; + let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; + const path = await media.getPublicDirectory(DIR_IMAGE); + asset = await media.createAsset(mediaType, "image00003.jpg", path); + asset.open('rw', (openError, fd) => { + if(fd > 0){ + asset.close(fd); + }else{ + console.info('File Open Failed!' + openError); + } + }); +} +``` + +### open8+ + +open(mode: string): Promise<number> + +Opens this file asset. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA (when **mode** is set to **r**) and ohos.permission.WRITE_MEDIA (when **mode** is set to **w**) + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------------------------------------------- | +| mode | string | Yes | Mode of opening the file, for example, **r** (read-only), **w** (write-only), and **rw** (read-write).| + +**Return value** + +| Type | Description | +| --------------------- | ------------------- | +| Promise<number> | Promise used to return the file handle.| + +**Example** + +``` +async function example() { + let mediaType = mediaLibrary.MediaType.IMAGE; + let DIR_IMAGE = mediaLibrary.DirectoryType.DIR_IMAGE; + const path = await media.getPublicDirectory(DIR_IMAGE); + asset = await media.createAsset(mediaType, "image00003.jpg", path); + asset.open('rw') + .then((fd) => { + console.info('File fd!' + fd); + }) + .catch((err) => { + console.info('File err!' + err); + }); +} +``` + +### close8+ + +close(fd: number, callback: AsyncCallback<void>): void + +Closes this file asset. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA ('r' enabled) and ohos.permission.WRITE_MEDIA ('w' enabled) + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| fd | number | Yes | File descriptor.| +| callback | AsyncCallback<void> | Yes | Void callback.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.close(fd, (closeErr) => { + if (closeErr != undefined) { + console.info('mediaLibraryTest : close : FAIL ' + closeErr.message); + console.info('mediaLibraryTest : ASSET_CALLBACK : FAIL'); + } else { + console.info("=======asset.close success====>"); + } + }); +} +``` + +### close8+ + +close(fd: number): Promise<void> + +Closes this file asset. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA ('r' enabled) and ohos.permission.WRITE_MEDIA ('w' enabled) + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------- | +| fd | number | Yes | File descriptor.| + +**Return value** + +| Type | Description | +| ------------------- | ------------- | +| Promise<void> | Void promise.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.close(fd).then((closeErr) => { + if (closeErr != undefined) { + console.info('mediaLibraryTest : close : FAIL ' + closeErr.message); + console.info('mediaLibraryTest : ASSET_CALLBACK : FAIL'); + + } else { + console.info("=======asset.close success====>"); + } + }); +} +``` + +### getThumbnail8+ + +getThumbnail(callback: AsyncCallback<image.PixelMap>): void + +Obtains the thumbnail of this file asset. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------- | ---- | ------------------------ | +| callback | AsyncCallback<image.PixelMap> | Yes | Callback used to return the pixel map of the thumbnail.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.getThumbnail((err, pixelmap) => { + console.info('mediaLibraryTest : getThumbnail Successfull '+ pixelmap); + }); +} +``` + +### getThumbnail8+ + +getThumbnail(size: Size, callback: AsyncCallback<image.PixelMap>): void + +Obtains the thumbnail of this file asset, with the thumbnail size passed. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------- | ---- | ------------------------ | +| size | [Size](#size8) | Yes | Size of the thumbnail. | +| callback | AsyncCallback<image.PixelMap> | Yes | Callback used to return the pixel map of the thumbnail.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.getThumbnail(size, (err, pixelmap) => { + console.info('mediaLibraryTest : getThumbnail Successfull '+ pixelmap); + }); +} +``` + +### getThumbnail8+ + +getThumbnail(size?: Size): Promise<image.PixelMap> + +Obtains the thumbnail of this file asset, with the thumbnail size passed. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | -------------- | ---- | ---------- | +| size | [Size](#size8) | No | Size of the thumbnail.| + +**Return value** + +| Type | Description | +| ----------------------------- | --------------------------- | +| Promise<image.PixelMap> | Promise to return the pixel map of the thumbnail.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.getThumbnail(size, (err, pixelmap) => { + console.info('mediaLibraryTest : getThumbnail Successfull '+ pixelmap); + }); +} +``` + +### favorite8+ + +favorite(isFavorite: boolean, callback: AsyncCallback<void>): void + +Favorites or unfavorites this file asset. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------- | ---- | ---------------------------------------------------------- | +| isFavorite | boolean | Yes | Whether to favorite or unfavorite the file. The value **true** means to favorite the file, and **false** means to unfavorite the file.| +| callback | AsyncCallback<void> | Yes | Void callback. | + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.favorite(true,function(err){ + // do something + }); +} +``` + +### favorite8+ + +favorite(isFavorite: boolean): Promise<void> + +Favorites or unfavorites this file asset. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------- | ---- | ---------------------------------------------------------- | +| isFavorite | boolean | Yes | Whether to favorite or unfavorite the file. The value **true** means to favorite the file, and **false** means to unfavorite the file.| + +**Return value** + +| Type | Description | +| ------------------- | ------------- | +| Promise<void> | Void promise.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.favorite(true).then(function() { + console.info("favorite successfully"); + }).catch(function(err){ + console.info("favorite failed with error:"+ err); + }); +} +``` + +### isFavorite8+ + +isFavorite(callback: AsyncCallback<boolean>): void + +Checks whether this file asset is favorited. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ---------------------- | +| callback | AsyncCallback<boolean> | Yes | Callback used to return whether the file asset is favorited.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.isFavorite((err, isFavorite) => { + if (isFavorite) { + console.info('FileAsset is favorite'); + }else{ + console.info('FileAsset is not favorite'); + } + }); +} +``` + +### isFavorite8+ + +isFavorite():Promise<boolean> + +Checks whether this file asset is favorited. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| ---------------------- | ----------------------------- | +| Promise<boolean> | Promise used to return whether the file asset is favorited.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.isFavorite().then(function(isFavorite){ + console.info("isFavorite result:"+ isFavorite); + }).catch(function(err){ + console.info("isFavorite failed with error:"+ err); + }); +} +``` + +### trash8+ + +trash(isTrash: boolean, callback: AsyncCallback<void>): void + +Moves this file asset to the trash. This API uses an asynchronous callback to return the result. + +Files in the trash are not actually deleted. You can set **isTrash** to **false** to restore the files from the trash. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ------------------ | +| isTrash | boolean | Yes | Whether to move the file asset to the trash. The value **true** means to move the file asset to the trash, and **false** means the opposite.| +| callback | AsyncCallback<void> | Yes | Void callback. | + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.trash(true, trashCallBack); + function trashCallBack(err, trash) { + console.info('mediaLibraryTest : ASSET_CALLBACK ASSET_CALLBACK trash'); + } +} +``` + +### trash8+ + +trash(isTrash: boolean): Promise<void> + +Moves this file asset to the trash. This API uses a promise to return the result. + +Files in the trash are not actually deleted. You can set **isTrash** to **false** to restore the files from the trash. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------- | ---- | ------------------ | +| isTrash | boolean | Yes | Whether to move the file asset to the trash. The value **true** means to move the file asset to the trash, and **false** means the opposite.| + +**Return value** + +| Type | Description | +| ------------------- | ------------- | +| Promise<void> | Void promise.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.trash(true).then(function() { + console.info("trash successfully"); + }).catch(function(err){ + console.info("trash failed with error:"+ err); + }); +} +``` + +### isTrash8+ + +isTrash(callback: AsyncCallback<boolean>): void + +Checks whether this file asset is in the trash. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ------------------------------ | +| callback | AsyncCallback<boolean> | Yes | Callback used to return whether the file asset is in the trash. If the file asset is in the trash, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.isTrash(isTrashCallBack); + function isTrashCallBack(err, isTrash) { + if (isTrash == true) { + console.info('mediaLibraryTest : ASSET_CALLBACK ASSET_CALLBACK isTrash = ' + isTrash); + asset.trash(true, trashCallBack); + + } else { + console.info('mediaLibraryTest : ASSET_CALLBACK isTrash Unsuccessfull = ' + err); + console.info('mediaLibraryTest : ASSET_CALLBACK isTrash : FAIL'); + + } + } +} +``` + +### isTrash8+ + +isTrash():Promise<boolean> + +Checks whether this file asset is in the trash. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| ------------------- | --------------------------------- | +| Promise<void> | Promise used to return whether the file asset is in the trash. If the file asset is in the trash, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const asset = await fetchFileResult.getFirstObject(); + asset.isTrash().then(function(isTrash){ + console.info("isTrash result:"+ isTrash); + }).catch(function(err){ + console.info("isTrash failed with error:"+ err); + }); +} +``` + +## FetchFileResult8+ + +Implements the result set of the file retrieval operation. + +### getCount8+ + +getCount(): number + +Obtains the total number of files in the result set. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| ------ | ---------------- | +| number | Total number of files.| + +**Example** + +``` +async function example() { + let getFileCountOneOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [fileType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getFileCountOneOp); + const fetchCount = fetchFileResult.getCount(); +} +``` + +### isAfterLast8+ + +isAfterLast(): boolean + +Checks whether the cursor is in the last row of the result set. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| ------- | ----------------------------------------------------------- | +| boolean | Returns **true** if the cursor is in the last row of the result set; returns *false** otherwise.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + const fetchCount = fetchFileResult.getCount(); + console.info('mediaLibraryTest : count:' + fetchCount); + let fileAsset = await fetchFileResult.getFirstObject(); + for (var i = 1; i < fetchCount; i++) { + fileAsset = await fetchFileResult.getNextObject(); + if(i == fetchCount - 1) { + console.info('mediaLibraryTest : isLast'); + var result = fetchFileResult.isAfterLast(); + console.info('mediaLibraryTest : isAfterLast:' + result); + console.info('mediaLibraryTest : isAfterLast end'); + fetchFileResult.close(); + + } + } +} +``` + +### close8+ + +close(): void + +Releases and invalidates this **FetchFileResult** instance. Other APIs cannot be invoked after the instance is released. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + fetchFileResult.close(); +} +``` + +### getFirstObject8+ + +getFirstObject(callback: AsyncCallback<FileAsset>): void + +Obtains the first file asset in the result set. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------------------------- | ---- | ------------------------------------------- | +| callback | AsyncCallback<[FileAsset](#fileasset8)> | Yes | Callback used to return the first file asset.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + fetchFileResult.getFirstObject((err, value) => { + if (err) { + console.error('Failed '); + return; + } + console.log(value); + }) +} +``` + +### getFirstObject8+ + +getFirstObject(): Promise<FileAsset> + +Obtains the first file asset in the result set. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| --------------------------------------- | ------------------------ | +| Promise<[FileAsset](#fileasset8)> | Promise used to return the file asset.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + fetchFileResult.getFirstObject().then(function(fileAsset){ + console.info("getFirstObject successfully:"+ JSON.stringify(fileAsset)); + }).catch(function(err){ + console.info("getFirstObject failed with error:"+ err); + }); +} +``` + +### getNextObject8+ + + getNextObject(callback: AsyncCallback<FileAsset>): void + +Obtains the next file asset in the result set. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | --------------------------------------------- | ---- | ----------------------------------------- | +| callbacke | AsyncCallback<[FileAsset](#fileasset8)> | Yes | Callback used to return the next file asset.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + fetchFileResult.getNextObject((err, value) => { + if (err) { + console.error('Failed '); + return; + } + console.log(value); + }) +} +``` + +### getNextObject8+ + + getNextObject(): Promise<FileAsset> + +Obtains the next file asset in the result set. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| --------------------------------------- | ----------------- | +| Promise<[FileAsset](#fileasset8)> | Promise used to return the next file asset.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + const fetchCount = fetchFileResult.getCount(); + console.info('mediaLibraryTest : count:' + fetchCount); + fileAsset = await fetchFileResult.getNextObject(); +} +``` + +### getLastObject8+ + +getLastObject(callback: AsyncCallback<FileAsset>): void + +Obtains the last file asset in the result set. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------------------------- | ---- | --------------------------- | +| callback | AsyncCallback<[FileAsset](#fileasset8)> | Yes | Callback used to return the last file asset.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + fetchFileResult.getLastObject((err, value) => { + if (err) { + console.error('Failed '); + return; + } + console.log(value); + }) +} +``` + +### getLastObject8+ + +getLastObject(): Promise<FileAsset> + +Obtains the last file asset in the result set. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| --------------------------------------- | ----------------- | +| Promise<[FileAsset](#fileasset8)> | Promise used to return the next file asset.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + let lastObject = await fetchFileResult.getLastObject(); +} +``` + +### getPositionObject8+ + +getPositionObject(index: number, callback: AsyncCallback<FileAsset>): void + +Obtains a file asset with the specified index in the result set. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------------------------- | ---- | --------------------------- | +| index | number | Yes | Index of the file asset to obtain. The value starts from **0**.| +| callback | AsyncCallback<[FileAsset](#fileasset8)> | Yes | Callback used to return the last file asset.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + fetchFileResult.getPositionObject(0, (err, value) => { + if (err) { + console.error('Failed '); + return; + } + console.log(value); + }) +} +``` + +### getPositionObject8+ + +getPositionObject(index: number): Promise<FileAsset> + +Obtains a file asset with the specified index in the result set. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----- | ------ | ---- | --------------------------- | +| index | number | Yes | Index of the file asset to obtain. The value starts from **0**.| + +**Return value** + +| Type | Description | +| --------------------------------------- | ----------------- | +| Promise<[FileAsset](#fileasset8)> | Promise used to return the next file asset.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + fetchFileResult.getPositionObject(1, (err, value) => { + if (err) { + console.error('Failed '); + return; + } + console.log(value); + }) +} +``` + +### getAllObject8+ + +getAllObject(callback: AsyncCallback<Array<FileAsset>>): void + +Obtains all the file assets in the result set. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------------- | ---- | ------------------------------- | +| callback | AsyncCallback> | Yes | Callback used to return the file assets.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + fetchFileResult.getAllObject((err, value) => { + if (err) { + console.error('Failed '); + return; + } + console.log(value); + }) +} +``` + +### getAllObject8+ + +getAllObject(): Promise<Array<FileAsset>> + +Obtains all the file assets in the result set. This API uses a promise to return the result. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| ---------------------------------------- | --------------------- | +| Promise> | Promise used to return the file assets.| + +**Example** + +``` +async function example() { + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], + order: fileKeyObj.DATE_ADDED + " DESC", + extendArgs: "", + }; + let fetchFileResult = await media.getFileAssets(getImageOp); + var data = fetchFileResult.getAllObject(); +} +``` + +## Album8+ + +Provides APIs to implement a physical album. + +### **Attributes** + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +| Name | Type| Readable| Writable| Description | +| ------------ | ------ | ---- | ---- | -------------- | +| albumId | number | Yes | No | Album ID. | +| albumName | string | Yes | Yes | Album name. | +| albumUri | string | Yes | No | Album URI. | +| dateModified | number | Yes | No | Date when the album was modified. | +| count | number | Yes | No | Number of files in the album.| +| relativePath | string | Yes | No | Relative path of the album. | +| coverUri | string | Yes | No | URI of the cover file of the album. | + +### commitModify8+ + +commitModify(callback: AsyncCallback<void>): void + +Commits the modification of the album attributes to the database. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| callback | AsyncCallback<void> | Yes | Void callback.| + +**Example** + +``` +async function example() { + let AlbumNoArgsfetchOp = { + selections: '', + selectionArgs: [], + }; + const albumList = await media.getAlbums(AlbumNoArgsfetchOp); + const album = albumList[0]; + album.albumName = 'hello'; + album.commitModify((err) => { + if (err) { + console.error('Failed '); + return; + } + console.log('Modify successful.'); + }) +} +``` + +### commitModify8+ + +commitModify(): Promise<void> + +Commits the modification of the album attributes to the database. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA and ohos.permission.WRITE_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Return value** + +| Type | Description | +| ------------------- | ----------------- | +| Promise<void> | Void promise.| + +**Example** + +``` +async function example() { + let AlbumNoArgsfetchOp = { + selections: '', + selectionArgs: [], + }; + const albumList = await media.getAlbums(AlbumNoArgsfetchOp); + const album = albumList[0]; + album.albumName = 'hello'; + album.commitModify().then(function() { + console.info("commitModify successfully"); + }).catch(function(err){ + console.info("commitModify failed with error:"+ err); + }); +} +``` + +### getFileAssets8+ + +getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void + +Obtains the file assets in this album. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------------------------------- | ---- | --------------------------------- | +| options | [MediaFetchOptions](#mediafetchoptions8) | Yes | Options for fetching the files. | +| callback | AsyncCallback<[FetchFileResult](#fetchfileresult8)> | Yes | Callback used to return the file assets.| + +**Example** + +``` +async function example() { + let AlbumNoArgsfetchOp = { + selections: '', + selectionArgs: [], + }; + const albumList = await media.getAlbums(AlbumNoArgsfetchOp); + const album = albumList[0]; + album.getFileAssets(fileNoArgsfetchOp, getFileAssetsCallBack); + function getFileAssetsCallBack(err, fetchFileResult) { + // do something + } +} +``` + +### getFileAssets8+ + + getFileAssets(options?: MediaFetchOptions): Promise<FetchFileResult> + +Obtains the file assets in this album. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.READ_MEDIA + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------------------------------- | ---- | ------------ | +| options | [MediaFetchOptions](#mediafetchoptions8) | No | Options for fetching the files.| + +**Return value** + +| Type | Description | +| --------------------------------------------- | ----------------------- | +| Promise<[FetchFileResult](#fetchfileresult8)> | Promise used to return the file assets.| + +**Example** + +``` +async function example() { + let AlbumNoArgsfetchOp = { + selections: '', + selectionArgs: [], + }; + const albumList = await media.getAlbums(AlbumNoArgsfetchOp); + const album = albumList[0]; + album.getFileAssets(fileNoArgsfetchOp).then(function(albumFetchFileResult){ + console.info("getFileAssets successfully:"+ JSON.stringify(albumFetchFileResult)); + }).catch(function(err){ + console.info("getFileAssets failed with error:"+ err); + }); +} +``` + +## PeerInfo8+ + +Describes information about a registered device. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +| Name | Type | Readable| Writable| Description | +| ---------- | ---------- | ---- | ---- | ---------------- | +| deviceName | string | Yes | No | Name of the registered device. | +| networkId | string | Yes | No | Network ID of the registered device.| +| deviceType | DeviceType | Yes | No | Type of the registered device. | +| isOnline | boolean | Yes | No | Whether the registered device is online. | + + + +MediaType +--------- + +Enumerates media types. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +| Name | Default Value | Description| +| ----- | ------ | ---- | +| FILE | 0 | File.| +| IMAGE | 1 | Image.| +| VIDEO | 2 | Video.| +| AUDIO | 3 | Audio.| + +FileKey +------- + +Enumerates key file information. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +| Name | Default Value | Description | +| ------------- | ------------------- | ---------------------------------------------------------- | +| ID | file_id | File ID. | +| RELATIVE_PATH | relative_path | Relative public directory of the file. | +| DISPLAY_NAME | display_name | Display file name. | +| PARENT | parent | Parent directory ID. | +| MIME_TYPE | mime_type | Extended file attributes. | +| MEDIA_TYPE | media_type | Media type. | +| SIZE | size | File size, in bytes. | +| 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 was modified. (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.) | +| TITLE | title | Title in the file. | +| ARTIST | artist | Artist of the file. | +| AUDIOALBUM | audio_album | Audio album. | +| DURATION | duration | Duration, in seconds. | +| WIDTH | width | Image width, in pixels. | +| HEIGHT | height | Image height, in pixels. | +| ORIENTATION | orientation | Image display direction (clockwise rotation angle, for example, 0, 90, and 180, in degrees).| +| ALBUM_ID | bucket_id | ID of the album to which the file belongs. | +| ALBUM_NAME | bucket_display_name | Name of the album to which the file belongs. | + +DirectoryType +------------- + +Enumerates directory types. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +| Name | Default Value | Description | +| ------------- | ------ | ------------------ | +| DIR_CAMERA | 0 | Directory of camera files.| +| DIR_VIDEO | 1 | Directory of video files. | +| DIR_IMAGE | 2 | Directory of image files. | +| DIR_AUDIO | 3 | Directory of audio files. | +| DIR_DOCUMENTS | 4 | Directory of documents. | +| DIR_DOWNLOAD | 5 | Download directory. | + +DeviceType +----------- + +Enumerates device types. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +| Name | Default Value | Description | +| ------------ | ------ | ---------- | +| TYPE_UNKNOWN | 0 | Unknown.| +| TYPE_LAPTOP | 1 | Laptop.| +| TYPE_PHONE | 2 | Phone. | +| TYPE_TABLET | 3 | Tablet. | +| TYPE_WATCH | 4 | Smart watch. | +| TYPE_CAR | 5 | Vehicle-mounted device. | +| TYPE_TV | 6 | TV. | + +## MediaFetchOptions8+ + +Describes options for fetching media files. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +| Name | Type | Readable| Writable| Mandatory| Description | +| ------------- | ------------------- | ---- | ---- | ---- | ------------------------------------------------------------ | +| selections | string | Yes | Yes | Yes | Conditions for fetching files. The enumerated values in [FileKey](#filekey) are used as the column names of the conditions. Example:
selections: mediaLibrary.FileKey.MEDIA_TYPE + '= ? OR' +mediaLibrary.FileKey.MEDIA_TYPE + '= ?',| +| selectionArgs | Array<string> | Yes | Yes | Yes | Value of the condition, which corresponds to the value of the condition column in **selections**.
Example:
selectionArgs: [mediaLibrary.MediaType.IMAGE.toString(), mediaLibrary.MediaType.VIDEO.toString()], | +| order | string | Yes | Yes | No | Sorting mode of the search results, which can be ascending or descending. The enumerated values in [FileKey](#filekey) are used as the columns for sorting the search results. Example:
Ascending: order: mediaLibrary.FileKey.DATE_ADDED + " AESC"
Descending: order: mediaLibrary.FileKey.DATE_ADDED + " DESC"| +| uri | string | Yes | Yes | No | File URI. | +| networkId | string | Yes | Yes | No | Network ID of the registered device. | +| extendArgs | string | Yes | Yes | No | Extended parameters for fetching the files. Currently, no extended parameters are available. | + +## Size8+ + +Describes the image size. + +| Name | Type | Readable| Writable| Description | +| ------ | ------ | ---- | ---- | ---------------- | +| width | number | Yes | Yes | Image width, in pixels.| +| height | number | Yes | Yes | Image height, in pixels.| + +## MediaAssetOption + +Implements the media asset option. + +This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + + +| Name | Type | Mandatory| Description | +| ------------ | ------ | ---- | ------------------------------------------------------------ | +| src | string | Yes | URI of the media library. | +| mimeType | string | Yes | Multipurpose Internet Mail Extensions (MIME) type of the media.
Example: 'image/\*' and 'video/\*'.| +| relativePath | string | No | Custom path for storing media assets. If this parameter is unspecified, media assets are stored in the default path. For example, if you set this parameter to **imageDir/image2/**, the media assets will be stored in **default/imageDir/image2/**, where **default** represents the default path.| + +## MediaSelectOption + +Describes media selection option. + +This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.Multimedia.MediaLibrary.Core + +| Name | Type | Mandatory| Description | +| ----- | ------ | ---- | ------------------------------ | +| type | string | Yes | Media type, which can be **image** and **video**.| +| count | number | Yes | Maximum number of media assets that can be selected. |