:right-sidebar: True Volume =================================================================== .. currentmodule:: gi.repository.Gio .. class:: Volume(*args, **kwargs) :no-contents-entry: 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 :obj:`~gi.repository.Gio.Mount` can be retrieved using :obj:`~gi.repository.Gio.Volume.get_mount`\. Mounting a ``GVolume`` instance is an asynchronous operation. For more information about asynchronous operations, see :obj:`~gi.repository.Gio.AsyncResult` and :obj:`~gi.repository.Gio.Task`\. To mount a ``GVolume``\, first call :obj:`~gi.repository.Gio.Volume.mount` with (at least) the ``GVolume`` instance, optionally a :obj:`~gi.repository.Gio.MountOperation` object and a :obj:`~gi.repository.Gio.AsyncReadyCallback`\. Typically, one will only want to pass ``NULL`` for the :obj:`~gi.repository.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 :obj:`~gi.repository.Gio.AsyncResult` instance will be passed to the callback. That callback should then call :obj:`~gi.repository.Gio.Volume.mount_finish` with the ``GVolume`` instance and the :obj:`~gi.repository.Gio.AsyncResult` data to see if the operation was completed successfully. If a :obj:`~gi.repository.GLib.Error` is present when :obj:`~gi.repository.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 :obj:`~gi.repository.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()``\. Methods ------- .. rst-class:: interim-class .. class:: Volume :no-index: .. method:: can_eject() -> bool Checks if a volume can be ejected. .. method:: can_mount() -> bool Checks if a volume can be mounted. .. method:: eject(flags: ~gi.repository.Gio.MountUnmountFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Ejects a volume. This is an asynchronous operation, and is finished by calling :func:`~gi.repository.Gio.Volume.eject_finish` with the ``volume`` and :obj:`~gi.repository.Gio.AsyncResult` returned in the ``callback``\. .. deprecated:: 2.22 Use :func:`~gi.repository.Gio.Volume.eject_with_operation` instead. :param flags: flags affecting the unmount if required for eject :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None` :param user_data: user data that gets passed to ``callback`` .. method:: eject_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes ejecting a volume. If any errors occurred during the operation, ``error`` will be set to contain the errors and :const:`False` will be returned. .. deprecated:: 2.22 Use :func:`~gi.repository.Gio.Volume.eject_with_operation_finish` instead. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: eject_with_operation(flags: ~gi.repository.Gio.MountUnmountFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Ejects a volume. This is an asynchronous operation, and is finished by calling :func:`~gi.repository.Gio.Volume.eject_with_operation_finish` with the ``volume`` and :obj:`~gi.repository.Gio.AsyncResult` data returned in the ``callback``\. .. versionadded:: 2.22 :param flags: flags affecting the unmount if required for eject :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None` :param user_data: user data passed to ``callback`` .. method:: eject_with_operation_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes ejecting a volume. If any errors occurred during the operation, ``error`` will be set to contain the errors and :const:`False` will be returned. .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: enumerate_identifiers() -> list[str] Gets the kinds of `identifiers <#volume-identifiers>`__ that ``volume`` has. Use :func:`~gi.repository.Gio.Volume.get_identifier` to obtain the identifiers themselves. .. method:: get_activation_root() -> ~gi.repository.Gio.File | None Gets the activation root for a :obj:`~gi.repository.Gio.Volume` if it is known ahead of mount time. Returns :const:`None` otherwise. If not :const:`None` and if ``volume`` is mounted, then the result of :func:`~gi.repository.Gio.Mount.get_root` on the :obj:`~gi.repository.Gio.Mount` object obtained from :func:`~gi.repository.Gio.Volume.get_mount` will always either be equal or a prefix of what this function returns. In other words, in code .. code-block:: C :dedent: 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 .. code-block:: C :dedent: (g_file_has_prefix (volume_activation_root, mount_root) || g_file_equal (volume_activation_root, mount_root)) will always be :const:`True`. Activation roots are typically used in :obj:`~gi.repository.Gio.VolumeMonitor` implementations to find the underlying mount to shadow, see :func:`~gi.repository.Gio.Mount.is_shadowed` for more details. .. versionadded:: 2.18 .. method:: get_drive() -> ~gi.repository.Gio.Drive | None Gets the drive for the ``volume``\. .. method:: get_icon() -> ~gi.repository.Gio.Icon Gets the icon for ``volume``\. .. method:: get_identifier(kind: str) -> str | None Gets the identifier of the given kind for ``volume``\. See the `introduction <#volume-identifiers>`__ for more information about volume identifiers. :param kind: the kind of identifier to return .. method:: get_mount() -> ~gi.repository.Gio.Mount | None Gets the mount for the ``volume``\. .. method:: get_name() -> str Gets the name of ``volume``\. .. method:: get_sort_key() -> str | None Gets the sort key for ``volume``\, if any. .. versionadded:: 2.32 .. method:: get_symbolic_icon() -> ~gi.repository.Gio.Icon Gets the symbolic icon for ``volume``\. .. versionadded:: 2.34 .. method:: get_uuid() -> 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 :const:`None` if there is no UUID available. .. method:: mount(flags: ~gi.repository.Gio.MountMountFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Mounts a volume. This is an asynchronous operation, and is finished by calling :func:`~gi.repository.Gio.Volume.mount_finish` with the ``volume`` and :obj:`~gi.repository.Gio.AsyncResult` returned in the ``callback``\. :param flags: flags affecting the operation :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None` :param user_data: user data that gets passed to ``callback`` .. method:: mount_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes mounting a volume. If any errors occurred during the operation, ``error`` will be set to contain the errors and :const:`False` will be returned. If the mount operation succeeded, :func:`~gi.repository.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 :obj:`~gi.repository.Gio.VolumeMonitor`\. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: should_automount() -> bool Returns whether the volume should be automatically mounted. Signals ------- .. rst-class:: interim-class .. class:: Volume.signals :no-index: .. method:: changed() -> None The type of the None singleton. .. method:: removed() -> None The type of the None singleton. Virtual Methods --------------- .. rst-class:: interim-class .. class:: Volume :no-index: .. method:: do_can_eject() -> bool Checks if a volume can be ejected. .. method:: do_can_mount() -> bool Checks if a volume can be mounted. .. method:: do_changed() -> None The type of the None singleton. .. method:: do_eject(flags: ~gi.repository.Gio.MountUnmountFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Ejects a volume. This is an asynchronous operation, and is finished by calling :func:`~gi.repository.Gio.Volume.eject_finish` with the ``volume`` and :obj:`~gi.repository.Gio.AsyncResult` returned in the ``callback``\. .. deprecated:: 2.22 Use :func:`~gi.repository.Gio.Volume.eject_with_operation` instead. :param flags: flags affecting the unmount if required for eject :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None` :param user_data: user data that gets passed to ``callback`` .. method:: do_eject_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes ejecting a volume. If any errors occurred during the operation, ``error`` will be set to contain the errors and :const:`False` will be returned. .. deprecated:: 2.22 Use :func:`~gi.repository.Gio.Volume.eject_with_operation_finish` instead. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: do_eject_with_operation(flags: ~gi.repository.Gio.MountUnmountFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Ejects a volume. This is an asynchronous operation, and is finished by calling :func:`~gi.repository.Gio.Volume.eject_with_operation_finish` with the ``volume`` and :obj:`~gi.repository.Gio.AsyncResult` data returned in the ``callback``\. .. versionadded:: 2.22 :param flags: flags affecting the unmount if required for eject :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None` :param user_data: user data passed to ``callback`` .. method:: do_eject_with_operation_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes ejecting a volume. If any errors occurred during the operation, ``error`` will be set to contain the errors and :const:`False` will be returned. .. versionadded:: 2.22 :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: do_enumerate_identifiers() -> list[str] Gets the kinds of `identifiers <#volume-identifiers>`__ that ``volume`` has. Use :func:`~gi.repository.Gio.Volume.get_identifier` to obtain the identifiers themselves. .. method:: do_get_activation_root() -> ~gi.repository.Gio.File | None Gets the activation root for a :obj:`~gi.repository.Gio.Volume` if it is known ahead of mount time. Returns :const:`None` otherwise. If not :const:`None` and if ``volume`` is mounted, then the result of :func:`~gi.repository.Gio.Mount.get_root` on the :obj:`~gi.repository.Gio.Mount` object obtained from :func:`~gi.repository.Gio.Volume.get_mount` will always either be equal or a prefix of what this function returns. In other words, in code .. code-block:: C :dedent: 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 .. code-block:: C :dedent: (g_file_has_prefix (volume_activation_root, mount_root) || g_file_equal (volume_activation_root, mount_root)) will always be :const:`True`. Activation roots are typically used in :obj:`~gi.repository.Gio.VolumeMonitor` implementations to find the underlying mount to shadow, see :func:`~gi.repository.Gio.Mount.is_shadowed` for more details. .. versionadded:: 2.18 .. method:: do_get_drive() -> ~gi.repository.Gio.Drive | None Gets the drive for the ``volume``\. .. method:: do_get_icon() -> ~gi.repository.Gio.Icon Gets the icon for ``volume``\. .. method:: do_get_identifier(kind: str) -> str | None Gets the identifier of the given kind for ``volume``\. See the `introduction <#volume-identifiers>`__ for more information about volume identifiers. :param kind: the kind of identifier to return .. method:: do_get_mount() -> ~gi.repository.Gio.Mount | None Gets the mount for the ``volume``\. .. method:: do_get_name() -> str Gets the name of ``volume``\. .. method:: do_get_sort_key() -> str | None Gets the sort key for ``volume``\, if any. .. versionadded:: 2.32 .. method:: do_get_symbolic_icon() -> ~gi.repository.Gio.Icon Gets the symbolic icon for ``volume``\. .. versionadded:: 2.34 .. method:: do_get_uuid() -> 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 :const:`None` if there is no UUID available. .. method:: do_mount_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finishes mounting a volume. If any errors occurred during the operation, ``error`` will be set to contain the errors and :const:`False` will be returned. If the mount operation succeeded, :func:`~gi.repository.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 :obj:`~gi.repository.Gio.VolumeMonitor`\. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: do_mount_fn(flags: ~gi.repository.Gio.MountMountFlags, mount_operation: ~gi.repository.Gio.MountOperation | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None The type of the None singleton. :param flags: flags affecting the operation :param mount_operation: a :obj:`~gi.repository.Gio.MountOperation` or :const:`None` to avoid user interaction :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\, or :const:`None` :param user_data: user data that gets passed to ``callback`` .. method:: do_removed() -> None The type of the None singleton. .. method:: do_should_automount() -> bool Returns whether the volume should be automatically mounted.