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
.
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
.
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
.
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.
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().
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.
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.
Since: 2.22
g_drive_can_start ()
gboolean
g_drive_can_start (GDrive *drive);
Checks if a drive can be started.
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.
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.
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.
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.
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.
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.
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.
Returns
TRUE if the drive
is capabable of automatically detecting
media changes, FALSE otherwise.
g_drive_is_removable ()
gboolean
g_drive_is_removable (GDrive *drive);
Checks if the GDrive and/or its media is considered removable by the user.
See g_drive_is_media_removable().
Returns
TRUE if drive
and/or its media is considered removable, FALSE otherwise.
Since: 2.50
g_drive_is_media_removable ()
gboolean
g_drive_is_media_removable (GDrive *drive);
Checks if the drive
supports removable media.
Returns
TRUE if drive
supports removable media, FALSE otherwise.
g_drive_eject_finish ()
gboolean
g_drive_eject_finish (GDrive *drive,
GAsyncResult *result,
GError **error);
Finishes ejecting a drive.
Returns
TRUE if the drive has been ejected successfully,
FALSE otherwise.
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.
Returns
TRUE if the drive was successfully ejected. FALSE otherwise.
Since: 2.22
g_drive_start_finish ()
gboolean
g_drive_start_finish (GDrive *drive,
GAsyncResult *result,
GError **error);
Finishes starting a drive.
Returns
TRUE if the drive has been started successfully,
FALSE otherwise.
Since: 2.22
g_drive_stop_finish ()
gboolean
g_drive_stop_finish (GDrive *drive,
GAsyncResult *result,
GError **error);
Finishes stopping a drive.
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.
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
. The only
identifier currently available is
G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.
Returns
a newly allocated string containing the
requested identifier, or NULL if the GDrive
doesn't have this kind of identifier.
[nullable][transfer full]
g_drive_get_sort_key ()
const gchar *
g_drive_get_sort_key (GDrive *drive);
Gets the sort key for drive
, if any.
Returns
Sorting key for drive
or NULL if no such key is available.
[nullable]
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);
gboolean (* is_removable) (GDrive *drive);
};
Interface for creating GDrive implementations.
enum GDriveStartFlags
Flags used when starting a drive.
Since: 2.22
enum GDriveStartStopType
Enumeration describing how a drive can be started/stopped.
Since: 2.22
G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE
#define G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE "unix-device"
The string used to obtain a Unix device path with g_drive_get_identifier().
Since: 2.58