1 /* GIO - GLib Input, Output and Streaming Library
2 *
3 * Copyright (C) 2006-2007 Red Hat, Inc.
4 *
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.
9 *
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.
14 *
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.
19 *
20 * Author: Alexander Larsson <alexl@redhat.com>
21 * David Zeuthen <davidz@redhat.com>
22 */
23
24 #include "config.h"
25 #include "gdrive.h"
26 #include "gsimpleasyncresult.h"
27 #include "gasyncresult.h"
28 #include "gioerror.h"
29 #include "glibintl.h"
30
31 #include "gioalias.h"
32
33 /**
34 * SECTION:gdrive
35 * @short_description: Virtual File System drive management
36 * @include: gio/gio.h
37 *
38 * #GDrive - this represent a piece of hardware connected to the machine.
39 * It's generally only created for removable hardware or hardware with
40 * removable media.
41 *
42 * #GDrive is a container class for #GVolume objects that stem from
43 * the same piece of media. As such, #GDrive abstracts a drive with
44 * (or without) removable media and provides operations for querying
45 * whether media is available, determing whether media change is
46 * automatically detected and ejecting the media.
47 *
48 * If the #GDrive reports that media isn't automatically detected, one
49 * can poll for media; typically one should not do this periodically
50 * as a poll for media operation is potententially expensive and may
51 * spin up the drive creating noise.
52 *
53 * For porting from GnomeVFS note that there is no equivalent of
54 * #GDrive in that API.
55 **/
56
57 static void g_drive_base_init (gpointer g_class);
58 static void g_drive_class_init (gpointer g_class,
59 gpointer class_data);
60
61 GType
g_drive_get_type(void)62 g_drive_get_type (void)
63 {
64 static volatile gsize g_define_type_id__volatile = 0;
65
66 if (g_once_init_enter (&g_define_type_id__volatile))
67 {
68 const GTypeInfo drive_info =
69 {
70 sizeof (GDriveIface), /* class_size */
71 g_drive_base_init, /* base_init */
72 NULL, /* base_finalize */
73 g_drive_class_init,
74 NULL, /* class_finalize */
75 NULL, /* class_data */
76 0,
77 0, /* n_preallocs */
78 NULL
79 };
80 GType g_define_type_id =
81 g_type_register_static (G_TYPE_INTERFACE, I_("GDrive"),
82 &drive_info, 0);
83
84 g_type_interface_add_prerequisite (g_define_type_id, G_TYPE_OBJECT);
85
86 g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
87 }
88
89 return g_define_type_id__volatile;
90 }
91
92 static void
g_drive_class_init(gpointer g_class,gpointer class_data)93 g_drive_class_init (gpointer g_class,
94 gpointer class_data)
95 {
96 }
97
98 static void
g_drive_base_init(gpointer g_class)99 g_drive_base_init (gpointer g_class)
100 {
101 static gboolean initialized = FALSE;
102
103 if (! initialized)
104 {
105 /**
106 * GDrive::changed:
107 * @drive: a #GDrive.
108 *
109 * Emitted when the drive's state has changed.
110 **/
111 g_signal_new (I_("changed"),
112 G_TYPE_DRIVE,
113 G_SIGNAL_RUN_LAST,
114 G_STRUCT_OFFSET (GDriveIface, changed),
115 NULL, NULL,
116 g_cclosure_marshal_VOID__VOID,
117 G_TYPE_NONE, 0);
118
119 /**
120 * GDrive::disconnected:
121 * @drive: a #GDrive.
122 *
123 * This signal is emitted when the #GDrive have been
124 * disconnected. If the recipient is holding references to the
125 * object they should release them so the object can be
126 * finalized.
127 **/
128 g_signal_new (I_("disconnected"),
129 G_TYPE_DRIVE,
130 G_SIGNAL_RUN_LAST,
131 G_STRUCT_OFFSET (GDriveIface, disconnected),
132 NULL, NULL,
133 g_cclosure_marshal_VOID__VOID,
134 G_TYPE_NONE, 0);
135
136 /**
137 * GDrive::eject-button:
138 * @drive: a #GDrive.
139 *
140 * Emitted when the physical eject button (if any) of a drive has
141 * been pressed.
142 **/
143 g_signal_new (I_("eject-button"),
144 G_TYPE_DRIVE,
145 G_SIGNAL_RUN_LAST,
146 G_STRUCT_OFFSET (GDriveIface, eject_button),
147 NULL, NULL,
148 g_cclosure_marshal_VOID__VOID,
149 G_TYPE_NONE, 0);
150
151 initialized = TRUE;
152 }
153 }
154
155 /**
156 * g_drive_get_name:
157 * @drive: a #GDrive.
158 *
159 * Gets the name of @drive.
160 *
161 * Returns: a string containing @drive's name. The returned
162 * string should be freed when no longer needed.
163 **/
164 char *
g_drive_get_name(GDrive * drive)165 g_drive_get_name (GDrive *drive)
166 {
167 GDriveIface *iface;
168
169 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
170
171 iface = G_DRIVE_GET_IFACE (drive);
172
173 return (* iface->get_name) (drive);
174 }
175
176 /**
177 * g_drive_get_icon:
178 * @drive: a #GDrive.
179 *
180 * Gets the icon for @drive.
181 *
182 * Returns: #GIcon for the @drive.
183 * Free the returned object with g_object_unref().
184 **/
185 GIcon *
g_drive_get_icon(GDrive * drive)186 g_drive_get_icon (GDrive *drive)
187 {
188 GDriveIface *iface;
189
190 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
191
192 iface = G_DRIVE_GET_IFACE (drive);
193
194 return (* iface->get_icon) (drive);
195 }
196
197 /**
198 * g_drive_has_volumes:
199 * @drive: a #GDrive.
200 *
201 * Check if @drive has any mountable volumes.
202 *
203 * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
204 **/
205 gboolean
g_drive_has_volumes(GDrive * drive)206 g_drive_has_volumes (GDrive *drive)
207 {
208 GDriveIface *iface;
209
210 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
211
212 iface = G_DRIVE_GET_IFACE (drive);
213
214 return (* iface->has_volumes) (drive);
215 }
216
217 /**
218 * g_drive_get_volumes:
219 * @drive: a #GDrive.
220 *
221 * Get a list of mountable volumes for @drive.
222 *
223 * The returned list should be freed with g_list_free(), after
224 * its elements have been unreffed with g_object_unref().
225 *
226 * Returns: #GList containing any #GVolume objects on the given @drive.
227 **/
228 GList *
g_drive_get_volumes(GDrive * drive)229 g_drive_get_volumes (GDrive *drive)
230 {
231 GDriveIface *iface;
232
233 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
234
235 iface = G_DRIVE_GET_IFACE (drive);
236
237 return (* iface->get_volumes) (drive);
238 }
239
240 /**
241 * g_drive_is_media_check_automatic:
242 * @drive: a #GDrive.
243 *
244 * Checks if @drive is capabable of automatically detecting media changes.
245 *
246 * Returns: %TRUE if the @drive is capabable of automatically detecting
247 * media changes, %FALSE otherwise.
248 **/
249 gboolean
g_drive_is_media_check_automatic(GDrive * drive)250 g_drive_is_media_check_automatic (GDrive *drive)
251 {
252 GDriveIface *iface;
253
254 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
255
256 iface = G_DRIVE_GET_IFACE (drive);
257
258 return (* iface->is_media_check_automatic) (drive);
259 }
260
261 /**
262 * g_drive_is_media_removable:
263 * @drive: a #GDrive.
264 *
265 * Checks if the @drive supports removable media.
266 *
267 * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
268 **/
269 gboolean
g_drive_is_media_removable(GDrive * drive)270 g_drive_is_media_removable (GDrive *drive)
271 {
272 GDriveIface *iface;
273
274 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
275
276 iface = G_DRIVE_GET_IFACE (drive);
277
278 return (* iface->is_media_removable) (drive);
279 }
280
281 /**
282 * g_drive_has_media:
283 * @drive: a #GDrive.
284 *
285 * Checks if the @drive has media. Note that the OS may not be polling
286 * the drive for media changes; see g_drive_is_media_check_automatic()
287 * for more details.
288 *
289 * Returns: %TRUE if @drive has media, %FALSE otherwise.
290 **/
291 gboolean
g_drive_has_media(GDrive * drive)292 g_drive_has_media (GDrive *drive)
293 {
294 GDriveIface *iface;
295
296 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
297
298 iface = G_DRIVE_GET_IFACE (drive);
299
300 return (* iface->has_media) (drive);
301 }
302
303 /**
304 * g_drive_can_eject:
305 * @drive: a #GDrive.
306 *
307 * Checks if a drive can be ejected.
308 *
309 * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
310 **/
311 gboolean
g_drive_can_eject(GDrive * drive)312 g_drive_can_eject (GDrive *drive)
313 {
314 GDriveIface *iface;
315
316 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
317
318 iface = G_DRIVE_GET_IFACE (drive);
319
320 if (iface->can_eject == NULL)
321 return FALSE;
322
323 return (* iface->can_eject) (drive);
324 }
325
326 /**
327 * g_drive_can_poll_for_media:
328 * @drive: a #GDrive.
329 *
330 * Checks if a drive can be polled for media changes.
331 *
332 * Returns: %TRUE if the @drive can be polled for media changes,
333 * %FALSE otherwise.
334 **/
335 gboolean
g_drive_can_poll_for_media(GDrive * drive)336 g_drive_can_poll_for_media (GDrive *drive)
337 {
338 GDriveIface *iface;
339
340 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
341
342 iface = G_DRIVE_GET_IFACE (drive);
343
344 if (iface->poll_for_media == NULL)
345 return FALSE;
346
347 return (* iface->can_poll_for_media) (drive);
348 }
349
350 /**
351 * g_drive_eject:
352 * @drive: a #GDrive.
353 * @flags: flags affecting the unmount if required for eject
354 * @cancellable: optional #GCancellable object, %NULL to ignore.
355 * @callback: a #GAsyncReadyCallback, or %NULL.
356 * @user_data: user data to pass to @callback
357 *
358 * Asynchronously ejects a drive.
359 *
360 * When the operation is finished, @callback will be called.
361 * You can then call g_drive_eject_finish() to obtain the
362 * result of the operation.
363 **/
364 void
g_drive_eject(GDrive * drive,GMountUnmountFlags flags,GCancellable * cancellable,GAsyncReadyCallback callback,gpointer user_data)365 g_drive_eject (GDrive *drive,
366 GMountUnmountFlags flags,
367 GCancellable *cancellable,
368 GAsyncReadyCallback callback,
369 gpointer user_data)
370 {
371 GDriveIface *iface;
372
373 g_return_if_fail (G_IS_DRIVE (drive));
374
375 iface = G_DRIVE_GET_IFACE (drive);
376
377 if (iface->eject == NULL)
378 {
379 g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
380 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
381 _("drive doesn't implement eject"));
382
383 return;
384 }
385
386 (* iface->eject) (drive, flags, cancellable, callback, user_data);
387 }
388
389 /**
390 * g_drive_eject_finish:
391 * @drive: a #GDrive.
392 * @result: a #GAsyncResult.
393 * @error: a #GError, or %NULL
394 *
395 * Finishes ejecting a drive.
396 *
397 * Returns: %TRUE if the drive has been ejected successfully,
398 * %FALSE otherwise.
399 **/
400 gboolean
g_drive_eject_finish(GDrive * drive,GAsyncResult * result,GError ** error)401 g_drive_eject_finish (GDrive *drive,
402 GAsyncResult *result,
403 GError **error)
404 {
405 GDriveIface *iface;
406
407 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
408 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
409
410 if (G_IS_SIMPLE_ASYNC_RESULT (result))
411 {
412 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
413 if (g_simple_async_result_propagate_error (simple, error))
414 return FALSE;
415 }
416
417 iface = G_DRIVE_GET_IFACE (drive);
418
419 return (* iface->eject_finish) (drive, result, error);
420 }
421
422 /**
423 * g_drive_poll_for_media:
424 * @drive: a #GDrive.
425 * @cancellable: optional #GCancellable object, %NULL to ignore.
426 * @callback: a #GAsyncReadyCallback, or %NULL.
427 * @user_data: user data to pass to @callback
428 *
429 * Asynchronously polls @drive to see if media has been inserted or removed.
430 *
431 * When the operation is finished, @callback will be called.
432 * You can then call g_drive_poll_for_media_finish() to obtain the
433 * result of the operation.
434 **/
435 void
g_drive_poll_for_media(GDrive * drive,GCancellable * cancellable,GAsyncReadyCallback callback,gpointer user_data)436 g_drive_poll_for_media (GDrive *drive,
437 GCancellable *cancellable,
438 GAsyncReadyCallback callback,
439 gpointer user_data)
440 {
441 GDriveIface *iface;
442
443 g_return_if_fail (G_IS_DRIVE (drive));
444
445 iface = G_DRIVE_GET_IFACE (drive);
446
447 if (iface->poll_for_media == NULL)
448 {
449 g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
450 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
451 _("drive doesn't implement polling for media"));
452
453 return;
454 }
455
456 (* iface->poll_for_media) (drive, cancellable, callback, user_data);
457 }
458
459 /**
460 * g_drive_poll_for_media_finish:
461 * @drive: a #GDrive.
462 * @result: a #GAsyncResult.
463 * @error: a #GError, or %NULL
464 *
465 * Finishes an operation started with g_drive_poll_for_media() on a drive.
466 *
467 * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
468 * %FALSE otherwise.
469 **/
470 gboolean
g_drive_poll_for_media_finish(GDrive * drive,GAsyncResult * result,GError ** error)471 g_drive_poll_for_media_finish (GDrive *drive,
472 GAsyncResult *result,
473 GError **error)
474 {
475 GDriveIface *iface;
476
477 g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
478 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
479
480 if (G_IS_SIMPLE_ASYNC_RESULT (result))
481 {
482 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
483 if (g_simple_async_result_propagate_error (simple, error))
484 return FALSE;
485 }
486
487 iface = G_DRIVE_GET_IFACE (drive);
488
489 return (* iface->poll_for_media_finish) (drive, result, error);
490 }
491
492 /**
493 * g_drive_get_identifier:
494 * @drive: a #GDrive
495 * @kind: the kind of identifier to return
496 *
497 * Gets the identifier of the given kind for @drive.
498 *
499 * Returns: a newly allocated string containing the
500 * requested identfier, or %NULL if the #GDrive
501 * doesn't have this kind of identifier.
502 */
503 char *
g_drive_get_identifier(GDrive * drive,const char * kind)504 g_drive_get_identifier (GDrive *drive,
505 const char *kind)
506 {
507 GDriveIface *iface;
508
509 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
510 g_return_val_if_fail (kind != NULL, NULL);
511
512 iface = G_DRIVE_GET_IFACE (drive);
513
514 if (iface->get_identifier == NULL)
515 return NULL;
516
517 return (* iface->get_identifier) (drive, kind);
518 }
519
520 /**
521 * g_drive_enumerate_identifiers:
522 * @drive: a #GDrive
523 *
524 * Gets the kinds of identifiers that @drive has.
525 * Use g_drive_get_identifer() to obtain the identifiers
526 * themselves.
527 *
528 * Returns: a %NULL-terminated array of strings containing
529 * kinds of identifiers. Use g_strfreev() to free.
530 */
531 char **
g_drive_enumerate_identifiers(GDrive * drive)532 g_drive_enumerate_identifiers (GDrive *drive)
533 {
534 GDriveIface *iface;
535
536 g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
537 iface = G_DRIVE_GET_IFACE (drive);
538
539 if (iface->enumerate_identifiers == NULL)
540 return NULL;
541
542 return (* iface->enumerate_identifiers) (drive);
543 }
544
545
546 #define __G_DRIVE_C__
547 #include "gioaliasdef.c"
548