Interface

GioDrive

Description [src]

interface Gio.Drive : GObject.Object

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 GVolume 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 g_drive_get_start_stop_type().

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

Prerequisite

In order to implement Drive, your type must inherit fromGObject.

Instance methods

g_drive_can_eject

Checks if a drive can be ejected.

g_drive_can_poll_for_media

Checks if a drive can be polled for media changes.

g_drive_can_start

Checks if a drive can be started.

since: 2.22

g_drive_can_start_degraded

Checks if a drive can be started degraded.

since: 2.22

g_drive_can_stop

Checks if a drive can be stopped.

since: 2.22

g_drive_eject

Asynchronously ejects a drive.

deprecated: 2.22

g_drive_eject_finish

Finishes ejecting a drive.

deprecated: 2.22

g_drive_eject_with_operation

Ejects a drive. This is an asynchronous operation, and is finished by calling g_drive_eject_with_operation_finish() with the drive and GAsyncResult data returned in the callback.

since: 2.22

g_drive_eject_with_operation_finish

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

since: 2.22

g_drive_enumerate_identifiers

Gets the kinds of identifiers that drive has. Use g_drive_get_identifier() to obtain the identifiers themselves.

g_drive_get_icon

Gets the icon for drive.

g_drive_get_identifier

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

g_drive_get_name

Gets the name of drive.

g_drive_get_sort_key

Gets the sort key for drive, if any.

since: 2.32

g_drive_get_start_stop_type

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

since: 2.22

g_drive_get_symbolic_icon

Gets the icon for drive.

since: 2.34

g_drive_get_volumes

Get a list of mountable volumes for drive.

g_drive_has_media

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

g_drive_has_volumes

Check if drive has any mountable volumes.

g_drive_is_media_check_automatic

Checks if drive is capable of automatically detecting media changes.

g_drive_is_media_removable

Checks if the drive supports removable media.

g_drive_is_removable

Checks if the GDrive and/or its media is considered removable by the user. See g_drive_is_media_removable().

since: 2.50

g_drive_poll_for_media

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

g_drive_poll_for_media_finish

Finishes an operation started with g_drive_poll_for_media() on a drive.

g_drive_start

Asynchronously starts a drive.

since: 2.22

g_drive_start_finish

Finishes starting a drive.

since: 2.22

g_drive_stop

Asynchronously stops a drive.

since: 2.22

g_drive_stop_finish

Finishes stopping a drive.

since: 2.22

Signals

Gio.Drive::changed

Emitted when the drive’s state has changed.

Gio.Drive::disconnected

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

Gio.Drive::eject-button

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

Gio.Drive::stop-button

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

since: 2.22

Interface structure

struct GioDriveIface {
  GTypeInterface g_iface;
  void (* changed) (
    GDrive* drive
  );
  void (* disconnected) (
    GDrive* drive
  );
  void (* eject_button) (
    GDrive* drive
  );
  char* (* get_name) (
    GDrive* drive
  );
  GIcon* (* get_icon) (
    GDrive* drive
  );
  gboolean (* has_volumes) (
    GDrive* drive
  );
  GList* (* get_volumes) (
    GDrive* drive
  );
  gboolean (* is_media_removable) (
    GDrive* drive
  );
  gboolean (* has_media) (
    GDrive* drive
  );
  gboolean (* is_media_check_automatic) (
    GDrive* drive
  );
  gboolean (* can_eject) (
    GDrive* drive
  );
  gboolean (* can_poll_for_media) (
    GDrive* drive
  );
  void (* eject) (
    GDrive* drive,
    GMountUnmountFlags flags,
    GCancellable* cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data
  );
  gboolean (* eject_finish) (
    GDrive* drive,
    GAsyncResult* result,
    GError** error
  );
  void (* poll_for_media) (
    GDrive* drive,
    GCancellable* cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data
  );
  gboolean (* poll_for_media_finish) (
    GDrive* drive,
    GAsyncResult* result,
    GError** error
  );
  char* (* get_identifier) (
    GDrive* drive,
    const char* kind
  );
  char** (* enumerate_identifiers) (
    GDrive* drive
  );
  GDriveStartStopType (* get_start_stop_type) (
    GDrive* drive
  );
  gboolean (* can_start) (
    GDrive* drive
  );
  gboolean (* can_start_degraded) (
    GDrive* drive
  );
  void (* start) (
    GDrive* drive,
    GDriveStartFlags flags,
    GMountOperation* mount_operation,
    GCancellable* cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data
  );
  gboolean (* start_finish) (
    GDrive* drive,
    GAsyncResult* result,
    GError** error
  );
  gboolean (* can_stop) (
    GDrive* drive
  );
  void (* stop) (
    GDrive* drive,
    GMountUnmountFlags flags,
    GMountOperation* mount_operation,
    GCancellable* cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data
  );
  gboolean (* stop_finish) (
    GDrive* drive,
    GAsyncResult* result,
    GError** error
  );
  void (* stop_button) (
    GDrive* drive
  );
  void (* eject_with_operation) (
    GDrive* drive,
    GMountUnmountFlags flags,
    GMountOperation* mount_operation,
    GCancellable* cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data
  );
  gboolean (* eject_with_operation_finish) (
    GDrive* drive,
    GAsyncResult* result,
    GError** error
  );
  const gchar* (* get_sort_key) (
    GDrive* drive
  );
  GIcon* (* get_symbolic_icon) (
    GDrive* drive
  );
  gboolean (* is_removable) (
    GDrive* drive
  );
  
}

Interface for creating GDrive implementations.

Interface members

`g_iface`	`GTypeInterface`
	The parent interface.
`changed`	`void (* changed) ( GDrive* drive )`
	Signal emitted when the drive is changed.
`disconnected`	`void (* disconnected) ( GDrive* drive )`
	The removed signal that is emitted when the `GDrive` have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized.
`eject_button`	`void (* eject_button) ( GDrive* drive )`
	Signal emitted when the physical eject button (if any) of a drive have been pressed.
`get_name`	`char* (* get_name) ( GDrive* drive )`
	Returns the name for the given `GDrive`.
`get_icon`	`GIcon* (* get_icon) ( GDrive* drive )`
	Returns a `GIcon` for the given `GDrive`.
`has_volumes`	`gboolean (* has_volumes) ( GDrive* drive )`
	Returns `TRUE` if the `GDrive` has mountable volumes.
`get_volumes`	`GList* (* get_volumes) ( GDrive* drive )`
	Returns a list `GList` of `GVolume` for the `GDrive`.
`is_media_removable`	`gboolean (* is_media_removable) ( GDrive* drive )`
	Returns `TRUE` if the `GDrive` supports removal and insertion of media.
`has_media`	`gboolean (* has_media) ( GDrive* drive )`
	Returns `TRUE` if the `GDrive` has media inserted.
`is_media_check_automatic`	`gboolean (* is_media_check_automatic) ( GDrive* drive )`
	Returns `TRUE` if the `GDrive` is capable of automatically detecting media changes.
`can_eject`	`gboolean (* can_eject) ( GDrive* drive )`
	Returns `TRUE` if the `GDrive` can eject media.
`can_poll_for_media`	`gboolean (* can_poll_for_media) ( GDrive* drive )`
	Returns `TRUE` if the `GDrive` is capable of manually polling for media change.
`eject`	`void (* eject) ( GDrive* drive, GMountUnmountFlags flags, GCancellable* cancellable, GAsyncReadyCallback callback, gpointer user_data )`
	Ejects a `GDrive`.
`eject_finish`	`gboolean (* eject_finish) ( GDrive* drive, GAsyncResult* result, GError** error )`
	Finishes an eject operation.
`poll_for_media`	`void (* poll_for_media) ( GDrive* drive, GCancellable* cancellable, GAsyncReadyCallback callback, gpointer user_data )`
	Poll for media insertion/removal on a `GDrive`.
`poll_for_media_finish`	`gboolean (* poll_for_media_finish) ( GDrive* drive, GAsyncResult* result, GError** error )`
	Finishes a media poll operation.
`get_identifier`	`char* (* get_identifier) ( GDrive* drive, const char* kind )`
	Returns the identifier of the given kind, or `NULL` if the `GDrive` doesn’t have one.
`enumerate_identifiers`	`char** (* enumerate_identifiers) ( GDrive* drive )`
	Returns an array strings listing the kinds of identifiers which the `GDrive` has.
`get_start_stop_type`	`GDriveStartStopType (* get_start_stop_type) ( GDrive* drive )`
	Gets a `GDriveStartStopType` with details about starting/stopping the drive. Since 2.22.
`can_start`	`gboolean (* can_start) ( GDrive* drive )`
	Returns `TRUE` if a `GDrive` can be started. Since 2.22.
`can_start_degraded`	`gboolean (* can_start_degraded) ( GDrive* drive )`
	Returns `TRUE` if a `GDrive` can be started degraded. Since 2.22.
`start`	`void (* start) ( GDrive* drive, GDriveStartFlags flags, GMountOperation* mount_operation, GCancellable* cancellable, GAsyncReadyCallback callback, gpointer user_data )`
	Starts a `GDrive`. Since 2.22.
`start_finish`	`gboolean (* start_finish) ( GDrive* drive, GAsyncResult* result, GError** error )`
	Finishes a start operation. Since 2.22.
`can_stop`	`gboolean (* can_stop) ( GDrive* drive )`
	Returns `TRUE` if a `GDrive` can be stopped. Since 2.22.
`stop`	`void (* stop) ( GDrive* drive, GMountUnmountFlags flags, GMountOperation* mount_operation, GCancellable* cancellable, GAsyncReadyCallback callback, gpointer user_data )`
	Stops a `GDrive`. Since 2.22.
`stop_finish`	`gboolean (* stop_finish) ( GDrive* drive, GAsyncResult* result, GError** error )`
	Finishes a stop operation. Since 2.22.
`stop_button`	`void (* stop_button) ( GDrive* drive )`
	Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22.
`eject_with_operation`	`void (* eject_with_operation) ( GDrive* drive, GMountUnmountFlags flags, GMountOperation* mount_operation, GCancellable* cancellable, GAsyncReadyCallback callback, gpointer user_data )`
	Starts ejecting a `GDrive` using a `GMountOperation`. Since 2.22.
`eject_with_operation_finish`	`gboolean (* eject_with_operation_finish) ( GDrive* drive, GAsyncResult* result, GError** error )`
	Finishes an eject operation using a `GMountOperation`. Since 2.22.
`get_sort_key`	`const gchar* (* get_sort_key) ( GDrive* drive )`
	Gets a key used for sorting `GDrive` instances or `NULL` if no such key exists. Since 2.32.
`get_symbolic_icon`	`GIcon* (* get_symbolic_icon) ( GDrive* drive )`
	Returns a symbolic `GIcon` for the given `GDrive`. Since 2.34.
`is_removable`	`gboolean (* is_removable) ( GDrive* drive )`
	Returns `TRUE` if the `GDrive` and/or its media is considered removable by the user. Since 2.50.

Virtual methods

Gio.Drive.can_eject

Checks if a drive can be ejected.

Gio.Drive.can_poll_for_media

Checks if a drive can be polled for media changes.

Gio.Drive.can_start

Checks if a drive can be started.

since: 2.22

Gio.Drive.can_start_degraded

Checks if a drive can be started degraded.

since: 2.22

Gio.Drive.can_stop

Checks if a drive can be stopped.

since: 2.22

Gio.Drive.changed

Signal emitted when the drive is changed.

Gio.Drive.disconnected

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

Gio.Drive.eject

Asynchronously ejects a drive.

deprecated: 2.22

Gio.Drive.eject_button

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

Gio.Drive.eject_finish

Finishes ejecting a drive.

deprecated: 2.22

Gio.Drive.eject_with_operation

Ejects a drive. This is an asynchronous operation, and is finished by calling g_drive_eject_with_operation_finish() with the drive and GAsyncResult data returned in the callback.

since: 2.22

Gio.Drive.eject_with_operation_finish

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

since: 2.22

Gio.Drive.enumerate_identifiers

Gets the kinds of identifiers that drive has. Use g_drive_get_identifier() to obtain the identifiers themselves.

Gio.Drive.get_icon

Gets the icon for drive.

Gio.Drive.get_identifier

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

Gio.Drive.get_name

Gets the name of drive.

Gio.Drive.get_sort_key

Gets the sort key for drive, if any.

since: 2.32

Gio.Drive.get_start_stop_type

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

since: 2.22

Gio.Drive.get_symbolic_icon

Gets the icon for drive.

since: 2.34

Gio.Drive.get_volumes

Get a list of mountable volumes for drive.

Gio.Drive.has_media

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