1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Alexander Larsson <alexl@redhat.com>
21 * David Zeuthen <davidz@redhat.com>
27 #include "gsimpleasyncresult.h"
34 * @short_description: Volume management
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.
41 * Mounting a #GVolume instance is an asynchronous operation. For more
42 * information about asynchronous operations, see #GAsyncReady and
43 * #GSimpleAsyncReady. To mount a #GVolume, first call
44 * g_volume_mount() with (at least) the #GVolume instance, optionally
45 * a #GMountOperation object and a #GAsyncReadyCallback.
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
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.
60 * <para id="volume-identifier">
61 * It is sometimes necessary to directly access the underlying
62 * operating system object behind a volume (e.g. for passing a volume
63 * to an application via the commandline). For this purpose, GIO
64 * allows to obtain an 'identifier' for the volume. There can be
65 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
66 * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
67 * uuids. GIO uses predefind strings as names for the different kinds
68 * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
69 * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
70 * to obtain an identifier for a volume.
74 static void g_volume_base_init (gpointer g_class);
75 static void g_volume_class_init (gpointer g_class,
79 g_volume_get_type (void)
81 static GType volume_type = 0;
85 static const GTypeInfo volume_info =
87 sizeof (GVolumeIface), /* class_size */
88 g_volume_base_init, /* base_init */
89 NULL, /* base_finalize */
91 NULL, /* class_finalize */
92 NULL, /* class_data */
99 g_type_register_static (G_TYPE_INTERFACE, I_("GVolume"),
102 g_type_interface_add_prerequisite (volume_type, G_TYPE_OBJECT);
109 g_volume_class_init (gpointer g_class,
115 g_volume_base_init (gpointer g_class)
117 static gboolean initialized = FALSE;
124 * Emitted when the volume has been changed.
126 g_signal_new (I_("changed"),
129 G_STRUCT_OFFSET (GVolumeIface, changed),
131 g_cclosure_marshal_VOID__VOID,
137 * This signal is emitted when the #GVolume have been removed. If
138 * the recipient is holding references to the object they should
139 * release them so the object can be finalized.
141 g_signal_new (I_("removed"),
144 G_STRUCT_OFFSET (GVolumeIface, removed),
146 g_cclosure_marshal_VOID__VOID,
155 * @volume: a #GVolume.
157 * Gets the name of @volume.
159 * Returns: the name for the given @volume. The returned string should
160 * be freed when no longer needed.
163 g_volume_get_name (GVolume *volume)
167 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
169 iface = G_VOLUME_GET_IFACE (volume);
171 return (* iface->get_name) (volume);
176 * @volume: a #GVolume.
178 * Gets the icon for @volume.
183 g_volume_get_icon (GVolume *volume)
187 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
189 iface = G_VOLUME_GET_IFACE (volume);
191 return (* iface->get_icon) (volume);
196 * @volume: a #GVolume.
198 * Gets the UUID for the @volume. The reference is typically based on
199 * the file system UUID for the volume in question and should be
200 * considered an opaque string. Returns %NULL if there is no UUID
203 * Returns: the UUID for @volume or %NULL if no UUID can be computed.
206 g_volume_get_uuid (GVolume *volume)
210 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
212 iface = G_VOLUME_GET_IFACE (volume);
214 return (* iface->get_uuid) (volume);
218 * g_volume_get_drive:
219 * @volume: a #GVolume.
221 * Gets the drive for the @volume.
223 * Returns: a #GDrive or %NULL if @volume is not associated with a drive.
226 g_volume_get_drive (GVolume *volume)
230 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
232 iface = G_VOLUME_GET_IFACE (volume);
234 return (* iface->get_drive) (volume);
238 * g_volume_get_mount:
239 * @volume: a #GVolume.
241 * Gets the mount for the @volume.
243 * Returns: a #GMount or %NULL if @volume isn't mounted.
246 g_volume_get_mount (GVolume *volume)
250 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
252 iface = G_VOLUME_GET_IFACE (volume);
254 return (* iface->get_mount) (volume);
259 * g_volume_can_mount:
260 * @volume: a #GVolume.
262 * Checks if a volume can be mounted.
264 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise.
267 g_volume_can_mount (GVolume *volume)
271 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
273 iface = G_VOLUME_GET_IFACE (volume);
275 if (iface->can_mount == NULL)
278 return (* iface->can_mount) (volume);
282 * g_volume_can_eject:
283 * @volume: a #GVolume.
285 * Checks if a volume can be ejected.
287 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise.
290 g_volume_can_eject (GVolume *volume)
294 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
296 iface = G_VOLUME_GET_IFACE (volume);
298 if (iface->can_eject == NULL)
301 return (* iface->can_eject) (volume);
305 * g_volume_should_automount:
306 * @volume: a #GVolume
308 * Returns whether the volume should be automatically mounted.
310 * Returns: %TRUE if the volume should be automatically mounted.
313 g_volume_should_automount (GVolume *volume)
317 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
319 iface = G_VOLUME_GET_IFACE (volume);
321 if (iface->should_automount == NULL)
324 return (* iface->should_automount) (volume);
330 * @volume: a #GVolume.
331 * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
332 * @cancellable: optional #GCancellable object, %NULL to ignore.
333 * @callback: a #GAsyncReadyCallback, or %NULL.
334 * @user_data: a #gpointer.
339 g_volume_mount (GVolume *volume,
340 GMountOperation *mount_operation,
341 GCancellable *cancellable,
342 GAsyncReadyCallback callback,
347 g_return_if_fail (G_IS_VOLUME (volume));
349 iface = G_VOLUME_GET_IFACE (volume);
351 if (iface->mount_fn == NULL)
353 g_simple_async_report_error_in_idle (G_OBJECT (volume), callback, user_data,
354 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
355 _("volume doesn't implement mount"));
360 (* iface->mount_fn) (volume, mount_operation, cancellable, callback, user_data);
364 * g_volume_mount_finish:
365 * @volume: pointer to a #GVolume.
366 * @result: a #GAsyncResult.
369 * Finishes mounting a volume.
371 * Returns: %TRUE, %FALSE if operation failed.
374 g_volume_mount_finish (GVolume *volume,
375 GAsyncResult *result,
380 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
381 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
383 if (G_IS_SIMPLE_ASYNC_RESULT (result))
385 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
386 if (g_simple_async_result_propagate_error (simple, error))
390 iface = G_VOLUME_GET_IFACE (volume);
391 return (* iface->mount_finish) (volume, result, error);
396 * @volume: a #GVolume.
397 * @flags: flags affecting the unmount if required for eject
398 * @cancellable: optional #GCancellable object, %NULL to ignore.
399 * @callback: a #GAsyncReadyCallback, or %NULL.
400 * @user_data: a #gpointer.
405 g_volume_eject (GVolume *volume,
406 GMountUnmountFlags flags,
407 GCancellable *cancellable,
408 GAsyncReadyCallback callback,
413 g_return_if_fail (G_IS_VOLUME (volume));
415 iface = G_VOLUME_GET_IFACE (volume);
417 if (iface->eject == NULL)
419 g_simple_async_report_error_in_idle (G_OBJECT (volume), callback, user_data,
420 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
421 _("volume doesn't implement eject"));
426 (* iface->eject) (volume, flags, cancellable, callback, user_data);
430 * g_volume_eject_finish:
431 * @volume: pointer to a #GVolume.
432 * @result: a #GAsyncResult.
435 * Finishes ejecting a volume.
437 * Returns: %TRUE, %FALSE if operation failed.
440 g_volume_eject_finish (GVolume *volume,
441 GAsyncResult *result,
446 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
447 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
449 if (G_IS_SIMPLE_ASYNC_RESULT (result))
451 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
452 if (g_simple_async_result_propagate_error (simple, error))
456 iface = G_VOLUME_GET_IFACE (volume);
457 return (* iface->eject_finish) (volume, result, error);
461 * g_volume_get_identifier:
462 * @volume: a #GVolume
463 * @kind: the kind of identifier to return
465 * Gets the identifier of the given kind for @volume.
466 * See the <link linkend="volume-identifier">introduction</link>
467 * for more information about volume identifiers.
469 * Returns: a newly allocated string containing the
470 * requested identfier, or %NULL if the #GVolume
471 * doesn't have this kind of identifier
474 g_volume_get_identifier (GVolume *volume,
479 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
480 g_return_val_if_fail (kind != NULL, NULL);
482 iface = G_VOLUME_GET_IFACE (volume);
484 if (iface->get_identifier == NULL)
487 return (* iface->get_identifier) (volume, kind);
491 * g_volume_enumerate_identifiers:
492 * @volume: a #GVolume
494 * Gets the kinds of <link linkend="volume-identifier">identifiers</link>
495 * that @volume has. Use g_volume_get_identifer() to obtain
496 * the identifiers themselves.
498 * Returns: a %NULL-terminated array of strings containing
499 * kinds of identifiers. Use g_strfreev() to free.
502 g_volume_enumerate_identifiers (GVolume *volume)
506 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
507 iface = G_VOLUME_GET_IFACE (volume);
509 if (iface->enumerate_identifiers == NULL)
512 return (* iface->enumerate_identifiers) (volume);
516 #define __G_VOLUME_C__
517 #include "gioaliasdef.c"