Skip to content

Gio.Volume

interface

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 Mount can be retrieved using Volume.get_mount.

Mounting a GVolume instance is an asynchronous operation. For more information about asynchronous operations, see AsyncResult and Task. To mount a GVolume, first call Volume.mount with (at least) the GVolume instance, optionally a MountOperation object and a AsyncReadyCallback.

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

Methods

can_eject

def can_eject(self) -> bool

Checks if a volume can be ejected.

can_mount

def can_mount(self) -> bool

Checks if a volume can be mounted.

eject

def eject(self, flags: MountUnmountFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[Volume | None, AsyncResult], None] | None = ...) -> None

:::warning Deprecated since 2.22 This API is deprecated. :::

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

Parameters:

  • flags — flags affecting the unmount if required for eject
  • cancellable — optional Cancellable object, None to ignore
  • callback — a GAsyncReadyCallback, or None

eject_finish

def eject_finish(self, result: AsyncResult) -> bool

:::warning Deprecated since 2.22 This API is deprecated. :::

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

Parameters:

eject_with_operation

def eject_with_operation(self, flags: MountUnmountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[Volume | None, AsyncResult], None] | None = ...) -> None

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

Parameters:

  • flags — flags affecting the unmount if required for eject
  • mount_operation — a MountOperation or None to avoid user interaction
  • cancellable — optional Cancellable object, None to ignore
  • callback — a GAsyncReadyCallback, or None

eject_with_operation_finish

def eject_with_operation_finish(self, result: AsyncResult) -> 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.

Parameters:

enumerate_identifiers

def enumerate_identifiers(self) -> list[str]

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

get_activation_root

def get_activation_root(self) -> File | None

Gets the activation root for a Volume if it is known ahead of mount time. Returns None otherwise. If not None and if volume is mounted, then the result of Mount.get_root on the Mount object obtained from 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 VolumeMonitor implementations to find the underlying mount to shadow, see Mount.is_shadowed for more details.

get_drive

def get_drive(self) -> Drive | None

Gets the drive for the volume.

get_icon

def get_icon(self) -> Icon

Gets the icon for volume.

get_identifier

def get_identifier(self, kind: str) -> str | None

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

Parameters:

  • kind — the kind of identifier to return

get_mount

def get_mount(self) -> Mount | None

Gets the mount for the volume.

get_name

def get_name(self) -> str

Gets the name of volume.

get_sort_key

def get_sort_key(self) -> str | None

Gets the sort key for volume, if any.

get_symbolic_icon

def get_symbolic_icon(self) -> Icon

Gets the symbolic icon for volume.

get_uuid

def get_uuid(self) -> str | 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.

mount

def mount(self, flags: MountMountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[Volume | None, AsyncResult], None] | None = ...) -> None

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

Parameters:

  • flags — flags affecting the operation
  • mount_operation — a MountOperation or None to avoid user interaction
  • cancellable — optional Cancellable object, None to ignore
  • callback — a GAsyncReadyCallback, or None

mount_finish

def mount_finish(self, result: AsyncResult) -> 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, 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 VolumeMonitor.

Parameters:

should_automount

def should_automount(self) -> bool

Returns whether the volume should be automatically mounted.

Virtual methods

do_can_eject

def do_can_eject(self) -> bool

Checks if a volume can be ejected.

do_can_mount

def do_can_mount(self) -> bool

Checks if a volume can be mounted.

do_changed

def do_changed(self) -> None

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

do_eject

def do_eject(self, flags: MountUnmountFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[Volume | None, AsyncResult], None] | None = ...) -> None

:::warning Deprecated since 2.22 This API is deprecated. :::

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

Parameters:

  • flags — flags affecting the unmount if required for eject
  • cancellable — optional Cancellable object, None to ignore
  • callback — a GAsyncReadyCallback, or None

do_eject_finish

def do_eject_finish(self, result: AsyncResult) -> bool

:::warning Deprecated since 2.22 This API is deprecated. :::

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

Parameters:

do_eject_with_operation

def do_eject_with_operation(self, flags: MountUnmountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[Volume | None, AsyncResult], None] | None = ...) -> None

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

Parameters:

  • flags — flags affecting the unmount if required for eject
  • mount_operation — a MountOperation or None to avoid user interaction
  • cancellable — optional Cancellable object, None to ignore
  • callback — a GAsyncReadyCallback, or None

do_eject_with_operation_finish

def do_eject_with_operation_finish(self, result: AsyncResult) -> 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.

Parameters:

do_enumerate_identifiers

def do_enumerate_identifiers(self) -> list[str]

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

do_get_activation_root

def do_get_activation_root(self) -> File | None

Gets the activation root for a Volume if it is known ahead of mount time. Returns None otherwise. If not None and if volume is mounted, then the result of Mount.get_root on the Mount object obtained from 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 VolumeMonitor implementations to find the underlying mount to shadow, see Mount.is_shadowed for more details.

do_get_drive

def do_get_drive(self) -> Drive | None

Gets the drive for the volume.

do_get_icon

def do_get_icon(self) -> Icon

Gets the icon for volume.

do_get_identifier

def do_get_identifier(self, kind: str) -> str | None

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

Parameters:

  • kind — the kind of identifier to return

do_get_mount

def do_get_mount(self) -> Mount | None

Gets the mount for the volume.

do_get_name

def do_get_name(self) -> str

Gets the name of volume.

do_get_sort_key

def do_get_sort_key(self) -> str | None

Gets the sort key for volume, if any.

do_get_symbolic_icon

def do_get_symbolic_icon(self) -> Icon

Gets the symbolic icon for volume.

do_get_uuid

def do_get_uuid(self) -> str | 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

def do_mount_finish(self, result: AsyncResult) -> 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, 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 VolumeMonitor.

Parameters:

do_mount_fn

def do_mount_fn(self, flags: MountMountFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[Volume | None, AsyncResult], None] | None = ...) -> None

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

Parameters:

  • flags — flags affecting the operation
  • mount_operation — a MountOperation or None to avoid user interaction
  • cancellable — optional Cancellable object, None to ignore
  • callback — a GAsyncReadyCallback, or None

do_removed

def do_removed(self) -> None

The removed signal that is emitted when the 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

def do_should_automount(self) -> bool

Returns whether the volume should be automatically mounted.

Signals

changed

def on_changed(self) -> None: ...

Emitted when the volume has been changed.

removed

def on_removed(self) -> None: ...

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