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 "gasyncresult.h"
28 #include "gsimpleasyncresult.h"
36 * @short_description: Volume management
39 * The #GVolume interface represents user-visible objects that can be
40 * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
41 * equivalent of #GnomeVFSDrive.
43 * Mounting a #GVolume instance is an asynchronous operation. For more
44 * information about asynchronous operations, see #GAsyncReady and
45 * #GSimpleAsyncReady. To mount a #GVolume, first call
46 * g_volume_mount() with (at least) the #GVolume instance, optionally
47 * a #GMountOperation object and a #GAsyncReadyCallback.
49 * Typically, one will only want to pass %NULL for the
50 * #GMountOperation if automounting all volumes when a desktop session
51 * starts since it's not desirable to put up a lot of dialogs asking
54 * The callback will be fired when the operation has resolved (either
55 * with success or failure), and a #GAsyncReady structure will be
56 * passed to the callback. That callback should then call
57 * g_volume_mount_finish() with the #GVolume instance and the
58 * #GAsyncReady data to see if the operation was completed
59 * successfully. If an @error is present when g_volume_mount_finish()
60 * is called, then it will be filled with any error information.
62 * <para id="volume-identifier">
63 * It is sometimes necessary to directly access the underlying
64 * operating system object behind a volume (e.g. for passing a volume
65 * to an application via the commandline). For this purpose, GIO
66 * allows to obtain an 'identifier' for the volume. There can be
67 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
68 * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
69 * uuids. GIO uses predefind strings as names for the different kinds
70 * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
71 * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
72 * to obtain an identifier for a volume.
76 static void g_volume_base_init (gpointer g_class);
77 static void g_volume_class_init (gpointer g_class,
81 g_volume_get_type (void)
83 static GType volume_type = 0;
87 static const GTypeInfo volume_info =
89 sizeof (GVolumeIface), /* class_size */
90 g_volume_base_init, /* base_init */
91 NULL, /* base_finalize */
93 NULL, /* class_finalize */
94 NULL, /* class_data */
101 g_type_register_static (G_TYPE_INTERFACE, I_("GVolume"),
104 g_type_interface_add_prerequisite (volume_type, G_TYPE_OBJECT);
111 g_volume_class_init (gpointer g_class,
117 g_volume_base_init (gpointer g_class)
119 static gboolean initialized = FALSE;
126 * Emitted when the volume has been changed.
128 g_signal_new (I_("changed"),
131 G_STRUCT_OFFSET (GVolumeIface, changed),
133 g_cclosure_marshal_VOID__VOID,
139 * This signal is emitted when the #GVolume have been removed. If
140 * the recipient is holding references to the object they should
141 * release them so the object can be finalized.
143 g_signal_new (I_("removed"),
146 G_STRUCT_OFFSET (GVolumeIface, removed),
148 g_cclosure_marshal_VOID__VOID,
157 * @volume: a #GVolume.
159 * Gets the name of @volume.
161 * Returns: the name for the given @volume. The returned string should
162 * be freed when no longer needed.
165 g_volume_get_name (GVolume *volume)
169 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
171 iface = G_VOLUME_GET_IFACE (volume);
173 return (* iface->get_name) (volume);
178 * @volume: a #GVolume.
180 * Gets the icon for @volume.
185 g_volume_get_icon (GVolume *volume)
189 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
191 iface = G_VOLUME_GET_IFACE (volume);
193 return (* iface->get_icon) (volume);
198 * @volume: a #GVolume.
200 * Gets the UUID for the @volume. The reference is typically based on
201 * the file system UUID for the volume in question and should be
202 * considered an opaque string. Returns %NULL if there is no UUID
205 * Returns: the UUID for @volume or %NULL if no UUID can be computed.
208 g_volume_get_uuid (GVolume *volume)
212 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
214 iface = G_VOLUME_GET_IFACE (volume);
216 return (* iface->get_uuid) (volume);
220 * g_volume_get_drive:
221 * @volume: a #GVolume.
223 * Gets the drive for the @volume.
225 * Returns: a #GDrive or %NULL if @volume is not associated with a drive.
228 g_volume_get_drive (GVolume *volume)
232 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
234 iface = G_VOLUME_GET_IFACE (volume);
236 return (* iface->get_drive) (volume);
240 * g_volume_get_mount:
241 * @volume: a #GVolume.
243 * Gets the mount for the @volume.
245 * Returns: a #GMount or %NULL if @volume isn't mounted.
248 g_volume_get_mount (GVolume *volume)
252 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
254 iface = G_VOLUME_GET_IFACE (volume);
256 return (* iface->get_mount) (volume);
261 * g_volume_can_mount:
262 * @volume: a #GVolume.
264 * Checks if a volume can be mounted.
266 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise.
269 g_volume_can_mount (GVolume *volume)
273 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
275 iface = G_VOLUME_GET_IFACE (volume);
277 if (iface->can_mount == NULL)
280 return (* iface->can_mount) (volume);
284 * g_volume_can_eject:
285 * @volume: a #GVolume.
287 * Checks if a volume can be ejected.
289 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise.
292 g_volume_can_eject (GVolume *volume)
296 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
298 iface = G_VOLUME_GET_IFACE (volume);
300 if (iface->can_eject == NULL)
303 return (* iface->can_eject) (volume);
307 * g_volume_should_automount:
308 * @volume: a #GVolume
310 * Returns whether the volume should be automatically mounted.
312 * Returns: %TRUE if the volume should be automatically mounted.
315 g_volume_should_automount (GVolume *volume)
319 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
321 iface = G_VOLUME_GET_IFACE (volume);
323 if (iface->should_automount == NULL)
326 return (* iface->should_automount) (volume);
332 * @volume: a #GVolume.
333 * @flags: flags affecting the operation
334 * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
335 * @cancellable: optional #GCancellable object, %NULL to ignore.
336 * @callback: a #GAsyncReadyCallback, or %NULL.
337 * @user_data: a #gpointer.
342 g_volume_mount (GVolume *volume,
343 GMountMountFlags flags,
344 GMountOperation *mount_operation,
345 GCancellable *cancellable,
346 GAsyncReadyCallback callback,
351 g_return_if_fail (G_IS_VOLUME (volume));
353 iface = G_VOLUME_GET_IFACE (volume);
355 if (iface->mount_fn == NULL)
357 g_simple_async_report_error_in_idle (G_OBJECT (volume), callback, user_data,
358 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
359 _("volume doesn't implement mount"));
364 (* iface->mount_fn) (volume, flags, mount_operation, cancellable, callback, user_data);
368 * g_volume_mount_finish:
369 * @volume: pointer to a #GVolume.
370 * @result: a #GAsyncResult.
373 * Finishes mounting a volume.
375 * Returns: %TRUE, %FALSE if operation failed.
378 g_volume_mount_finish (GVolume *volume,
379 GAsyncResult *result,
384 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
385 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
387 if (G_IS_SIMPLE_ASYNC_RESULT (result))
389 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
390 if (g_simple_async_result_propagate_error (simple, error))
394 iface = G_VOLUME_GET_IFACE (volume);
395 return (* iface->mount_finish) (volume, result, error);
400 * @volume: a #GVolume.
401 * @flags: flags affecting the unmount if required for eject
402 * @cancellable: optional #GCancellable object, %NULL to ignore.
403 * @callback: a #GAsyncReadyCallback, or %NULL.
404 * @user_data: a #gpointer.
409 g_volume_eject (GVolume *volume,
410 GMountUnmountFlags flags,
411 GCancellable *cancellable,
412 GAsyncReadyCallback callback,
417 g_return_if_fail (G_IS_VOLUME (volume));
419 iface = G_VOLUME_GET_IFACE (volume);
421 if (iface->eject == NULL)
423 g_simple_async_report_error_in_idle (G_OBJECT (volume), callback, user_data,
424 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
425 _("volume doesn't implement eject"));
430 (* iface->eject) (volume, flags, cancellable, callback, user_data);
434 * g_volume_eject_finish:
435 * @volume: pointer to a #GVolume.
436 * @result: a #GAsyncResult.
439 * Finishes ejecting a volume.
441 * Returns: %TRUE, %FALSE if operation failed.
444 g_volume_eject_finish (GVolume *volume,
445 GAsyncResult *result,
450 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
451 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
453 if (G_IS_SIMPLE_ASYNC_RESULT (result))
455 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
456 if (g_simple_async_result_propagate_error (simple, error))
460 iface = G_VOLUME_GET_IFACE (volume);
461 return (* iface->eject_finish) (volume, result, error);
465 * g_volume_get_identifier:
466 * @volume: a #GVolume
467 * @kind: the kind of identifier to return
469 * Gets the identifier of the given kind for @volume.
470 * See the <link linkend="volume-identifier">introduction</link>
471 * for more information about volume identifiers.
473 * Returns: a newly allocated string containing the
474 * requested identfier, or %NULL if the #GVolume
475 * doesn't have this kind of identifier
478 g_volume_get_identifier (GVolume *volume,
483 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
484 g_return_val_if_fail (kind != NULL, NULL);
486 iface = G_VOLUME_GET_IFACE (volume);
488 if (iface->get_identifier == NULL)
491 return (* iface->get_identifier) (volume, kind);
495 * g_volume_enumerate_identifiers:
496 * @volume: a #GVolume
498 * Gets the kinds of <link linkend="volume-identifier">identifiers</link>
499 * that @volume has. Use g_volume_get_identifer() to obtain
500 * the identifiers themselves.
502 * Returns: a %NULL-terminated array of strings containing
503 * kinds of identifiers. Use g_strfreev() to free.
506 g_volume_enumerate_identifiers (GVolume *volume)
510 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
511 iface = G_VOLUME_GET_IFACE (volume);
513 if (iface->enumerate_identifiers == NULL)
516 return (* iface->enumerate_identifiers) (volume);
520 #define __G_VOLUME_C__
521 #include "gioaliasdef.c"