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.
61 static void g_volume_base_init (gpointer g_class);
62 static void g_volume_class_init (gpointer g_class,
66 g_volume_get_type (void)
68 static GType volume_type = 0;
72 static const GTypeInfo volume_info =
74 sizeof (GVolumeIface), /* class_size */
75 g_volume_base_init, /* base_init */
76 NULL, /* base_finalize */
78 NULL, /* class_finalize */
79 NULL, /* class_data */
86 g_type_register_static (G_TYPE_INTERFACE, I_("GVolume"),
89 g_type_interface_add_prerequisite (volume_type, G_TYPE_OBJECT);
96 g_volume_class_init (gpointer g_class,
102 g_volume_base_init (gpointer g_class)
104 static gboolean initialized = FALSE;
111 * Emitted when the volume has been changed.
113 g_signal_new (I_("changed"),
116 G_STRUCT_OFFSET (GVolumeIface, changed),
118 g_cclosure_marshal_VOID__VOID,
124 * This signal is emitted when the #GVolume have been removed. If
125 * the recipient is holding references to the object they should
126 * release them so the object can be finalized.
128 g_signal_new (I_("removed"),
131 G_STRUCT_OFFSET (GVolumeIface, removed),
133 g_cclosure_marshal_VOID__VOID,
142 * @volume: a #GVolume.
144 * Gets the name of @volume.
146 * Returns: the name for the given @volume. The returned string should
147 * be freed when no longer needed.
150 g_volume_get_name (GVolume *volume)
154 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
156 iface = G_VOLUME_GET_IFACE (volume);
158 return (* iface->get_name) (volume);
163 * @volume: a #GVolume.
165 * Gets the icon for @volume.
170 g_volume_get_icon (GVolume *volume)
174 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
176 iface = G_VOLUME_GET_IFACE (volume);
178 return (* iface->get_icon) (volume);
183 * @volume: a #GVolume.
185 * Gets the UUID for the @volume. The reference is typically based on
186 * the file system UUID for the volume in question and should be
187 * considered an opaque string. Returns %NULL if there is no UUID
190 * Returns: the UUID for @volume or %NULL if no UUID can be computed.
193 g_volume_get_uuid (GVolume *volume)
197 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
199 iface = G_VOLUME_GET_IFACE (volume);
201 return (* iface->get_uuid) (volume);
205 * g_volume_get_drive:
206 * @volume: a #GVolume.
208 * Gets the drive for the @volume.
210 * Returns: a #GDrive or %NULL if @volume is not associated with a drive.
213 g_volume_get_drive (GVolume *volume)
217 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
219 iface = G_VOLUME_GET_IFACE (volume);
221 return (* iface->get_drive) (volume);
225 * g_volume_get_mount:
226 * @volume: a #GVolume.
228 * Gets the mount for the @volume.
230 * Returns: a #GMount or %NULL if @volume isn't mounted.
233 g_volume_get_mount (GVolume *volume)
237 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
239 iface = G_VOLUME_GET_IFACE (volume);
241 return (* iface->get_mount) (volume);
246 * g_volume_can_mount:
247 * @volume: a #GVolume.
249 * Checks if a volume can be mounted.
251 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise.
254 g_volume_can_mount (GVolume *volume)
258 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
260 iface = G_VOLUME_GET_IFACE (volume);
262 if (iface->can_mount == NULL)
265 return (* iface->can_mount) (volume);
269 * g_volume_can_eject:
270 * @volume: a #GVolume.
272 * Checks if a volume can be ejected.
274 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise.
277 g_volume_can_eject (GVolume *volume)
281 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
283 iface = G_VOLUME_GET_IFACE (volume);
285 if (iface->can_eject == NULL)
288 return (* iface->can_eject) (volume);
293 * @volume: a #GVolume.
294 * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
295 * @cancellable: optional #GCancellable object, %NULL to ignore.
296 * @callback: a #GAsyncReadyCallback, or %NULL.
297 * @user_data: a #gpointer.
302 g_volume_mount (GVolume *volume,
303 GMountOperation *mount_operation,
304 GCancellable *cancellable,
305 GAsyncReadyCallback callback,
310 g_return_if_fail (G_IS_VOLUME (volume));
312 iface = G_VOLUME_GET_IFACE (volume);
314 if (iface->mount_fn == NULL)
316 g_simple_async_report_error_in_idle (G_OBJECT (volume), callback, user_data,
317 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
318 _("volume doesn't implement mount"));
323 (* iface->mount_fn) (volume, mount_operation, cancellable, callback, user_data);
327 * g_volume_mount_finish:
328 * @volume: pointer to a #GVolume.
329 * @result: a #GAsyncResult.
332 * Finishes mounting a volume.
334 * Returns: %TRUE, %FALSE if operation failed.
337 g_volume_mount_finish (GVolume *volume,
338 GAsyncResult *result,
343 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
344 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
346 if (G_IS_SIMPLE_ASYNC_RESULT (result))
348 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
349 if (g_simple_async_result_propagate_error (simple, error))
353 iface = G_VOLUME_GET_IFACE (volume);
354 return (* iface->mount_finish) (volume, result, error);
359 * @volume: a #GVolume.
360 * @flags: flags affecting the unmount if required for eject
361 * @cancellable: optional #GCancellable object, %NULL to ignore.
362 * @callback: a #GAsyncReadyCallback, or %NULL.
363 * @user_data: a #gpointer.
368 g_volume_eject (GVolume *volume,
369 GMountUnmountFlags flags,
370 GCancellable *cancellable,
371 GAsyncReadyCallback callback,
376 g_return_if_fail (G_IS_VOLUME (volume));
378 iface = G_VOLUME_GET_IFACE (volume);
380 if (iface->eject == NULL)
382 g_simple_async_report_error_in_idle (G_OBJECT (volume), callback, user_data,
383 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
384 _("volume doesn't implement eject"));
389 (* iface->eject) (volume, flags, cancellable, callback, user_data);
393 * g_volume_eject_finish:
394 * @volume: pointer to a #GVolume.
395 * @result: a #GAsyncResult.
398 * Finishes ejecting a volume.
400 * Returns: %TRUE, %FALSE if operation failed.
403 g_volume_eject_finish (GVolume *volume,
404 GAsyncResult *result,
409 g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
410 g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
412 if (G_IS_SIMPLE_ASYNC_RESULT (result))
414 GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
415 if (g_simple_async_result_propagate_error (simple, error))
419 iface = G_VOLUME_GET_IFACE (volume);
420 return (* iface->eject_finish) (volume, result, error);
424 * g_volume_get_identifier:
425 * @volume: a #GVolume
426 * @kind: the kind of identifier to return
428 * Gets the identifier of the given kind for @volume.
430 * Returns: a newly allocated string containing the
431 * requested identfier, or %NULL if the #GVolume
432 * doesn't have this kind of identifier
435 g_volume_get_identifier (GVolume *volume,
440 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
441 g_return_val_if_fail (kind != NULL, NULL);
443 iface = G_VOLUME_GET_IFACE (volume);
445 if (iface->get_identifier == NULL)
448 return (* iface->get_identifier) (volume, kind);
452 * g_volume_enumerate_identifiers:
453 * @volume: a #GVolume
455 * Gets the kinds of identifiers that @volume has.
456 * Use g_volume_get_identifer() to obtain the identifiers
459 * Returns: a %NULL-terminated array of strings containing
460 * kinds of identifiers. Use g_strfreev() to free.
463 g_volume_enumerate_identifiers (GVolume *volume)
467 g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
468 iface = G_VOLUME_GET_IFACE (volume);
470 if (iface->enumerate_identifiers == NULL)
473 return (* iface->enumerate_identifiers) (volume);
477 #define __G_VOLUME_C__
478 #include "gioaliasdef.c"