GDrive

GDrive — Drive management

Synopsis

#include <gio/gio.h>

                    GDrive;
struct              GDriveIface;
enum                GDriveStartFlags;
enum                GDriveStartStopType;
char *              g_drive_get_name                    (GDrive *drive);
GIcon *             g_drive_get_icon                    (GDrive *drive);
gboolean            g_drive_has_volumes                 (GDrive *drive);
GList *             g_drive_get_volumes                 (GDrive *drive);
gboolean            g_drive_can_eject                   (GDrive *drive);
GDriveStartStopType  g_drive_get_start_stop_type        (GDrive *drive);
gboolean            g_drive_can_start                   (GDrive *drive);
gboolean            g_drive_can_start_degraded          (GDrive *drive);
gboolean            g_drive_can_stop                    (GDrive *drive);
gboolean            g_drive_can_poll_for_media          (GDrive *drive);
void                g_drive_poll_for_media              (GDrive *drive,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            g_drive_poll_for_media_finish       (GDrive *drive,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            g_drive_has_media                   (GDrive *drive);
gboolean            g_drive_is_media_check_automatic    (GDrive *drive);
gboolean            g_drive_is_media_removable          (GDrive *drive);
void                g_drive_eject                       (GDrive *drive,
                                                         GMountUnmountFlags flags,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            g_drive_eject_finish                (GDrive *drive,
                                                         GAsyncResult *result,
                                                         GError **error);
void                g_drive_eject_with_operation        (GDrive *drive,
                                                         GMountUnmountFlags flags,
                                                         GMountOperation *mount_operation,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            g_drive_eject_with_operation_finish (GDrive *drive,
                                                         GAsyncResult *result,
                                                         GError **error);
void                g_drive_start                       (GDrive *drive,
                                                         GDriveStartFlags flags,
                                                         GMountOperation *mount_operation,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            g_drive_start_finish                (GDrive *drive,
                                                         GAsyncResult *result,
                                                         GError **error);
void                g_drive_stop                        (GDrive *drive,
                                                         GMountUnmountFlags flags,
                                                         GMountOperation *mount_operation,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            g_drive_stop_finish                 (GDrive *drive,
                                                         GAsyncResult *result,
                                                         GError **error);
char **             g_drive_enumerate_identifiers       (GDrive *drive);
char *              g_drive_get_identifier              (GDrive *drive,
                                                         const char *kind);

Object Hierarchy

  GInterface
   +----GDrive

Prerequisites

GDrive requires GObject.

Signals

  "changed"                                        : Run Last
  "disconnected"                                   : Run Last
  "eject-button"                                   : Run Last
  "stop-button"                                    : Run Last

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, determing 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.

Details

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);
};

Interface for creating GDrive implementations.

GTypeInterface g_iface;

 The parent interface.

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.

enum GDriveStartFlags

typedef enum {
  G_DRIVE_START_NONE = 0
} GDriveStartFlags;

Flags used when starting a drive.

G_DRIVE_START_NONE

 No flags set.

Since 2.22

enum GDriveStartStopType

typedef enum {
  G_DRIVE_START_STOP_TYPE_UNKNOWN,
  G_DRIVE_START_STOP_TYPE_SHUTDOWN,
  G_DRIVE_START_STOP_TYPE_NETWORK,
  G_DRIVE_START_STOP_TYPE_MULTIDISK,
  G_DRIVE_START_STOP_TYPE_PASSWORD
} GDriveStartStopType;

Enumeration describing how a drive can be started/stopped.

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 “SECURITY UNLOCK DEVICE” command)

Since 2.22

g_drive_get_name ()

char *              g_drive_get_name                    (GDrive *drive);

Gets the name of drive.

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.

drive :

 a GDrive.

Returns :

 GIcon for the drive. Free the returned object with g_object_unref(). [transfer full]

g_drive_has_volumes ()

gboolean            g_drive_has_volumes                 (GDrive *drive);

Check if drive has any mountable volumes.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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);

Warning

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.

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);

Warning

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.

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.

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.

drive :

 a GDrive.

result :

 a GAsyncResult.

error :

 a GError location to store the error occuring, 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.

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.

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.

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.

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

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.

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.

Signal Details

The "changed" signal

void                user_function                      (GDrive  *drive,
                                                        gpointer user_data)      : Run Last

Emitted when the drive's state has changed.

drive :

 a GDrive.

user_data :

 user data set when the signal handler was connected.

The "disconnected" signal

void                user_function                      (GDrive  *drive,
                                                        gpointer user_data)      : Run Last

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.

drive :

 a GDrive.

user_data :

 user data set when the signal handler was connected.

The "eject-button" signal

void                user_function                      (GDrive  *drive,
                                                        gpointer user_data)      : Run Last

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

drive :

 a GDrive.

user_data :

 user data set when the signal handler was connected.

The "stop-button" signal

void                user_function                      (GDrive  *drive,
                                                        gpointer user_data)      : Run Last

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

drive :

 a GDrive.

user_data :

 user data set when the signal handler was connected.

Since 2.22

Generated by GTK-Doc V1.17