Gio.Volume

g GObject.GInterface GObject.GInterface Gio.Volume Gio.Volume GObject.GInterface->Gio.Volume

Implementations:

None

Methods

can_eject ()

can_mount ()

eject (flags, cancellable, callback, *user_data)

eject_finish (result)

eject_with_operation (flags, mount_operation, cancellable, callback, *user_data)

eject_with_operation_finish (result)

enumerate_identifiers ()

get_activation_root ()

get_drive ()

get_icon ()

get_identifier (kind)

get_mount ()

get_name ()

get_sort_key ()

get_symbolic_icon ()

get_uuid ()

mount (flags, mount_operation, cancellable, callback, *user_data)

mount_finish (result)

should_automount ()

Virtual Methods

do_can_eject ()

do_can_mount ()

do_changed ()

do_eject (flags, cancellable, callback, *user_data)

do_eject_finish (result)

do_eject_with_operation (flags, mount_operation, cancellable, callback, *user_data)

do_eject_with_operation_finish (result)

do_enumerate_identifiers ()

do_get_activation_root ()

do_get_drive ()

do_get_icon ()

do_get_identifier (kind)

do_get_mount ()

do_get_name ()

do_get_sort_key ()

do_get_symbolic_icon ()

do_get_uuid ()

do_mount_finish (result)

do_mount_fn (flags, mount_operation, cancellable, callback, *user_data)

do_removed ()

do_should_automount ()

Properties

None

Signals

Name

Short Description

changed

Emitted when the volume has been changed.

removed

This signal is emitted when the Gio.Volume have been removed.

Fields

None

Class Details

class Gio.Volume
Bases:

GObject.GInterface

Structure:

Gio.VolumeIface

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 [iface`Gio`.AsyncResult] and [class`Gio`.Task]. To mount a GVolume, first call [method`Gio`.Volume.mount] with (at least) the GVolume instance, optionally a [class`Gio`.MountOperation] object and a [type`Gio`.AsyncReadyCallback].

Typically, one will only want to pass NULL for the [class`Gio`.MountOperation] 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 [iface`Gio`.AsyncResult] instance will be passed to the callback. That callback should then call [method`Gio`.Volume.mount_finish] with the GVolume instance and the [iface`Gio`.AsyncResult] data to see if the operation was completed successfully. If a [type`GLib`.Error] is present when [method`Gio`.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 [method`Gio`.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().

can_eject()[source]
Returns:

True if the self can be ejected. False otherwise

Return type:

bool

Checks if a volume can be ejected.

can_mount()[source]
Returns:

True if the self can be mounted. False otherwise

Return type:

bool

Checks if a volume can be mounted.

eject(flags, cancellable, callback, *user_data)[source]
Parameters:

Ejects a volume. This is an asynchronous operation, and is finished by calling Gio.Volume.eject_finish() with the self and Gio.AsyncResult returned in the callback.

Deprecated since version 2.22: Use Gio.Volume.eject_with_operation() instead.

eject_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True, False if operation failed

Return type:

bool

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 since version 2.22: Use Gio.Volume.eject_with_operation_finish() instead.

eject_with_operation(flags, mount_operation, cancellable, callback, *user_data)[source]
Parameters:

Ejects a volume. This is an asynchronous operation, and is finished by calling Gio.Volume.eject_with_operation_finish() with the self and Gio.AsyncResult data returned in the callback.

New in version 2.22.

eject_with_operation_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if the volume was successfully ejected. False otherwise

Return type:

bool

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

New in version 2.22.

enumerate_identifiers()[source]
Returns:

a None-terminated array of strings containing kinds of identifiers. Use GLib.strfreev() to free.

Return type:

[str]

Gets the kinds of identifiers that self has. Use Gio.Volume.get_identifier() to obtain the identifiers themselves.

get_activation_root()[source]
Returns:

the activation root of self or None. Use GObject.Object.unref() to free.

Return type:

Gio.File or None

Gets the activation root for a Gio.Volume if it is known ahead of mount time. Returns None otherwise. If not None and if self is mounted, then the result of Gio.Mount.get_root() on the Gio.Mount 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

GMount *mount;
GFile *mount_root
GFile *volume_activation_root;

mount = g_volume_get_mount (volume); // mounted, so never NULL
mount_root = g_mount_get_root (mount);
volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL

then the expression

(g_file_has_prefix (volume_activation_root, mount_root) ||
g_file_equal (volume_activation_root, 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.

New in version 2.18.

get_drive()[source]
Returns:

a Gio.Drive or None if self is not associated with a drive. The returned object should be unreffed with GObject.Object.unref() when no longer needed.

Return type:

Gio.Drive or None

Gets the drive for the self.

get_icon()[source]
Returns:

a Gio.Icon. The returned object should be unreffed with GObject.Object.unref() when no longer needed.

Return type:

Gio.Icon

Gets the icon for self.

get_identifier(kind)[source]
Parameters:

kind (str) – the kind of identifier to return

Returns:

a newly allocated string containing the requested identifier, or None if the Gio.Volume doesn’t have this kind of identifier

Return type:

str or None

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

get_mount()[source]
Returns:

a Gio.Mount or None if self isn’t mounted. The returned object should be unreffed with GObject.Object.unref() when no longer needed.

Return type:

Gio.Mount or None

Gets the mount for the self.

get_name()[source]
Returns:

the name for the given self. The returned string should be freed with GLib.free() when no longer needed.

Return type:

str

Gets the name of self.

get_sort_key()[source]
Returns:

Sorting key for self or None if no such key is available

Return type:

str or None

Gets the sort key for self, if any.

New in version 2.32.

get_symbolic_icon()[source]
Returns:

a Gio.Icon. The returned object should be unreffed with GObject.Object.unref() when no longer needed.

Return type:

Gio.Icon

Gets the symbolic icon for self.

New in version 2.34.

get_uuid()[source]
Returns:

the UUID for self or None if no UUID can be computed. The returned string should be freed with GLib.free() when no longer needed.

Return type:

str or None

Gets the UUID for the self. 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.

mount(flags, mount_operation, cancellable, callback, *user_data)[source]
Parameters:

Mounts a volume. This is an asynchronous operation, and is finished by calling Gio.Volume.mount_finish() with the self and Gio.AsyncResult returned in the callback.

mount_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True, False if operation failed

Return type:

bool

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

If the mount operation succeeded, Gio.Volume.get_mount() on self 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.

should_automount()[source]
Returns:

True if the volume should be automatically mounted

Return type:

bool

Returns whether the volume should be automatically mounted.

do_can_eject() virtual
Returns:

True if the volume can be ejected. False otherwise

Return type:

bool

Checks if a volume can be ejected.

do_can_mount() virtual
Returns:

True if the volume can be mounted. False otherwise

Return type:

bool

Checks if a volume can be mounted.

do_changed() virtual

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

do_eject(flags, cancellable, callback, *user_data) virtual
Parameters:

Ejects a volume. This is an asynchronous operation, and is finished by calling Gio.Volume.eject_finish() with the volume and Gio.AsyncResult returned in the callback.

Deprecated since version 2.22: Use Gio.Volume.eject_with_operation() instead.

do_eject_finish(result) virtual
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Returns:

True, False if operation failed

Return type:

bool

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 since version 2.22: Use Gio.Volume.eject_with_operation_finish() instead.

do_eject_with_operation(flags, mount_operation, cancellable, callback, *user_data) virtual
Parameters:

Ejects a volume. This is an asynchronous operation, and is finished by calling Gio.Volume.eject_with_operation_finish() with the volume and Gio.AsyncResult data returned in the callback.

New in version 2.22.

do_eject_with_operation_finish(result) virtual
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Returns:

True if the volume was successfully ejected. False otherwise

Return type:

bool

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

New in version 2.22.

do_enumerate_identifiers() virtual
Returns:

a None-terminated array of strings containing kinds of identifiers. Use GLib.strfreev() to free.

Return type:

[str]

Gets the kinds of identifiers that volume has. Use Gio.Volume.get_identifier() to obtain the identifiers themselves.

do_get_activation_root() virtual
Returns:

the activation root of volume or None. Use GObject.Object.unref() to free.

Return type:

Gio.File or None

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 Gio.Mount 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

GMount *mount;
GFile *mount_root
GFile *volume_activation_root;

mount = g_volume_get_mount (volume); // mounted, so never NULL
mount_root = g_mount_get_root (mount);
volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL

then the expression

(g_file_has_prefix (volume_activation_root, mount_root) ||
g_file_equal (volume_activation_root, 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.

New in version 2.18.

do_get_drive() virtual
Returns:

a Gio.Drive or None if volume is not associated with a drive. The returned object should be unreffed with GObject.Object.unref() when no longer needed.

Return type:

Gio.Drive or None

Gets the drive for the volume.

do_get_icon() virtual
Returns:

a Gio.Icon. The returned object should be unreffed with GObject.Object.unref() when no longer needed.

Return type:

Gio.Icon

Gets the icon for volume.

do_get_identifier(kind) virtual
Parameters:

kind (str) – the kind of identifier to return

Returns:

a newly allocated string containing the requested identifier, or None if the Gio.Volume doesn’t have this kind of identifier

Return type:

str or None

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

do_get_mount() virtual
Returns:

a Gio.Mount or None if volume isn’t mounted. The returned object should be unreffed with GObject.Object.unref() when no longer needed.

Return type:

Gio.Mount or None

Gets the mount for the volume.

do_get_name() virtual
Returns:

the name for the given volume. The returned string should be freed with GLib.free() when no longer needed.

Return type:

str

Gets the name of volume.

do_get_sort_key() virtual
Returns:

Sorting key for volume or None if no such key is available

Return type:

str or None

Gets the sort key for volume, if any.

New in version 2.32.

do_get_symbolic_icon() virtual
Returns:

a Gio.Icon. The returned object should be unreffed with GObject.Object.unref() when no longer needed.

Return type:

Gio.Icon

Gets the symbolic icon for volume.

New in version 2.34.

do_get_uuid() virtual
Returns:

the UUID for volume or None if no UUID can be computed. The returned string should be freed with GLib.free() when no longer needed.

Return type:

str or None

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.

do_mount_finish(result) virtual
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Returns:

True, False if operation failed

Return type:

bool

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

If the mount operation succeeded, Gio.Volume.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.

do_mount_fn(flags, mount_operation, cancellable, callback, *user_data) virtual
Parameters:

Mounts a volume. This is an asynchronous operation, and is finished by calling Gio.Volume.mount_finish() with the volume and Gio.AsyncResult returned in the callback.

do_removed() virtual

The removed signal that 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.

do_should_automount() virtual
Returns:

True if the volume should be automatically mounted

Return type:

bool

Returns whether the volume should be automatically mounted.

Signal Details

Gio.Volume.signals.changed(volume)
Signal Name:

changed

Flags:

RUN_LAST

Parameters:

volume (Gio.Volume) – The object which received the signal

Emitted when the volume has been changed.

Gio.Volume.signals.removed(volume)
Signal Name:

removed

Flags:

RUN_LAST

Parameters:

volume (Gio.Volume) – The object which received the signal

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.