nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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, see <http://www.gnu.org/licenses/>.
17 *
18 * Author: Alexander Larsson <alexl@redhat.com>
19 * David Zeuthen <davidz@redhat.com>
20 */
21  
22 #include "config.h"
23 #include "gmount.h"
24 #include "gvolume.h"
25 #include "gthemedicon.h"
26 #include "gasyncresult.h"
27 #include "gtask.h"
28 #include "gioerror.h"
29 #include "glibintl.h"
30  
31  
32 /**
33 * SECTION:gvolume
34 * @short_description: Volume management
35 * @include: gio/gio.h
36 *
37 * The #GVolume interface represents user-visible objects that can be
38 * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
39 * equivalent of #GnomeVFSDrive.
40 *
41 * Mounting a #GVolume instance is an asynchronous operation. For more
42 * information about asynchronous operations, see #GAsyncResult and
43 * #GTask. To mount a #GVolume, first call g_volume_mount() with (at
44 * least) the #GVolume instance, optionally a #GMountOperation object
45 * and a #GAsyncReadyCallback.
46 *
47 * Typically, one will only want to pass %NULL for the
48 * #GMountOperation if automounting all volumes when a desktop session
49 * starts since it's not desirable to put up a lot of dialogs asking
50 * for credentials.
51 *
52 * The callback will be fired when the operation has resolved (either
53 * with success or failure), and a #GAsyncReady structure will be
54 * passed to the callback. That callback should then call
55 * g_volume_mount_finish() with the #GVolume instance and the
56 * #GAsyncReady data to see if the operation was completed
57 * successfully. If an @error is present when g_volume_mount_finish()
58 * is called, then it will be filled with any error information.
59 *
60 * ## Volume Identifiers # {#volume-identifier}
61 *
62 * It is sometimes necessary to directly access the underlying
63 * operating system object behind a volume (e.g. for passing a volume
64 * to an application via the commandline). For this purpose, GIO
65 * allows to obtain an 'identifier' for the volume. There can be
66 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
67 * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
68 * strings as names for the different kinds of identifiers:
69 * #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
70 * Use g_volume_get_identifier() to obtain an identifier for a volume.
71 *
72 *
73 * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
74 * when the gvfs hal volume monitor is in use. Other volume monitors
75 * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
76 * identifier, which can be used to obtain a hal device by means of
77 * libhal_manager_find_device_string_match().
78 */
79  
80 typedef GVolumeIface GVolumeInterface;
81 G_DEFINE_INTERFACE(GVolume, g_volume, G_TYPE_OBJECT)
82  
83 static void
84 g_volume_default_init (GVolumeInterface *iface)
85 {
86 /**
87 * GVolume::changed:
88 *
89 * Emitted when the volume has been changed.
90 */
91 g_signal_new (I_("changed"),
92 G_TYPE_VOLUME,
93 G_SIGNAL_RUN_LAST,
94 G_STRUCT_OFFSET (GVolumeIface, changed),
95 NULL, NULL,
96 g_cclosure_marshal_VOID__VOID,
97 G_TYPE_NONE, 0);
98  
99 /**
100 * GVolume::removed:
101 *
102 * This signal is emitted when the #GVolume have been removed. If
103 * the recipient is holding references to the object they should
104 * release them so the object can be finalized.
105 */
106 g_signal_new (I_("removed"),
107 G_TYPE_VOLUME,
108 G_SIGNAL_RUN_LAST,
109 G_STRUCT_OFFSET (GVolumeIface, removed),
110 NULL, NULL,
111 g_cclosure_marshal_VOID__VOID,
112 G_TYPE_NONE, 0);
113 }
114  
115 /**
116 * g_volume_get_name:
117 * @volume: a #GVolume
118 *
119 * Gets the name of @volume.
120 *
121 * Returns: the name for the given @volume. The returned string should
122 * be freed with g_free() when no longer needed.
123 */
124 char *
125 g_volume_get_name (GVolume *volume)
126 {
127 GVolumeIface *iface;
128  
129 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
130  
131 iface = G_VOLUME_GET_IFACE (volume);
132  
133 return (* iface->get_name) (volume);
134 }
135  
136 /**
137 * g_volume_get_icon:
138 * @volume: a #GVolume
139 *
140 * Gets the icon for @volume.
141 *
142 * Returns: (transfer full): a #GIcon.
143 * The returned object should be unreffed with g_object_unref()
144 * when no longer needed.
145 */
146 GIcon *
147 g_volume_get_icon (GVolume *volume)
148 {
149 GVolumeIface *iface;
150  
151 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
152  
153 iface = G_VOLUME_GET_IFACE (volume);
154  
155 return (* iface->get_icon) (volume);
156 }
157  
158 /**
159 * g_volume_get_symbolic_icon:
160 * @volume: a #GVolume
161 *
162 * Gets the symbolic icon for @volume.
163 *
164 * Returns: (transfer full): a #GIcon.
165 * The returned object should be unreffed with g_object_unref()
166 * when no longer needed.
167 *
168 * Since: 2.34
169 */
170 GIcon *
171 g_volume_get_symbolic_icon (GVolume *volume)
172 {
173 GVolumeIface *iface;
174 GIcon *ret;
175  
176 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
177  
178 iface = G_VOLUME_GET_IFACE (volume);
179  
180 if (iface->get_symbolic_icon != NULL)
181 ret = iface->get_symbolic_icon (volume);
182 else
183 ret = g_themed_icon_new_with_default_fallbacks ("folder-remote-symbolic");
184  
185 return ret;
186  
187 }
188  
189 /**
190 * g_volume_get_uuid:
191 * @volume: a #GVolume
192 *
193 * Gets the UUID for the @volume. The reference is typically based on
194 * the file system UUID for the volume in question and should be
195 * considered an opaque string. Returns %NULL if there is no UUID
196 * available.
197 *
198 * Returns: the UUID for @volume or %NULL if no UUID can be computed.
199 * The returned string should be freed with g_free()
200 * when no longer needed.
201 */
202 char *
203 g_volume_get_uuid (GVolume *volume)
204 {
205 GVolumeIface *iface;
206  
207 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
208  
209 iface = G_VOLUME_GET_IFACE (volume);
210  
211 return (* iface->get_uuid) (volume);
212 }
213  
214 /**
215 * g_volume_get_drive:
216 * @volume: a #GVolume
217 *
218 * Gets the drive for the @volume.
219 *
220 * Returns: (transfer full): a #GDrive or %NULL if @volume is not
221 * associated with a drive. The returned object should be unreffed
222 * with g_object_unref() when no longer needed.
223 */
224 GDrive *
225 g_volume_get_drive (GVolume *volume)
226 {
227 GVolumeIface *iface;
228  
229 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
230  
231 iface = G_VOLUME_GET_IFACE (volume);
232  
233 return (* iface->get_drive) (volume);
234 }
235  
236 /**
237 * g_volume_get_mount:
238 * @volume: a #GVolume
239 *
240 * Gets the mount for the @volume.
241 *
242 * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted.
243 * The returned object should be unreffed with g_object_unref()
244 * when no longer needed.
245 */
246 GMount *
247 g_volume_get_mount (GVolume *volume)
248 {
249 GVolumeIface *iface;
250  
251 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
252  
253 iface = G_VOLUME_GET_IFACE (volume);
254  
255 return (* iface->get_mount) (volume);
256 }
257  
258  
259 /**
260 * g_volume_can_mount:
261 * @volume: a #GVolume
262 *
263 * Checks if a volume can be mounted.
264 *
265 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise
266 */
267 gboolean
268 g_volume_can_mount (GVolume *volume)
269 {
270 GVolumeIface *iface;
271  
272 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
273  
274 iface = G_VOLUME_GET_IFACE (volume);
275  
276 if (iface->can_mount == NULL)
277 return FALSE;
278  
279 return (* iface->can_mount) (volume);
280 }
281  
282 /**
283 * g_volume_can_eject:
284 * @volume: a #GVolume
285 *
286 * Checks if a volume can be ejected.
287 *
288 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise
289 */
290 gboolean
291 g_volume_can_eject (GVolume *volume)
292 {
293 GVolumeIface *iface;
294  
295 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
296  
297 iface = G_VOLUME_GET_IFACE (volume);
298  
299 if (iface->can_eject == NULL)
300 return FALSE;
301  
302 return (* iface->can_eject) (volume);
303 }
304  
305 /**
306 * g_volume_should_automount:
307 * @volume: a #GVolume
308 *
309 * Returns whether the volume should be automatically mounted.
310 *
311 * Returns: %TRUE if the volume should be automatically mounted
312 */
313 gboolean
314 g_volume_should_automount (GVolume *volume)
315 {
316 GVolumeIface *iface;
317  
318 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
319  
320 iface = G_VOLUME_GET_IFACE (volume);
321  
322 if (iface->should_automount == NULL)
323 return FALSE;
324  
325 return (* iface->should_automount) (volume);
326 }
327  
328  
329 /**
330 * g_volume_mount:
331 * @volume: a #GVolume
332 * @flags: flags affecting the operation
333 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction
334 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
335 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
336 * @user_data: user data that gets passed to @callback
337 *
338 * Mounts a volume. This is an asynchronous operation, and is
339 * finished by calling g_volume_mount_finish() with the @volume
340 * and #GAsyncResult returned in the @callback.
341 *
342 * Virtual: mount_fn
343 */
344 void
345 g_volume_mount (GVolume *volume,
346 GMountMountFlags flags,
347 GMountOperation *mount_operation,
348 GCancellable *cancellable,
349 GAsyncReadyCallback callback,
350 gpointer user_data)
351 {
352 GVolumeIface *iface;
353  
354 g_return_if_fail (G_IS_VOLUME (volume));
355  
356 iface = G_VOLUME_GET_IFACE (volume);
357  
358 if (iface->mount_fn == NULL)
359 {
360 g_task_report_new_error (volume, callback, user_data,
361 g_volume_mount,
362 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
363 _("volume doesn't implement mount"));
364 return;
365 }
366  
367 (* iface->mount_fn) (volume, flags, mount_operation, cancellable, callback, user_data);
368 }
369  
370 /**
371 * g_volume_mount_finish:
372 * @volume: a #GVolume
373 * @result: a #GAsyncResult
374 * @error: a #GError location to store an error, or %NULL to ignore
375 *
376 * Finishes mounting a volume. If any errors occurred during the operation,
377 * @error will be set to contain the errors and %FALSE will be returned.
378 *
379 * If the mount operation succeeded, g_volume_get_mount() on @volume
380 * is guaranteed to return the mount right after calling this
381 * function; there's no need to listen for the 'mount-added' signal on
382 * #GVolumeMonitor.
383 *
384 * Returns: %TRUE, %FALSE if operation failed
385 */
386 gboolean
387 g_volume_mount_finish (GVolume *volume,
388 GAsyncResult *result,
389 GError **error)
390 {
391 GVolumeIface *iface;
392  
393 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
394 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
395  
396 if (g_async_result_legacy_propagate_error (result, error))
397 return FALSE;
398 else if (g_async_result_is_tagged (result, g_volume_mount))
399 return g_task_propagate_boolean (G_TASK (result), error);
400  
401 iface = G_VOLUME_GET_IFACE (volume);
402 return (* iface->mount_finish) (volume, result, error);
403 }
404  
405 /**
406 * g_volume_eject:
407 * @volume: a #GVolume
408 * @flags: flags affecting the unmount if required for eject
409 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
410 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
411 * @user_data: user data that gets passed to @callback
412 *
413 * Ejects a volume. This is an asynchronous operation, and is
414 * finished by calling g_volume_eject_finish() with the @volume
415 * and #GAsyncResult returned in the @callback.
416 *
417 * Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
418 */
419 void
420 g_volume_eject (GVolume *volume,
421 GMountUnmountFlags flags,
422 GCancellable *cancellable,
423 GAsyncReadyCallback callback,
424 gpointer user_data)
425 {
426 GVolumeIface *iface;
427  
428 g_return_if_fail (G_IS_VOLUME (volume));
429  
430 iface = G_VOLUME_GET_IFACE (volume);
431  
432 if (iface->eject == NULL)
433 {
434 g_task_report_new_error (volume, callback, user_data,
435 g_volume_eject_with_operation,
436 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
437 _("volume doesn't implement eject"));
438 return;
439 }
440  
441 (* iface->eject) (volume, flags, cancellable, callback, user_data);
442 }
443  
444 /**
445 * g_volume_eject_finish:
446 * @volume: pointer to a #GVolume
447 * @result: a #GAsyncResult
448 * @error: a #GError location to store an error, or %NULL to ignore
449 *
450 * Finishes ejecting a volume. If any errors occurred during the operation,
451 * @error will be set to contain the errors and %FALSE will be returned.
452 *
453 * Returns: %TRUE, %FALSE if operation failed
454 *
455 * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
456 **/
457 gboolean
458 g_volume_eject_finish (GVolume *volume,
459 GAsyncResult *result,
460 GError **error)
461 {
462 GVolumeIface *iface;
463  
464 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
465 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
466  
467 if (g_async_result_legacy_propagate_error (result, error))
468 return FALSE;
469 if (g_async_result_is_tagged (result, g_volume_eject_with_operation))
470 return g_task_propagate_boolean (G_TASK (result), error);
471  
472 iface = G_VOLUME_GET_IFACE (volume);
473 return (* iface->eject_finish) (volume, result, error);
474 }
475  
476 /**
477 * g_volume_eject_with_operation:
478 * @volume: a #GVolume
479 * @flags: flags affecting the unmount if required for eject
480 * @mount_operation: (allow-none): a #GMountOperation or %NULL to
481 * avoid user interaction
482 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
483 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
484 * @user_data: user data passed to @callback
485 *
486 * Ejects a volume. This is an asynchronous operation, and is
487 * finished by calling g_volume_eject_with_operation_finish() with the @volume
488 * and #GAsyncResult data returned in the @callback.
489 *
490 * Since: 2.22
491 **/
492 void
493 g_volume_eject_with_operation (GVolume *volume,
494 GMountUnmountFlags flags,
495 GMountOperation *mount_operation,
496 GCancellable *cancellable,
497 GAsyncReadyCallback callback,
498 gpointer user_data)
499 {
500 GVolumeIface *iface;
501  
502 g_return_if_fail (G_IS_VOLUME (volume));
503  
504 iface = G_VOLUME_GET_IFACE (volume);
505  
506 if (iface->eject == NULL && iface->eject_with_operation == NULL)
507 {
508 g_task_report_new_error (volume, callback, user_data,
509 g_volume_eject_with_operation,
510 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
511 /* Translators: This is an error
512 * message for volume objects that
513 * don't implement any of eject or eject_with_operation. */
514 _("volume doesn't implement eject or eject_with_operation"));
515 return;
516 }
517  
518 if (iface->eject_with_operation != NULL)
519 (* iface->eject_with_operation) (volume, flags, mount_operation, cancellable, callback, user_data);
520 else
521 (* iface->eject) (volume, flags, cancellable, callback, user_data);
522 }
523  
524 /**
525 * g_volume_eject_with_operation_finish:
526 * @volume: a #GVolume
527 * @result: a #GAsyncResult
528 * @error: a #GError location to store the error occurring, or %NULL
529 *
530 * Finishes ejecting a volume. If any errors occurred during the operation,
531 * @error will be set to contain the errors and %FALSE will be returned.
532 *
533 * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise
534 *
535 * Since: 2.22
536 **/
537 gboolean
538 g_volume_eject_with_operation_finish (GVolume *volume,
539 GAsyncResult *result,
540 GError **error)
541 {
542 GVolumeIface *iface;
543  
544 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
545 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
546  
547 if (g_async_result_legacy_propagate_error (result, error))
548 return FALSE;
549 else if (g_async_result_is_tagged (result, g_volume_eject_with_operation))
550 return g_task_propagate_boolean (G_TASK (result), error);
551  
552 iface = G_VOLUME_GET_IFACE (volume);
553 if (iface->eject_with_operation_finish != NULL)
554 return (* iface->eject_with_operation_finish) (volume, result, error);
555 else
556 return (* iface->eject_finish) (volume, result, error);
557 }
558  
559 /**
560 * g_volume_get_identifier:
561 * @volume: a #GVolume
562 * @kind: the kind of identifier to return
563 *
564 * Gets the identifier of the given kind for @volume.
565 * See the [introduction][volume-identifier] for more
566 * information about volume identifiers.
567 *
568 * Returns: a newly allocated string containing the
569 * requested identfier, or %NULL if the #GVolume
570 * doesn't have this kind of identifier
571 */
572 char *
573 g_volume_get_identifier (GVolume *volume,
574 const char *kind)
575 {
576 GVolumeIface *iface;
577  
578 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
579 g_return_val_if_fail (kind != NULL, NULL);
580  
581 iface = G_VOLUME_GET_IFACE (volume);
582  
583 if (iface->get_identifier == NULL)
584 return NULL;
585  
586 return (* iface->get_identifier) (volume, kind);
587 }
588  
589 /**
590 * g_volume_enumerate_identifiers:
591 * @volume: a #GVolume
592 *
593 * Gets the kinds of [identifiers][volume-identifier] that @volume has.
594 * Use g_volume_get_identifier() to obtain the identifiers themselves.
595 *
596 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
597 * of strings containing kinds of identifiers. Use g_strfreev() to free.
598 */
599 char **
600 g_volume_enumerate_identifiers (GVolume *volume)
601 {
602 GVolumeIface *iface;
603  
604 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
605 iface = G_VOLUME_GET_IFACE (volume);
606  
607 if (iface->enumerate_identifiers == NULL)
608 return NULL;
609  
610 return (* iface->enumerate_identifiers) (volume);
611 }
612  
613 /**
614 * g_volume_get_activation_root:
615 * @volume: a #GVolume
616 *
617 * Gets the activation root for a #GVolume if it is known ahead of
618 * mount time. Returns %NULL otherwise. If not %NULL and if @volume
619 * is mounted, then the result of g_mount_get_root() on the
620 * #GMount object obtained from g_volume_get_mount() will always
621 * either be equal or a prefix of what this function returns. In
622 * other words, in code
623 *
624 * |[<!-- language="C" -->
625 * GMount *mount;
626 * GFile *mount_root
627 * GFile *volume_activation_root;
628 *
629 * mount = g_volume_get_mount (volume); // mounted, so never NULL
630 * mount_root = g_mount_get_root (mount);
631 * volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
632 * ]|
633 * then the expression
634 * |[<!-- language="C" -->
635 * (g_file_has_prefix (volume_activation_root, mount_root) ||
636 g_file_equal (volume_activation_root, mount_root))
637 * ]|
638 * will always be %TRUE.
639 *
640 * Activation roots are typically used in #GVolumeMonitor
641 * implementations to find the underlying mount to shadow, see
642 * g_mount_is_shadowed() for more details.
643 *
644 * Returns: (nullable) (transfer full): the activation root of @volume
645 * or %NULL. Use g_object_unref() to free.
646 *
647 * Since: 2.18
648 */
649 GFile *
650 g_volume_get_activation_root (GVolume *volume)
651 {
652 GVolumeIface *iface;
653  
654 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
655 iface = G_VOLUME_GET_IFACE (volume);
656  
657 if (iface->get_activation_root == NULL)
658 return NULL;
659  
660 return (* iface->get_activation_root) (volume);
661 }
662  
663 /**
664 * g_volume_get_sort_key:
665 * @volume: a #GVolume
666 *
667 * Gets the sort key for @volume, if any.
668 *
669 * Returns: Sorting key for @volume or %NULL if no such key is available
670 *
671 * Since: 2.32
672 */
673 const gchar *
674 g_volume_get_sort_key (GVolume *volume)
675 {
676 const gchar *ret = NULL;
677 GVolumeIface *iface;
678  
679 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
680  
681 iface = G_VOLUME_GET_IFACE (volume);
682 if (iface->get_sort_key != NULL)
683 ret = iface->get_sort_key (volume);
684  
685 return ret;
686 }