# MediaLibrary > **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.getMediaLibrary8+ getMediaLibrary(context: Context): MediaLibrary Obtains a **MediaLibrary** instance, which is used to access and modify personal media data such as audios, videos, images, and documents. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core **Parameters** | Name | Type | Mandatory| Description | | ------- | ------- | ---- | -------------------------- | | context | Context | Yes | Context of the ability.| **Return value** | Type | Description | | ----------------------------- | :---- | | [MediaLibrary](#medialibrary) | **MediaLibrary** instance.| **Example (from API version 9)** ``` var media = mediaLibrary.getMediaLibrary(this.context); ``` **Example (API version 8)** ``` import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext() var media = mediaLibrary.getMediaLibrary(context); ``` ## mediaLibrary.getMediaLibrary getMediaLibrary(): MediaLibrary Obtains a **MediaLibrary** instance, which is used to access and modify personal media data such as audios, videos, images, and documents. > **NOTE** > > This API is no longer maintained since API version 8. You are advised to use [mediaLibrary.getMediaLibrary8+](#medialibrarygetmedialibrary8) instead. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core **Return value** | Type | Description | | ----------------------------- | :--------- | | [MediaLibrary](#medialibrary) | **MediaLibrary** instance.| **Example** ```js var media = mediaLibrary.getMediaLibrary(); ``` ## MediaLibrary ### getFileAssets7+ 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](#mediafetchoptions7) | Yes | Options for fetching the files. | | callback | AsyncCallback<[FetchFileResult](#fetchfileresult7)> | Yes | Asynchronous callback of **FetchFileResult**.| **Example** ``` let fileKeyObj = mediaLibrary.FileKey let imageType = mediaLibrary.MediaType.IMAGE let imagesfetchOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], }; media.getFileAssets(imagesfetchOp, (error, fetchFileResult) => { if (fetchFileResult != undefined) { console.info('mediaLibraryTest : ASSET_CALLBACK fetchFileResult success'); fetchFileResult.getAllObject((err, fileAssetList) => { if (fileAssetList != undefined) { fileAssetList.forEach(function(getAllObjectInfo){ console.info("getAllObjectInfo.displayName :" + getAllObjectInfo.displayName); }); } }); } }); ``` ### getFileAssets7+ 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](#mediafetchoptions7) | Yes | Options for fetching the files.| **Return value** | Type | Description | | ------------------------------------ | -------------- | | [FetchFileResult](#fetchfileresult7) | 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()], }; media.getFileAssets(imagesfetchOp).then(function(fetchFileResult){ console.info("getFileAssets successfully: image number is "+ fetchFileResult.getCount()); }).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** ``` media.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** ``` media.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](#mediatype8) | 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](#fileasset7)> | 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); media.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](#mediatype8) | 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](#fileasset7) | 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); media.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](#directorytype8) | 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](#directorytype8) | 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'); } } ``` ### getAlbums7+ 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](#mediafetchoptions7) | Yes | Options for fetching the albums. | | callback | AsyncCallback<Array<[Album](#album7)>> | Yes | Callback used to return the albums.| **Example** ``` let AlbumNoArgsfetchOp = { selections: '', selectionArgs: [], }; media.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); } }) ``` ### getAlbums7+ 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](#mediafetchoptions7) | Yes | Options for fetching the albums.| **Return value** | Type | Description | | -------------------------------- | ------------- | | Promise> | Promise used to return the albums.| **Example** ``` let AlbumNoArgsfetchOp = { selections: '', selectionArgs: [], }; media.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** ``` media.release() ``` ### storeMediaAsset(deprecated) 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. > **NOTE** > > This API is deprecated since API version 9. **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 : "/data/storage/el2/base/haps/entry/image.png", mimeType : "image/*", relativePath : "Pictures/" }; 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(deprecated) storeMediaAsset(option: MediaAssetOption): Promise<string> Stores a media asset. This API uses a promise to return the URI that stores the media asset. > **NOTE** > > This API is deprecated since API version 9. **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 : "/data/storage/el2/base/haps/entry/image.png", mimeType : "image/*", relativePath : "Pictures/" }; 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(deprecated) 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. > **NOTE** > > This API is deprecated since API version 9. You are advised to use the **\<[Image](../arkui-ts/ts-basic-components-image.md)>** component instead. The **\** component can be used to render and display local and online images. **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 **dataability://** or **https://**.| | 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/xxxx/2", "dataability:///media/xxxx/3" ]; /* Preview online images. 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(deprecated) 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. > **NOTE** > > This API is deprecated since API version 9. You are advised to use the **\<[Image](../arkui-ts/ts-basic-components-image.md)>** component instead. The **** component can be used to render and display local images and network images. **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/xxxx/2", "dataability:///media/xxxx/3" ]; /* Preview online images. 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(deprecated) 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. > **NOTE** > > This API is deprecated since API version 9. You are advised to use the **\<[Image](../arkui-ts/ts-basic-components-image.md)>** component instead. The **** component can be used to render and display local images and network images. **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 **dataability://** or **https://**.| | 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/xxxx/2", "dataability:///media/xxxx/3" ]; /* Preview online images. 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(deprecated) 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. > **NOTE** > > This API is deprecated since API version 9. You are advised to use the system app Gallery instead. Gallery is a built-in visual resource access application that provides features such as image and video management and browsing. For details about how to use Gallery, visit [OpenHarmony/applications_photos](https://gitee.com/openharmony/applications_photos). **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 : "media", 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(deprecated) 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. > **NOTE** > > This API is deprecated since API version 9. You are advised to use the system app Gallery instead. Gallery is a built-in visual resource access application that provides features such as image and video management and browsing. For details about how to use Gallery, visit [OpenHarmony/applications_photos](https://gitee.com/openharmony/applications_photos). **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 : "media", 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."); }); ``` ## FileAsset7+ 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. | | mediaType8+ | [MediaType](#mediatype8) | Yes | No | Media type. | | displayName | string | Yes | Yes | Display file name, including the file name extension. | | title | string | Yes | Yes | Title in the file. | | relativePath8+ | string | Yes | Yes | Relative public directory of the file. | | parent8+ | 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.) | | artist8+ | string | Yes | No | Artist of the file. | | audioAlbum8+ | 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).| | duration8+ | number | Yes | No | Duration, in ms. | | albumId | number | Yes | No | ID of the album to which the file belongs. | | albumUri8+ | 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 fileKeyObj = mediaLibrary.FileKey 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 fileKeyObj = mediaLibrary.FileKey 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 in 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 fileKeyObj = mediaLibrary.FileKey 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 in 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 fileKeyObj = mediaLibrary.FileKey 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. > **NOTE** > > Currently, the write operations are mutually exclusive. After the write operation is complete, you must call **close** to release the resource. **Required permissions**: ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA **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); const 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. > **NOTE** > > Currently, the write operations are mutually exclusive. After the write operation is complete, you must call **close** to release the resource. **Required permissions**: ohos.permission.READ_MEDIA or ohos.permission.WRITE_MEDIA **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); const 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 or ohos.permission.WRITE_MEDIA **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 fileKeyObj = mediaLibrary.FileKey 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.open('rw').then((fd) => { console.info('File fd!' + fd); 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====>"); } }); }) .catch((err) => { console.info('File err!' + err); }); } ``` ### 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 or ohos.permission.WRITE_MEDIA **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 fileKeyObj = mediaLibrary.FileKey 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.open('rw').then((fd) => { console.info('File fd!' + fd); 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====>"); } }); }) .catch((err) => { console.info('File err!' + err); }); } ``` ### 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 fileKeyObj = mediaLibrary.FileKey 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 fileKeyObj = mediaLibrary.FileKey let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + " DESC", extendArgs: "", }; let size = { width: 720, height: 720 }; 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 fileKeyObj = mediaLibrary.FileKey let imageType = mediaLibrary.MediaType.IMAGE; let getImageOp = { selections: fileKeyObj.MEDIA_TYPE + '= ?', selectionArgs: [imageType.toString()], order: fileKeyObj.DATE_ADDED + " DESC", extendArgs: "", }; let size = { width: 720, height: 720 }; const fetchFileResult = await media.getFileAssets(getImageOp); const asset = await fetchFileResult.getFirstObject(); asset.getThumbnail(size) .then((pixelmap) => { console.info('mediaLibraryTest : getThumbnail Successfull '+ pixelmap); }) .catch((err) => { console.info('mediaLibraryTest : getThumbnail fail'+ err); }); } ``` ### 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 fileKeyObj = mediaLibrary.FileKey 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 fileKeyObj = mediaLibrary.FileKey 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 fileKeyObj = mediaLibrary.FileKey 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 fileKeyObj = mediaLibrary.FileKey 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 fileKeyObj = mediaLibrary.FileKey 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 fileKeyObj = mediaLibrary.FileKey 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 fileKeyObj = mediaLibrary.FileKey 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, istrashCallBack); } 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 fileKeyObj = mediaLibrary.FileKey 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); }); } ``` ## FetchFileResult7+ Implements the result set of the file retrieval operation. ### getCount7+ 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 fileKeyObj = mediaLibrary.FileKey let fileType = mediaLibrary.MediaType.FILE; 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(); } ``` ### isAfterLast7+ 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 fileKeyObj = mediaLibrary.FileKey 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(); } } } ``` ### close7+ close(): void Releases and invalidates this **FetchFileResult** instance. Other APIs in this instance cannot be invoked after it is released. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core **Example** ``` async function example() { let fileKeyObj = mediaLibrary.FileKey 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(); } ``` ### getFirstObject7+ 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](#fileasset7)> | Yes | Callback used to return the first file asset.| **Example** ``` async function example() { let fileKeyObj = mediaLibrary.FileKey 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, fileAsset) => { if (err) { console.error('Failed '); return; } console.log('fileAsset.displayName : ' + fileAsset.displayName); }) } ``` ### getFirstObject7+ 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](#fileasset7)> | Promise used to return the file asset.| **Example** ``` async function example() { let fileKeyObj = mediaLibrary.FileKey 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); }); } ``` ### getNextObject7+ getNextObject(callback: AsyncCallback<FileAsset>): void Obtains the next 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 | | --------- | --------------------------------------------- | ---- | ----------------------------------------- | | callbacke | AsyncCallback<[FileAsset](#fileasset7)> | Yes | Callback used to return the next file asset.| **Example** ``` async function example() { let fileKeyObj = mediaLibrary.FileKey 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, fileAsset) => { if (err) { console.error('Failed '); return; } console.log('fileAsset.displayName : ' + fileAsset.displayName); }) } ``` ### getNextObject7+ getNextObject(): Promise<FileAsset> Obtains the next 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](#fileasset7)> | Promise used to return the next file asset.| **Example** ``` async function example() { let fileKeyObj = mediaLibrary.FileKey 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.getNextObject(); } ``` ### getLastObject7+ 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](#fileasset7)> | Yes | Callback used to return the last file asset.| **Example** ``` async function example() { let fileKeyObj = mediaLibrary.FileKey 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, fileAsset) => { if (err) { console.error('Failed '); return; } console.log('fileAsset.displayName : ' + fileAsset.displayName); }) } ``` ### getLastObject7+ 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](#fileasset7)> | Promise used to return the next file asset.| **Example** ``` async function example() { let fileKeyObj = mediaLibrary.FileKey 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(); } ``` ### getPositionObject7+ 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](#fileasset7)> | Yes | Callback used to return the last file asset.| **Example** ``` async function example() { let fileKeyObj = mediaLibrary.FileKey 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, fileAsset) => { if (err) { console.error('Failed '); return; } console.log('fileAsset.displayName : ' + fileAsset.displayName); }) } ``` ### getPositionObject7+ 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. **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](#fileasset7)> | Promise used to return the next file asset.| **Example** ``` async function example() { let fileKeyObj = mediaLibrary.FileKey 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, fileAsset) => { if (err) { console.error('Failed '); return; } console.log('fileAsset.displayName : ' + fileAsset.displayName); }) } ``` ### getAllObject7+ 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. **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 fileKeyObj = mediaLibrary.FileKey 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, fileAsset) => { if (err) { console.error('Failed '); return; } console.log('fileAsset.displayName : ' + fileAsset.displayName); }) } ``` ### getAllObject7+ 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 fileKeyObj = mediaLibrary.FileKey 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(); } ``` ## Album7+ 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. | | albumUri8+ | string | Yes | No | Album URI. | | dateModified | number | Yes | No | Date when the album was modified. | | count8+ | number | Yes | No | Number of files in the album.| | relativePath8+ | string | Yes | No | Relative path of the album. | | coverUri8+ | string | Yes | No | URI of the cover file of the album.| ### commitModify8+ commitModify(callback: AsyncCallback<void>): void Commits the modification in 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 in 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); }); } ``` ### getFileAssets7+ 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](#mediafetchoptions7) | Yes | Options for fetching the files. | | callback | AsyncCallback<[FetchFileResult](#fetchfileresult7)> | Yes | Callback used to return the file assets.| **Example** ``` async function example() { let AlbumNoArgsfetchOp = { selections: '', selectionArgs: [], }; let fileNoArgsfetchOp = { selections: '', selectionArgs: [], } const albumList = await media.getAlbums(AlbumNoArgsfetchOp); const album = albumList[0]; album.getFileAssets(fileNoArgsfetchOp, getFileAssetsCallBack); function getFileAssetsCallBack(err, fetchFileResult) { // do something } } ``` ### getFileAssets7+ 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](#mediafetchoptions7) | No | Options for fetching the files.| **Return value** | Type | Description | | --------------------------------------------- | ------------------------- | | Promise<[FetchFileResult](#fetchfileresult7)> | Promise used to return the file assets.| **Example** ``` async function example() { let AlbumNoArgsfetchOp = { selections: '', selectionArgs: [], }; let fileNoArgsfetchOp = { 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. This is a system API. **System capability**: SystemCapability.Multimedia.MediaLibrary.DistributedCore | Name | Type | Readable| Writable| Description | | ---------- | -------------------------- | ---- | ---- | ---------------- | | deviceName | string | Yes | No | Name of the registered device. | | networkId | string | Yes | No | Network ID of the registered device.| | deviceType | [DeviceType](#devicetype8) | Yes | No | Type of the registered device. | | isOnline | boolean | Yes | No | Whether the registered device is online. | ## MediaType8+ Enumerates media types. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core | Name | Description| | ----- | ---- | | FILE | File.| | IMAGE | Image.| | VIDEO | Video.| | AUDIO | Audio.| ## FileKey8+ 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 ms. | | 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. | ## DirectoryType8+ Enumerates directory types. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core | Name | Description | | ------------- | ------------------ | | DIR_CAMERA | Directory of camera files.| | DIR_VIDEO | Directory of video files. | | DIR_IMAGE | Directory of image files. | | DIR_AUDIO | Directory of audio files. | | DIR_DOCUMENTS | Directory of documents. | | DIR_DOWNLOAD | Download directory. | ## DeviceType8+ Enumerates device types. This is a system API. **System capability**: SystemCapability.Multimedia.MediaLibrary.DistributedCore | Name | Description | | ------------ | ---------- | | TYPE_UNKNOWN | Unknown.| | TYPE_LAPTOP | Laptop.| | TYPE_PHONE | Phone. | | TYPE_TABLET | Tablet. | | TYPE_WATCH | Smart watch. | | TYPE_CAR | Vehicle-mounted device. | | TYPE_TV | TV. | ## MediaFetchOptions7+ 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](#filekey8) 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](#filekey8) 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"| | uri8+ | string | Yes | Yes | No | File URI. | | networkId8+ | string | Yes | Yes | No | Network ID of the registered device. | | extendArgs8+ | string | Yes | Yes | No | Extended parameters for fetching the files. Currently, no extended parameters are available. | ## Size8+ Describes the image size. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core | Name | Type | Readable | Writable | Description | | ------ | ------ | ---- | ---- | -------- | | width | number | Yes | Yes | Image width, in pixels.| | height | number | Yes | Yes | Image height, in pixels.| ## MediaAssetOption(deprecated) Implements the media asset option. > **NOTE** > > This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core | Name | Type | Mandatory| Description | | ------------ | ------ | ---- | ------------------------------------------------------------ | | src | string | Yes | Application sandbox oath of the local file. | | mimeType | string | Yes | Multipurpose Internet Mail Extensions (MIME) type of the media.
The value can be 'image/\*', 'video/\*', 'audio/\*' or 'file\*'.| | relativePath | string | No | Custom path for storing media assets, for example, 'Pictures/'. If this parameter is unspecified, media assets are stored in the default path.
Default path of images: 'Pictures/'
Default path of videos: 'Videos/'
Default path of audios: 'Audios/'
Default path of files: 'Documents/'| ## MediaSelectOption(deprecated) Describes media selection option. > **NOTE** > > This API is deprecated since API version 9. **System capability**: SystemCapability.Multimedia.MediaLibrary.Core | Name | Type | Mandatory | Description | | ----- | ------ | ---- | -------------------- | | type | string | Yes | Media type, which can be **image**, **media**, or **video**. Currently, only **media** is supported.| | count | number | Yes | Number of media assets selected. The value starts from 1, which indicates that one media asset can be selected. |