# gio.Volume

Volume management.

## Synopsis

gio.Volume
gobject.GInterface
can_eject
can_mount
eject
callback
flags
gio.MOUNT_UNMOUNT_NONE
cancellable
None
user_data
None
eject_finish
result
enumerate_identifiers
get_activation_root
get_drive
get_icon
get_identifier
get_mount
get_name
get_uuid
mount
mount_operation
callback
flags
gio.MOUNT_MOUNT_NONE
cancellable
None
user_data
None
mount_finish
result
should_automount

## Ancestry

    +-- gobject.GInterface
      +-- gio.Volume

## Prerequisites

`gio.Volume` requires `gobject.GObject`

## gio.Volume Signal Prototypes

gobject.GObject Signal Prototypes

"changed"
  callback
  volume
  user_param1
  ...
"removed"
  callback
  volume
  user_param1
  ...

## Description

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

Mounting a `gio.Volume` instance is an asynchronous operation. For more information about asynchronous operations. To mount a `gio.Volume`, first call `gio.Volume.mount`() with (at least) the `gio.Volume` instance, optionally a `gio.MountOperation` object and a GAsyncReadyCallback.

Typically, one will only want to pass `None` 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 GAsyncReady structure will be passed to the callback. That callback should then call `gio.Volume.mount_finish`() with the GVolume instance and the GAsyncReady data to see if the operation was completed successfully. If an error is present when `gio.Volume.mount_finish`() is called, then it will be filled with any error information.

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 commandline). 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 predefind strings as names for the different kinds of identifiers: "hal-udi", "label", etc. Use `gio.Volume.get_identifier`() to obtain an identifier for a volume.

## Methods

### gio.Volume.can_eject

                    can_eject

Returns :

  `True` if the volume can be ejected, `False` otherwise.

The `can_eject`() method checks if a volume can be ejected.

### gio.Volume.can_mount

                    can_mount

Returns :

  `True` if the volume can be mounted for media changes, `False` otherwise.

The `can_mount`() method checks if a volume can be mounted.

### gio.Volume.eject

                    eject

                        callback

                        flagsgio.MOUNT_UNMOUNT_NONE

                        cancellableNone

                        user_dataNone

`callback` :

  A GAsyncReadyCallback to call when the request is satisfied.

`flags` :

  flags affecting the unmount if required for eject.

`cancellable` :

  Optional `gio.Cancellable` object, `None` to ignore.

`user_data` :

  The data to pass to callback function.

The `eject`() method asynchronously ejects a volume.

When the operation is finished, callback will be called. You can then call `gio.Volume.eject_finish`() to obtain the result of the operation.

### gio.Volume.eject_finish

                    eject_finish
                    result

`result` :

  a `gio.AsyncResult`.

Returns :

  `True` if the volume has been ejected successfully, `False` otherwise.

The `eject_finish`() method finishes ejecting a volume. If any errors occured during the operation, error will be set to contain the errors and `False` will be returned.

### gio.Volume.enumerate_identifiers

                    enumerate_identifiers

Returns :

  a list of strings containing kinds of identifiers.

The `enumerate_identifiers`() method gets the kinds of identifiers that volume has. Use `gio.Volume.get_identifier`() to obtain the identifiers themselves.

### gio.Volume.get_activation_root

                    get_activation_root

Returns :

  the activation root of volume or `None`.

The `get_activation_root`() method gets the activation root for a `gio.Volume` if it is known ahead of mount time. Returns `None` otherwise. If not `None` and if volume is mounted, then the result of `gio.Mount.get_root`() on the GMount object obtained from `gio.Volume.get_mount`() will always either be equal or a prefix of what this function returns. In other words, in code:

    mount = volume.get_mount() # mounted, so never None
    mount_root = mount.get_root()
    volume_activation_root = volume.get_activation_root() # assume not None

then the expression

    volume_activation_root.has_prefix(mount_root) || volume_activation_root.equal(mount_root)

will always be `True`.

Activation roots are typically used in `gio.VolumeMonitor` implementations to find the underlying mount to shadow, see `gio.Mount.is_shadowed`() for more details.

### gio.Volume.get_drive

                    get_drive

Returns :

  A `gio.Drive` or `None` if volume is not associated with a drive.

The `get_drive`() method gets the drive for the volume.

### gio.Volume.get_icon

                    get_icon

Returns :

  `gio.Icon` for the volume.

The `get_icon`() method gets the icon for volume.

### gio.Volume.get_identifier

                    get_identifier

Returns :

  A string containing the requested identfier, or `None` if the `gio.Volume` doesn't have this kind of identifier.

The `get_identifier`() method gets the identifier of the given kind for volume.

### gio.Volume.get_mount

                    get_mount

Returns :

  A `gio.Mount` or `None` if volume isn't mounted.

The `get_mount`() method gets the mount for the volume.

### gio.Volume.get_name

                    get_name

Returns :

  A string containing volume's name.

The `get_name`() method gets the name of volume.

### gio.Volume.get_uuid

                    get_uuid

Returns :

  the UUID for volume or `None` if no UUID can be computed.

The `get_uuid`() method 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 `None` if there is no UUID available.

### gio.Volume.mount

                    mount

                        mount_operation

                        callback

                        flagsgio.MOUNT_MOUNT_NONE

                        cancellableNone

                        user_dataNone

`mount_operation` :

  A `gio.MountOperation` or `None` to avoid user interaction.

`callback` :

  A GAsyncReadyCallback to call when the request is satisfied.

`flags` :

  Flags affecting the operation

`cancellable` :

  Optional `gio.Cancellable` object, `None` to ignore.

`user_data` :

  The data to pass to callback function.

The `mount`() method mounts a volume. This is an asynchronous operation, and is finished by calling `gio.Volume.mount_finish`() with the volume and GAsyncResult returned in the callback.

### gio.Volume.mount_finish

                    mount_finish
                    result

`result` :

  a `gio.AsyncResult`.

Returns :

  `True` if the volume has been mounted successfully, `False` otherwise.

The `mounted`() method finishes mounting a volume. If any errors occured during the operation, error will be set to contain the errors and `False` will be returned.

If the mount operation succeeded, `get_mount`() on volume is guaranteed to return the mount right after calling this function; there's no need to listen for the 'mount-added' signal on `gio.VolumeMonitor`.

### gio.Volume.should_automount

                    should_automount

Returns :

  `True` if the volume should be automatically mounted.

The `should_automount`() method returns whether the volume should be automatically mounted.

## Signals

### The "changed" gio.Volume Signal

    callback
                    volume
                    user_param1
                    ...

`volume` :

  the volume

`user_param1` :

  the first user parameter (if any) specified with the `connect`() method

`...` :

  additional user parameters (if any)

Emitted when the volume has been changed.

### The "removed" gio.Volume Signal

    callback
                    volume
                    user_param1
                    ...

`volume` :

  the volume

`user_param1` :

  the first user parameter (if any) specified with the `connect`() method

`...` :

  additional user parameters (if any)

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