Skip to content

Gio.Drive

interface

GDrive represents a piece of hardware connected to the machine. It’s generally only created for removable hardware or hardware with removable media. For example, an optical disc drive, or a USB flash drive.

GDrive is a container class for Volume objects that stem from the same piece of media. As such, GDrive abstracts a drive with (or without) removable media and provides operations for querying whether media is available, determining whether media change is automatically detected and ejecting the media.

If the GDrive reports that media isn’t automatically detected, one can poll for media; typically one should not do this periodically as a poll for media operation is potentially expensive and may spin up the drive creating noise.

GDrive supports starting and stopping drives with authentication support for the former. This can be used to support a diverse set of use cases including connecting/disconnecting iSCSI devices, powering down external disk enclosures and starting/stopping multi-disk devices such as RAID devices. Note that the actual semantics and side-effects of starting/stopping a GDrive may vary according to implementation. To choose the correct verbs in e.g. a file manager, use Drive.get_start_stop_type.

For porting from GnomeVFS note that there is no equivalent of GDrive in that API.

Methods

can_eject

def can_eject(self) -> bool

Checks if a drive can be ejected.

can_poll_for_media

def can_poll_for_media(self) -> bool

Checks if a drive can be polled for media changes.

can_start

def can_start(self) -> bool

Checks if a drive can be started.

can_start_degraded

def can_start_degraded(self) -> bool

Checks if a drive can be started degraded.

can_stop

def can_stop(self) -> bool

Checks if a drive can be stopped.

eject

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

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

Asynchronously ejects a drive.

When the operation is finished, callback will be called. You can then call Drive.eject_finish to obtain the result of the operation.

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 drive.

Parameters:

eject_with_operation

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

Ejects a drive. This is an asynchronous operation, and is finished by calling Drive.eject_with_operation_finish with the drive 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 drive. 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 drive has. Use Drive.get_identifier to obtain the identifiers themselves.

get_icon

def get_icon(self) -> Icon

Gets the icon for drive.

get_identifier

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

Gets the identifier of the given kind for drive. The only identifier currently available is DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.

Parameters:

  • kind — the kind of identifier to return

get_name

def get_name(self) -> str

Gets the name of drive.

get_sort_key

def get_sort_key(self) -> str | None

Gets the sort key for drive, if any.

get_start_stop_type

def get_start_stop_type(self) -> DriveStartStopType

Gets a hint about how a drive can be started/stopped.

get_symbolic_icon

def get_symbolic_icon(self) -> Icon

Gets the icon for drive.

get_volumes

def get_volumes(self) -> list[Volume]

Get a list of mountable volumes for drive.

The returned list should be freed with g_list_free(), after its elements have been unreffed with GObject.Object.unref.

has_media

def has_media(self) -> bool

Checks if the drive has media. Note that the OS may not be polling the drive for media changes; see Drive.is_media_check_automatic for more details.

has_volumes

def has_volumes(self) -> bool

Check if drive has any mountable volumes.

is_media_check_automatic

def is_media_check_automatic(self) -> bool

Checks if drive is capable of automatically detecting media changes.

is_media_removable

def is_media_removable(self) -> bool

Checks if the drive supports removable media.

is_removable

def is_removable(self) -> bool

Checks if the Drive and/or its media is considered removable by the user. See Drive.is_media_removable.

poll_for_media

def poll_for_media(self, cancellable: Cancellable | None = ..., callback: Callable[[Drive | None, AsyncResult], None] | None = ...) -> None

Asynchronously polls drive to see if media has been inserted or removed.

When the operation is finished, callback will be called. You can then call Drive.poll_for_media_finish to obtain the result of the operation.

Parameters:

  • cancellable — optional Cancellable object, None to ignore.
  • callback — a GAsyncReadyCallback, or None.

poll_for_media_finish

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

Finishes an operation started with Drive.poll_for_media on a drive.

Parameters:

start

def start(self, flags: DriveStartFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[Drive | None, AsyncResult], None] | None = ...) -> None

Asynchronously starts a drive.

When the operation is finished, callback will be called. You can then call Drive.start_finish to obtain the result of the operation.

Parameters:

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

start_finish

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

Finishes starting a drive.

Parameters:

stop

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

Asynchronously stops a drive.

When the operation is finished, callback will be called. You can then call Drive.stop_finish to obtain the result of the operation.

Parameters:

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

stop_finish

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

Finishes stopping a drive.

Parameters:

Virtual methods

do_can_eject

def do_can_eject(self) -> bool

Checks if a drive can be ejected.

do_can_poll_for_media

def do_can_poll_for_media(self) -> bool

Checks if a drive can be polled for media changes.

do_can_start

def do_can_start(self) -> bool

Checks if a drive can be started.

do_can_start_degraded

def do_can_start_degraded(self) -> bool

Checks if a drive can be started degraded.

do_can_stop

def do_can_stop(self) -> bool

Checks if a drive can be stopped.

do_changed

def do_changed(self) -> None

Signal emitted when the drive is changed.

do_disconnected

def do_disconnected(self) -> None

The removed signal that is emitted when the Drive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized.

do_eject

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

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

Asynchronously ejects a drive.

When the operation is finished, callback will be called. You can then call Drive.eject_finish to obtain the result of the operation.

Parameters:

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

do_eject_button

def do_eject_button(self) -> None

Signal emitted when the physical eject button (if any) of a drive have been pressed.

do_eject_finish

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

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

Finishes ejecting a drive.

Parameters:

do_eject_with_operation

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

Ejects a drive. This is an asynchronous operation, and is finished by calling Drive.eject_with_operation_finish with the drive 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 drive. 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 drive has. Use Drive.get_identifier to obtain the identifiers themselves.

do_get_icon

def do_get_icon(self) -> Icon

Gets the icon for drive.

do_get_identifier

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

Gets the identifier of the given kind for drive. The only identifier currently available is DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.

Parameters:

  • kind — the kind of identifier to return

do_get_name

def do_get_name(self) -> str

Gets the name of drive.

do_get_sort_key

def do_get_sort_key(self) -> str | None

Gets the sort key for drive, if any.

do_get_start_stop_type

def do_get_start_stop_type(self) -> DriveStartStopType

Gets a hint about how a drive can be started/stopped.

do_get_symbolic_icon

def do_get_symbolic_icon(self) -> Icon

Gets the icon for drive.

do_get_volumes

def do_get_volumes(self) -> list[Volume]

Get a list of mountable volumes for drive.

The returned list should be freed with g_list_free(), after its elements have been unreffed with GObject.Object.unref.

do_has_media

def do_has_media(self) -> bool

Checks if the drive has media. Note that the OS may not be polling the drive for media changes; see Drive.is_media_check_automatic for more details.

do_has_volumes

def do_has_volumes(self) -> bool

Check if drive has any mountable volumes.

do_is_media_check_automatic

def do_is_media_check_automatic(self) -> bool

Checks if drive is capable of automatically detecting media changes.

do_is_media_removable

def do_is_media_removable(self) -> bool

Checks if the drive supports removable media.

do_is_removable

def do_is_removable(self) -> bool

Checks if the Drive and/or its media is considered removable by the user. See Drive.is_media_removable.

do_poll_for_media

def do_poll_for_media(self, cancellable: Cancellable | None = ..., callback: Callable[[Drive | None, AsyncResult], None] | None = ...) -> None

Asynchronously polls drive to see if media has been inserted or removed.

When the operation is finished, callback will be called. You can then call Drive.poll_for_media_finish to obtain the result of the operation.

Parameters:

  • cancellable — optional Cancellable object, None to ignore.
  • callback — a GAsyncReadyCallback, or None.

do_poll_for_media_finish

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

Finishes an operation started with Drive.poll_for_media on a drive.

Parameters:

do_start

def do_start(self, flags: DriveStartFlags | int, mount_operation: MountOperation | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[Drive | None, AsyncResult], None] | None = ...) -> None

Asynchronously starts a drive.

When the operation is finished, callback will be called. You can then call Drive.start_finish to obtain the result of the operation.

Parameters:

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

do_start_finish

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

Finishes starting a drive.

Parameters:

do_stop

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

Asynchronously stops a drive.

When the operation is finished, callback will be called. You can then call Drive.stop_finish to obtain the result of the operation.

Parameters:

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

do_stop_button

def do_stop_button(self) -> None

Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22.

do_stop_finish

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

Finishes stopping a drive.

Parameters:

Signals

changed

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

Emitted when the drive's state has changed.

disconnected

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

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

eject-button

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

Emitted when the physical eject button (if any) of a drive has been pressed.

stop-button

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

Emitted when the physical stop button (if any) of a drive has been pressed.