### Interface

# Gio Volume

#### Description

    interface Gio.Volume : GObject.Object

The `GVolume` interface represents user-visible objects that can be mounted. Note, when porting from GnomeVFS, `GVolume` is the moral equivalent of `GnomeVFSDrive`.

Mounting a `GVolume` instance is an asynchronous operation. For more information about asynchronous operations, see `GAsyncResult` and `GTask`. To mount a `GVolume`, first call `g_volume_mount()` with (at least) the `GVolume` instance, optionally a `GMountOperation` object and a `GAsyncReadyCallback`.

Typically, one will only want to pass `NULL` for the `GMountOperation` if automounting all volumes when a desktop session starts since it’s not desirable to put up a lot of dialogs asking for credentials.

The callback will be fired when the operation has resolved (either with success or failure), and a `GAsyncResult` instance will be passed to the callback. That callback should then call `g_volume_mount_finish()` with the `GVolume` instance and the `GAsyncResult` data to see if the operation was completed successfully. If a `GError` is present when `g_volume_mount_finish()` is called, then it will be filled with any error information.

## Volume Identifiers

It is sometimes necessary to directly access the underlying operating system object behind a volume (e.g. for passing a volume to an application via the command line). For this purpose, GIO allows to obtain an ‘identifier’ for the volume. There can be different kinds of identifiers, such as Hal UDIs, filesystem labels, traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined strings as names for the different kinds of identifiers: `G_VOLUME_IDENTIFIER_KIND_UUID`, `G_VOLUME_IDENTIFIER_KIND_LABEL`, etc. Use `g_volume_get_identifier()` to obtain an identifier for a volume.

Note that `G_VOLUME_IDENTIFIER_KIND_HAL_UDI` will only be available when the GVFS hal volume monitor is in use. Other volume monitors will generally be able to provide the `G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE` identifier, which can be used to obtain a hal device by means of `libhal_manager_find_device_string_match()`.

#### Prerequisite

In order to implement Volume, your type must inherit from`GObject`.

#### Instance methods

###### g_volume_can_eject

Checks if a volume can be ejected.

###### g_volume_can_mount

Checks if a volume can be mounted.

###### g_volume_eject

Ejects a volume. This is an asynchronous operation, and is finished by calling `g_volume_eject_finish()` with the `volume` and `GAsyncResult` returned in the `callback`.

deprecated: 2.22

###### g_volume_eject_finish

Finishes ejecting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `FALSE` will be returned.

deprecated: 2.22

###### g_volume_eject_with_operation

Ejects a volume. This is an asynchronous operation, and is finished by calling `g_volume_eject_with_operation_finish()` with the `volume` and `GAsyncResult` data returned in the `callback`.

since: 2.22

###### g_volume_eject_with_operation_finish

Finishes ejecting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `FALSE` will be returned.

since: 2.22

###### g_volume_enumerate_identifiers

Gets the kinds of identifiers that `volume` has. Use `g_volume_get_identifier()` to obtain the identifiers themselves.

###### g_volume_get_activation_root

Gets the activation root for a `GVolume` if it is known ahead of mount time. Returns `NULL` otherwise. If not `NULL` and if `volume` is mounted, then the result of `g_mount_get_root()` on the `GMount` object obtained from `g_volume_get_mount()` will always either be equal or a prefix of what this function returns. In other words, in code.

since: 2.18

###### g_volume_get_drive

Gets the drive for the `volume`.

###### g_volume_get_icon

Gets the icon for `volume`.

###### g_volume_get_identifier

Gets the identifier of the given kind for `volume`. See the introduction for more information about volume identifiers.

###### g_volume_get_mount

Gets the mount for the `volume`.

###### g_volume_get_name

Gets the name of `volume`.

###### g_volume_get_sort_key

Gets the sort key for `volume`, if any.

since: 2.32

###### g_volume_get_symbolic_icon

Gets the symbolic icon for `volume`.

since: 2.34

###### g_volume_get_uuid

Gets the UUID for the `volume`. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns `NULL` if there is no UUID available.

###### g_volume_mount

Mounts a volume. This is an asynchronous operation, and is finished by calling `g_volume_mount_finish()` with the `volume` and `GAsyncResult` returned in the `callback`.

###### g_volume_mount_finish

Finishes mounting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `FALSE` will be returned.

###### g_volume_should_automount

Returns whether the volume should be automatically mounted.

#### Signals

###### Gio.Volume::changed

Emitted when the volume has been changed.

###### Gio.Volume::removed

This signal is emitted when the `GVolume` have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.

#### Interface structure

    struct GioVolumeIface {
      GTypeInterface g_iface;
      void (* changed) (
        GVolume* volume
      );
      void (* removed) (
        GVolume* volume
      );
      char* (* get_name) (
        GVolume* volume
      );
      GIcon* (* get_icon) (
        GVolume* volume
      );
      char* (* get_uuid) (
        GVolume* volume
      );
      GDrive* (* get_drive) (
        GVolume* volume
      );
      GMount* (* get_mount) (
        GVolume* volume
      );
      gboolean (* can_mount) (
        GVolume* volume
      );
      gboolean (* can_eject) (
        GVolume* volume
      );
      void (* mount_fn) (
        GVolume* volume,
        GMountMountFlags flags,
        GMountOperation* mount_operation,
        GCancellable* cancellable,
        GAsyncReadyCallback callback,
        gpointer user_data
      );
      gboolean (* mount_finish) (
        GVolume* volume,
        GAsyncResult* result,
        GError** error
      );
      void (* eject) (
        GVolume* volume,
        GMountUnmountFlags flags,
        GCancellable* cancellable,
        GAsyncReadyCallback callback,
        gpointer user_data
      );
      gboolean (* eject_finish) (
        GVolume* volume,
        GAsyncResult* result,
        GError** error
      );
      char* (* get_identifier) (
        GVolume* volume,
        const char* kind
      );
      char** (* enumerate_identifiers) (
        GVolume* volume
      );
      gboolean (* should_automount) (
        GVolume* volume
      );
      GFile* (* get_activation_root) (
        GVolume* volume
      );
      void (* eject_with_operation) (
        GVolume* volume,
        GMountUnmountFlags flags,
        GMountOperation* mount_operation,
        GCancellable* cancellable,
        GAsyncReadyCallback callback,
        gpointer user_data
      );
      gboolean (* eject_with_operation_finish) (
        GVolume* volume,
        GAsyncResult* result,
        GError** error
      );
      const gchar* (* get_sort_key) (
        GVolume* volume
      );
      GIcon* (* get_symbolic_icon) (
        GVolume* volume
      );

    }

Interface for implementing operations for mountable volumes.

###### Interface members

`g_iface` |
    GTypeInterface
| The parent interface.
`changed` |
    void (* changed) (
        GVolume* volume
      )
| Changed signal that is emitted when the volume’s state has changed.
`removed` |
    void (* removed) (
        GVolume* volume
      )
| The removed signal that is emitted when the `GVolume` have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.
`get_name` |
    char* (* get_name) (
        GVolume* volume
      )
| Gets a string containing the name of the `GVolume`.
`get_icon` |
    GIcon* (* get_icon) (
        GVolume* volume
      )
| Gets a `GIcon` for the `GVolume`.
`get_uuid` |
    char* (* get_uuid) (
        GVolume* volume
      )
| Gets the UUID for the `GVolume`. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns `NULL` if there is no UUID available.
`get_drive` |
    GDrive* (* get_drive) (
        GVolume* volume
      )
| Gets a `GDrive` the volume is located on. Returns `NULL` if the `GVolume` is not associated with a `GDrive`.
`get_mount` |
    GMount* (* get_mount) (
        GVolume* volume
      )
| Gets a `GMount` representing the mounted volume. Returns `NULL` if the `GVolume` is not mounted.
`can_mount` |
    gboolean (* can_mount) (
        GVolume* volume
      )
| Returns `TRUE` if the `GVolume` can be mounted.
`can_eject` |
    gboolean (* can_eject) (
        GVolume* volume
      )
| Checks if a `GVolume` can be ejected.
`mount_fn` |
    void (* mount_fn) (
        GVolume* volume,
        GMountMountFlags flags,
        GMountOperation* mount_operation,
        GCancellable* cancellable,
        GAsyncReadyCallback callback,
        gpointer user_data
      )
| Mounts a given `GVolume`. `GVolume` implementations must emit the `GMountOperation::aborted` signal before completing a mount operation that is aborted while awaiting input from the user through a `GMountOperation` instance.
`mount_finish` |
    gboolean (* mount_finish) (
        GVolume* volume,
        GAsyncResult* result,
        GError** error
      )
| Finishes a mount operation.
`eject` |
    void (* eject) (
        GVolume* volume,
        GMountUnmountFlags flags,
        GCancellable* cancellable,
        GAsyncReadyCallback callback,
        gpointer user_data
      )
| Ejects a given `GVolume`.
`eject_finish` |
    gboolean (* eject_finish) (
        GVolume* volume,
        GAsyncResult* result,
        GError** error
      )
| Finishes an eject operation.
`get_identifier` |
    char* (* get_identifier) (
        GVolume* volume,
        const char* kind
      )
| Returns the identifier of the given kind, or `NULL` if the `GVolume` doesn’t have one.
`enumerate_identifiers` |
    char** (* enumerate_identifiers) (
        GVolume* volume
      )
| Returns an array strings listing the kinds of identifiers which the `GVolume` has.
`should_automount` |
    gboolean (* should_automount) (
        GVolume* volume
      )
| Returns `TRUE` if the `GVolume` should be automatically mounted.
`get_activation_root` |
    GFile* (* get_activation_root) (
        GVolume* volume
      )
| Returns the activation root for the `GVolume` if it is known in advance or `NULL` if it is not known.
`eject_with_operation` |
    void (* eject_with_operation) (
        GVolume* volume,
        GMountUnmountFlags flags,
        GMountOperation* mount_operation,
        GCancellable* cancellable,
        GAsyncReadyCallback callback,
        gpointer user_data
      )
| Starts ejecting a `GVolume` using a `GMountOperation`. Since 2.22.
`eject_with_operation_finish` |
    gboolean (* eject_with_operation_finish) (
        GVolume* volume,
        GAsyncResult* result,
        GError** error
      )
| Finishes an eject operation using a `GMountOperation`. Since 2.22.
`get_sort_key` |
    const gchar* (* get_sort_key) (
        GVolume* volume
      )
| Gets a key used for sorting `GVolume` instance or `NULL` if no such key exists. Since 2.32.
`get_symbolic_icon` |
    GIcon* (* get_symbolic_icon) (
        GVolume* volume
      )
| Gets a symbolic `GIcon` for the `GVolume`. Since 2.34.

#### Virtual methods

###### Gio.Volume.can_eject

Checks if a volume can be ejected.

###### Gio.Volume.can_mount

Checks if a volume can be mounted.

###### Gio.Volume.changed

Changed signal that is emitted when the volume’s state has changed.

###### Gio.Volume.eject

Ejects a volume. This is an asynchronous operation, and is finished by calling `g_volume_eject_finish()` with the `volume` and `GAsyncResult` returned in the `callback`.

deprecated: 2.22

###### Gio.Volume.eject_finish

Finishes ejecting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `FALSE` will be returned.

deprecated: 2.22

###### Gio.Volume.eject_with_operation

Ejects a volume. This is an asynchronous operation, and is finished by calling `g_volume_eject_with_operation_finish()` with the `volume` and `GAsyncResult` data returned in the `callback`.

since: 2.22

###### Gio.Volume.eject_with_operation_finish

Finishes ejecting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `FALSE` will be returned.

since: 2.22

###### Gio.Volume.enumerate_identifiers

Gets the kinds of identifiers that `volume` has. Use `g_volume_get_identifier()` to obtain the identifiers themselves.

###### Gio.Volume.get_activation_root

Gets the activation root for a `GVolume` if it is known ahead of mount time. Returns `NULL` otherwise. If not `NULL` and if `volume` is mounted, then the result of `g_mount_get_root()` on the `GMount` object obtained from `g_volume_get_mount()` will always either be equal or a prefix of what this function returns. In other words, in code.

since: 2.18

###### Gio.Volume.get_drive

Gets the drive for the `volume`.

###### Gio.Volume.get_icon

Gets the icon for `volume`.

###### Gio.Volume.get_identifier

Gets the identifier of the given kind for `volume`. See the introduction for more information about volume identifiers.

###### Gio.Volume.get_mount

Gets the mount for the `volume`.

###### Gio.Volume.get_name

Gets the name of `volume`.

###### Gio.Volume.get_sort_key

Gets the sort key for `volume`, if any.

since: 2.32

###### Gio.Volume.get_symbolic_icon

Gets the symbolic icon for `volume`.

since: 2.34

###### Gio.Volume.get_uuid

Gets the UUID for the `volume`. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns `NULL` if there is no UUID available.

###### Gio.Volume.mount_finish

Finishes mounting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `FALSE` will be returned.

###### Gio.Volume.mount_fn

Mounts a volume. This is an asynchronous operation, and is finished by calling `g_volume_mount_finish()` with the `volume` and `GAsyncResult` returned in the `callback`.

###### Gio.Volume.removed

The removed signal that is emitted when the `GVolume` have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.

###### Gio.Volume.should_automount

Returns whether the volume should be automatically mounted.