1# File Subsystem Changelog 2 3## cl.file.1 Change of Compatibility of mediaLibrary APIs 4 5The compatibility of some [mediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md) APIs is changed. 6 71. Due to the change of the directory structure of the file subsystem, the **mediaLibrary** APIs will no longer be used to access document directories (**Documents** and **Download**). Use the [FilePicker](../../../application-dev/reference/apis/js-apis-file-picker.md) APIs instead. 8 9- Before the change, the following directories can be accessed by using **mediaLibrary** APIs: 10 11 **Camera**, **Videos**, **Pictures**, **Audios**, **Documents**, and **Download** 12 13- After the change, the following directories can be accessed by using **mediaLibrary** APIs: 14 15 **Camera**, **Videos**, **Pictures**, and **Audios** 16 172. The URI format of the corresponding assets is changed. For details, see [File Subsystem ChangeLog](../OpenHarmony_4.0.11.2/changelogs-filemanagement.md). 18 19**Change Impact** 20 21For applications developed based on earlier versions, check for the **mediaLibrary** APIs called to access the **Documents** and **Download** directories and use the **FilePicker** APIs. 22 23**Key API/Component Changes** 24 25| Module | Method/Attribute/Enum/Constant | Change Type| 26| ------------------------- | ------------------------------------------------------------ | -------- | 27| medialibrary | **function** getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void | The compatibility of the applicable range of the API is changed. | 28| medialibrary | **function** getFileAssets(options: MediaFetchOptions): Promise<FetchFileResult> | The compatibility of the applicable range of the API is changed. | 29| medialibrary | **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string, callback: AsyncCallback<FileAsset>): void | The compatibility of the applicable range of the API is changed. | 30| medialibrary | **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string): Promise<FileAsset> | The compatibility of the applicable range of the API is changed. | 31| medialibrary | **function** deleteAsset(uri: string, callback: AsyncCallback<void>): void | The compatibility of the applicable range of the API is changed. | 32| medialibrary | **function** deleteAsset(uri: string): Promise<void> | The compatibility of the applicable range of the API is changed. | 33| medialibrary | **function** getPublicDirectory(type: DirectoryType, callback: AsyncCallback<string>): void | The compatibility of the applicable range of the API is changed. | 34| medialibrary | **function** getPublicDirectory(type: DirectoryType): Promise<string> | The compatibility of the applicable range of the API is changed. | 35| medialibrary | **function** storeMediaAsset(option: MediaAssetOption, callback: AsyncCallback<string>): void | The compatibility of the applicable range of the API is changed. | 36| medialibrary | **function** storeMediaAsset(option: MediaAssetOption): Promise<string> | The compatibility of the applicable range of the API is changed. | 37| medialibrary | **interface** DirectoryType | The compatibility of the applicable range of the API is changed. | 38| medialibrary | **interface** MediaAssetOption | The compatibility of the applicable range of the API is changed. | 39 40**getFileAssets**: 41 42The **getFileAssets** API cannot be used to obtain file assets in the **Documents** and **Download** directories. Use the [FilePicker](../../../application-dev/reference/apis/js-apis-file-picker.md) APIs instead. 43 44**createAsset**: 45 46If **relativePath** in **createAsset()** is set to a directory in **Documents** or **Download**), the file asset cannot be created in the specified directory. Use the [FilePicker](../../../application-dev/reference/apis/js-apis-file-picker.md) APIs instead. 47 48**deleteAsset**: 49 50If **URI** in **deleteAsset()** specifies a file asset in the **Documents** or **Download** directory, the specified file asset cannot be deleted. Use [fileAccess.delete](../../../application-dev/reference/apis/js-apis-fileAccess.md) APIs instead. 51 52**getPublicDirectory**: 53 54If **type** in **getPublicDirectory()** is set to **mediaLibrary.DirectoryType.DIR_DOCUMENTS** or **mediaLibrary.DirectoryType.DIR_DOWNLOAD**, the specified file path cannot be obtained. 55 56**storeMediaAsset**: 57 58If **MediaAssetOption.relativePath** in **storeMediaAsset()** is set to a path of the file in the **Documents** or **Download**) directory, the file asset cannot be stored. Use the [FilePicker](../../../application-dev/reference/apis/js-apis-file-picker.md) APIs instead. 59 60**DirectoryType**: 61 62**DirectoryType** does not support **mediaLibrary.DirectoryType.DIR_DOCUMENTS** or **mediaLibrary.DirectoryType.DIR_DOWNLOAD** in **mediaLibrary** APIs. 63 64**MediaAssetOption**: 65 66The **relativePath** in the **MediaAssetOption** attribute cannot be set to the path of a file in the **Documents** or **Download** directory when **storeMediaAsset()** is used. 67 68**Adaptation Guide** 69 70Do not use the **mediaLibrary** APIs to access or operate the files in the **Documents** and **Download** directories. Use the [FilePicker](../../../application-dev/reference/apis/js-apis-file-picker.md) APIs instead. 71 72 73 74Example: 75 76Before the change, the **mediaLibrary** APIs are used to edit files in the **Documents** and **Download** directories. 77 781. Call **getMediaLibrary** to obtain a **mediaLibrary** instance. 792. Create a **MediaFetchOptions** object, and call **getFileAssets** to obtain files in the use file directory. 803. Call the **FetchFileResult** APIs to obtain the file asset of the target file. 814. Call **fileAsset.open** to open the file and obtain the FD. 825. Call [fs.writeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#writesync) to edit the file based on the FD. 836. After the edit, call **fileAsset.close** to close the FD of the file. 847. Call **fetchFileResult.close** to release the resources occupied by **getFileAssets**. 858. Call **release** to release the **mediaLibrary** instance. 86 87**Sample code**: 88 89```js 90import mediaLibrary from '@ohos.multimedia.mediaLibrary'; 91import fs from '@ohos.file.fs'; 92 93async function example() { 94 try { 95 let context = getContext(this); 96 let media = mediaLibrary.getMediaLibrary(context); 97 let fileKeyObj = mediaLibrary.FileKey; 98 let imageType = mediaLibrary.MediaType.IMAGE; 99 let getImageOp = { 100 selections: fileKeyObj.MEDIA_TYPE + '= ?', 101 selectionArgs: [imageType.toString()], 102 order: fileKeyObj.DATE_ADDED + ' DESC', 103 }; 104 const fetchFileResult = await media.getFileAssets(getImageOp); 105 const fileAsset = await fetchFileResult.getFirstObject(); 106 console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName); 107 let fd = await fileAsset.open('rw'); 108 console.info('mediaLibrary fileAsset open fd: ' + fd); 109 let writeLen = fs.writeSync(fd, 'hello, world'); 110 console.info('write data to file succeed and size is: ' + writeLen); 111 fileAsset.close(fd); 112 fetchFileResult.close(); 113 media.release(); 114 } catch (err) { 115 console.error('mediaLibrary fail, err: ' + err); 116 } 117} 118``` 119 120After the change, use **FilePicker** APIs to edit the files in the user file directory. 121 1221. Obtain a **DocumentViewPicker** object. 1232. Call **DocumentViewPicker.select** to select a file. 1243. After a file is selected, the file URI is returned. 1254. After the UI is returned from **DocumentViewPicker**, call [fs.openSync](../../../application-dev/reference/apis/js-apis-file-fs.md#fsopensync) to open the file based on the URI and obtain the FD. 1265. Call [fs.writeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#writesync) to edit the file based on the FD. 1276. After the edit, call [fs.closeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#closesync) to close the FD. 128 129**Sample code**: 130 131```js 132import picker from '@ohos.file.picker'; 133import fs from '@ohos.file.fs'; 134 135let uri; 136 137async function example() { 138 try { 139 let DocumentSelectOptions = new picker.DocumentSelectOptions(); 140 let documentPicker = new picker.DocumentViewPicker(); 141 documentPicker.select(DocumentSelectOptions).then((DocumentSelectResult) => { 142 console.info('DocumentViewPicker.select successfully, DocumentSelectResult uri: ' + JSON.stringify(DocumentSelectResult)); 143 uri = DocumentSelectResult[0]; 144 }).catch((err) => { 145 console.error('DocumentViewPicker.select failed with err: ' + err); 146 }); 147 } catch (err) { 148 console.error('DocumentViewPicker failed with err: ' + err); 149 } 150} 151 152async function writeFile() { 153 try { 154 let file = fs.openSync(uri, fs.OpenMode.READ_WRITE); 155 console.info('DocumentViewPicker file fd: ' + file.fd); 156 let writeLen = fs.writeSync(file.fd, 'hello, world'); 157 console.info('write data to file succeed and size is: ' + writeLen); 158 fs.closeSync(file); 159 } catch (err) { 160 console.error('DocumentViewPicker fail, err: ' + err); 161 } 162} 163``` 164 165Before the change, use the **mediaLibrary** APIs to create a file in the **Documents** and **Download** directories. 166 1671. Call **getMediaLibrary** to obtain a **mediaLibrary** instance. 1682. Call **getPublicDirectory** to obtain the path of the user file directory. 1693. Call **createAsset** to create a file and obtain the file asset. 1704. Call **fileAsset.open** to open the file and obtain the FD. 1715. Call **fs.write** to edit the file based on the FD. 1726. After the edit, call **fileAsset.close** to close the FD of the file. 1737. Call **release** to release the **mediaLibrary** instance. 174 175**Sample code**: 176 177```js 178import mediaLibrary from '@ohos.multimedia.mediaLibrary'; 179import fs from '@ohos.file.fs'; 180 181async function example() { 182 try { 183 let context = getContext(this); 184 let media = mediaLibrary.getMediaLibrary(context); 185 let mediaType = mediaLibrary.MediaType.FILE; 186 let DIR_DOWNLOAD = mediaLibrary.DirectoryType.DIR_DOWNLOAD; 187 const path = await media.getPublicDirectory(DIR_DOWNLOAD); 188 const fileAsset = await media.createAsset(mediaType, 'test.txt', path); 189 console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName); 190 let fd = await fileAsset.open('rw'); 191 console.info('mediaLibrary fileAsset open fd: ' + fd); 192 let writeLen = fs.writeSync(fd, 'hello, world'); 193 console.info('write data to file succeed and size is: ' + writeLen); 194 fileAsset.close(fd); 195 media.release(); 196 } catch (err) { 197 console.error('mediaLibrary fail, err: ' + err); 198 } 199} 200``` 201 202After the change, use **FilePicker** APIs to create a file in the **Documents** and **Download** directories. 203 2041. Obtain a **DocumentViewPicker** object. 2052. Call **DocumentViewPicker.save** to create and save an empty file. 2063. After the file is saved, the file URI is returned. 2074. After the UI is returned from **DocumentViewPicker**, call [fs.openSync](../../../application-dev/reference/apis/js-apis-file-fs.md#fsopensync) to open the file based on the URI and obtain the FD. 2085. Call [fs.writeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#writesync) to edit the file based on the FD. 2096. After the edit, call [fs.closeSync](../../../application-dev/reference/apis/js-apis-file-fs.md#closesync) to close the FD. 210 211**Sample code**: 212 213```js 214import picker from '@ohos.file.picker'; 215import fs from '@ohos.file.fs'; 216 217let uri; 218 219async function example() { 220 try { 221 let DocumentSaveOptions = new picker.DocumentSaveOptions(); 222 DocumentSaveOptions.newFileNames = ['DocumentViewPicker01.txt']; 223 let documentPicker = new picker.DocumentViewPicker(); 224 documentPicker.save(DocumentSaveOptions).then((DocumentSaveResult) => { 225 console.info('DocumentViewPicker.save successfully, DocumentSaveResult uri: ' + JSON.stringify(DocumentSaveResult)); 226 uri = DocumentSaveResult[0]; 227 }).catch((err) => { 228 console.error('DocumentViewPicker.save failed with err: ' + err); 229 }); 230 } catch (err) { 231 console.error('DocumentViewPicker failed with err: ' + err); 232 } 233} 234 235async function writeFile() { 236 try { 237 let file = fs.openSync(uri, fs.OpenMode.READ_WRITE); 238 console.info('DocumentViewPicker file fd: ' + file.fd); 239 let writeLen = fs.writeSync(file.fd, 'hello, world'); 240 console.info('write data to file succeed and size is: ' + writeLen); 241 fs.closeSync(file); 242 } catch (err) { 243 console.error('DocumentViewPicker fail, err: ' + err); 244 } 245} 246``` 247