gio.Volume
Prev | PyGio Class Reference | Next

## gio.Volume

gio.Volume — Volume management.

## Synopsis

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

## Ancestry

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

## Prerequisites

`gio.Volume` requires `gobject.GObject`

## gio.Volume Signal Prototypes

gobject.GObject Signal Prototypes

"changed" | `def callback(`volume`, `user_param1`, `...`)`
"removed" | `def 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

        def 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

        def 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

        def eject(callback, flags=gio.MOUNT_UNMOUNT_NONE, cancellable=None, user_data=None)

`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

        def 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

        def 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

        def 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

        def 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

        def get_icon()

Returns : | `gio.Icon` for the volume.

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

### gio.Volume.get_identifier

        def 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

        def 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

        def get_name()

Returns : | A string containing volume's name.

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

### gio.Volume.get_uuid

        def 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

        def mount(mount_operation, callback, flags=gio.MOUNT_MOUNT_NONE, cancellable=None, user_data=None)

`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

        def 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

        def 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

        def 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

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

Prev | Up | Next
gio.ThemedIcon | Home | gio.VolumeMonitor