1# File Subsystem Changelog
2
3## cl.file.1 Change of the mediaLibrary Interface Compatibility
4
5Changed the compatibility of some **mediaLibrary** APIs.
6
7**Change Impact**
8
9The compatibility of some [mediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md) APIs is changed.
10For applications developed based on earlier versions, pay attention to the iterative update of deprecated APIs.
11
12**Key API/Component Changes**
13
14| Module                   | Method/Attribute/Enum/Constant                                         | Change Type|
15| ------------------------- | ------------------------------------------------------------ | -------- |
16| medialibrary   |  **function** getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void | Interface compatibility changed    |
17| medialibrary   |  **function** getFileAssets(options: MediaFetchOptions): Promise<FetchFileResult> | Interface compatibility changed    |
18| medialibrary   |  **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string, callback: AsyncCallback<FileAsset>): void| Interface compatibility changed    |
19| medialibrary   |  **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string): Promise<FileAsset>| Interface compatibility changed    |
20| medialibrary   |  **function** getAlbums(options: MediaFetchOptions, callback: AsyncCallback<Array<Album>>): void | Interface compatibility changed    |
21| medialibrary   |  **function** getAlbums(options: MediaFetchOptions): Promise<Array<Album>> | Interface compatibility changed    |
22| medialibrary   |  **function** FileAsset.commitModify(callback: AsyncCallback<void>): void | Interface compatibility changed    |
23| medialibrary   |  **function** FileAsset.commitModify(): Promise<void> | Interface compatibility changed    |
24| medialibrary   |  **function** FileAsset.deleteAsset(uri: string, callback: AsyncCallback<void>): void | Interface compatibility changed    |
25| medialibrary   |  **function** FileAsset.deleteAsset(uri: string): Promise<void> | Interface compatibility changed    |
26
27**Adaptation Guide**
28
29**getFileAssets**
30
31From API version 10, the albums represented by physical directories are replaced by logical albums, which allow multiple files in an album and presence of a file in multiple albums. This design, however, makes **parent**, **albumId**, **albumUri**, and **albumName** incompatible. They cannot be used as parameters of **MediaFetchOptions** in **getFileAssets()**. The following is an example of incorrect use of the APIs.
32
331. Call [getMediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md#medialibrarygetmedialibrary) to obtain a **MediaLibrary** instance.
342. Call [MediaFetchOptions](../../../application-dev/reference/apis/js-apis-medialibrary.md#mediafetchoptions7) to create the file fetching options.
353. Call [getFileAssets](../../../application-dev/reference/apis/js-apis-medialibrary.md#getfileassets7) to obtain file assets.
36
37**Example (incorrect)**:
38
39```js
40import mediaLibrary from '@ohos.multimedia.mediaLibrary';
41
42async function example() {
43  try {
44    let context = getContext(this);
45    let media = mediaLibrary.getMediaLibrary(context);
46    let fileKeyObj = mediaLibrary.FileKey;
47    let albumId = 1;
48    let getImageOp = {
49      selections: fileKeyObj.ALBUM_ID + '= ?', // File assets cannot be obtained based on the parent, albumId, albumUri, and albumName attributes.
50      selectionArgs: [albumId.toString()],
51    };
52    const fetchFileResult = await media.getFileAssets(getImageOp); // The obtained fetchFileResult is empty.
53    const fileAsset = await fetchFileResult.getFirstObject();
54    console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName);
55  } catch (err) {
56    console.error('mediaLibrary fail, err: ' + err);
57  }
58}
59```
60
61Use **getFileAssets()** as follows:
62
63**Example (correct)**:
64
65```js
66import mediaLibrary from '@ohos.multimedia.mediaLibrary';
67
68async function example() {
69  try {
70    let context = getContext(this);
71    let media = mediaLibrary.getMediaLibrary(context);
72    let fileKeyObj = mediaLibrary.FileKey;
73    let imageType = mediaLibrary.MediaType.IMAGE;
74    let getImageOp = {
75      selections: fileKeyObj.MEDIA_TYPE + '= ?',
76      selectionArgs: [imageType.toString()], // Query all files of the image type.
77    };
78    const fetchFileResult = await media.getFileAssets(getImageOp);
79    const fileAsset = await fetchFileResult.getFirstObject();
80    console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName);
81  } catch (err) {
82    console.error('mediaLibrary fail, err: ' + err);
83  }
84}
85```
86
87**createAsset**
88
89Since the SDK of API version 10, **relativePath** is no longer associated with an album. After a file is created, the last-level directory of **relativePath** is not displayed as an album.
90
91**getAlbums**
92
93Since the SDK of API version 10, **relativePath** is no longer associated with an album. Therefore, **relativePath** cannot be used as a search criterion in **getAlbums**, and the values of **ALBUM_NAME** can be **Camera** and **Screenshots** only. The following is an example of incorrect use of the APIs.
94
951. Use [getMediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md#medialibrarygetmedialibrary) to obtain a **MediaLibrary** instance.
962. Use [MediaFetchOptions](../../../application-dev/reference/apis/js-apis-medialibrary.md#mediafetchoptions7) to create the album fetching options.
973. Use [getAlbums](../../../application-dev/reference/apis/js-apis-medialibrary.md#getalbums7) to obtain albums.
98
99**Example (incorrect)**:
100
101```js
102import mediaLibrary from '@ohos.multimedia.mediaLibrary';
103
104async function example() {
105  try {
106    let context = getContext(this);
107    let media = mediaLibrary.getMediaLibrary(context);
108    let AlbumNoArgsfetchOp = {
109      selections: mediaLibrary.FileKey.ALBUM_NAME + ' = ?',
110      selectionArgs:['New album 1'], //Obtain the album named New album 1.
111    };
112    const albumList = await media.getAlbums(AlbumNoArgsfetchOp); // The fetchFileResult returned is empty.
113    for (let i = 0; i < albumList.length; i++) {
114      console.info('mediaLibrary album albumName: ' + albumList[i].albumName);
115    }
116  } catch (err) {
117    console.error('mediaLibrary fail, err: ' + err);
118  }
119}
120```
121
122The following example shows how to obtain **Camera** and **Screenshots** albums:
123
124**Example (correct)**:
125
126```js
127import mediaLibrary from '@ohos.multimedia.mediaLibrary';
128
129async function example() {
130  try {
131    let context = getContext(this);
132    let media = mediaLibrary.getMediaLibrary(context);
133    let AlbumNoArgsfetchOp = {
134      selections: mediaLibrary.FileKey.ALBUM_NAME + ' = ? OR ' + mediaLibrary.FileKey.ALBUM_NAME + ' = ?',
135      selectionArgs: ['Camera', 'Screenshots'], // Obtain the camera and screenshot albums.
136    };
137    const albumList = await media.getAlbums(AlbumNoArgsfetchOp);
138    for (let i = 0; i < albumList.length; i++) {
139      console.info('mediaLibrary album albumName: ' + albumList[i].albumName);
140    }
141  } catch (err) {
142    console.error('mediaLibrary fail, err: ' + err);
143  }
144}
145```
146
147**FileAsset.commitModify**
148
149The **orientation** attribute for audio is deleted from the SDK of API version 10. When **commitModify** is used, the **orientation** attribute of audio resources cannot be modified.
150
151**FileAsset.deleteAsset**
152
153The change has resolved a known issue of the file deletion mechanism. This issue may cause a system application to permanently delete a file that is not in the trash using **MediaLibrary.deleteAsset**.
154
155The correct procedure for a system application to permanently delete a file is as follows:
156
1571. Call [getFileAssets](../../../application-dev/reference/apis/js-apis-medialibrary.md#getfileassets7) to obtain file assets.
1582. Call [FileAsset.trash](../../../application-dev/reference/apis/js-apis-medialibrary.md#trash8) to move the file to the trash.
1593. Call [MediaLibrary.deleteAsset](../../../application-dev/reference/apis/js-apis-medialibrary.md#deleteasset8) to permanently delete the file.
160
161**Example (correct)**:
162
163```js
164import mediaLibrary from '@ohos.multimedia.mediaLibrary';
165
166async function example() {
167  try {
168    let context = getContext(this);
169    let media = mediaLibrary.getMediaLibrary(context);
170    let fileKeyObj = mediaLibrary.FileKey;
171    let imageType = mediaLibrary.MediaType.IMAGE;
172    let getImageOp = {
173      selections: fileKeyObj.MEDIA_TYPE + '= ?',
174      selectionArgs: [imageType.toString()],
175    };
176    const fetchFileResult = await media.getFileAssets(getImageOp);
177    const fileAsset = await fetchFileResult.getFirstObject();
178    // Delete the file (move it to the trash of Gallery).
179    await fileAsset.trash(true);
180    // Delete the file from the system permanently.
181    await media.deleteAsset(fileAsset.uri);
182  } catch (err) {
183    console.error('Failed to delete asset permanently from system, error: ' + err);
184  }
185}
186```
187