# @ohos.file.volumeManager (Volume Management)

The **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.

> **NOTE**
>
> - 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.
> - The APIs provided by this module are system APIs.
> - The APIs of this module support processing of error codes. For details, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).

## Modules to Import

```js
import volumemanager from "@ohos.file.volumeManager";
```

## volumemanager.getAllVolumes

getAllVolumes(): Promise<Array<Volume>>

Obtains information about all volumes of this external storage device. This API uses a promise to return the result.

**Required permissions**: ohos.permission.STORAGE_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Return value**

| Type                              | Description                      |
| ---------------------------------- | -------------------------- |
| Promise<[Volume](#volume)[]> | Promise used to return information about all available volumes.|

**Example**

  ```js
  volumemanager.getAllVolumes().then(function(volumes){
      // Do something.
  }).catch(function(error){
    console.info("getAllVolumes failed");
  });
  ```

## volumemanager.getAllVolumes

getAllVolumes(callback: AsyncCallback<Array<Volume>>): void

Obtains information about all volumes of this external storage device. This API uses an asynchronous callback to return the result.

**Required permissions**: ohos.permission.STORAGE_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name  | Type                                             | Mandatory| Description                                |
| -------- | ------------------------------------------------- | ---- | ------------------------------------ |
| callback | AsyncCallback<[Volume](#volume)[]> | Yes  | Callback invoked to return information about all available volumes.|

**Example**

  ```js
  let uuid = "";
  volumemanager.getAllVolumes(function(error, volumes){
      // Do something
  });
  ```


## volumemanager.mount

mount(volumeId: string): Promise<void>

Asynchronously 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.

**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name  | Type  | Mandatory| Description|
| -------- | ------ | ---- | ---- |
| volumeId | string | Yes  | Volume ID.|

**Return value**

| Type                  | Description      |
| ---------------------- | ---------- |
| Promise<void> | Promise that returns no value.|

**Example**

  ```js
  let volumeId = "";
  volumemanager.mount(volumeId).then(function(){
      // Do something.
  }).catch(function(error){
    console.info("mount failed");
  });
  ```

## volumemanager.mount

mount(volumeId: string, callback:AsyncCallback<void>):void

Asynchronously mounts a volume. This API uses an asynchronous callback to return the result. Currently, only the FAT, exFAT, and NTFS file systems are supported.

**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name  | Type                                 | Mandatory| Description                |
| -------- | ------------------------------------- | ---- | -------------------- |
| volumeId | string                                | Yes  | Volume ID.                |
| callback | AsyncCallback<void> | Yes  | Callback that returns no value.|

**Example**

  ```js
  let volumeId = "";
  volumemanager.mount(volumeId, function(error){
      // Do something.
  });
  ```

## volumemanager.unmount

unmount(volumeId: string): Promise<void>

Asynchronously unmounts a volume. This API uses a promise to return the result.

**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name  | Type  | Mandatory| Description|
| -------- | ------ | ---- | ---- |
| volumeId | string | Yes  | Volume ID.|

**Return value**

| Type                  | Description      |
| ---------------------- | ---------- |
| Promise<void> | Promise that returns no value.|

**Example**

  ```js
  let volumeId = "";
  volumemanager.unmount(volumeId).then(function(){
      // Do something.
  }).catch(function(error){
    console.info("mount failed");
  });
  ```

## volumemanager.unmount

unmount(volumeId: string, callback: AsyncCallback<void>): void

Asynchronously unmounts a volume. This API uses an asynchronous callback to return the result.

**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name  | Type                                 | Mandatory| Description                |
| -------- | ------------------------------------- | ---- | -------------------- |
| volumeId | string                                | Yes  | Volume ID.                |
| callback | AsyncCallback<void> | Yes  | Callback that returns no value.|

**Example**

  ```js
  let volumeId = "";
  volumemanager.unmount(volumeId, function(error){
      // Do something.
  });
  ```

## volumemanager.getVolumeByUuid

getVolumeByUuid(uuid: string): Promise<Volume>

Obtains information about a volume based on the universally unique identifier (UUID). This API uses a promise to return the result.

**Required permissions**: ohos.permission.STORAGE_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name  | Type  | Mandatory| Description|
| -------- | ------ | ---- | ---- |
| uuid | string | Yes  | UUID of the volume.|

**Return value**

| Type                              | Description                      |
| ---------------------------------- | -------------------------- |
| Promise<[Volume](#volume)> | Promise used to return the volume information obtained.|

**Example**

  ```js
  let uuid = "";
  volumemanager.getVolumeByUuid(uuid).then(function(volume) {
      console.info("getVolumeByUuid successfully:" + JSON.stringify(volume));
  }).catch(function(error){
      console.info("getVolumeByUuid failed with error:"+ error);
  });
  ```

## volumemanager.getVolumeByUuid

getVolumeByUuid(uuid: string, callback: AsyncCallback<Volume>): void

Obtains information about a volume based on the UUID. This API uses an asynchronous callback to return the result.

**Required permissions**: ohos.permission.STORAGE_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name   | Type                                                | Mandatory| Description                |
| -------- | ------------------------------------------------ | ---- | -------------------- |
| uuid | string                                                 | Yes  | UUID of the volume.                |
| callback | AsyncCallback<[Volume](#volume)>  | Yes  | Callback invoked to return the volume information obtained.|

**Example**

  ```js
  let uuid = "";
  volumemanager.getVolumeByUuid(uuid, (error, volume) => {
      // Do something.   
  });
  ```

## volumemanager.getVolumeById

getVolumeById(volumeId: string): Promise<Volume>

Obtains information about a volume based on the volume ID. This API uses a promise to return the result.

**Required permissions**: ohos.permission.STORAGE_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name   | Type   | Mandatory | Description|
| -------- | ------ | ---- | ---- |
| volumeId | string | Yes  | Volume ID.|

**Return value**

| Type                              | Description                      |
| ---------------------------------- | -------------------------- |
| Promise<[Volume](#volume)> | Promise used to return the volume information obtained.|

**Example**

  ```js
  let volumeId = "";
  volumemanager.getVolumeById(volumeId).then(function(volume) {
      console.info("getVolumeById successfully:" + JSON.stringify(volume));
  }).catch(function(error){
      console.info("getVolumeById failed with error:"+ error);
  });
  ```

## volumemanager.getVolumeById

getVolumeById(volumeId: string, callback: AsyncCallback<Volume>): void

Obtains information about a volume based on the volume ID. This API uses an asynchronous callback to return the result.

**Required permissions**: ohos.permission.STORAGE_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name  | Type                     | Mandatory| Description                         |
| -------- | ------------------------- | ---- | ----------------------------- |
| volumeId | string                    | Yes  | Volume ID.               |
| callback | AsyncCallback<[Volume](#volume)> | Yes  | Callback invoked to return the volume information obtained. |

**Example**

  ```js
  let volumeId = "";
  volumemanager.getVolumeById(volumeId, (error, volume) => {
      // Do something.   
  });
  ```

## volumemanager.setVolumeDescription

setVolumeDescription(uuid: string, description: string): Promise<void>

Sets volume description. This API uses a promise to return the result.

**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name    | Type  | Mandatory| Description|
| --------- | ------ | ---- | ---- |
| uuid      | string | Yes  | UUID of the volume.|
| description | string | Yes  | Volume description to set.|

**Return value**

| Type                   | Description                      |
| ---------------------- | -------------------------- |
| Promise<void> | Promise that returns no value.                 |

**Example**

  ```js
  let uuid = "";
  let description = "";
  volumemanager.setVolumeDescription(uuid, description).then(function() {
      console.info("setVolumeDescription successfully");
  }).catch(function(error){
      console.info("setVolumeDescription failed with error:"+ error);
  });
  ```

## volumemanager.setVolumeDescription

setVolumeDescription(uuid: string, description: string, callback: AsyncCallback<void>): void

Sets volume description. This API uses an asynchronous callback to return the result.

**Required permissions**: ohos.permission.MOUNT_UNMOUNT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name     | Type                                    | Mandatory| Description             |
| ---------- | --------------------------------------- | ---- | ---------------- |
| uuid       | string                                  | Yes  | UUID of the volume.           |
| description | string                                 | Yes  | Volume description to set.           |
| callback   | AsyncCallback<void>   | Yes  | Callback that returns no value.|

**Example**

  ```js
  let uuid = "";
  let description = "";
  volumemanager.setVolumeDescription(uuid, description, (error) => {
      // Do something.   
  });
  ```

## volumemanager.format

format(volumeId: string, fsType: string): Promise<void>

Formats 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.

**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name      | Type  | Mandatory| Description|
| ----------- | ------ | ---- | ---- |
| volumeId    | string | Yes  | Volume ID.|
| fsType    | string | Yes  | File system type, which can be VFAT or exFAT.|

**Return value**

| Type                  | Description      |
| ---------------------- | ---------- |
| Promise<void> | Promise that returns no value.|

**Example**

  ```js
  let volumeId = "";
  let fsType = "";
  volumemanager.format(volumeId, fsType).then(function() {
      console.info("format successfully");
  }).catch(function(error){
      console.info("format failed with error:"+ error);
  });
  ```

## volumemanager.format

format(volumeId: string, fsType: string, callback: AsyncCallback<void>): void

Formats 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.

**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name  | Type                     | Mandatory| Description                         |
| -------- | ------------------------- | ---- | ----------------------------- |
| volumeId | string                    | Yes  | Volume ID.               |
| fsType    | string | Yes  | File system type, which can be VFAT or exFAT.|
| callback | AsyncCallback<void>  | Yes  | Callback that returns no value. |

**Example**

  ```js
  let volumeId = "";
  let fsType = "";
  volumemanager.format(volumeId, fsType, (error) => {
      // Do something.   
  });
  ```

## volumemanager.partition

partition(diskId: string, type: number): Promise<void>

Partitions 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.

**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name      | Type  | Mandatory| Description|
| ----------- | ------ | ---- | ---- |
| diskId    | string | Yes  | ID of the disk to partition.|
| type      | number | Yes  | Partition type.   |

**Return value**

| Type                     | Description                      |
| --------------------- | ----------------------- |
| Promise<void>   | Promise used to return the result.             |

**Example**

  ```js
  let diskId = "";
  let type = 0;
  volumemanager.partition(diskId, type).then(function() {
      console.info("partition successfully");
  }).catch(function(error){
      console.info("partition failed with error:"+ error);
  });
  ```

## volumemanager.partition

partition(diskId: string, type: number, callback: AsyncCallback<void>): void

Asynchronously 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.

**Required permissions**: ohos.permission.MOUNT_FORMAT_MANAGER

**System capability**: SystemCapability.FileManagement.StorageService.Volume

**Parameters**

| Name     | Type                                  | Mandatory| Description             |
| -------- | --------------------------------------- | ---- | ---------------- |
| diskId   | string                                  | Yes  | ID of the disk to partition.     |
| type     | number                                  | Yes  | Partition type.          |
| callback | AsyncCallback<void>   | Yes  | Callback that returns no value.     |

**Example**

  ```js
  let diskId = "";
  let type = 0;
  volumemanager.partition(diskId, type, (error) => {
      // Do something.   
  });
  ```

## Volume

**System capability**: SystemCapability.FileManagement.StorageService.Volume

### Attributes

| Name        | Type   | Readable  | Writable  | Description                |
| ----------- | ------- | ------- | ----- | -------------------- |
| 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.                |
| 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.              |
| 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.       |
| description | string  | Yes| No| Description of the volume.          |
| removable   | boolean | Yes| No| Whether the volume can be removed. Currently, only removable storage devices are supported.|
| 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.         |
| path        | string  | Yes| No| Path of the volume mounted. Generally, the path is **/mnt/external/{uuid}**.        |