Spelling fixes
[platform/upstream/glib.git] / gio / gmount.c
1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2
3 /* GIO - GLib Input, Output and Streaming Library
4  * 
5  * Copyright (C) 2006-2008 Red Hat, Inc.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General
18  * Public License along with this library; if not, write to the
19  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
20  * Boston, MA 02111-1307, USA.
21  *
22  * Author: Alexander Larsson <alexl@redhat.com>
23  *         David Zeuthen <davidz@redhat.com>
24  */
25
26 #include "config.h"
27
28 #include <string.h>
29
30 #include "gmount.h"
31 #include "gmountprivate.h"
32 #include "gasyncresult.h"
33 #include "gsimpleasyncresult.h"
34 #include "gioerror.h"
35 #include "glibintl.h"
36
37
38 /**
39  * SECTION:gmount
40  * @short_description: Mount management
41  * @include: gio/gio.h
42  * @see_also: GVolume, GUnixMount
43  *
44  * The #GMount interface represents user-visible mounts. Note, when 
45  * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
46  *
47  * #GMount is a "mounted" filesystem that you can access. Mounted is in
48  * quotes because it's not the same as a unix mount, it might be a gvfs
49  * mount, but you can still access the files on it if you use GIO. Might or
50  * might not be related to a volume object.
51  * 
52  * Unmounting a #GMount instance is an asynchronous operation. For
53  * more information about asynchronous operations, see #GAsyncReady
54  * and #GSimpleAsyncReady. To unmount a #GMount instance, first call
55  * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
56  * #GAsyncReadyCallback.  The callback will be fired when the
57  * operation has resolved (either with success or failure), and a
58  * #GAsyncReady structure will be passed to the callback.  That
59  * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
60  * and the #GAsyncReady data to see if the operation was completed
61  * successfully.  If an @error is present when g_mount_unmount_with_operation_finish() 
62  * is called, then it will be filled with any error information.
63  **/
64
65 typedef GMountIface GMountInterface;
66 G_DEFINE_INTERFACE (GMount, g_mount, G_TYPE_OBJECT)
67
68 static void
69 g_mount_default_init (GMountInterface *iface)
70 {
71   /**
72    * GMount::changed:
73    * @mount: the object on which the signal is emitted
74    *
75    * Emitted when the mount has been changed.
76    **/
77   g_signal_new (I_("changed"),
78                 G_TYPE_MOUNT,
79                 G_SIGNAL_RUN_LAST,
80                 G_STRUCT_OFFSET (GMountIface, changed),
81                 NULL, NULL,
82                 g_cclosure_marshal_VOID__VOID,
83                 G_TYPE_NONE, 0);
84
85   /**
86    * GMount::unmounted:
87    * @mount: the object on which the signal is emitted
88    *
89    * This signal is emitted when the #GMount have been
90    * unmounted. If the recipient is holding references to the
91    * object they should release them so the object can be
92    * finalized.
93    **/
94   g_signal_new (I_("unmounted"),
95                 G_TYPE_MOUNT,
96                 G_SIGNAL_RUN_LAST,
97                 G_STRUCT_OFFSET (GMountIface, unmounted),
98                 NULL, NULL,
99                 g_cclosure_marshal_VOID__VOID,
100                 G_TYPE_NONE, 0);
101   /**
102    * GMount::pre-unmount:
103    * @mount: the object on which the signal is emitted
104    *
105    * This signal is emitted when the #GMount is about to be
106    * unmounted.
107    *
108    * Since: 2.22
109    **/
110   g_signal_new (I_("pre-unmount"),
111                 G_TYPE_MOUNT,
112                 G_SIGNAL_RUN_LAST,
113                 G_STRUCT_OFFSET (GMountIface, pre_unmount),
114                 NULL, NULL,
115                 g_cclosure_marshal_VOID__VOID,
116                 G_TYPE_NONE, 0);
117 }
118
119 /**
120  * g_mount_get_root:
121  * @mount: a #GMount.
122  * 
123  * Gets the root directory on @mount.
124  * 
125  * Returns: (transfer full): a #GFile. 
126  *      The returned object should be unreffed with 
127  *      g_object_unref() when no longer needed.
128  **/
129 GFile *
130 g_mount_get_root (GMount *mount)
131 {
132   GMountIface *iface;
133
134   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
135
136   iface = G_MOUNT_GET_IFACE (mount);
137
138   return (* iface->get_root) (mount);
139 }
140
141 /**
142  * g_mount_get_default_location:
143  * @mount: a #GMount.
144  *
145  * Gets the default location of @mount. The default location of the given
146  * @mount is a path that reflects the main entry point for the user (e.g.
147  * the home directory, or the root of the volume).
148  *
149  * Returns: (transfer full): a #GFile.
150  *      The returned object should be unreffed with
151  *      g_object_unref() when no longer needed.
152  **/
153 GFile *
154 g_mount_get_default_location (GMount *mount)
155 {
156   GMountIface *iface;
157   GFile       *file;
158
159   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
160
161   iface = G_MOUNT_GET_IFACE (mount);
162   
163   /* Fallback to get_root when default_location () is not available */
164   if (iface->get_default_location)
165     file = (* iface->get_default_location) (mount);
166   else
167     file = (* iface->get_root) (mount);
168
169   return file;
170 }
171
172 /**
173  * g_mount_get_name:
174  * @mount: a #GMount.
175  * 
176  * Gets the name of @mount.
177  * 
178  * Returns: the name for the given @mount. 
179  *     The returned string should be freed with g_free()
180  *     when no longer needed.
181  **/
182 char *
183 g_mount_get_name (GMount *mount)
184 {
185   GMountIface *iface;
186
187   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
188
189   iface = G_MOUNT_GET_IFACE (mount);
190
191   return (* iface->get_name) (mount);
192 }
193
194 /**
195  * g_mount_get_icon:
196  * @mount: a #GMount.
197  * 
198  * Gets the icon for @mount.
199  * 
200  * Returns: (transfer full): a #GIcon.
201  *      The returned object should be unreffed with 
202  *      g_object_unref() when no longer needed.
203  **/
204 GIcon *
205 g_mount_get_icon (GMount *mount)
206 {
207   GMountIface *iface;
208
209   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
210
211   iface = G_MOUNT_GET_IFACE (mount);
212
213   return (* iface->get_icon) (mount);
214 }
215
216 /**
217  * g_mount_get_uuid:
218  * @mount: a #GMount.
219  * 
220  * Gets the UUID for the @mount. The reference is typically based on
221  * the file system UUID for the mount in question and should be
222  * considered an opaque string. Returns %NULL if there is no UUID
223  * available.
224  * 
225  * Returns: the UUID for @mount or %NULL if no UUID can be computed.
226  *     The returned string should be freed with g_free()
227  *     when no longer needed.
228  **/
229 char *
230 g_mount_get_uuid (GMount *mount)
231 {
232   GMountIface *iface;
233
234   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
235
236   iface = G_MOUNT_GET_IFACE (mount);
237
238   return (* iface->get_uuid) (mount);
239 }
240
241 /**
242  * g_mount_get_volume:
243  * @mount: a #GMount.
244  * 
245  * Gets the volume for the @mount.
246  * 
247  * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume.
248  *      The returned object should be unreffed with 
249  *      g_object_unref() when no longer needed.
250  **/
251 GVolume *
252 g_mount_get_volume (GMount *mount)
253 {
254   GMountIface *iface;
255
256   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
257
258   iface = G_MOUNT_GET_IFACE (mount);
259
260   return (* iface->get_volume) (mount);
261 }
262
263 /**
264  * g_mount_get_drive:
265  * @mount: a #GMount.
266  * 
267  * Gets the drive for the @mount.
268  *
269  * This is a convenience method for getting the #GVolume and then
270  * using that object to get the #GDrive.
271  * 
272  * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive.
273  *      The returned object should be unreffed with 
274  *      g_object_unref() when no longer needed.
275  **/
276 GDrive *
277 g_mount_get_drive (GMount *mount)
278 {
279   GMountIface *iface;
280
281   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
282
283   iface = G_MOUNT_GET_IFACE (mount);
284
285   return (* iface->get_drive) (mount);
286 }
287
288 /**
289  * g_mount_can_unmount: 
290  * @mount: a #GMount.
291  * 
292  * Checks if @mount can be mounted.
293  * 
294  * Returns: %TRUE if the @mount can be unmounted.
295  **/
296 gboolean
297 g_mount_can_unmount (GMount *mount)
298 {
299   GMountIface *iface;
300
301   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
302
303   iface = G_MOUNT_GET_IFACE (mount);
304
305   return (* iface->can_unmount) (mount);
306 }
307
308 /**
309  * g_mount_can_eject: 
310  * @mount: a #GMount.
311  * 
312  * Checks if @mount can be eject.
313  * 
314  * Returns: %TRUE if the @mount can be ejected.
315  **/
316 gboolean
317 g_mount_can_eject (GMount *mount)
318 {
319   GMountIface *iface;
320
321   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
322
323   iface = G_MOUNT_GET_IFACE (mount);
324
325   return (* iface->can_eject) (mount);
326 }
327
328 /**
329  * g_mount_unmount:
330  * @mount: a #GMount.
331  * @flags: flags affecting the operation
332  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
333  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
334  * @user_data: user data passed to @callback.
335  * 
336  * Unmounts a mount. This is an asynchronous operation, and is 
337  * finished by calling g_mount_unmount_finish() with the @mount 
338  * and #GAsyncResult data returned in the @callback.
339  *
340  * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
341  **/
342 void
343 g_mount_unmount (GMount              *mount,
344                  GMountUnmountFlags   flags,
345                  GCancellable        *cancellable,
346                  GAsyncReadyCallback  callback,
347                  gpointer             user_data)
348 {
349   GMountIface *iface;
350
351   g_return_if_fail (G_IS_MOUNT (mount));
352   
353   iface = G_MOUNT_GET_IFACE (mount);
354
355   if (iface->unmount == NULL)
356     {
357       g_simple_async_report_error_in_idle (G_OBJECT (mount),
358                                            callback, user_data,
359                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
360                                            /* Translators: This is an error
361                                             * message for mount objects that
362                                             * don't implement unmount. */
363                                            _("mount doesn't implement \"unmount\""));
364
365       return;
366     }
367   
368   (* iface->unmount) (mount, flags, cancellable, callback, user_data);
369 }
370
371 /**
372  * g_mount_unmount_finish:
373  * @mount: a #GMount.
374  * @result: a #GAsyncResult.
375  * @error: a #GError location to store the error occurring, or %NULL to 
376  *     ignore.
377  * 
378  * Finishes unmounting a mount. If any errors occurred during the operation, 
379  * @error will be set to contain the errors and %FALSE will be returned.
380  * 
381  * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
382  *
383  * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
384  **/
385 gboolean
386 g_mount_unmount_finish (GMount        *mount,
387                         GAsyncResult  *result,
388                         GError       **error)
389 {
390   GMountIface *iface;
391
392   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
393   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
394
395   if (G_IS_SIMPLE_ASYNC_RESULT (result))
396     {
397       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
398       if (g_simple_async_result_propagate_error (simple, error))
399         return FALSE;
400     }
401   
402   iface = G_MOUNT_GET_IFACE (mount);
403   return (* iface->unmount_finish) (mount, result, error);
404 }
405
406
407 /**
408  * g_mount_eject:
409  * @mount: a #GMount.
410  * @flags: flags affecting the unmount if required for eject
411  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
412  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
413  * @user_data: user data passed to @callback.
414  * 
415  * Ejects a mount. This is an asynchronous operation, and is 
416  * finished by calling g_mount_eject_finish() with the @mount 
417  * and #GAsyncResult data returned in the @callback.
418  *
419  * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
420  **/
421 void
422 g_mount_eject (GMount              *mount,
423                GMountUnmountFlags   flags,
424                GCancellable        *cancellable,
425                GAsyncReadyCallback  callback,
426                gpointer             user_data)
427 {
428   GMountIface *iface;
429
430   g_return_if_fail (G_IS_MOUNT (mount));
431   
432   iface = G_MOUNT_GET_IFACE (mount);
433
434   if (iface->eject == NULL)
435     {
436       g_simple_async_report_error_in_idle (G_OBJECT (mount),
437                                            callback, user_data,
438                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
439                                            /* Translators: This is an error
440                                             * message for mount objects that
441                                             * don't implement eject. */
442                                            _("mount doesn't implement \"eject\""));
443       
444       return;
445     }
446   
447   (* iface->eject) (mount, flags, cancellable, callback, user_data);
448 }
449
450 /**
451  * g_mount_eject_finish:
452  * @mount: a #GMount.
453  * @result: a #GAsyncResult.
454  * @error: a #GError location to store the error occurring, or %NULL to 
455  *     ignore.
456  * 
457  * Finishes ejecting a mount. If any errors occurred during the operation, 
458  * @error will be set to contain the errors and %FALSE will be returned.
459  * 
460  * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
461  *
462  * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
463  **/
464 gboolean
465 g_mount_eject_finish (GMount        *mount,
466                       GAsyncResult  *result,
467                       GError       **error)
468 {
469   GMountIface *iface;
470
471   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
472   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
473
474   if (G_IS_SIMPLE_ASYNC_RESULT (result))
475     {
476       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
477       if (g_simple_async_result_propagate_error (simple, error))
478         return FALSE;
479     }
480   
481   iface = G_MOUNT_GET_IFACE (mount);
482   return (* iface->eject_finish) (mount, result, error);
483 }
484
485 /**
486  * g_mount_unmount_with_operation:
487  * @mount: a #GMount.
488  * @flags: flags affecting the operation
489  * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
490  *     user interaction.
491  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
492  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
493  * @user_data: user data passed to @callback.
494  *
495  * Unmounts a mount. This is an asynchronous operation, and is
496  * finished by calling g_mount_unmount_with_operation_finish() with the @mount 
497  * and #GAsyncResult data returned in the @callback.
498  *
499  * Since: 2.22
500  **/
501 void
502 g_mount_unmount_with_operation (GMount              *mount,
503                                 GMountUnmountFlags   flags,
504                                 GMountOperation     *mount_operation,
505                                 GCancellable        *cancellable,
506                                 GAsyncReadyCallback  callback,
507                                 gpointer             user_data)
508 {
509   GMountIface *iface;
510
511   g_return_if_fail (G_IS_MOUNT (mount));
512
513   iface = G_MOUNT_GET_IFACE (mount);
514
515   if (iface->unmount == NULL && iface->unmount_with_operation == NULL)
516     {
517       g_simple_async_report_error_in_idle (G_OBJECT (mount),
518                                            callback, user_data,
519                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
520                                            /* Translators: This is an error
521                                             * message for mount objects that
522                                             * don't implement any of unmount or unmount_with_operation. */
523                                            _("mount doesn't implement \"unmount\" or \"unmount_with_operation\""));
524
525       return;
526     }
527
528   if (iface->unmount_with_operation != NULL)
529     (* iface->unmount_with_operation) (mount, flags, mount_operation, cancellable, callback, user_data);
530   else
531     (* iface->unmount) (mount, flags, cancellable, callback, user_data);
532 }
533
534 /**
535  * g_mount_unmount_with_operation_finish:
536  * @mount: a #GMount.
537  * @result: a #GAsyncResult.
538  * @error: a #GError location to store the error occurring, or %NULL to
539  *     ignore.
540  *
541  * Finishes unmounting a mount. If any errors occurred during the operation,
542  * @error will be set to contain the errors and %FALSE will be returned.
543  *
544  * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
545  *
546  * Since: 2.22
547  **/
548 gboolean
549 g_mount_unmount_with_operation_finish (GMount        *mount,
550                                        GAsyncResult  *result,
551                                        GError       **error)
552 {
553   GMountIface *iface;
554
555   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
556   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
557
558   if (G_IS_SIMPLE_ASYNC_RESULT (result))
559     {
560       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
561       if (g_simple_async_result_propagate_error (simple, error))
562         return FALSE;
563     }
564
565   iface = G_MOUNT_GET_IFACE (mount);
566   if (iface->unmount_with_operation_finish != NULL)
567     return (* iface->unmount_with_operation_finish) (mount, result, error);
568   else
569     return (* iface->unmount_finish) (mount, result, error);
570 }
571
572
573 /**
574  * g_mount_eject_with_operation:
575  * @mount: a #GMount.
576  * @flags: flags affecting the unmount if required for eject
577  * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
578  *     user interaction.
579  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
580  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
581  * @user_data: user data passed to @callback.
582  *
583  * Ejects a mount. This is an asynchronous operation, and is
584  * finished by calling g_mount_eject_with_operation_finish() with the @mount
585  * and #GAsyncResult data returned in the @callback.
586  *
587  * Since: 2.22
588  **/
589 void
590 g_mount_eject_with_operation (GMount              *mount,
591                               GMountUnmountFlags   flags,
592                               GMountOperation     *mount_operation,
593                               GCancellable        *cancellable,
594                               GAsyncReadyCallback  callback,
595                               gpointer             user_data)
596 {
597   GMountIface *iface;
598
599   g_return_if_fail (G_IS_MOUNT (mount));
600
601   iface = G_MOUNT_GET_IFACE (mount);
602
603   if (iface->eject == NULL && iface->eject_with_operation == NULL)
604     {
605       g_simple_async_report_error_in_idle (G_OBJECT (mount),
606                                            callback, user_data,
607                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
608                                            /* Translators: This is an error
609                                             * message for mount objects that
610                                             * don't implement any of eject or eject_with_operation. */
611                                            _("mount doesn't implement \"eject\" or \"eject_with_operation\""));
612       return;
613     }
614
615   if (iface->eject_with_operation != NULL)
616     (* iface->eject_with_operation) (mount, flags, mount_operation, cancellable, callback, user_data);
617   else
618     (* iface->eject) (mount, flags, cancellable, callback, user_data);
619 }
620
621 /**
622  * g_mount_eject_with_operation_finish:
623  * @mount: a #GMount.
624  * @result: a #GAsyncResult.
625  * @error: a #GError location to store the error occurring, or %NULL to
626  *     ignore.
627  *
628  * Finishes ejecting a mount. If any errors occurred during the operation,
629  * @error will be set to contain the errors and %FALSE will be returned.
630  *
631  * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
632  *
633  * Since: 2.22
634  **/
635 gboolean
636 g_mount_eject_with_operation_finish (GMount        *mount,
637                                      GAsyncResult  *result,
638                                      GError       **error)
639 {
640   GMountIface *iface;
641
642   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
643   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
644
645   if (G_IS_SIMPLE_ASYNC_RESULT (result))
646     {
647       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
648       if (g_simple_async_result_propagate_error (simple, error))
649         return FALSE;
650     }
651
652   iface = G_MOUNT_GET_IFACE (mount);
653   if (iface->eject_with_operation_finish != NULL)
654     return (* iface->eject_with_operation_finish) (mount, result, error);
655   else
656     return (* iface->eject_finish) (mount, result, error);
657 }
658
659 /**
660  * g_mount_remount:
661  * @mount: a #GMount.
662  * @flags: flags affecting the operation
663  * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
664  *     user interaction.
665  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
666  * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
667  * @user_data: user data passed to @callback.
668  * 
669  * Remounts a mount. This is an asynchronous operation, and is 
670  * finished by calling g_mount_remount_finish() with the @mount 
671  * and #GAsyncResults data returned in the @callback.
672  *
673  * Remounting is useful when some setting affecting the operation
674  * of the volume has been changed, as these may need a remount to
675  * take affect. While this is semantically equivalent with unmounting
676  * and then remounting not all backends might need to actually be
677  * unmounted.
678  **/
679 void
680 g_mount_remount (GMount              *mount,
681                  GMountMountFlags     flags,
682                  GMountOperation     *mount_operation,
683                  GCancellable        *cancellable,
684                  GAsyncReadyCallback  callback,
685                  gpointer             user_data)
686 {
687   GMountIface *iface;
688
689   g_return_if_fail (G_IS_MOUNT (mount));
690   
691   iface = G_MOUNT_GET_IFACE (mount);
692
693   if (iface->remount == NULL)
694     { 
695       g_simple_async_report_error_in_idle (G_OBJECT (mount),
696                                            callback, user_data,
697                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
698                                            /* Translators: This is an error
699                                             * message for mount objects that
700                                             * don't implement remount. */
701                                            _("mount doesn't implement \"remount\""));
702       
703       return;
704     }
705   
706   (* iface->remount) (mount, flags, mount_operation, cancellable, callback, user_data);
707 }
708
709 /**
710  * g_mount_remount_finish:
711  * @mount: a #GMount.
712  * @result: a #GAsyncResult.
713  * @error: a #GError location to store the error occurring, or %NULL to 
714  *     ignore.
715  * 
716  * Finishes remounting a mount. If any errors occurred during the operation, 
717  * @error will be set to contain the errors and %FALSE will be returned.
718  * 
719  * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
720  **/
721 gboolean
722 g_mount_remount_finish (GMount        *mount,
723                         GAsyncResult  *result,
724                         GError       **error)
725 {
726   GMountIface *iface;
727
728   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
729   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
730
731   if (G_IS_SIMPLE_ASYNC_RESULT (result))
732     {
733       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
734       if (g_simple_async_result_propagate_error (simple, error))
735         return FALSE;
736     }
737   
738   iface = G_MOUNT_GET_IFACE (mount);
739   return (* iface->remount_finish) (mount, result, error);
740 }
741
742 /**
743  * g_mount_guess_content_type:
744  * @mount: a #GMount
745  * @force_rescan: Whether to force a rescan of the content. 
746  *     Otherwise a cached result will be used if available
747  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
748  * @callback: a #GAsyncReadyCallback
749  * @user_data: user data passed to @callback
750  * 
751  * Tries to guess the type of content stored on @mount. Returns one or
752  * more textual identifiers of well-known content types (typically
753  * prefixed with "x-content/"), e.g. x-content/image-dcf for camera 
754  * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
755  * specification for more on x-content types.
756  *
757  * This is an asynchronous operation (see
758  * g_mount_guess_content_type_sync() for the synchronous version), and
759  * is finished by calling g_mount_guess_content_type_finish() with the
760  * @mount and #GAsyncResult data returned in the @callback.
761  *
762  * Since: 2.18
763  */
764 void
765 g_mount_guess_content_type (GMount              *mount,
766                             gboolean             force_rescan,
767                             GCancellable        *cancellable,
768                             GAsyncReadyCallback  callback,
769                             gpointer             user_data)
770 {
771   GMountIface *iface;
772
773   g_return_if_fail (G_IS_MOUNT (mount));
774
775   iface = G_MOUNT_GET_IFACE (mount);
776
777   if (iface->guess_content_type == NULL)
778     {
779       g_simple_async_report_error_in_idle (G_OBJECT (mount),
780                                            callback, user_data,
781                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
782                                            /* Translators: This is an error
783                                             * message for mount objects that
784                                             * don't implement content type guessing. */
785                                            _("mount doesn't implement content type guessing"));
786
787       return;
788     }
789   
790   (* iface->guess_content_type) (mount, force_rescan, cancellable, callback, user_data);
791 }
792
793 /**
794  * g_mount_guess_content_type_finish:
795  * @mount: a #GMount
796  * @result: a #GAsyncResult
797  * @error: a #GError location to store the error occurring, or %NULL to 
798  *     ignore
799  * 
800  * Finishes guessing content types of @mount. If any errors occurred
801  * during the operation, @error will be set to contain the errors and
802  * %FALSE will be returned. In particular, you may get an 
803  * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content 
804  * guessing.
805  * 
806  * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. 
807  *     Caller should free this array with g_strfreev() when done with it.
808  *
809  * Since: 2.18
810  **/
811 gchar **
812 g_mount_guess_content_type_finish (GMount        *mount,
813                                    GAsyncResult  *result,
814                                    GError       **error)
815 {
816   GMountIface *iface;
817
818   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
819   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
820
821   if (G_IS_SIMPLE_ASYNC_RESULT (result))
822     {
823       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
824       if (g_simple_async_result_propagate_error (simple, error))
825         return NULL;
826     }
827   
828   iface = G_MOUNT_GET_IFACE (mount);
829   return (* iface->guess_content_type_finish) (mount, result, error);
830 }
831
832 /**
833  * g_mount_guess_content_type_sync:
834  * @mount: a #GMount
835  * @force_rescan: Whether to force a rescan of the content.
836  *     Otherwise a cached result will be used if available
837  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
838  * @error: a #GError location to store the error occurring, or %NULL to
839  *     ignore
840  *
841  * Tries to guess the type of content stored on @mount. Returns one or
842  * more textual identifiers of well-known content types (typically
843  * prefixed with "x-content/"), e.g. x-content/image-dcf for camera 
844  * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
845  * specification for more on x-content types.
846  *
847  * This is an synchronous operation and as such may block doing IO;
848  * see g_mount_guess_content_type() for the asynchronous version.
849  *
850  * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
851  *     Caller should free this array with g_strfreev() when done with it.
852  *
853  * Since: 2.18
854  */
855 char **
856 g_mount_guess_content_type_sync (GMount              *mount,
857                                  gboolean             force_rescan,
858                                  GCancellable        *cancellable,
859                                  GError             **error)
860 {
861   GMountIface *iface;
862
863   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
864
865   iface = G_MOUNT_GET_IFACE (mount);
866
867   if (iface->guess_content_type_sync == NULL)
868     {
869       g_set_error_literal (error,
870                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
871                            /* Translators: This is an error
872                             * message for mount objects that
873                             * don't implement content type guessing. */
874                            _("mount doesn't implement synchronous content type guessing"));
875
876       return NULL;
877     }
878
879   return (* iface->guess_content_type_sync) (mount, force_rescan, cancellable, error);
880 }
881
882 G_LOCK_DEFINE_STATIC (priv_lock);
883
884 /* only access this structure when holding priv_lock */
885 typedef struct
886 {
887   gint shadow_ref_count;
888 } GMountPrivate;
889
890 static void
891 free_private (GMountPrivate *private)
892 {
893   G_LOCK (priv_lock);
894   g_free (private);
895   G_UNLOCK (priv_lock);
896 }
897
898 /* may only be called when holding priv_lock */
899 static GMountPrivate *
900 get_private (GMount *mount)
901 {
902   GMountPrivate *private;
903
904   private = g_object_get_data (G_OBJECT (mount), "g-mount-private");
905   if (G_LIKELY (private != NULL))
906     goto out;
907
908   private = g_new0 (GMountPrivate, 1);
909   g_object_set_data_full (G_OBJECT (mount),
910                           "g-mount-private",
911                           private,
912                           (GDestroyNotify) free_private);
913
914  out:
915   return private;
916 }
917
918 /**
919  * g_mount_is_shadowed:
920  * @mount: A #GMount.
921  *
922  * Determines if @mount is shadowed. Applications or libraries should
923  * avoid displaying @mount in the user interface if it is shadowed.
924  *
925  * A mount is said to be shadowed if there exists one or more user
926  * visible objects (currently #GMount objects) with a root that is
927  * inside the root of @mount.
928  *
929  * One application of shadow mounts is when exposing a single file
930  * system that is used to address several logical volumes. In this
931  * situation, a #GVolumeMonitor implementation would create two
932  * #GVolume objects (for example, one for the camera functionality of
933  * the device and one for a SD card reader on the device) with
934  * activation URIs <literal>gphoto2://[usb:001,002]/store1/</literal>
935  * and <literal>gphoto2://[usb:001,002]/store2/</literal>. When the
936  * underlying mount (with root
937  * <literal>gphoto2://[usb:001,002]/</literal>) is mounted, said
938  * #GVolumeMonitor implementation would create two #GMount objects
939  * (each with their root matching the corresponding volume activation
940  * root) that would shadow the original mount.
941  *
942  * The proxy monitor in GVfs 2.26 and later, automatically creates and
943  * manage shadow mounts (and shadows the underlying mount) if the
944  * activation root on a #GVolume is set.
945  *
946  * Returns: %TRUE if @mount is shadowed.
947  *
948  * Since: 2.20
949  **/
950 gboolean
951 g_mount_is_shadowed (GMount *mount)
952 {
953   GMountPrivate *priv;
954   gboolean ret;
955
956   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
957
958   G_LOCK (priv_lock);
959   priv = get_private (mount);
960   ret = (priv->shadow_ref_count > 0);
961   G_UNLOCK (priv_lock);
962
963   return ret;
964 }
965
966 /**
967  * g_mount_shadow:
968  * @mount: A #GMount.
969  *
970  * Increments the shadow count on @mount. Usually used by
971  * #GVolumeMonitor implementations when creating a shadow mount for
972  * @mount, see g_mount_is_shadowed() for more information. The caller
973  * will need to emit the #GMount::changed signal on @mount manually.
974  *
975  * Since: 2.20
976  **/
977 void
978 g_mount_shadow (GMount *mount)
979 {
980   GMountPrivate *priv;
981
982   g_return_if_fail (G_IS_MOUNT (mount));
983
984   G_LOCK (priv_lock);
985   priv = get_private (mount);
986   priv->shadow_ref_count += 1;
987   G_UNLOCK (priv_lock);
988 }
989
990 /**
991  * g_mount_unshadow:
992  * @mount: A #GMount.
993  *
994  * Decrements the shadow count on @mount. Usually used by
995  * #GVolumeMonitor implementations when destroying a shadow mount for
996  * @mount, see g_mount_is_shadowed() for more information. The caller
997  * will need to emit the #GMount::changed signal on @mount manually.
998  *
999  * Since: 2.20
1000  **/
1001 void
1002 g_mount_unshadow (GMount *mount)
1003 {
1004   GMountPrivate *priv;
1005
1006   g_return_if_fail (G_IS_MOUNT (mount));
1007
1008   G_LOCK (priv_lock);
1009   priv = get_private (mount);
1010   priv->shadow_ref_count -= 1;
1011   if (priv->shadow_ref_count < 0)
1012     g_warning ("Shadow ref count on GMount is negative");
1013   G_UNLOCK (priv_lock);
1014 }