1# User File Access and Management 2 3The **fileManager** module provides APIs for accessing and managing user files. It interworks with the underlying file management services to implement media library and external card management, and provides capabilities for applications to query and create user files. 4 5>**NOTE**<br/> 6> 7>- The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8>- The APIs of this module are system APIs and cannot be called by third-party applications. Currently, these APIs can be called only by **filepicker**. 9 10## Modules to Import 11 12```js 13import filemanager from '@ohos.fileManager'; 14``` 15 16## filemanager.getRoot 17 18getRoot(options? : {dev? : DevInfo}) : Promise<FileInfo[]> 19 20Obtains information about the root album or directory in asynchronous mode. This API uses a promise to return the result. 21 22**System capability**: SystemCapability.FileManagement.UserFileService 23 24**Parameters** 25| Name| Type| Mandatory| Description| 26| --- | --- | --- | -- | 27| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.| 28 29**Return value** 30 31| Type| Description| 32| --- | -- | 33| Promise<[FileInfo](#fileinfo)[]> | Promise used to return the root album or directory information obtained.| 34 35**Example** 36 37 ```js 38 filemanager.getRoot().then((fileInfos) => { 39 for (var i = 0; i < fileInfos.length; i++) { 40 console.log("files:"+JSON.stringify(fileInfos)); 41 } 42 }).catch((err) => { 43 console.log(err) 44 }); 45 ``` 46 47## filemanager.getRoot 48 49getRoot(options? : {dev? : DevInfo}, callback : AsyncCallback<FileInfo[]>) : void 50 51Obtains information about the root album or directory in asynchronous mode. This API uses a callback to return the result. 52 53**System capability**: SystemCapability.FileManagement.UserFileService 54 55**Parameters** 56 57| Name | Type | Mandatory| Description | 58| -------- | ------------------------- | ---- | ----------------------------- | 59| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.| 60| callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the root album or directory information obtained. | 61 62**Example** 63 64 ```js 65 let options = { 66 "dev":{ 67 "name":"local" 68 } 69 }; 70 filemanager.getRoot(options, (err, fileInfos)=>{ 71 for (var i = 0; i < fileInfos.length; i++) { 72 console.log("files:"+JSON.stringify(fileInfos)); 73 } 74 }); 75 ``` 76 77## filemanager.listFile 78 79listFile(path : string, type : string, options? : {dev? : DevInfo, offset? : number, count? : number}) : Promise<FileInfo[]> 80 81Obtains information about the second-level album or files in asynchronous mode. This API uses a promise to return the result. 82 83**System capability**: SystemCapability.FileManagement.UserFileService 84 85**Parameters** 86| Name| Type| Mandatory| Description| 87| --- | --- | --- | -- | 88| path | string | Yes| URI of the directory to query.| 89| type | string | Yes| Type of the files to query. The file type can be **file**, **image**, **audio**, or **video**.| 90| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.<br>- **offset**: position to start the query. The value is a number.<br>- **count**: number of files to query.| 91 92**Return value** 93 94| Type| Description| 95| --- | -- | 96| Promise<FileInfo[]> | Promise used to return the album or file information obtained.| 97 98**Error** 99 100| Error Info| Error Code|Description| 101| -- | --- | -- | 102| No such file or directory | 2 | The directory or album of the specified URI does not exist.| 103| No such process | 3 | Failed to obtain the FMS service.| 104| Not a directory | 20 | The object specified by the URI is not a directory or album.| 105 106**Example** 107 108 ```js 109 // Obtain all files in the directory. You can use getRoot to obtain the directory URI. 110 filemanager.getRoot().then((fileInfos) => { 111 let file = fileInfos.find(item => item.name == "file_folder"); 112 let path = file.path; 113 filemanager.listFile(path, "file").then((files) => { 114 console.log("files:" + JSON.stringify(files)); 115 }).catch((err) => { 116 console.log("failed to get files" + err); 117 }); 118 }).catch((err) => { 119 console.log("failed to get root" + err); 120 }); 121 ``` 122 123## filemanager.listFile 124 125listFile(path : string, type : string, options? : {dev? : DevInfo, offset? : number, count? : number}, callback : AsyncCallback<FileInfo[]>) : void 126 127Obtains information about the second-level album or files in asynchronous mode. This API uses a callback to return the result. 128 129**System capability**: SystemCapability.FileManagement.UserFileService 130 131**Parameters** 132 133| Name | Type | Mandatory| Description | 134| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 135| path | string | Yes | URI of the directory to query. | 136| type | string | Yes | Type of the files to query. The file type can be **file**, **image**, **audio**, or **video**.| 137| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.<br>- **offset**: position to start the query. The value is a number.<br>- **count**: number of files to query.| 138| callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the root album or directory information obtained. | 139 140**Error** 141 142| Error Info | Error Code| Description | 143| ------------------------- | ------ | ------------------------- | 144| No such file or directory | 2 | The directory or album of the specified URI does not exist.| 145| No such process | 3 | Failed to obtain the FMS service. | 146| Not a directory | 20 | The object specified by the URI is not a directory or album.| 147 148**Example** 149 150```js 151// Obtain all files in the directory. You can use getRoot to obtain the directory URI. 152filemanager.getRoot().then((fileInfos) => { 153 let file = fileInfos.find(item => item.name == "image_album"); 154 let path = file.path; 155 filemanager.listFile(path, "image",function(err, files){ 156 console.log("files:" + JSON.stringify(files)); 157 }) 158}).catch((err) => { 159 console.log("failed to get root" + err); 160}); 161``` 162 163## filemanager.createFile 164 165createFile(path : string, filename : string, options? : {dev? : DevInfo}) : Promise<string> 166 167Creates a file in the specified path in asynchronous mode. This API uses a promise to return the result. 168 169**System capability**: SystemCapability.FileManagement.UserFileService 170 171**Parameters** 172| Name| Type| Mandatory| Description| 173| --- | --- | --- | -- | 174| filename | string | Yes| Name of the file to create.| 175| path | string | Yes| URI of the file to create.| 176| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.| 177 178**Return value** 179 180| Type| Description| 181| --- | -- | 182| Promise<string> | Promise used to return the URI of the file created.| 183 184**Error** 185 186| Error Info| Error Code|Description| 187| -- | --- | -- | 188| Operation not permitted | 1 | A file with the same name already exists.| 189| No such file or directory | 2 | The directory or album of the specified URI does not exist.| 190| No such process | 3 | Failed to obtain the FMS service.| 191| Not a directory | 20 | The object specified by the URI is not a directory or album.| 192 193**Example** 194 195 ```js 196 // Create a file. 197 let media_path = "" // Obtain the file URI using listFile() and getRoot(). 198 let name = "xxx.jpg" // File to be saved. 199 filemanager.createFile(media_path, name).then((uri) => { 200 // The URI of the file created is returned. 201 console.log("file uri:"+uri); 202 }).catch((err) => { 203 console.log(err); 204 }); 205 ``` 206 207## filemanager.createFile 208 209createFile(path : string, filename: string, options? : {dev? : DevInfo}, callback : AsyncCallback<string>) : void 210 211Creates a file in the specified path in asynchronous mode. This API uses a callback to return the result. 212 213**System capability**: SystemCapability.FileManagement.UserFileService 214 215**Parameters** 216 217| Name | Type | Mandatory| Description | 218| -------- | ------------------------- | ---- | ----------------------------- | 219| filename | string | Yes | Name of the file to create. | 220| path | string | Yes | URI of the file to create. | 221| options | Object | No| The options are as follows:<br>- **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.| 222| callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the root album or directory information obtained. | 223 224**Error** 225 226| Error Info | Error Code| Description | 227| ------------------------- | ------ | ------------------------- | 228| Operation not permitted | 1 | A file with the same name already exists. | 229| No such file or directory | 2 | The directory or album of the specified URI does not exist.| 230| No such process | 3 | Failed to obtain the FMS service. | 231| Not a directory | 20 | The object specified by the URI is not a directory or album.| 232 233**Example** 234 235 ```js 236 // Create a file. 237 // Call listFile() and getRoot() to obtain the file URI. 238 let media_path = "" 239 // File to be saved. 240 let name = "xxx.jpg" 241 let options = { 242 "dev":{ 243 "name":"local" 244 } 245 }; 246 filemanager.createFile(media_path, name, options, function(err, uri) { 247 // The URI of the file created is returned. 248 console.log("file uri:"+uri); 249 }); 250 251 ``` 252 253## FileInfo 254Defines the file information returned by **getRoot()** or **listFile()**. 255 256**System capability**: SystemCapability.FileManagement.UserFileService 257 258### Attributes 259 260| Name| Type| Readable| Writable| Description| 261| --- | -- | -- | -- | -- | 262| name | string | Yes| No| File name.| 263| path | string | Yes| No| URI of the file.| 264| type | string | Yes| No| File type.| 265| size | number | Yes| No| File size.| 266| addedTime | number | Yes| No| Time when the file was scanned to the database.| 267| modifiedTime | number | Yes| No| Time when the file was modified.| 268 269## DevInfo 270 271Defines the device type. 272 273**System capability**: SystemCapability.FileManagement.UserFileService 274 275### Attributes 276 277| Name| Type | Readable| Writable| Description | 278| ------ | ------ | ---- | ---- | -------- | 279| name | string | Yes | Yes | Device name.| 280
