Gio.Drive

g GObject.GInterface GObject.GInterface Gio.Drive Gio.Drive GObject.GInterface->Gio.Drive

Implementations:

None

Methods

can_eject ()

can_poll_for_media ()

can_start ()

can_start_degraded ()

can_stop ()

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_icon ()

get_identifier (kind)

get_name ()

get_sort_key ()

get_start_stop_type ()

get_symbolic_icon ()

get_volumes ()

has_media ()

has_volumes ()

is_media_check_automatic ()

is_media_removable ()

is_removable ()

poll_for_media (cancellable, callback, *user_data)

poll_for_media_finish (result)

start (flags, mount_operation, cancellable, callback, *user_data)

start_finish (result)

stop (flags, mount_operation, cancellable, callback, *user_data)

stop_finish (result)

Virtual Methods

do_can_eject ()

do_can_poll_for_media ()

do_can_start ()

do_can_start_degraded ()

do_can_stop ()

do_changed ()

do_disconnected ()

do_eject (flags, cancellable, callback, *user_data)

do_eject_button ()

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_icon ()

do_get_identifier (kind)

do_get_name ()

do_get_sort_key ()

do_get_start_stop_type ()

do_get_symbolic_icon ()

do_get_volumes ()

do_has_media ()

do_has_volumes ()

do_is_media_check_automatic ()

do_is_media_removable ()

do_is_removable ()

do_poll_for_media (cancellable, callback, *user_data)

do_poll_for_media_finish (result)

do_start (flags, mount_operation, cancellable, callback, *user_data)

do_start_finish (result)

do_stop (flags, mount_operation, cancellable, callback, *user_data)

do_stop_button ()

do_stop_finish (result)

Properties

None

Signals

Name

Short Description

changed

Emitted when the drive’s state has changed.

disconnected

This signal is emitted when the Gio.Drive have been disconnected.

eject-button

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

stop-button

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

Fields

None

Class Details

class Gio.Drive
Bases:

GObject.GInterface

Structure:

Gio.DriveIface

GDrive represents a piece of hardware connected to the machine. It’s generally only created for removable hardware or hardware with removable media.

GDrive is a container class for [iface`Gio`.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 [method`Gio`.Drive.get_start_stop_type].

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

can_eject()[source]
Returns:

True if the self can be ejected, False otherwise.

Return type:

bool

Checks if a drive can be ejected.

can_poll_for_media()[source]
Returns:

True if the self can be polled for media changes, False otherwise.

Return type:

bool

Checks if a drive can be polled for media changes.

can_start()[source]
Returns:

True if the self can be started, False otherwise.

Return type:

bool

Checks if a drive can be started.

New in version 2.22.

can_start_degraded()[source]
Returns:

True if the self can be started degraded, False otherwise.

Return type:

bool

Checks if a drive can be started degraded.

New in version 2.22.

can_stop()[source]
Returns:

True if the self can be stopped, False otherwise.

Return type:

bool

Checks if a drive can be stopped.

New in version 2.22.

eject(flags, cancellable, callback, *user_data)[source]
Parameters:

Asynchronously ejects a drive.

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

Deprecated since version 2.22: Use Gio.Drive.eject_with_operation() instead.

eject_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

True if the drive has been ejected successfully, False otherwise.

Return type:

bool

Finishes ejecting a drive.

Deprecated since version 2.22: Use Gio.Drive.eject_with_operation_finish() instead.

eject_with_operation(flags, mount_operation, cancellable, callback, *user_data)[source]
Parameters:

Ejects a drive. This is an asynchronous operation, and is finished by calling Gio.Drive.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 drive was successfully ejected. False otherwise.

Return type:

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.

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.Drive.get_identifier() to obtain the identifiers themselves.

get_icon()[source]
Returns:

Gio.Icon for the self. Free the returned object with GObject.Object.unref().

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.Drive doesn’t have this kind of identifier.

Return type:

str or None

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

get_name()[source]
Returns:

a string containing self's name. The returned string should be freed 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_start_stop_type()[source]
Returns:

A value from the Gio.DriveStartStopType enumeration.

Return type:

Gio.DriveStartStopType

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

New in version 2.22.

get_symbolic_icon()[source]
Returns:

symbolic Gio.Icon for the self. Free the returned object with GObject.Object.unref().

Return type:

Gio.Icon

Gets the icon for self.

New in version 2.34.

get_volumes()[source]
Returns:

GLib.List containing any Gio.Volume objects on the given self.

Return type:

[Gio.Volume]

Get a list of mountable volumes for self.

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

has_media()[source]
Returns:

True if self has media, False otherwise.

Return type:

bool

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

has_volumes()[source]
Returns:

True if the self contains volumes, False otherwise.

Return type:

bool

Check if self has any mountable volumes.

is_media_check_automatic()[source]
Returns:

True if the self is capable of automatically detecting media changes, False otherwise.

Return type:

bool

Checks if self is capable of automatically detecting media changes.

is_media_removable()[source]
Returns:

True if self supports removable media, False otherwise.

Return type:

bool

Checks if the self supports removable media.

is_removable()[source]
Returns:

True if self and/or its media is considered removable, False otherwise.

Return type:

bool

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

New in version 2.50.

poll_for_media(cancellable, callback, *user_data)[source]
Parameters:

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

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

poll_for_media_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

True if the drive has been poll_for_mediaed successfully, False otherwise.

Return type:

bool

Finishes an operation started with Gio.Drive.poll_for_media() on a drive.

start(flags, mount_operation, cancellable, callback, *user_data)[source]
Parameters:

Asynchronously starts a drive.

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

New in version 2.22.

start_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

True if the drive has been started successfully, False otherwise.

Return type:

bool

Finishes starting a drive.

New in version 2.22.

stop(flags, mount_operation, cancellable, callback, *user_data)[source]
Parameters:

Asynchronously stops a drive.

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

New in version 2.22.

stop_finish(result)[source]
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

True if the drive has been stopped successfully, False otherwise.

Return type:

bool

Finishes stopping a drive.

New in version 2.22.

do_can_eject() virtual
Returns:

True if the drive can be ejected, False otherwise.

Return type:

bool

Checks if a drive can be ejected.

do_can_poll_for_media() virtual
Returns:

True if the drive can be polled for media changes, False otherwise.

Return type:

bool

Checks if a drive can be polled for media changes.

do_can_start() virtual
Returns:

True if the drive can be started, False otherwise.

Return type:

bool

Checks if a drive can be started.

New in version 2.22.

do_can_start_degraded() virtual
Returns:

True if the drive can be started degraded, False otherwise.

Return type:

bool

Checks if a drive can be started degraded.

New in version 2.22.

do_can_stop() virtual
Returns:

True if the drive can be stopped, False otherwise.

Return type:

bool

Checks if a drive can be stopped.

New in version 2.22.

do_changed() virtual

Signal emitted when the drive is changed.

do_disconnected() virtual

The removed signal that is emitted when the Gio.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(flags, cancellable, callback, *user_data) virtual
Parameters:

Asynchronously ejects a drive.

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

Deprecated since version 2.22: Use Gio.Drive.eject_with_operation() instead.

do_eject_button() virtual

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

do_eject_finish(result) virtual
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Returns:

True if the drive has been ejected successfully, False otherwise.

Return type:

bool

Finishes ejecting a drive.

Deprecated since version 2.22: Use Gio.Drive.eject_with_operation_finish() instead.

do_eject_with_operation(flags, mount_operation, cancellable, callback, *user_data) virtual
Parameters:

Ejects a drive. This is an asynchronous operation, and is finished by calling Gio.Drive.eject_with_operation_finish() with the drive 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 drive was successfully ejected. False otherwise.

Return type:

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.

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 drive has. Use Gio.Drive.get_identifier() to obtain the identifiers themselves.

do_get_icon() virtual
Returns:

Gio.Icon for the drive. Free the returned object with GObject.Object.unref().

Return type:

Gio.Icon

Gets the icon for drive.

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.Drive doesn’t have this kind of identifier.

Return type:

str or None

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

do_get_name() virtual
Returns:

a string containing drive's name. The returned string should be freed when no longer needed.

Return type:

str

Gets the name of drive.

do_get_sort_key() virtual
Returns:

Sorting key for drive or None if no such key is available.

Return type:

str or None

Gets the sort key for drive, if any.

New in version 2.32.

do_get_start_stop_type() virtual
Returns:

A value from the Gio.DriveStartStopType enumeration.

Return type:

Gio.DriveStartStopType

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

New in version 2.22.

do_get_symbolic_icon() virtual
Returns:

symbolic Gio.Icon for the drive. Free the returned object with GObject.Object.unref().

Return type:

Gio.Icon

Gets the icon for drive.

New in version 2.34.

do_get_volumes() virtual
Returns:

GLib.List containing any Gio.Volume objects on the given drive.

Return type:

[Gio.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() virtual
Returns:

True if drive has media, False otherwise.

Return type:

bool

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

do_has_volumes() virtual
Returns:

True if the drive contains volumes, False otherwise.

Return type:

bool

Check if drive has any mountable volumes.

do_is_media_check_automatic() virtual
Returns:

True if the drive is capable of automatically detecting media changes, False otherwise.

Return type:

bool

Checks if drive is capable of automatically detecting media changes.

do_is_media_removable() virtual
Returns:

True if drive supports removable media, False otherwise.

Return type:

bool

Checks if the drive supports removable media.

do_is_removable() virtual
Returns:

True if drive and/or its media is considered removable, False otherwise.

Return type:

bool

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

New in version 2.50.

do_poll_for_media(cancellable, callback, *user_data) virtual
Parameters:

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 Gio.Drive.poll_for_media_finish() to obtain the result of the operation.

do_poll_for_media_finish(result) virtual
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Returns:

True if the drive has been poll_for_mediaed successfully, False otherwise.

Return type:

bool

Finishes an operation started with Gio.Drive.poll_for_media() on a drive.

do_start(flags, mount_operation, cancellable, callback, *user_data) virtual
Parameters:

Asynchronously starts a drive.

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

New in version 2.22.

do_start_finish(result) virtual
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Returns:

True if the drive has been started successfully, False otherwise.

Return type:

bool

Finishes starting a drive.

New in version 2.22.

do_stop(flags, mount_operation, cancellable, callback, *user_data) virtual
Parameters:

Asynchronously stops a drive.

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

New in version 2.22.

do_stop_button() virtual

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

New in version 2.22.

do_stop_finish(result) virtual
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Returns:

True if the drive has been stopped successfully, False otherwise.

Return type:

bool

Finishes stopping a drive.

New in version 2.22.

Signal Details

Gio.Drive.signals.changed(drive)
Signal Name:

changed

Flags:

RUN_LAST

Parameters:

drive (Gio.Drive) – The object which received the signal

Emitted when the drive’s state has changed.

Gio.Drive.signals.disconnected(drive)
Signal Name:

disconnected

Flags:

RUN_LAST

Parameters:

drive (Gio.Drive) – The object which received the signal

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

Gio.Drive.signals.eject_button(drive)
Signal Name:

eject-button

Flags:

RUN_LAST

Parameters:

drive (Gio.Drive) – The object which received the signal

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

Gio.Drive.signals.stop_button(drive)
Signal Name:

stop-button

Flags:

RUN_LAST

Parameters:

drive (Gio.Drive) – The object which received the signal

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

New in version 2.22.