* David Zeuthen <davidz@redhat.com>
*/
-#include <config.h>
+#include "config.h"
#include "gmount.h"
#include "gvolume.h"
+#include "gasyncresult.h"
#include "gsimpleasyncresult.h"
+#include "gioerror.h"
#include "glibintl.h"
#include "gioalias.h"
/**
* SECTION:gvolume
* @short_description: Volume management
- * @include: gio.h
+ * @include: gio/gio.h
*
* The #GVolume interface represents user-visible objects that can be
* mounted. Note, when porting from GnomeVFS, #GVolume is the moral
* is called, then it will be filled with any error information.
*
* <para id="volume-identifier">
- * It is sometimes necessary to directly access the underlying
+ * It is sometimes necessary to directly access the underlying
* operating system object behind a volume (e.g. for passing a volume
* to an application via the commandline). For this purpose, GIO
* allows to obtain an 'identifier' for the volume. There can be
* different kinds of identifiers, such as Hal UDIs, filesystem labels,
* traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
* uuids. GIO uses predefind strings as names for the different kinds
- * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
- * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
+ * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
+ * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
* to obtain an identifier for a volume.
* </para>
- **/
+ *
+ * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
+ * when the gvfs hal volume monitor is in use. Other volume monitors
+ * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
+ * identifier, which can be used to obtain a hal device by means of
+ * libhal_manger_find_device_string_match().
+ */
static void g_volume_base_init (gpointer g_class);
static void g_volume_class_init (gpointer g_class,
GType
g_volume_get_type (void)
{
- static GType volume_type = 0;
+ static volatile gsize g_define_type_id__volatile = 0;
- if (! volume_type)
+ if (g_once_init_enter (&g_define_type_id__volatile))
{
- static const GTypeInfo volume_info =
+ const GTypeInfo volume_info =
{
sizeof (GVolumeIface), /* class_size */
g_volume_base_init, /* base_init */
0, /* n_preallocs */
NULL
};
-
- volume_type =
+ GType g_define_type_id =
g_type_register_static (G_TYPE_INTERFACE, I_("GVolume"),
&volume_info, 0);
- g_type_interface_add_prerequisite (volume_type, G_TYPE_OBJECT);
+ g_type_interface_add_prerequisite (g_define_type_id, G_TYPE_OBJECT);
+
+ g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
}
- return volume_type;
+ return g_define_type_id__volatile;
}
static void
* Gets the name of @volume.
*
* Returns: the name for the given @volume. The returned string should
- * be freed when no longer needed.
+ * be freed with g_free() when no longer needed.
**/
char *
g_volume_get_name (GVolume *volume)
* Gets the icon for @volume.
*
* Returns: a #GIcon.
+ * The returned object should be unreffed with g_object_unref()
+ * when no longer needed.
**/
GIcon *
g_volume_get_icon (GVolume *volume)
* available.
*
* Returns: the UUID for @volume or %NULL if no UUID can be computed.
+ * The returned string should be freed with g_free()
+ * when no longer needed.
**/
char *
g_volume_get_uuid (GVolume *volume)
* Gets the drive for the @volume.
*
* Returns: a #GDrive or %NULL if @volume is not associated with a drive.
+ * The returned object should be unreffed with g_object_unref()
+ * when no longer needed.
**/
GDrive *
g_volume_get_drive (GVolume *volume)
* Gets the mount for the @volume.
*
* Returns: a #GMount or %NULL if @volume isn't mounted.
+ * The returned object should be unreffed with g_object_unref()
+ * when no longer needed.
**/
GMount *
g_volume_get_mount (GVolume *volume)
/**
* g_volume_mount:
* @volume: a #GVolume.
+ * @flags: flags affecting the operation
* @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback, or %NULL.
- * @user_data: a #gpointer.
+ * @user_data: user data that gets passed to @callback
*
- * Mounts a volume.
+ * Mounts a volume. This is an asynchronous operation, and is
+ * finished by calling g_volume_mount_finish() with the @volume
+ * and #GAsyncResult returned in the @callback.
**/
void
-g_volume_mount (GVolume *volume,
+g_volume_mount (GVolume *volume,
+ GMountMountFlags flags,
GMountOperation *mount_operation,
GCancellable *cancellable,
GAsyncReadyCallback callback,
return;
}
- (* iface->mount_fn) (volume, mount_operation, cancellable, callback, user_data);
+ (* iface->mount_fn) (volume, flags, mount_operation, cancellable, callback, user_data);
}
/**
* g_volume_mount_finish:
- * @volume: pointer to a #GVolume.
- * @result: a #GAsyncResult.
- * @error: a #GError.
+ * @volume: a #GVolume
+ * @result: a #GAsyncResult
+ * @error: a #GError location to store an error, or %NULL to ignore
*
- * Finishes mounting a volume.
+ * Finishes mounting a volume. If any errors occured during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
+ *
+ * If the mount operation succeeded, g_volume_get_mount() on @volume
+ * is guaranteed to return the mount right after calling this
+ * function; there's no need to listen for the 'mount-added' signal on
+ * #GVolumeMonitor.
*
* Returns: %TRUE, %FALSE if operation failed.
**/
gboolean
-g_volume_mount_finish (GVolume *volume,
- GAsyncResult *result,
- GError **error)
+g_volume_mount_finish (GVolume *volume,
+ GAsyncResult *result,
+ GError **error)
{
GVolumeIface *iface;
* @flags: flags affecting the unmount if required for eject
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback, or %NULL.
- * @user_data: a #gpointer.
+ * @user_data: user data that gets passed to @callback
*
- * Ejects a volume.
+ * Ejects a volume. This is an asynchronous operation, and is
+ * finished by calling g_volume_eject_finish() with the @volume
+ * and #GAsyncResult returned in the @callback.
**/
void
-g_volume_eject (GVolume *volume,
+g_volume_eject (GVolume *volume,
GMountUnmountFlags flags,
GCancellable *cancellable,
GAsyncReadyCallback callback,
* g_volume_eject_finish:
* @volume: pointer to a #GVolume.
* @result: a #GAsyncResult.
- * @error: a #GError.
+ * @error: a #GError location to store an error, or %NULL to ignore
*
- * Finishes ejecting a volume.
+ * Finishes ejecting a volume. If any errors occured during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
* Returns: %TRUE, %FALSE if operation failed.
**/
gboolean
-g_volume_eject_finish (GVolume *volume,
- GAsyncResult *result,
- GError **error)
+g_volume_eject_finish (GVolume *volume,
+ GAsyncResult *result,
+ GError **error)
{
GVolumeIface *iface;
return (* iface->enumerate_identifiers) (volume);
}
+/**
+ * g_volume_get_activation_root:
+ * @volume: a #GVolume
+ *
+ * Gets the activation root for a #GVolume if it is known ahead of
+ * mount time. Returns %NULL otherwise. If not %NULL and if @volume
+ * is mounted, then the result of g_mount_get_root() on the
+ * #GMount object obtained from g_volume_get_mount() will always
+ * either be equal or a prefix of what this function returns. In
+ * other words, in code
+ *
+ * <programlisting>
+ * GMount *mount;
+ * GFile *mount_root
+ * GFile *volume_activation_root;
+ *
+ * mount = g_volume_get_mount (volume); /* mounted, so never NULL */
+ * mount_root = g_mount_get_root (mount);
+ * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */
+ * </programlisting>
+ *
+ * then the expression
+ *
+ * <programlisting>
+ * (g_file_has_prefix (volume_activation_root, mount_root) ||
+ g_file_equal (volume_activation_root, mount_root))
+ * </programlisting>
+ *
+ * will always be %TRUE.
+ *
+ * Activation roots are typically used in #GVolumeMonitor
+ * implementations to find the underlying mount to shadow, see
+ * g_mount_is_shadowed() for more details.
+ *
+ * Returns: the activation root of @volume or %NULL. Use
+ * g_object_unref() to free.
+ *
+ * Since: 2.18
+ **/
+GFile *
+g_volume_get_activation_root (GVolume *volume)
+{
+ GVolumeIface *iface;
+
+ g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
+ iface = G_VOLUME_GET_IFACE (volume);
+
+ if (iface->get_activation_root == NULL)
+ return NULL;
+
+ return (* iface->get_activation_root) (volume);
+}
+
+
#define __G_VOLUME_C__
#include "gioaliasdef.c"
projects / platform / upstream / glib.git / blobdiff