1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Alexander Larsson <alexl@redhat.com>
21 * David Zeuthen <davidz@redhat.com>
26 #include "gsimpleasyncresult.h"
33 * @short_description: Virtual File System drive management
36 * #GDrive - this represent a piece of hardware connected to the machine.
37 * Its generally only created for removable hardware or hardware with
40 * #GDrive is a container class for #GVolume objects that stem from
41 * the same piece of media. As such, #GDrive abstracts a drive with
42 * (or without) removable media and provides operations for querying
43 * whether media is available, determing whether media change is
44 * automatically detected and ejecting the media.
46 * If the #GDrive reports that media isn't automatically detected, one
47 * can poll for media; typically one should not do this periodically
48 * as a poll for media operation is potententially expensive and may
49 * spin up the drive creating noise.
51 * For porting from GnomeVFS note that there is no equivalent of
52 * #GDrive in that API.
55 static void g_drive_base_init (gpointer g_class);
56 static void g_drive_class_init (gpointer g_class,
60 g_drive_get_type (void)
62 static GType drive_type = 0;
66 static const GTypeInfo drive_info =
68 sizeof (GDriveIface), /* class_size */
69 g_drive_base_init, /* base_init */
70 NULL, /* base_finalize */
72 NULL, /* class_finalize */
73 NULL, /* class_data */
80 g_type_register_static (G_TYPE_INTERFACE, I_("GDrive"),
83 g_type_interface_add_prerequisite (drive_type, G_TYPE_OBJECT);
90 g_drive_class_init (gpointer g_class,
96 g_drive_base_init (gpointer g_class)
98 static gboolean initialized = FALSE;
106 * Emitted when the drive's state has changed.
108 g_signal_new (I_("changed"),
111 G_STRUCT_OFFSET (GDriveIface, changed),
113 g_cclosure_marshal_VOID__VOID,
117 * GDrive::disconnected:
120 * This signal is emitted when the #GDrive have been
121 * disconnected. If the recipient is holding references to the
122 * object they should release them so the object can be
125 g_signal_new (I_("disconnected"),
128 G_STRUCT_OFFSET (GDriveIface, disconnected),
130 g_cclosure_marshal_VOID__VOID,
134 * GDrive::eject-button:
137 * Emitted when the physical eject button (if any) of a drive have been pressed.
140 g_signal_new (I_("eject-button"),
143 G_STRUCT_OFFSET (GDriveIface, eject_button),
145 g_cclosure_marshal_VOID__VOID,
156 * Gets the name of @drive.
158 * Returns: a string containing @drive's name. The returned
159 * string should be freed when no longer needed.
162 g_drive_get_name (GDrive *drive)
166 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
168 iface = G_DRIVE_GET_IFACE (drive);
170 return (* iface->get_name) (drive);
177 * Gets the icon for @drive.
179 * Returns: #GIcon for the @drive.
182 g_drive_get_icon (GDrive *drive)
186 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
188 iface = G_DRIVE_GET_IFACE (drive);
190 return (* iface->get_icon) (drive);
194 * g_drive_has_volumes:
197 * Check if @drive has any mountable volumes.
199 * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
202 g_drive_has_volumes (GDrive *drive)
206 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
208 iface = G_DRIVE_GET_IFACE (drive);
210 return (* iface->has_volumes) (drive);
214 * g_drive_get_volumes:
217 * Get a list of mountable volumes for @drive.
219 * The returned list should be freed with g_list_free(), after
220 * its elements have been unreffed with g_object_unref().
222 * Returns: #GList containing any #GVolume<!---->s on the given @drive.
225 g_drive_get_volumes (GDrive *drive)
229 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
231 iface = G_DRIVE_GET_IFACE (drive);
233 return (* iface->get_volumes) (drive);
237 * g_drive_is_media_check_automatic:
240 * Checks if @drive is capabable of automatically detecting media changes.
242 * Returns: %TRUE if the @drive is capabable of automatically detecting media changes, %FALSE otherwise.
245 g_drive_is_media_check_automatic (GDrive *drive)
249 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
251 iface = G_DRIVE_GET_IFACE (drive);
253 return (* iface->is_media_check_automatic) (drive);
257 * g_drive_is_media_removable:
260 * Checks if the @drive supports removable media.
262 * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
265 g_drive_is_media_removable (GDrive *drive)
269 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
271 iface = G_DRIVE_GET_IFACE (drive);
273 return (* iface->is_media_removable) (drive);
280 * Checks if the @drive has media. Note that the OS may not be polling
281 * the drive for media changes; see g_drive_is_media_check_automatic()
284 * Returns: %TRUE if @drive has media, %FALSE otherwise.
287 g_drive_has_media (GDrive *drive)
291 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
293 iface = G_DRIVE_GET_IFACE (drive);
295 return (* iface->has_media) (drive);
300 * @drive: pointer to a #GDrive.
302 * Checks if a drive can be ejected.
304 * Returns: %TRUE if the @drive can be ejected. %FALSE otherwise.
307 g_drive_can_eject (GDrive *drive)
311 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
313 iface = G_DRIVE_GET_IFACE (drive);
315 if (iface->can_eject == NULL)
318 return (* iface->can_eject) (drive);
322 * g_drive_can_poll_for_media:
325 * Checks if a drive can be polled for media changes.
327 * Returns: %TRUE if the @drive can be polled for media changes. %FALSE otherwise.
330 g_drive_can_poll_for_media (GDrive *drive)
334 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
336 iface = G_DRIVE_GET_IFACE (drive);
338 if (iface->poll_for_media == NULL)
341 return (* iface->can_poll_for_media) (drive);
347 * @flags: flags affecting the unmount if required for eject
348 * @cancellable: optional #GCancellable object, %NULL to ignore.
349 * @callback: a #GAsyncReadyCallback, or %NULL.
350 * @user_data: a #gpointer.
356 g_drive_eject (GDrive *drive,
357 GMountUnmountFlags flags,
358 GCancellable *cancellable,
359 GAsyncReadyCallback callback,
364 g_return_if_fail (G_IS_DRIVE (drive));
366 iface = G_DRIVE_GET_IFACE (drive);
368 if (iface->eject == NULL)
370 g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
371 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
372 _("drive doesn't implement eject"));
377 (* iface->eject) (drive, flags, cancellable, callback, user_data);
381 * g_drive_eject_finish
383 * @result: a #GAsyncResult.
386 * Finishes ejecting a drive.
388 * Returns: %TRUE if the drive has been ejected successfully,
392 g_drive_eject_finish (GDrive *drive,
393 GAsyncResult *result,
398 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
399 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
401 if (G_IS_SIMPLE_ASYNC_RESULT (result))
403 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
404 if (g_simple_async_result_propagate_error (simple, error))
408 iface = G_DRIVE_GET_IFACE (drive);
410 return (* iface->eject_finish) (drive, result, error);
414 * g_drive_poll_for_media:
416 * @cancellable: optional #GCancellable object, %NULL to ignore.
417 * @callback: a #GAsyncReadyCallback, or %NULL.
418 * @user_data: a #gpointer.
420 * Polls @drive to see if media has been inserted or removed.
424 g_drive_poll_for_media (GDrive *drive,
425 GCancellable *cancellable,
426 GAsyncReadyCallback callback,
431 g_return_if_fail (G_IS_DRIVE (drive));
433 iface = G_DRIVE_GET_IFACE (drive);
435 if (iface->poll_for_media == NULL)
437 g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
438 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
439 _("drive doesn't implement polling for media"));
444 (* iface->poll_for_media) (drive, cancellable, callback, user_data);
448 * g_drive_poll_for_media_finish
450 * @result: a #GAsyncResult.
453 * Finishes poll_for_mediaing a drive.
455 * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
459 g_drive_poll_for_media_finish (GDrive *drive,
460 GAsyncResult *result,
465 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
466 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
468 if (G_IS_SIMPLE_ASYNC_RESULT (result))
470 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
471 if (g_simple_async_result_propagate_error (simple, error))
475 iface = G_DRIVE_GET_IFACE (drive);
477 return (* iface->poll_for_media_finish) (drive, result, error);
481 * g_drive_get_identifier:
483 * @kind: the kind of identifier to return
485 * Gets the identifier of the given kind for @drive.
487 * Returns: a newly allocated string containing the
488 * requested identfier, or %NULL if the #GDrive
489 * doesn't have this kind of identifier
492 g_drive_get_identifier (GDrive *drive,
497 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
498 g_return_val_if_fail (kind != NULL, NULL);
500 iface = G_DRIVE_GET_IFACE (drive);
502 if (iface->get_identifier == NULL)
505 return (* iface->get_identifier) (drive, kind);
509 * g_drive_enumerate_identifiers:
512 * Gets the kinds of identifiers that @drive has.
513 * Use g_drive_get_identifer() to obtain the identifiers
516 * Returns: a %NULL-terminated array of strings containing
517 * kinds of identifiers. Use g_strfreev() to free.
520 g_drive_enumerate_identifiers (GDrive *drive)
524 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
525 iface = G_DRIVE_GET_IFACE (drive);
527 if (iface->enumerate_identifiers == NULL)
530 return (* iface->enumerate_identifiers) (drive);
534 #define __G_DRIVE_C__
535 #include "gioaliasdef.c"