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 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, see Gio.AsyncResult and Gio.Task. To mount a Gio.Volume, first call Gio.Volume.mount() with (at least) the Gio.Volume instance, optionally a Gio.MountOperation object and a Gio.AsyncReadyCallback.

Typically, one will only want to pass None for the 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 Gio.AsyncResult instance will be passed to the callback. That callback should then call Gio.Volume.mount_finish() with the Gio.Volume instance and the Gio.AsyncResult 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.

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 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 predefined strings as names for the different kinds of identifiers: Gio.VOLUME_IDENTIFIER_KIND_UUID, Gio.VOLUME_IDENTIFIER_KIND_LABEL, etc. Use Gio.Volume.get_identifier() to obtain an identifier for a volume.

Note that Gio.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 Gio.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¶

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¶

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.