Add symbolic icon support to drive, volume, and mount
[platform/upstream/glib.git] / gio / gdrive.c
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 "gthemedicon.h"
28 #include "gasyncresult.h"
29 #include "gioerror.h"
30 #include "glibintl.h"
31
32
33 /**
34  * SECTION:gdrive
35  * @short_description: 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  * #GDrive supports starting and stopping drives with authentication
54  * support for the former. This can be used to support a diverse set
55  * of use cases including connecting/disconnecting iSCSI devices,
56  * powering down external disk enclosures and starting/stopping
57  * multi-disk devices such as RAID devices. Note that the actual
58  * semantics and side-effects of starting/stopping a #GDrive may vary
59  * according to implementation. To choose the correct verbs in e.g. a
60  * file manager, use g_drive_get_start_stop_type().
61  *
62  * For porting from GnomeVFS note that there is no equivalent of
63  * #GDrive in that API.
64  **/
65
66 typedef GDriveIface GDriveInterface;
67 G_DEFINE_INTERFACE(GDrive, g_drive, G_TYPE_OBJECT)
68
69 static void
70 g_drive_default_init (GDriveInterface *iface)
71 {
72   /**
73    * GDrive::changed:
74    * @drive: a #GDrive.
75    *
76    * Emitted when the drive's state has changed.
77    **/
78   g_signal_new (I_("changed"),
79                 G_TYPE_DRIVE,
80                 G_SIGNAL_RUN_LAST,
81                 G_STRUCT_OFFSET (GDriveIface, changed),
82                 NULL, NULL,
83                 g_cclosure_marshal_VOID__VOID,
84                 G_TYPE_NONE, 0);
85
86   /**
87    * GDrive::disconnected:
88    * @drive: a #GDrive.
89    *
90    * This signal is emitted when the #GDrive have been
91    * disconnected. If the recipient is holding references to the
92    * object they should release them so the object can be
93    * finalized.
94    **/
95   g_signal_new (I_("disconnected"),
96                 G_TYPE_DRIVE,
97                 G_SIGNAL_RUN_LAST,
98                 G_STRUCT_OFFSET (GDriveIface, disconnected),
99                 NULL, NULL,
100                 g_cclosure_marshal_VOID__VOID,
101                 G_TYPE_NONE, 0);
102
103   /**
104    * GDrive::eject-button:
105    * @drive: a #GDrive.
106    *
107    * Emitted when the physical eject button (if any) of a drive has
108    * been pressed.
109    **/
110   g_signal_new (I_("eject-button"),
111                 G_TYPE_DRIVE,
112                 G_SIGNAL_RUN_LAST,
113                 G_STRUCT_OFFSET (GDriveIface, eject_button),
114                 NULL, NULL,
115                 g_cclosure_marshal_VOID__VOID,
116                 G_TYPE_NONE, 0);
117
118   /**
119    * GDrive::stop-button:
120    * @drive: a #GDrive.
121    *
122    * Emitted when the physical stop button (if any) of a drive has
123    * been pressed.
124    *
125    * Since: 2.22
126    **/
127   g_signal_new (I_("stop-button"),
128                 G_TYPE_DRIVE,
129                 G_SIGNAL_RUN_LAST,
130                 G_STRUCT_OFFSET (GDriveIface, stop_button),
131                 NULL, NULL,
132                 g_cclosure_marshal_VOID__VOID,
133                 G_TYPE_NONE, 0);
134 }
135
136 /**
137  * g_drive_get_name:
138  * @drive: a #GDrive.
139  * 
140  * Gets the name of @drive.
141  *
142  * Returns: a string containing @drive's name. The returned 
143  *     string should be freed when no longer needed.
144  **/
145 char *
146 g_drive_get_name (GDrive *drive)
147 {
148   GDriveIface *iface;
149
150   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
151
152   iface = G_DRIVE_GET_IFACE (drive);
153
154   return (* iface->get_name) (drive);
155 }
156
157 /**
158  * g_drive_get_icon:
159  * @drive: a #GDrive.
160  * 
161  * Gets the icon for @drive.
162  * 
163  * Returns: (transfer full): #GIcon for the @drive.
164  *    Free the returned object with g_object_unref().
165  **/
166 GIcon *
167 g_drive_get_icon (GDrive *drive)
168 {
169   GDriveIface *iface;
170   
171   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
172
173   iface = G_DRIVE_GET_IFACE (drive);
174
175   return (* iface->get_icon) (drive);
176 }
177
178 /**
179  * g_drive_get_symbolic_icon:
180  * @drive: a #GDrive.
181  * 
182  * Gets the icon for @drive.
183  * 
184  * Returns: (transfer full): symbolic #GIcon for the @drive.
185  *    Free the returned object with g_object_unref().
186  *
187  * Since: 2.34
188  **/
189 GIcon *
190 g_drive_get_symbolic_icon (GDrive *drive)
191 {
192   GDriveIface *iface;
193   GIcon *ret;
194
195   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
196
197   iface = G_DRIVE_GET_IFACE (drive);
198
199   if (iface->get_symbolic_icon != NULL)
200     ret = iface->get_symbolic_icon (drive);
201   else
202     ret = g_themed_icon_new_with_default_fallbacks ("drive-removable-media-symbolic");
203
204   return ret;
205 }
206
207 /**
208  * g_drive_has_volumes:
209  * @drive: a #GDrive.
210  * 
211  * Check if @drive has any mountable volumes.
212  * 
213  * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
214  **/
215 gboolean
216 g_drive_has_volumes (GDrive *drive)
217 {
218   GDriveIface *iface;
219
220   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
221
222   iface = G_DRIVE_GET_IFACE (drive);
223
224   return (* iface->has_volumes) (drive);
225 }
226
227 /**
228  * g_drive_get_volumes:
229  * @drive: a #GDrive.
230  * 
231  * Get a list of mountable volumes for @drive.
232  *
233  * The returned list should be freed with g_list_free(), after
234  * its elements have been unreffed with g_object_unref().
235  * 
236  * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
237  **/
238 GList *
239 g_drive_get_volumes (GDrive *drive)
240 {
241   GDriveIface *iface;
242
243   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
244
245   iface = G_DRIVE_GET_IFACE (drive);
246
247   return (* iface->get_volumes) (drive);
248 }
249
250 /**
251  * g_drive_is_media_check_automatic:
252  * @drive: a #GDrive.
253  * 
254  * Checks if @drive is capabable of automatically detecting media changes.
255  * 
256  * Returns: %TRUE if the @drive is capabable of automatically detecting 
257  *     media changes, %FALSE otherwise.
258  **/
259 gboolean
260 g_drive_is_media_check_automatic (GDrive *drive)
261 {
262   GDriveIface *iface;
263
264   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
265
266   iface = G_DRIVE_GET_IFACE (drive);
267
268   return (* iface->is_media_check_automatic) (drive);
269 }
270
271 /**
272  * g_drive_is_media_removable:
273  * @drive: a #GDrive.
274  * 
275  * Checks if the @drive supports removable media.
276  * 
277  * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
278  **/
279 gboolean
280 g_drive_is_media_removable (GDrive *drive)
281 {
282   GDriveIface *iface;
283
284   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
285
286   iface = G_DRIVE_GET_IFACE (drive);
287
288   return (* iface->is_media_removable) (drive);
289 }
290
291 /**
292  * g_drive_has_media:
293  * @drive: a #GDrive.
294  * 
295  * Checks if the @drive has media. Note that the OS may not be polling
296  * the drive for media changes; see g_drive_is_media_check_automatic()
297  * for more details.
298  * 
299  * Returns: %TRUE if @drive has media, %FALSE otherwise.
300  **/
301 gboolean
302 g_drive_has_media (GDrive *drive)
303 {
304   GDriveIface *iface;
305
306   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
307
308   iface = G_DRIVE_GET_IFACE (drive);
309
310   return (* iface->has_media) (drive);
311 }
312
313 /**
314  * g_drive_can_eject:
315  * @drive: a #GDrive.
316  * 
317  * Checks if a drive can be ejected.
318  * 
319  * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
320  **/
321 gboolean
322 g_drive_can_eject (GDrive *drive)
323 {
324   GDriveIface *iface;
325
326   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
327
328   iface = G_DRIVE_GET_IFACE (drive);
329
330   if (iface->can_eject == NULL)
331     return FALSE;
332
333   return (* iface->can_eject) (drive);
334 }
335
336 /**
337  * g_drive_can_poll_for_media:
338  * @drive: a #GDrive.
339  * 
340  * Checks if a drive can be polled for media changes.
341  * 
342  * Returns: %TRUE if the @drive can be polled for media changes,
343  *     %FALSE otherwise.
344  **/
345 gboolean
346 g_drive_can_poll_for_media (GDrive *drive)
347 {
348   GDriveIface *iface;
349
350   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
351
352   iface = G_DRIVE_GET_IFACE (drive);
353
354   if (iface->poll_for_media == NULL)
355     return FALSE;
356
357   return (* iface->can_poll_for_media) (drive);
358 }
359
360 /**
361  * g_drive_eject:
362  * @drive: a #GDrive.
363  * @flags: flags affecting the unmount if required for eject
364  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
365  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
366  * @user_data: user data to pass to @callback
367  * 
368  * Asynchronously ejects a drive.
369  *
370  * When the operation is finished, @callback will be called.
371  * You can then call g_drive_eject_finish() to obtain the
372  * result of the operation.
373  *
374  * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
375  **/
376 void
377 g_drive_eject (GDrive              *drive,
378                GMountUnmountFlags   flags,
379                GCancellable        *cancellable,
380                GAsyncReadyCallback  callback,
381                gpointer             user_data)
382 {
383   GDriveIface *iface;
384
385   g_return_if_fail (G_IS_DRIVE (drive));
386
387   iface = G_DRIVE_GET_IFACE (drive);
388
389   if (iface->eject == NULL)
390     {
391       g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
392                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
393                                            _("drive doesn't implement eject"));
394       
395       return;
396     }
397   
398   (* iface->eject) (drive, flags, cancellable, callback, user_data);
399 }
400
401 /**
402  * g_drive_eject_finish:
403  * @drive: a #GDrive.
404  * @result: a #GAsyncResult.
405  * @error: a #GError, or %NULL
406  * 
407  * Finishes ejecting a drive.
408  * 
409  * Returns: %TRUE if the drive has been ejected successfully,
410  *     %FALSE otherwise.
411  *
412  * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
413  **/
414 gboolean
415 g_drive_eject_finish (GDrive        *drive,
416                       GAsyncResult  *result,
417                       GError       **error)
418 {
419   GDriveIface *iface;
420
421   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
422   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
423
424   if (g_async_result_legacy_propagate_error (result, error))
425     return FALSE;
426
427   iface = G_DRIVE_GET_IFACE (drive);
428   
429   return (* iface->eject_finish) (drive, result, error);
430 }
431
432 /**
433  * g_drive_eject_with_operation:
434  * @drive: a #GDrive.
435  * @flags: flags affecting the unmount if required for eject
436  * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
437  *     user interaction.
438  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
439  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
440  * @user_data: user data passed to @callback.
441  *
442  * Ejects a drive. This is an asynchronous operation, and is
443  * finished by calling g_drive_eject_with_operation_finish() with the @drive
444  * and #GAsyncResult data returned in the @callback.
445  *
446  * Since: 2.22
447  **/
448 void
449 g_drive_eject_with_operation (GDrive              *drive,
450                               GMountUnmountFlags   flags,
451                               GMountOperation     *mount_operation,
452                               GCancellable        *cancellable,
453                               GAsyncReadyCallback  callback,
454                               gpointer             user_data)
455 {
456   GDriveIface *iface;
457
458   g_return_if_fail (G_IS_DRIVE (drive));
459
460   iface = G_DRIVE_GET_IFACE (drive);
461
462   if (iface->eject == NULL && iface->eject_with_operation == NULL)
463     {
464       g_simple_async_report_error_in_idle (G_OBJECT (drive),
465                                            callback, user_data,
466                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
467                                            /* Translators: This is an error
468                                             * message for drive objects that
469                                             * don't implement any of eject or eject_with_operation. */
470                                            _("drive doesn't implement eject or eject_with_operation"));
471       return;
472     }
473
474   if (iface->eject_with_operation != NULL)
475     (* iface->eject_with_operation) (drive, flags, mount_operation, cancellable, callback, user_data);
476   else
477     (* iface->eject) (drive, flags, cancellable, callback, user_data);
478 }
479
480 /**
481  * g_drive_eject_with_operation_finish:
482  * @drive: a #GDrive.
483  * @result: a #GAsyncResult.
484  * @error: a #GError location to store the error occurring, or %NULL to
485  *     ignore.
486  *
487  * Finishes ejecting a drive. If any errors occurred during the operation,
488  * @error will be set to contain the errors and %FALSE will be returned.
489  *
490  * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
491  *
492  * Since: 2.22
493  **/
494 gboolean
495 g_drive_eject_with_operation_finish (GDrive        *drive,
496                                      GAsyncResult  *result,
497                                      GError       **error)
498 {
499   GDriveIface *iface;
500
501   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
502   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
503
504   if (g_async_result_legacy_propagate_error (result, error))
505     return FALSE;
506
507   iface = G_DRIVE_GET_IFACE (drive);
508   if (iface->eject_with_operation_finish != NULL)
509     return (* iface->eject_with_operation_finish) (drive, result, error);
510   else
511     return (* iface->eject_finish) (drive, result, error);
512 }
513
514 /**
515  * g_drive_poll_for_media:
516  * @drive: a #GDrive.
517  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
518  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
519  * @user_data: user data to pass to @callback
520  * 
521  * Asynchronously polls @drive to see if media has been inserted or removed.
522  * 
523  * When the operation is finished, @callback will be called.
524  * You can then call g_drive_poll_for_media_finish() to obtain the
525  * result of the operation.
526  **/
527 void
528 g_drive_poll_for_media (GDrive              *drive,
529                         GCancellable        *cancellable,
530                         GAsyncReadyCallback  callback,
531                         gpointer             user_data)
532 {
533   GDriveIface *iface;
534
535   g_return_if_fail (G_IS_DRIVE (drive));
536
537   iface = G_DRIVE_GET_IFACE (drive);
538
539   if (iface->poll_for_media == NULL)
540     {
541       g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
542                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
543                                            _("drive doesn't implement polling for media"));
544       
545       return;
546     }
547   
548   (* iface->poll_for_media) (drive, cancellable, callback, user_data);
549 }
550
551 /**
552  * g_drive_poll_for_media_finish:
553  * @drive: a #GDrive.
554  * @result: a #GAsyncResult.
555  * @error: a #GError, or %NULL
556  * 
557  * Finishes an operation started with g_drive_poll_for_media() on a drive.
558  * 
559  * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
560  *     %FALSE otherwise.
561  **/
562 gboolean
563 g_drive_poll_for_media_finish (GDrive        *drive,
564                                GAsyncResult  *result,
565                                GError       **error)
566 {
567   GDriveIface *iface;
568
569   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
570   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
571
572   if (g_async_result_legacy_propagate_error (result, error))
573     return FALSE;
574
575   iface = G_DRIVE_GET_IFACE (drive);
576   
577   return (* iface->poll_for_media_finish) (drive, result, error);
578 }
579
580 /**
581  * g_drive_get_identifier:
582  * @drive: a #GDrive
583  * @kind: the kind of identifier to return
584  *
585  * Gets the identifier of the given kind for @drive.
586  *
587  * Returns: a newly allocated string containing the
588  *     requested identfier, or %NULL if the #GDrive
589  *     doesn't have this kind of identifier.
590  */
591 char *
592 g_drive_get_identifier (GDrive     *drive,
593                         const char *kind)
594 {
595   GDriveIface *iface;
596
597   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
598   g_return_val_if_fail (kind != NULL, NULL);
599
600   iface = G_DRIVE_GET_IFACE (drive);
601
602   if (iface->get_identifier == NULL)
603     return NULL;
604   
605   return (* iface->get_identifier) (drive, kind);
606 }
607
608 /**
609  * g_drive_enumerate_identifiers:
610  * @drive: a #GDrive
611  *
612  * Gets the kinds of identifiers that @drive has. 
613  * Use g_drive_get_identifier() to obtain the identifiers
614  * themselves.
615  *
616  * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
617  *     array of strings containing kinds of identifiers. Use g_strfreev()
618  *     to free.
619  */
620 char **
621 g_drive_enumerate_identifiers (GDrive *drive)
622 {
623   GDriveIface *iface;
624
625   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
626   iface = G_DRIVE_GET_IFACE (drive);
627
628   if (iface->enumerate_identifiers == NULL)
629     return NULL;
630   
631   return (* iface->enumerate_identifiers) (drive);
632 }
633
634 /**
635  * g_drive_get_start_stop_type:
636  * @drive: a #GDrive.
637  *
638  * Gets a hint about how a drive can be started/stopped.
639  *
640  * Returns: A value from the #GDriveStartStopType enumeration.
641  *
642  * Since: 2.22
643  */
644 GDriveStartStopType
645 g_drive_get_start_stop_type (GDrive *drive)
646 {
647   GDriveIface *iface;
648
649   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
650
651   iface = G_DRIVE_GET_IFACE (drive);
652
653   if (iface->get_start_stop_type == NULL)
654     return G_DRIVE_START_STOP_TYPE_UNKNOWN;
655
656   return (* iface->get_start_stop_type) (drive);
657 }
658
659
660 /**
661  * g_drive_can_start:
662  * @drive: a #GDrive.
663  *
664  * Checks if a drive can be started.
665  *
666  * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
667  *
668  * Since: 2.22
669  */
670 gboolean
671 g_drive_can_start (GDrive *drive)
672 {
673   GDriveIface *iface;
674
675   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
676
677   iface = G_DRIVE_GET_IFACE (drive);
678
679   if (iface->can_start == NULL)
680     return FALSE;
681
682   return (* iface->can_start) (drive);
683 }
684
685 /**
686  * g_drive_can_start_degraded:
687  * @drive: a #GDrive.
688  *
689  * Checks if a drive can be started degraded.
690  *
691  * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
692  *
693  * Since: 2.22
694  */
695 gboolean
696 g_drive_can_start_degraded (GDrive *drive)
697 {
698   GDriveIface *iface;
699
700   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
701
702   iface = G_DRIVE_GET_IFACE (drive);
703
704   if (iface->can_start_degraded == NULL)
705     return FALSE;
706
707   return (* iface->can_start_degraded) (drive);
708 }
709
710 /**
711  * g_drive_start:
712  * @drive: a #GDrive.
713  * @flags: flags affecting the start operation.
714  * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
715  *     user interaction.
716  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
717  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
718  * @user_data: user data to pass to @callback
719  *
720  * Asynchronously starts a drive.
721  *
722  * When the operation is finished, @callback will be called.
723  * You can then call g_drive_start_finish() to obtain the
724  * result of the operation.
725  *
726  * Since: 2.22
727  */
728 void
729 g_drive_start (GDrive              *drive,
730                GDriveStartFlags     flags,
731                GMountOperation     *mount_operation,
732                GCancellable        *cancellable,
733                GAsyncReadyCallback  callback,
734                gpointer             user_data)
735 {
736   GDriveIface *iface;
737
738   g_return_if_fail (G_IS_DRIVE (drive));
739
740   iface = G_DRIVE_GET_IFACE (drive);
741
742   if (iface->start == NULL)
743     {
744       g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
745                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
746                                            _("drive doesn't implement start"));
747       return;
748     }
749
750   (* iface->start) (drive, flags, mount_operation, cancellable, callback, user_data);
751 }
752
753 /**
754  * g_drive_start_finish:
755  * @drive: a #GDrive.
756  * @result: a #GAsyncResult.
757  * @error: a #GError, or %NULL
758  *
759  * Finishes starting a drive.
760  *
761  * Returns: %TRUE if the drive has been started successfully,
762  *     %FALSE otherwise.
763  *
764  * Since: 2.22
765  */
766 gboolean
767 g_drive_start_finish (GDrive         *drive,
768                       GAsyncResult   *result,
769                       GError        **error)
770 {
771   GDriveIface *iface;
772
773   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
774   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
775
776   if (g_async_result_legacy_propagate_error (result, error))
777     return FALSE;
778
779   iface = G_DRIVE_GET_IFACE (drive);
780
781   return (* iface->start_finish) (drive, result, error);
782 }
783
784 /**
785  * g_drive_can_stop:
786  * @drive: a #GDrive.
787  *
788  * Checks if a drive can be stopped.
789  *
790  * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
791  *
792  * Since: 2.22
793  */
794 gboolean
795 g_drive_can_stop (GDrive *drive)
796 {
797   GDriveIface *iface;
798
799   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
800
801   iface = G_DRIVE_GET_IFACE (drive);
802
803   if (iface->can_stop == NULL)
804     return FALSE;
805
806   return (* iface->can_stop) (drive);
807 }
808
809 /**
810  * g_drive_stop:
811  * @drive: a #GDrive.
812  * @flags: flags affecting the unmount if required for stopping.
813  * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
814  *     user interaction.
815  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
816  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
817  * @user_data: user data to pass to @callback
818  *
819  * Asynchronously stops a drive.
820  *
821  * When the operation is finished, @callback will be called.
822  * You can then call g_drive_stop_finish() to obtain the
823  * result of the operation.
824  *
825  * Since: 2.22
826  */
827 void
828 g_drive_stop (GDrive               *drive,
829               GMountUnmountFlags    flags,
830               GMountOperation      *mount_operation,
831               GCancellable         *cancellable,
832               GAsyncReadyCallback   callback,
833               gpointer              user_data)
834 {
835   GDriveIface *iface;
836
837   g_return_if_fail (G_IS_DRIVE (drive));
838
839   iface = G_DRIVE_GET_IFACE (drive);
840
841   if (iface->stop == NULL)
842     {
843       g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
844                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
845                                            _("drive doesn't implement stop"));
846       return;
847     }
848
849   (* iface->stop) (drive, flags, mount_operation, cancellable, callback, user_data);
850 }
851
852 /**
853  * g_drive_stop_finish:
854  * @drive: a #GDrive.
855  * @result: a #GAsyncResult.
856  * @error: a #GError, or %NULL
857  *
858  * Finishes stopping a drive.
859  *
860  * Returns: %TRUE if the drive has been stopped successfully,
861  *     %FALSE otherwise.
862  *
863  * Since: 2.22
864  */
865 gboolean
866 g_drive_stop_finish (GDrive        *drive,
867                      GAsyncResult  *result,
868                      GError       **error)
869 {
870   GDriveIface *iface;
871
872   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
873   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
874
875   if (g_async_result_legacy_propagate_error (result, error))
876     return FALSE;
877
878   iface = G_DRIVE_GET_IFACE (drive);
879
880   return (* iface->stop_finish) (drive, result, error);
881 }
882
883 /**
884  * g_drive_get_sort_key:
885  * @drive: A #GDrive.
886  *
887  * Gets the sort key for @drive, if any.
888  *
889  * Returns: Sorting key for @drive or %NULL if no such key is available.
890  *
891  * Since: 2.32
892  */
893 const gchar *
894 g_drive_get_sort_key (GDrive  *drive)
895 {
896   const gchar *ret = NULL;
897   GDriveIface *iface;
898
899   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
900
901   iface = G_DRIVE_GET_IFACE (drive);
902   if (iface->get_sort_key != NULL)
903     ret = iface->get_sort_key (drive);
904
905   return ret;
906 }