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. For example, a file system partition on a USB flash drive, or an optical disc inserted into a disc drive.

If a GVolume is currently mounted, the corresponding [iface`Gio`.Mount] can be retrieved using [method`Gio`.Volume.get_mount].

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.

Note, when porting from GnomeVFS, GVolume is the moral equivalent of GnomeVFSDrive.

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:

flags (Gio.MountUnmountFlags) – flags affecting the unmount if required for eject
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback, or None
user_data (object or None) – user data that gets passed to callback

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:

flags (Gio.MountUnmountFlags) – flags affecting the unmount if required for eject
mount_operation (Gio.MountOperation or None) – a Gio.MountOperation or None to avoid user interaction
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback, or None
user_data (object or None) – user data passed to callback

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:

flags (Gio.MountMountFlags) – flags affecting the operation
mount_operation (Gio.MountOperation or None) – a Gio.MountOperation or None to avoid user interaction
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback, or None
user_data (object or None) – user data that gets passed to callback

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:

flags (Gio.MountUnmountFlags) – flags affecting the unmount if required for eject
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback, or None
user_data (object or None) – user data that gets passed to callback

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:

flags (Gio.MountUnmountFlags) – flags affecting the unmount if required for eject
mount_operation (Gio.MountOperation or None) – a Gio.MountOperation or None to avoid user interaction
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback, or None
user_data (object or None) – user data passed to callback

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:

flags (Gio.MountMountFlags) – flags affecting the operation
mount_operation (Gio.MountOperation or None) – a Gio.MountOperation or None to avoid user interaction
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback, or None
user_data (object or None) – user data that gets passed to callback

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.