Gio.Drive
Description: Reference for Gio.Drive

### 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 from`GObject`.

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

###### Gio.Drive.has_volumes

Check if `drive` has any mountable volumes.

###### Gio.Drive.is_media_check_automatic

Checks if `drive` is capable of automatically detecting media changes.

###### Gio.Drive.is_media_removable

Checks if the `drive` supports removable media.

###### Gio.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

###### Gio.Drive.poll_for_media

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

###### Gio.Drive.poll_for_media_finish

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

###### Gio.Drive.start

Asynchronously starts a drive.

since: 2.22

###### Gio.Drive.start_finish

Finishes starting a drive.

since: 2.22

###### Gio.Drive.stop

Asynchronously stops a drive.

since: 2.22

###### Gio.Drive.stop_button

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

###### Gio.Drive.stop_finish

Finishes stopping a drive.

since: 2.22