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 10## Modules to Import 11 12```js 13import volumemanager from "@ohos.file.volumeManager"; 14``` 15 16## volumemanager.getAllVolumes 17 18getAllVolumes(): Promise<Array<Volume>> 19 20Obtains information about all volumes of this external storage device. This API uses a promise to return the result. 21 22**Required permissions**: ohos.permission.STORAGE_MANAGER 23 24**System capability**: SystemCapability.FileManagement.StorageService.Volume 25 26**Return value** 27 28 | Type | Description | 29 | ---------------------------------- | -------------------------- | 30 | Promise<[Volume](#volume)[]> | Promise used to return information about all available volumes.| 31 32**Error codes** 33 34For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 35 36| ID| Error Message| 37| -------- | -------- | 38| 201 | Permission verification failed. | 39| 202 | The caller is not a system application. | 40| 401 | The input parameter is invalid. | 41| 13600001 | IPC error. | 42| 13900032 | Unknown error. | 43 44**Example** 45 46 ```js 47 volumemanager.getAllVolumes().then(function(volumes){ 48 // Do something. 49 }).catch(function(error){ 50 console.info("getAllVolumes failed"); 51 }); 52 ``` 53 54## volumemanager.getAllVolumes 55 56getAllVolumes(callback: AsyncCallback<Array<Volume>>): void 57 58Obtains information about all volumes of this external storage device. This API uses an asynchronous callback to return the result. 59 60**Required permissions**: ohos.permission.STORAGE_MANAGER 61 62**System capability**: SystemCapability.FileManagement.StorageService.Volume 63 64**Parameters** 65 66 | Name | Type | Mandatory| Description | 67 | -------- | ------------------------------------------------- | ---- | ------------------------------------ | 68 | callback | AsyncCallback<[Volume](#volume)[]> | Yes | Callback invoked to return information about all available volumes.| 69 70**Error codes** 71 72For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 73 74| ID| Error Message| 75| -------- | -------- | 76| 201 | Permission verification failed. | 77| 202 | The caller is not a system application. | 78| 401 | The input parameter is invalid. | 79| 13600001 | IPC error. | 80| 13900032 | Unknown error. | 81 82**Example** 83 84 ```js 85 let uuid = ""; 86 volumemanager.getAllVolumes(function(error, volumes){ 87 // Do something 88 }); 89 ``` 90 91## volumemanager.mount 92 93mount(volumeId: string): Promise<void> 94 95Asynchronously 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. 96 97**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER 98 99**System capability**: SystemCapability.FileManagement.StorageService.Volume 100 101**Parameters** 102 103 | Name | Type | Mandatory| Description| 104 | -------- | ------ | ---- | ---- | 105 | volumeId | string | Yes | Volume ID.| 106 107**Return value** 108 109 | Type | Description | 110 | ---------------------- | ---------- | 111 | Promise<void> | Promise that returns no value.| 112 113**Error codes** 114 115For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 116 117| ID| Error Message| 118| -------- | -------- | 119| 201 | Permission verification failed. | 120| 202 | The caller is not a system application. | 121| 401 | The input parameter is invalid. | 122| 13600001 | IPC error. | 123| 13600002 | Not supported filesystem. | 124| 13600003 | Failed to mount. | 125| 13600005 | Incorrect volume state. | 126| 13600008 | No such object. | 127| 13900032 | Unknown error. | 128 129**Example** 130 131 ```js 132 let volumeId = ""; 133 volumemanager.mount(volumeId).then(function(){ 134 // Do something. 135 }).catch(function(error){ 136 console.info("mount failed"); 137 }); 138 ``` 139 140## volumemanager.mount 141 142mount(volumeId: string, callback:AsyncCallback<void>):void 143 144Asynchronously mounts a volume. This API uses an asynchronous callback to return the result. Currently, only the FAT, exFAT, and NTFS file systems are supported. 145 146**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER 147 148**System capability**: SystemCapability.FileManagement.StorageService.Volume 149 150**Parameters** 151 152 | Name | Type | Mandatory| Description | 153 | -------- | ------------------------------------- | ---- | -------------------- | 154 | volumeId | string | Yes | Volume ID. | 155 | callback | AsyncCallback<void> | Yes | Callback that returns no value.| 156 157**Error codes** 158 159For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 160 161| ID| Error Message| 162| -------- | -------- | 163| 201 | Permission verification failed. | 164| 202 | The caller is not a system application. | 165| 401 | The input parameter is invalid. | 166| 13600001 | IPC error. | 167| 13600002 | Not supported filesystem. | 168| 13600003 | Failed to mount. | 169| 13600005 | Incorrect volume state. | 170| 13600008 | No such object. | 171| 13900032 | Unknown error. | 172 173**Example** 174 175 ```js 176 let volumeId = ""; 177 volumemanager.mount(volumeId, function(error){ 178 // Do something. 179 }); 180 ``` 181 182## volumemanager.unmount 183 184unmount(volumeId: string): Promise<void> 185 186Asynchronously unmounts a volume. This API uses a promise to return the result. 187 188**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER 189 190**System capability**: SystemCapability.FileManagement.StorageService.Volume 191 192**Parameters** 193 194 | Name | Type | Mandatory| Description| 195 | -------- | ------ | ---- | ---- | 196 | volumeId | string | Yes | Volume ID.| 197 198**Return value** 199 200 | Type | Description | 201 | ---------------------- | ---------- | 202 | Promise<void> | Promise that returns no value.| 203 204**Error codes** 205 206For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 207 208| ID| Error Message| 209| -------- | -------- | 210| 201 | Permission verification failed. | 211| 202 | The caller is not a system application. | 212| 401 | The input parameter is invalid. | 213| 13600001 | IPC error. | 214| 13600002 | Not supported filesystem. | 215| 13600004 | Failed to unmount. | 216| 13600005 | Incorrect volume state. | 217| 13600008 | No such object. | 218| 13900032 | Unknown error. | 219 220**Example** 221 222 ```js 223 let volumeId = ""; 224 volumemanager.unmount(volumeId).then(function(){ 225 // Do something. 226 }).catch(function(error){ 227 console.info("mount failed"); 228 }); 229 ``` 230 231## volumemanager.unmount 232 233unmount(volumeId: string, callback: AsyncCallback<void>): void 234 235Asynchronously unmounts a volume. This API uses an asynchronous callback to return the result. 236 237**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER 238 239**System capability**: SystemCapability.FileManagement.StorageService.Volume 240 241**Parameters** 242 243 | Name | Type | Mandatory| Description | 244 | -------- | ------------------------------------- | ---- | -------------------- | 245 | volumeId | string | Yes | Volume ID. | 246 | callback | AsyncCallback<void> | Yes | Callback that returns no value.| 247 248**Error codes** 249 250For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 251 252| ID| Error Message| 253| -------- | -------- | 254| 201 | Permission verification failed. | 255| 202 | The caller is not a system application. | 256| 401 | The input parameter is invalid. | 257| 13600001 | IPC error. | 258| 13600002 | Not supported filesystem. | 259| 13600004 | Failed to unmount. | 260| 13600005 | Incorrect volume state. | 261| 13600008 | No such object. | 262| 13900032 | Unknown error. | 263 264**Example** 265 266 ```js 267 let volumeId = ""; 268 volumemanager.unmount(volumeId, function(error){ 269 // Do something. 270 }); 271 ``` 272 273## volumemanager.getVolumeByUuid 274 275getVolumeByUuid(uuid: string): Promise<Volume> 276 277Obtains information about a volume based on the universally unique identifier (UUID). This API uses a promise to return the result. 278 279**Required permissions**: ohos.permission.STORAGE_MANAGER 280 281**System capability**: SystemCapability.FileManagement.StorageService.Volume 282 283**Parameters** 284 285 | Name | Type | Mandatory| Description| 286 | -------- | ------ | ---- | ---- | 287 | uuid | string | Yes | UUID of the volume.| 288 289**Return value** 290 291 | Type | Description | 292 | ---------------------------------- | -------------------------- | 293 | Promise<[Volume](#volume)> | Promise used to return the volume information obtained.| 294 295**Error codes** 296 297For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 298 299| ID| Error Message| 300| -------- | -------- | 301| 201 | Permission verification failed. | 302| 202 | The caller is not a system application. | 303| 401 | The input parameter is invalid. | 304| 13600001 | IPC error. | 305| 13600008 | No such object. | 306| 13900032 | Unknown error. | 307 308**Example** 309 310 ```js 311 let uuid = ""; 312 volumemanager.getVolumeByUuid(uuid).then(function(volume) { 313 console.info("getVolumeByUuid successfully:" + JSON.stringify(volume)); 314 }).catch(function(error){ 315 console.info("getVolumeByUuid failed with error:"+ error); 316 }); 317 ``` 318 319## volumemanager.getVolumeByUuid 320 321getVolumeByUuid(uuid: string, callback: AsyncCallback<Volume>): void 322 323Obtains information about a volume based on the UUID. This API uses an asynchronous callback to return the result. 324 325**Required permissions**: ohos.permission.STORAGE_MANAGER 326 327**System capability**: SystemCapability.FileManagement.StorageService.Volume 328 329**Parameters** 330 331 | Name | Type | Mandatory| Description | 332 | -------- | ------------------------------------------------ | ---- | -------------------- | 333 | uuid | string | Yes | UUID of the volume. | 334 | callback | AsyncCallback<[Volume](#volume)> | Yes | Callback invoked to return the volume information obtained.| 335 336**Error codes** 337 338For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 339 340| ID| Error Message| 341| -------- | -------- | 342| 201 | Permission verification failed. | 343| 202 | The caller is not a system application. | 344| 401 | The input parameter is invalid. | 345| 13600001 | IPC error. | 346| 13600008 | No such object. | 347| 13900032 | Unknown error. | 348 349**Example** 350 351 ```js 352 let uuid = ""; 353 volumemanager.getVolumeByUuid(uuid, (error, volume) => { 354 // Do something. 355 }); 356 ``` 357 358## volumemanager.getVolumeById 359 360getVolumeById(volumeId: string): Promise<Volume> 361 362Obtains information about a volume based on the volume ID. This API uses a promise to return the result. 363 364**Required permissions**: ohos.permission.STORAGE_MANAGER 365 366**System capability**: SystemCapability.FileManagement.StorageService.Volume 367 368**Parameters** 369 370 | Name | Type | Mandatory | Description| 371 | -------- | ------ | ---- | ---- | 372 | volumeId | string | Yes | Volume ID.| 373 374**Return value** 375 376 | Type | Description | 377 | ---------------------------------- | -------------------------- | 378 | Promise<[Volume](#volume)> | Promise used to return the volume information obtained.| 379 380**Error codes** 381 382For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 383 384| ID| Error Message| 385| -------- | -------- | 386| 201 | Permission verification failed. | 387| 202 | The caller is not a system application. | 388| 401 | The input parameter is invalid. | 389| 13600001 | IPC error. | 390| 13600008 | No such object. | 391| 13900032 | Unknown error. | 392 393**Example** 394 395 ```js 396 let volumeId = ""; 397 volumemanager.getVolumeById(volumeId).then(function(volume) { 398 console.info("getVolumeById successfully:" + JSON.stringify(volume)); 399 }).catch(function(error){ 400 console.info("getVolumeById failed with error:"+ error); 401 }); 402 ``` 403 404## volumemanager.getVolumeById 405 406getVolumeById(volumeId: string, callback: AsyncCallback<Volume>): void 407 408Obtains information about a volume based on the volume ID. This API uses an asynchronous callback to return the result. 409 410**Required permissions**: ohos.permission.STORAGE_MANAGER 411 412**System capability**: SystemCapability.FileManagement.StorageService.Volume 413 414**Parameters** 415 416 | Name | Type | Mandatory| Description | 417 | -------- | ------------------------- | ---- | ----------------------------- | 418 | volumeId | string | Yes | Volume ID. | 419 | callback | AsyncCallback<[Volume](#volume)> | Yes | Callback invoked to return the volume information obtained. | 420 421**Error codes** 422 423For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 424 425| ID| Error Message| 426| -------- | -------- | 427| 201 | Permission verification failed. | 428| 202 | The caller is not a system application. | 429| 401 | The input parameter is invalid. | 430| 13600001 | IPC error. | 431| 13600008 | No such object. | 432| 13900032 | Unknown error. | 433 434**Example** 435 436 ```js 437 let volumeId = ""; 438 volumemanager.getVolumeById(volumeId, (error, volume) => { 439 // Do something. 440 }); 441 ``` 442 443## volumemanager.setVolumeDescription 444 445setVolumeDescription(uuid: string, description: string): Promise<void> 446 447Sets volume description. This API uses a promise to return the result. 448 449**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER 450 451**System capability**: SystemCapability.FileManagement.StorageService.Volume 452 453**Parameters** 454 455 | Name | Type | Mandatory| Description| 456 | --------- | ------ | ---- | ---- | 457 | uuid | string | Yes | UUID of the volume.| 458 | description | string | Yes | Volume description to set.| 459 460**Return value** 461 462 | Type | Description | 463 | ---------------------- | -------------------------- | 464 | Promise<void> | Promise that returns no value. | 465 466**Error codes** 467 468For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 469 470| ID| Error Message| 471| -------- | -------- | 472| 201 | Permission verification failed. | 473| 202 | The caller is not a system application. | 474| 401 | The input parameter is invalid. | 475| 13600001 | IPC error. | 476| 13600002 | Not supported filesystem. | 477| 13600005 | Incorrect volume state. | 478| 13600008 | No such object. | 479| 13900032 | Unknown error. | 480 481**Example** 482 483 ```js 484 let uuid = ""; 485 let description = ""; 486 volumemanager.setVolumeDescription(uuid, description).then(function() { 487 console.info("setVolumeDescription successfully"); 488 }).catch(function(error){ 489 console.info("setVolumeDescription failed with error:"+ error); 490 }); 491 ``` 492 493## volumemanager.setVolumeDescription 494 495setVolumeDescription(uuid: string, description: string, callback: AsyncCallback<void>): void 496 497Sets volume description. This API uses an asynchronous callback to return the result. 498 499**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER 500 501**System capability**: SystemCapability.FileManagement.StorageService.Volume 502 503**Parameters** 504 505 | Name | Type | Mandatory| Description | 506 | ---------- | --------------------------------------- | ---- | ---------------- | 507 | uuid | string | Yes | UUID of the volume. | 508 | description | string | Yes | Volume description to set. | 509 | callback | AsyncCallback<void> | Yes | Callback that returns no value.| 510 511**Error codes** 512 513For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 514 515| ID| Error Message| 516| -------- | -------- | 517| 201 | Permission verification failed. | 518| 202 | The caller is not a system application. | 519| 401 | The input parameter is invalid. | 520| 13600001 | IPC error. | 521| 13600002 | Not supported filesystem. | 522| 13600005 | Incorrect volume state. | 523| 13600008 | No such object. | 524| 13900032 | Unknown error. | 525 526**Example** 527 528 ```js 529 let uuid = ""; 530 let description = ""; 531 volumemanager.setVolumeDescription(uuid, description, (error) => { 532 // Do something. 533 }); 534 ``` 535 536## volumemanager.format 537 538format(volumeId: string, fsType: string): Promise<void> 539 540Formats 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. 541 542**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER 543 544**System capability**: SystemCapability.FileManagement.StorageService.Volume 545 546**Parameters** 547 548 | Name | Type | Mandatory| Description| 549 | ----------- | ------ | ---- | ---- | 550 | volumeId | string | Yes | Volume ID.| 551 | fsType | string | Yes | File system type, which can be VFAT or exFAT.| 552 553**Return value** 554 555 | Type | Description | 556 | ---------------------- | ---------- | 557 | Promise<void> | Promise that returns no value.| 558 559**Error codes** 560 561For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 562 563| ID| Error Message| 564| -------- | -------- | 565| 201 | Permission verification failed. | 566| 202 | The caller is not a system application. | 567| 401 | The input parameter is invalid. | 568| 13600001 | IPC error. | 569| 13600002 | Not supported filesystem. | 570| 13600005 | Incorrect volume state. | 571| 13600008 | No such object. | 572| 13900032 | Unknown error. | 573 574**Example** 575 576 ```js 577 let volumeId = ""; 578 let fsType = ""; 579 volumemanager.format(volumeId, fsType).then(function() { 580 console.info("format successfully"); 581 }).catch(function(error){ 582 console.info("format failed with error:"+ error); 583 }); 584 ``` 585 586## volumemanager.format 587 588format(volumeId: string, fsType: string, callback: AsyncCallback<void>): void 589 590Formats 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. 591 592**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER 593 594**System capability**: SystemCapability.FileManagement.StorageService.Volume 595 596**Parameters** 597 598 | Name | Type | Mandatory| Description | 599 | -------- | ------------------------- | ---- | ----------------------------- | 600 | volumeId | string | Yes | Volume ID. | 601 | fsType | string | Yes | File system type, which can be VFAT or exFAT.| 602 | callback | AsyncCallback<void> | Yes | Callback that returns no value. | 603 604**Error codes** 605 606For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 607 608| ID| Error Message| 609| -------- | -------- | 610| 201 | Permission verification failed. | 611| 202 | The caller is not a system application. | 612| 401 | The input parameter is invalid. | 613| 13600001 | IPC error. | 614| 13600002 | Not supported filesystem. | 615| 13600005 | Incorrect volume state. | 616| 13600008 | No such object. | 617| 13900032 | Unknown error. | 618 619**Example** 620 621 ```js 622 let volumeId = ""; 623 let fsType = ""; 624 volumemanager.format(volumeId, fsType, (error) => { 625 // Do something. 626 }); 627 ``` 628 629## volumemanager.partition 630 631partition(diskId: string, type: number): Promise<void> 632 633Partitions 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. 634 635**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER 636 637**System capability**: SystemCapability.FileManagement.StorageService.Volume 638 639**Parameters** 640 641 | Name | Type | Mandatory| Description| 642 | ----------- | ------ | ---- | ---- | 643 | diskId | string | Yes | ID of the disk to partition.| 644 | type | number | Yes | Partition type. | 645 646**Return value** 647 648 | Type | Description | 649 | --------------------- | ----------------------- | 650 | Promise<void> | Promise used to return the result. | 651 652**Error codes** 653 654For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 655 656| ID| Error Message| 657| -------- | -------- | 658| 201 | Permission verification failed. | 659| 202 | The caller is not a system application. | 660| 401 | The input parameter is invalid. | 661| 13600001 | IPC error. | 662| 13600008 | No such object. | 663| 13900032 | Unknown error. | 664 665**Example** 666 667 ```js 668 let diskId = ""; 669 let type = 0; 670 volumemanager.partition(diskId, type).then(function() { 671 console.info("partition successfully"); 672 }).catch(function(error){ 673 console.info("partition failed with error:"+ error); 674 }); 675 ``` 676 677## volumemanager.partition 678 679partition(diskId: string, type: number, callback: AsyncCallback<void>): void 680 681Asynchronously 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. 682 683**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER 684 685**System capability**: SystemCapability.FileManagement.StorageService.Volume 686 687**Parameters** 688 689 | Name | Type | Mandatory| Description | 690 | -------- | --------------------------------------- | ---- | ---------------- | 691 | diskId | string | Yes | ID of the disk to partition. | 692 | type | number | Yes | Partition type. | 693 | callback | AsyncCallback<void> | Yes | Callback that returns no value. | 694 695**Error codes** 696 697For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). 698 699| ID| Error Message| 700| -------- | -------- | 701| 201 | Permission verification failed. | 702| 202 | The caller is not a system application. | 703| 401 | The input parameter is invalid. | 704| 13600001 | IPC error. | 705| 13600008 | No such object. | 706| 13900032 | Unknown error. | 707 708**Example** 709 710 ```js 711 let diskId = ""; 712 let type = 0; 713 volumemanager.partition(diskId, type, (error) => { 714 // Do something. 715 }); 716 ``` 717 718## Volume 719 720**System capability**: SystemCapability.FileManagement.StorageService.Volume 721 722### Attributes 723 724| Name | Type | Readable | Writable | Description | 725| ----------- | ------- | ------- | ----- | -------------------- | 726| 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. | 727| 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. | 728| 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. | 729| description | string | Yes| No| Description of the volume. | 730| removable | boolean | Yes| No| Whether the volume can be removed. Currently, only removable storage devices are supported.| 731| 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. | 732| path | string | Yes| No| Path of the volume mounted. Generally, the path is **/mnt/external/{uuid}**. | 733