• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.file.volumeManager (Volume Management)
2
3The **volumeManager** module provides APIs for volume and disk management, including obtaining volume information, mounting or unmounting a volume, partitioning a disk, and formatting a volume.
4
5> **NOTE**
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 provided by this module are system APIs.
9> - The APIs of this module support processing of error codes. For details, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
10
11## Modules to Import
12
13```js
14import volumemanager from "@ohos.file.volumeManager";
15```
16
17## volumemanager.getAllVolumes
18
19getAllVolumes(): Promise<Array<Volume>>
20
21Obtains information about all volumes of this external storage device. This API uses a promise to return the result.
22
23**Required permissions**: ohos.permission.STORAGE_MANAGER
24
25**System capability**: SystemCapability.FileManagement.StorageService.Volume
26
27**Return value**
28
29| Type                              | Description                      |
30| ---------------------------------- | -------------------------- |
31| Promise<[Volume](#volume)[]> | Promise used to return information about all available volumes.|
32
33**Example**
34
35  ```js
36  volumemanager.getAllVolumes().then(function(volumes){
37      // Do something.
38  }).catch(function(error){
39    console.info("getAllVolumes failed");
40  });
41  ```
42
43## volumemanager.getAllVolumes
44
45getAllVolumes(callback: AsyncCallback<Array<Volume>>): void
46
47Obtains information about all volumes of this external storage device. This API uses an asynchronous callback to return the result.
48
49**Required permissions**: ohos.permission.STORAGE_MANAGER
50
51**System capability**: SystemCapability.FileManagement.StorageService.Volume
52
53**Parameters**
54
55| Name  | Type                                             | Mandatory| Description                                |
56| -------- | ------------------------------------------------- | ---- | ------------------------------------ |
57| callback | AsyncCallback<[Volume](#volume)[]> | Yes  | Callback invoked to return information about all available volumes.|
58
59**Example**
60
61  ```js
62  let uuid = "";
63  volumemanager.getAllVolumes(function(error, volumes){
64      // Do something
65  });
66  ```
67
68
69## volumemanager.mount
70
71mount(volumeId: string): Promise<void>
72
73Asynchronously mounts a volume. This API uses a promise to return the result. Currently, only the File Allocation Table (FAT), Extensible FAT (exFAT), and New Technology File System (NTFS) file systems are supported.
74
75**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER
76
77**System capability**: SystemCapability.FileManagement.StorageService.Volume
78
79**Parameters**
80
81| Name  | Type  | Mandatory| Description|
82| -------- | ------ | ---- | ---- |
83| volumeId | string | Yes  | Volume ID.|
84
85**Return value**
86
87| Type                  | Description      |
88| ---------------------- | ---------- |
89| Promise<void> | Promise that returns no value.|
90
91**Example**
92
93  ```js
94  let volumeId = "";
95  volumemanager.mount(volumeId).then(function(){
96      // Do something.
97  }).catch(function(error){
98    console.info("mount failed");
99  });
100  ```
101
102## volumemanager.mount
103
104mount(volumeId: string, callback:AsyncCallback<void>):void
105
106Asynchronously mounts a volume. This API uses an asynchronous callback to return the result. Currently, only the FAT, exFAT, and NTFS file systems are supported.
107
108**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER
109
110**System capability**: SystemCapability.FileManagement.StorageService.Volume
111
112**Parameters**
113
114| Name  | Type                                 | Mandatory| Description                |
115| -------- | ------------------------------------- | ---- | -------------------- |
116| volumeId | string                                | Yes  | Volume ID.                |
117| callback | AsyncCallback<void> | Yes  | Callback that returns no value.|
118
119**Example**
120
121  ```js
122  let volumeId = "";
123  volumemanager.mount(volumeId, function(error){
124      // Do something.
125  });
126  ```
127
128## volumemanager.unmount
129
130unmount(volumeId: string): Promise<void>
131
132Asynchronously unmounts a volume. This API uses a promise to return the result.
133
134**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER
135
136**System capability**: SystemCapability.FileManagement.StorageService.Volume
137
138**Parameters**
139
140| Name  | Type  | Mandatory| Description|
141| -------- | ------ | ---- | ---- |
142| volumeId | string | Yes  | Volume ID.|
143
144**Return value**
145
146| Type                  | Description      |
147| ---------------------- | ---------- |
148| Promise<void> | Promise that returns no value.|
149
150**Example**
151
152  ```js
153  let volumeId = "";
154  volumemanager.unmount(volumeId).then(function(){
155      // Do something.
156  }).catch(function(error){
157    console.info("mount failed");
158  });
159  ```
160
161## volumemanager.unmount
162
163unmount(volumeId: string, callback: AsyncCallback<void>): void
164
165Asynchronously unmounts a volume. This API uses an asynchronous callback to return the result.
166
167**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER
168
169**System capability**: SystemCapability.FileManagement.StorageService.Volume
170
171**Parameters**
172
173| Name  | Type                                 | Mandatory| Description                |
174| -------- | ------------------------------------- | ---- | -------------------- |
175| volumeId | string                                | Yes  | Volume ID.                |
176| callback | AsyncCallback<void> | Yes  | Callback that returns no value.|
177
178**Example**
179
180  ```js
181  let volumeId = "";
182  volumemanager.unmount(volumeId, function(error){
183      // Do something.
184  });
185  ```
186
187## volumemanager.getVolumeByUuid
188
189getVolumeByUuid(uuid: string): Promise<Volume>
190
191Obtains information about a volume based on the universally unique identifier (UUID). This API uses a promise to return the result.
192
193**Required permissions**: ohos.permission.STORAGE_MANAGER
194
195**System capability**: SystemCapability.FileManagement.StorageService.Volume
196
197**Parameters**
198
199| Name  | Type  | Mandatory| Description|
200| -------- | ------ | ---- | ---- |
201| uuid | string | Yes  | UUID of the volume.|
202
203**Return value**
204
205| Type                              | Description                      |
206| ---------------------------------- | -------------------------- |
207| Promise<[Volume](#volume)> | Promise used to return the volume information obtained.|
208
209**Example**
210
211  ```js
212  let uuid = "";
213  volumemanager.getVolumeByUuid(uuid).then(function(volume) {
214      console.info("getVolumeByUuid successfully:" + JSON.stringify(volume));
215  }).catch(function(error){
216      console.info("getVolumeByUuid failed with error:"+ error);
217  });
218  ```
219
220## volumemanager.getVolumeByUuid
221
222getVolumeByUuid(uuid: string, callback: AsyncCallback<Volume>): void
223
224Obtains information about a volume based on the UUID. This API uses an asynchronous callback to return the result.
225
226**Required permissions**: ohos.permission.STORAGE_MANAGER
227
228**System capability**: SystemCapability.FileManagement.StorageService.Volume
229
230**Parameters**
231
232| Name   | Type                                                | Mandatory| Description                |
233| -------- | ------------------------------------------------ | ---- | -------------------- |
234| uuid | string                                                 | Yes  | UUID of the volume.                |
235| callback | AsyncCallback<[Volume](#volume)>  | Yes  | Callback invoked to return the volume information obtained.|
236
237**Example**
238
239  ```js
240  let uuid = "";
241  volumemanager.getVolumeByUuid(uuid, (error, volume) => {
242      // Do something.
243  });
244  ```
245
246## volumemanager.getVolumeById
247
248getVolumeById(volumeId: string): Promise<Volume>
249
250Obtains information about a volume based on the volume ID. This API uses a promise to return the result.
251
252**Required permissions**: ohos.permission.STORAGE_MANAGER
253
254**System capability**: SystemCapability.FileManagement.StorageService.Volume
255
256**Parameters**
257
258| Name   | Type   | Mandatory | Description|
259| -------- | ------ | ---- | ---- |
260| volumeId | string | Yes  | Volume ID.|
261
262**Return value**
263
264| Type                              | Description                      |
265| ---------------------------------- | -------------------------- |
266| Promise<[Volume](#volume)> | Promise used to return the volume information obtained.|
267
268**Example**
269
270  ```js
271  let volumeId = "";
272  volumemanager.getVolumeById(volumeId).then(function(volume) {
273      console.info("getVolumeById successfully:" + JSON.stringify(volume));
274  }).catch(function(error){
275      console.info("getVolumeById failed with error:"+ error);
276  });
277  ```
278
279## volumemanager.getVolumeById
280
281getVolumeById(volumeId: string, callback: AsyncCallback<Volume>): void
282
283Obtains information about a volume based on the volume ID. This API uses an asynchronous callback to return the result.
284
285**Required permissions**: ohos.permission.STORAGE_MANAGER
286
287**System capability**: SystemCapability.FileManagement.StorageService.Volume
288
289**Parameters**
290
291| Name  | Type                     | Mandatory| Description                         |
292| -------- | ------------------------- | ---- | ----------------------------- |
293| volumeId | string                    | Yes  | Volume ID.               |
294| callback | AsyncCallback<[Volume](#volume)> | Yes  | Callback invoked to return the volume information obtained. |
295
296**Example**
297
298  ```js
299  let volumeId = "";
300  volumemanager.getVolumeById(volumeId, (error, volume) => {
301      // Do something.
302  });
303  ```
304
305## volumemanager.setVolumeDescription
306
307setVolumeDescription(uuid: string, description: string): Promise<void>
308
309Sets volume description. This API uses a promise to return the result.
310
311**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER
312
313**System capability**: SystemCapability.FileManagement.StorageService.Volume
314
315**Parameters**
316
317| Name    | Type  | Mandatory| Description|
318| --------- | ------ | ---- | ---- |
319| uuid      | string | Yes  | UUID of the volume.|
320| description | string | Yes  | Volume description to set.|
321
322**Return value**
323
324| Type                   | Description                      |
325| ---------------------- | -------------------------- |
326| Promise<void> | Promise that returns no value.                 |
327
328**Example**
329
330  ```js
331  let uuid = "";
332  let description = "";
333  volumemanager.setVolumeDescription(uuid, description).then(function() {
334      console.info("setVolumeDescription successfully");
335  }).catch(function(error){
336      console.info("setVolumeDescription failed with error:"+ error);
337  });
338  ```
339
340## volumemanager.setVolumeDescription
341
342setVolumeDescription(uuid: string, description: string, callback: AsyncCallback<void>): void
343
344Sets volume description. This API uses an asynchronous callback to return the result.
345
346**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER
347
348**System capability**: SystemCapability.FileManagement.StorageService.Volume
349
350**Parameters**
351
352| Name     | Type                                    | Mandatory| Description             |
353| ---------- | --------------------------------------- | ---- | ---------------- |
354| uuid       | string                                  | Yes  | UUID of the volume.           |
355| description | string                                 | Yes  | Volume description to set.           |
356| callback   | AsyncCallback<void>   | Yes  | Callback that returns no value.|
357
358**Example**
359
360  ```js
361  let uuid = "";
362  let description = "";
363  volumemanager.setVolumeDescription(uuid, description, (error) => {
364      // Do something.
365  });
366  ```
367
368## volumemanager.format
369
370format(volumeId: string, fsType: string): Promise<void>
371
372Formats a volume. This API uses a promise to return the result. Currently, only the virtual file allocation table (VFAT) and exFAT file systems are supported. Only unmounted volumes can be formatted. After a volume is formatted, the UUID, mounting path, and description of the volume change.
373
374**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER
375
376**System capability**: SystemCapability.FileManagement.StorageService.Volume
377
378**Parameters**
379
380| Name      | Type  | Mandatory| Description|
381| ----------- | ------ | ---- | ---- |
382| volumeId    | string | Yes  | Volume ID.|
383| fsType    | string | Yes  | File system type, which can be VFAT or exFAT.|
384
385**Return value**
386
387| Type                  | Description      |
388| ---------------------- | ---------- |
389| Promise<void> | Promise that returns no value.|
390
391**Example**
392
393  ```js
394  let volumeId = "";
395  let fsType = "";
396  volumemanager.format(volumeId, fsType).then(function() {
397      console.info("format successfully");
398  }).catch(function(error){
399      console.info("format failed with error:"+ error);
400  });
401  ```
402
403## volumemanager.format
404
405format(volumeId: string, fsType: string, callback: AsyncCallback<void>): void
406
407Formats a volume. This API uses an asynchronous callback to return the result. Currently, only the VFAT and exFAT file systems are supported. Only unmounted volumes can be formatted. After a volume is formatted, the UUID, mounting path, and description of the volume change.
408
409**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER
410
411**System capability**: SystemCapability.FileManagement.StorageService.Volume
412
413**Parameters**
414
415| Name  | Type                     | Mandatory| Description                         |
416| -------- | ------------------------- | ---- | ----------------------------- |
417| volumeId | string                    | Yes  | Volume ID.               |
418| fsType    | string | Yes  | File system type, which can be VFAT or exFAT.|
419| callback | AsyncCallback<void>  | Yes  | Callback that returns no value. |
420
421**Example**
422
423  ```js
424  let volumeId = "";
425  let fsType = "";
426  volumemanager.format(volumeId, fsType, (error) => {
427      // Do something.
428  });
429  ```
430
431## volumemanager.partition
432
433partition(diskId: string, type: number): Promise<void>
434
435Partitions a disk. This API uses a promise to return the result. The system supports access to multi-partition disks. Currently, this API can partition a disk into only one partition.
436
437**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER
438
439**System capability**: SystemCapability.FileManagement.StorageService.Volume
440
441**Parameters**
442
443| Name      | Type  | Mandatory| Description|
444| ----------- | ------ | ---- | ---- |
445| diskId    | string | Yes  | ID of the disk to partition.|
446| type      | number | Yes  | Partition type.   |
447
448**Return value**
449
450| Type                     | Description                      |
451| --------------------- | ----------------------- |
452| Promise<void>   | Promise used to return the result.             |
453
454**Example**
455
456  ```js
457  let diskId = "";
458  let type = 0;
459  volumemanager.partition(diskId, type).then(function() {
460      console.info("partition successfully");
461  }).catch(function(error){
462      console.info("partition failed with error:"+ error);
463  });
464  ```
465
466## volumemanager.partition
467
468partition(diskId: string, type: number, callback: AsyncCallback<void>): void
469
470Asynchronously partitions a disk. This API uses a callback to return the result. The system supports access to multi-partition disks. Currently, this API can partition a disk into only one partition.
471
472**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER
473
474**System capability**: SystemCapability.FileManagement.StorageService.Volume
475
476**Parameters**
477
478| Name     | Type                                  | Mandatory| Description             |
479| -------- | --------------------------------------- | ---- | ---------------- |
480| diskId   | string                                  | Yes  | ID of the disk to partition.     |
481| type     | number                                  | Yes  | Partition type.          |
482| callback | AsyncCallback<void>   | Yes  | Callback that returns no value.     |
483
484**Example**
485
486  ```js
487  let diskId = "";
488  let type = 0;
489  volumemanager.partition(diskId, type, (error) => {
490      // Do something.
491  });
492  ```
493
494## Volume
495
496**System capability**: SystemCapability.FileManagement.StorageService.Volume
497
498### Attributes
499
500| Name        | Type   | Readable  | Writable  | Description                |
501| ----------- | ------- | ------- | ----- | -------------------- |
502| id          | string  | Yes| No| Volume ID, in the vol-{Primary device ID}-{Secondary device ID} format. The primary device IDs identify devices of different types. The secondary device IDs identify different devices of the same type. The volume IDs vary depending on the card insertion sequence.                |
503| uuid        | string  | Yes| No| Volume UUID, which uniquely identifies a volume irrespective of the card insertion sequence. However, the UUID of a volume will change after the volume is formatted.              |
504| diskId      | string  | Yes| No| ID of the disk to which the volume belongs. A disk can have one or more volumes. The disk ID is in the disk-{Primary device ID}-{Secondary device ID} format, which is similar to the volume ID.       |
505| description | string  | Yes| No| Description of the volume.          |
506| removable   | boolean | Yes| No| Whether the volume can be removed. Currently, only removable storage devices are supported.|
507| state       | number  | Yes| No| Volume status.<br>**0**: The volume is unmounted.<br> **1**: The volume is being checked.<br> **2**: The volume is mounted.<br> **3**: The volume is being ejected.         |
508| path        | string  | Yes| No| Path of the volume mounted. Generally, the path is **/mnt/external/{uuid}**.        |
509