## GDrive

GDrive — Drive management

## Functions

char * | g_drive_get_name ()
GIcon * | g_drive_get_icon ()
GIcon * | g_drive_get_symbolic_icon ()
gboolean | g_drive_has_volumes ()
GList * | g_drive_get_volumes ()
gboolean | g_drive_can_eject ()
GDriveStartStopType | g_drive_get_start_stop_type ()
gboolean | g_drive_can_start ()
gboolean | g_drive_can_start_degraded ()
gboolean | g_drive_can_stop ()
gboolean | g_drive_can_poll_for_media ()
void | g_drive_poll_for_media ()
gboolean | g_drive_poll_for_media_finish ()
gboolean | g_drive_has_media ()
gboolean | g_drive_is_media_check_automatic ()
gboolean | g_drive_is_media_removable ()
void | g_drive_eject ()
gboolean | g_drive_eject_finish ()
void | g_drive_eject_with_operation ()
gboolean | g_drive_eject_with_operation_finish ()
void | g_drive_start ()
gboolean | g_drive_start_finish ()
void | g_drive_stop ()
gboolean | g_drive_stop_finish ()
char ** | g_drive_enumerate_identifiers ()
char * | g_drive_get_identifier ()
const gchar * | g_drive_get_sort_key ()

## Signals

void | changed | Run Last
void | disconnected | Run Last
void | eject-button | Run Last
void | stop-button | Run Last

## Types and Values

| GDrive
struct | GDriveIface
enum | GDriveStartFlags
enum | GDriveStartStopType

## Object Hierarchy

        GInterface
        ╰── GDrive

## Prerequisites

GDrive requires GObject.

## Includes

    #include <gio/gio.h>

## Description

GDrive - this represent 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 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 potententially 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.

## Functions

### g_drive_get_name ()

    char *
    g_drive_get_name (GDrive *drive);

Gets the name of `drive` .

#### Parameters

drive | a GDrive. |

#### Returns

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

### g_drive_get_icon ()

    GIcon *
    g_drive_get_icon (GDrive *drive);

Gets the icon for `drive` .

#### Parameters

drive | a GDrive. |

#### Returns

GIcon for the `drive` . Free the returned object with `g_object_unref()`.

[transfer full]

### g_drive_get_symbolic_icon ()

    GIcon *
    g_drive_get_symbolic_icon (GDrive *drive);

Gets the icon for `drive` .

#### Parameters

drive | a GDrive. |

#### Returns

symbolic GIcon for the `drive` . Free the returned object with `g_object_unref()`.

[transfer full]

Since: 2.34

### g_drive_has_volumes ()

    gboolean
    g_drive_has_volumes (GDrive *drive);

Check if `drive` has any mountable volumes.

#### Parameters

drive | a GDrive. |

#### Returns

`TRUE` if the `drive` contains volumes, `FALSE` otherwise.

### g_drive_get_volumes ()

    GList *
    g_drive_get_volumes (GDrive *drive);

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 `g_object_unref()`.

#### Parameters

drive | a GDrive. |

#### Returns

GList containing any GVolume objects on the given `drive` .

[element-type GVolume][transfer full]

### g_drive_can_eject ()

    gboolean
    g_drive_can_eject (GDrive *drive);

Checks if a drive can be ejected.

#### Parameters

drive | a GDrive. |

#### Returns

`TRUE` if the `drive` can be ejected, `FALSE` otherwise.

### g_drive_get_start_stop_type ()

    GDriveStartStopType
    g_drive_get_start_stop_type (GDrive *drive);

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

#### Parameters

drive | a GDrive. |

#### Returns

A value from the GDriveStartStopType enumeration.

Since: 2.22

### g_drive_can_start ()

    gboolean
    g_drive_can_start (GDrive *drive);

Checks if a drive can be started.

#### Parameters

drive | a GDrive. |

#### Returns

`TRUE` if the `drive` can be started, `FALSE` otherwise.

Since: 2.22

### g_drive_can_start_degraded ()

    gboolean
    g_drive_can_start_degraded (GDrive *drive);

Checks if a drive can be started degraded.

#### Parameters

drive | a GDrive. |

#### Returns

`TRUE` if the `drive` can be started degraded, `FALSE` otherwise.

Since: 2.22

### g_drive_can_stop ()

    gboolean
    g_drive_can_stop (GDrive *drive);

Checks if a drive can be stopped.

#### Parameters

drive | a GDrive. |

#### Returns

`TRUE` if the `drive` can be stopped, `FALSE` otherwise.

Since: 2.22

### g_drive_can_poll_for_media ()

    gboolean
    g_drive_can_poll_for_media (GDrive *drive);

Checks if a drive can be polled for media changes.

#### Parameters

drive | a GDrive. |

#### Returns

`TRUE` if the `drive` can be polled for media changes, `FALSE` otherwise.

### g_drive_poll_for_media ()

    void
    g_drive_poll_for_media (GDrive *drive,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

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 `g_drive_poll_for_media_finish()` to obtain the result of the operation.

#### Parameters

drive | a GDrive. |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback, or `NULL`. | [allow-none]
user_data | user data to pass to `callback` |

### g_drive_poll_for_media_finish ()

    gboolean
    g_drive_poll_for_media_finish (GDrive *drive,
                                   GAsyncResult *result,
                                   GError **error);

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

#### Parameters

drive | a GDrive. |
result | a GAsyncResult. |
error | a GError, or `NULL` |

#### Returns

`TRUE` if the drive has been poll_for_mediaed successfully, `FALSE` otherwise.

### g_drive_has_media ()

    gboolean
    g_drive_has_media (GDrive *drive);

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.

#### Parameters

drive | a GDrive. |

#### Returns

`TRUE` if `drive` has media, `FALSE` otherwise.

### g_drive_is_media_check_automatic ()

    gboolean
    g_drive_is_media_check_automatic (GDrive *drive);

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

#### Parameters

drive | a GDrive. |

#### Returns

`TRUE` if the `drive` is capabable of automatically detecting media changes, `FALSE` otherwise.

### g_drive_is_media_removable ()

    gboolean
    g_drive_is_media_removable (GDrive *drive);

Checks if the `drive` supports removable media.

#### Parameters

drive | a GDrive. |

#### Returns

`TRUE` if `drive` supports removable media, `FALSE` otherwise.

### g_drive_eject ()

    void
    g_drive_eject (GDrive *drive,
                   GMountUnmountFlags flags,
                   GCancellable *cancellable,
                   GAsyncReadyCallback callback,
                   gpointer user_data);

`g_drive_eject` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `g_drive_eject_with_operation()` instead.

Asynchronously ejects a drive.

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

#### Parameters

drive | a GDrive. |
flags | flags affecting the unmount if required for eject |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback, or `NULL`. | [allow-none]
user_data | user data to pass to `callback` |

### g_drive_eject_finish ()

    gboolean
    g_drive_eject_finish (GDrive *drive,
                          GAsyncResult *result,
                          GError **error);

`g_drive_eject_finish` has been deprecated since version 2.22 and should not be used in newly-written code.

Use `g_drive_eject_with_operation_finish()` instead.

Finishes ejecting a drive.

#### Parameters

drive | a GDrive. |
result | a GAsyncResult. |
error | a GError, or `NULL` |

#### Returns

`TRUE` if the drive has been ejected successfully, `FALSE` otherwise.

### g_drive_eject_with_operation ()

    void
    g_drive_eject_with_operation (GDrive *drive,
                                  GMountUnmountFlags flags,
                                  GMountOperation *mount_operation,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

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

#### Parameters

drive | a GDrive. |
flags | flags affecting the unmount if required for eject |
mount_operation | a GMountOperation or `NULL` to avoid user interaction. | [allow-none]
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback, or `NULL`. | [allow-none]
user_data | user data passed to `callback` . |

Since: 2.22

### g_drive_eject_with_operation_finish ()

    gboolean
    g_drive_eject_with_operation_finish (GDrive *drive,
                                         GAsyncResult *result,
                                         GError **error);

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

drive | a GDrive. |
result | a GAsyncResult. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` if the drive was successfully ejected. `FALSE` otherwise.

Since: 2.22

### g_drive_start ()

    void
    g_drive_start (GDrive *drive,
                   GDriveStartFlags flags,
                   GMountOperation *mount_operation,
                   GCancellable *cancellable,
                   GAsyncReadyCallback callback,
                   gpointer user_data);

Asynchronously starts a drive.

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

#### Parameters

drive | a GDrive. |
flags | flags affecting the start operation. |
mount_operation | a GMountOperation or `NULL` to avoid user interaction. | [allow-none]
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback, or `NULL`. | [allow-none]
user_data | user data to pass to `callback` |

Since: 2.22

### g_drive_start_finish ()

    gboolean
    g_drive_start_finish (GDrive *drive,
                          GAsyncResult *result,
                          GError **error);

Finishes starting a drive.

#### Parameters

drive | a GDrive. |
result | a GAsyncResult. |
error | a GError, or `NULL` |

#### Returns

`TRUE` if the drive has been started successfully, `FALSE` otherwise.

Since: 2.22

### g_drive_stop ()

    void
    g_drive_stop (GDrive *drive,
                  GMountUnmountFlags flags,
                  GMountOperation *mount_operation,
                  GCancellable *cancellable,
                  GAsyncReadyCallback callback,
                  gpointer user_data);

Asynchronously stops a drive.

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

#### Parameters

drive | a GDrive. |
flags | flags affecting the unmount if required for stopping. |
mount_operation | a GMountOperation or `NULL` to avoid user interaction. | [allow-none]
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback, or `NULL`. | [allow-none]
user_data | user data to pass to `callback` |

Since: 2.22

### g_drive_stop_finish ()

    gboolean
    g_drive_stop_finish (GDrive *drive,
                         GAsyncResult *result,
                         GError **error);

Finishes stopping a drive.

#### Parameters

drive | a GDrive. |
result | a GAsyncResult. |
error | a GError, or `NULL` |

#### Returns

`TRUE` if the drive has been stopped successfully, `FALSE` otherwise.

Since: 2.22

### g_drive_enumerate_identifiers ()

    char **
    g_drive_enumerate_identifiers (GDrive *drive);

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

#### Parameters

drive | a GDrive |

#### Returns

a `NULL`-terminated array of strings containing kinds of identifiers. Use `g_strfreev()` to free.

[transfer full][array zero-terminated=1]

### g_drive_get_identifier ()

    char *
    g_drive_get_identifier (GDrive *drive,
                            const char *kind);

Gets the identifier of the given kind for `drive` .

#### Parameters

drive | a GDrive |
kind | the kind of identifier to return |

#### Returns

a newly allocated string containing the requested identfier, or `NULL` if the GDrive doesn't have this kind of identifier.

### g_drive_get_sort_key ()

    const gchar *
    g_drive_get_sort_key (GDrive *drive);

Gets the sort key for `drive` , if any.

#### Parameters

drive | A GDrive. |

#### Returns

Sorting key for `drive` or `NULL` if no such key is available.

Since: 2.32

## Types and Values

### GDrive

    typedef struct _GDrive GDrive;

Opaque drive object.

### struct GDriveIface

    struct GDriveIface {
      GTypeInterface g_iface;

      /* signals */
      void     (* changed)                  (GDrive              *drive);
      void     (* disconnected)             (GDrive              *drive);
      void     (* eject_button)             (GDrive              *drive);

      /* Virtual Table */
      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);
      /* signal, not VFunc */
      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);
    };

Interface for creating GDrive implementations.

#### Members

`changed` () | Signal emitted when the drive is changed. |
`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. |
`eject_button` () | Signal emitted when the physical eject button (if any) of a drive have been pressed. |
`get_name` () | Returns the name for the given GDrive. |
`get_icon` () | Returns a GIcon for the given GDrive. |
`has_volumes` () | Returns `TRUE` if the GDrive has mountable volumes. |
`get_volumes` () | Returns a list GList of GVolume for the GDrive. |
`is_media_removable` () | Returns `TRUE` if the GDrive supports removal and insertion of media. |
`has_media` () | Returns `TRUE` if the GDrive has media inserted. |
`is_media_check_automatic` () | Returns `TRUE` if the GDrive is capabable of automatically detecting media changes. |
`can_eject` () | Returns `TRUE` if the GDrive can eject media. |
`can_poll_for_media` () | Returns `TRUE` if the GDrive is capable of manually polling for media change. |
`eject` () | Ejects a GDrive. |
`eject_finish` () | Finishes an eject operation. |
`poll_for_media` () | Poll for media insertion/removal on a GDrive. |
`poll_for_media_finish` () | Finishes a media poll operation. |
`get_identifier` () | Returns the identifier of the given kind, or `NULL` if the GDrive doesn't have one. |
`enumerate_identifiers` () | Returns an array strings listing the kinds of identifiers which the GDrive has. |
`get_start_stop_type` () | Gets a GDriveStartStopType with details about starting/stopping the drive. Since 2.22. |
`can_start` () | Returns `TRUE` if a GDrive can be started. Since 2.22. |
`can_start_degraded` () | Returns `TRUE` if a GDrive can be started degraded. Since 2.22. |
`start` () | Starts a GDrive. Since 2.22. |
`start_finish` () | Finishes a start operation. Since 2.22. |
`can_stop` () | Returns `TRUE` if a GDrive can be stopped. Since 2.22. |
`stop` () | Stops a GDrive. Since 2.22. |
`stop_finish` () | Finishes a stop operation. Since 2.22. |
`stop_button` () | Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22. |
`eject_with_operation` () | Starts ejecting a GDrive using a GMountOperation. Since 2.22. |
`eject_with_operation_finish` () | Finishes an eject operation using a GMountOperation. Since 2.22. |
`get_sort_key` () | Gets a key used for sorting GDrive instances or `NULL` if no such key exists. Since 2.32. |
`get_symbolic_icon` () | Returns a symbolic GIcon for the given GDrive. Since 2.34. |

### enum GDriveStartFlags

Flags used when starting a drive.

#### Members

G_DRIVE_START_NONE | No flags set. |

Since: 2.22

### enum GDriveStartStopType

Enumeration describing how a drive can be started/stopped.

#### Members

G_DRIVE_START_STOP_TYPE_UNKNOWN | Unknown or drive doesn't support start/stop. |
G_DRIVE_START_STOP_TYPE_SHUTDOWN | The stop method will physically shut down the drive and e.g. power down the port the drive is attached to. |
G_DRIVE_START_STOP_TYPE_NETWORK | The start/stop methods are used for connecting/disconnect to the drive over the network. |
G_DRIVE_START_STOP_TYPE_MULTIDISK | The start/stop methods will assemble/disassemble a virtual drive from several physical drives. |
G_DRIVE_START_STOP_TYPE_PASSWORD | The start/stop methods will unlock/lock the disk (for example using the ATA <quote>SECURITY UNLOCK DEVICE</quote> command) |

Since: 2.22

## Signal Details

### The `“changed”` signal

    void
    user_function (GDrive  *drive,
                   gpointer user_data)

Emitted when the drive's state has changed.

#### Parameters

drive | a GDrive. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“disconnected”` signal

    void
    user_function (GDrive  *drive,
                   gpointer user_data)

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.

#### Parameters

drive | a GDrive. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“eject-button”` signal

    void
    user_function (GDrive  *drive,
                   gpointer user_data)

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

#### Parameters

drive | a GDrive. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“stop-button”` signal

    void
    user_function (GDrive  *drive,
                   gpointer user_data)

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

#### Parameters

drive | a GDrive. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.22