gio/gvolume.c

   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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Author: Alexander Larsson <alexl@redhat.com>
  21  *         David Zeuthen <davidz@redhat.com>
  22  */
  23
  24 #include <config.h>
  25 #include "gmount.h"
  26 #include "gvolume.h"
  27 #include "gsimpleasyncresult.h"
  28 #include "glibintl.h"
  29
  30 #include "gioalias.h"
  31
  32 /**
  33  * SECTION:gvolume
  34  * @short_description: Volume management
  35  * @include: 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 #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.
  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  * <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.
  71  * </para>
  72  **/
  73
  74 static void g_volume_base_init (gpointer g_class);
  75 static void g_volume_class_init (gpointer g_class,
  76                                  gpointer class_data);
  77
  78 GType
  79 g_volume_get_type (void)
  80 {
  81   static GType volume_type = 0;
  82
  83   if (! volume_type)
  84     {
  85       static const GTypeInfo volume_info =
  86       {
  87         sizeof (GVolumeIface), /* class_size */
  88         g_volume_base_init,   /* base_init */
  89         NULL,           /* base_finalize */
  90         g_volume_class_init,
  91         NULL,           /* class_finalize */
  92         NULL,           /* class_data */
  93         0,
  94         0,              /* n_preallocs */
  95         NULL
  96       };
  97
  98       volume_type =
  99         g_type_register_static (G_TYPE_INTERFACE, I_("GVolume"),
 100                                 &volume_info, 0);
 101
 102       g_type_interface_add_prerequisite (volume_type, G_TYPE_OBJECT);
 103     }
 104
 105   return volume_type;
 106 }
 107
 108 static void
 109 g_volume_class_init (gpointer g_class,
 110                      gpointer class_data)
 111 {
 112 }
 113
 114 static void
 115 g_volume_base_init (gpointer g_class)
 116 {
 117   static gboolean initialized = FALSE;
 118
 119   if (! initialized)
 120     {
 121      /**
 122       * GVolume::changed:
 123       *
 124       * Emitted when the volume has been changed.
 125       **/
 126       g_signal_new (I_("changed"),
 127                     G_TYPE_VOLUME,
 128                     G_SIGNAL_RUN_LAST,
 129                     G_STRUCT_OFFSET (GVolumeIface, changed),
 130                     NULL, NULL,
 131                     g_cclosure_marshal_VOID__VOID,
 132                     G_TYPE_NONE, 0);
 133
 134      /**
 135       * GVolume::removed:
 136       *
 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.
 140       **/
 141       g_signal_new (I_("removed"),
 142                     G_TYPE_VOLUME,
 143                     G_SIGNAL_RUN_LAST,
 144                     G_STRUCT_OFFSET (GVolumeIface, removed),
 145                     NULL, NULL,
 146                     g_cclosure_marshal_VOID__VOID,
 147                     G_TYPE_NONE, 0);
 148
 149       initialized = TRUE;
 150     }
 151 }
 152
 153 /**
 154  * g_volume_get_name:
 155  * @volume: a #GVolume.
 156  *
 157  * Gets the name of @volume.
 158  *
 159  * Returns: the name for the given @volume. The returned string should
 160  * be freed when no longer needed.
 161  **/
 162 char *
 163 g_volume_get_name (GVolume *volume)
 164 {
 165   GVolumeIface *iface;
 166
 167   g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
 168
 169   iface = G_VOLUME_GET_IFACE (volume);
 170
 171   return (* iface->get_name) (volume);
 172 }
 173
 174 /**
 175  * g_volume_get_icon:
 176  * @volume: a #GVolume.
 177  *
 178  * Gets the icon for @volume.
 179  *
 180  * Returns: a #GIcon.
 181  **/
 182 GIcon *
 183 g_volume_get_icon (GVolume *volume)
 184 {
 185   GVolumeIface *iface;
 186
 187   g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
 188
 189   iface = G_VOLUME_GET_IFACE (volume);
 190
 191   return (* iface->get_icon) (volume);
 192 }
 193
 194 /**
 195  * g_volume_get_uuid:
 196  * @volume: a #GVolume.
 197  *
 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
 201  * available.
 202  *
 203  * Returns: the UUID for @volume or %NULL if no UUID can be computed.
 204  **/
 205 char *
 206 g_volume_get_uuid (GVolume *volume)
 207 {
 208   GVolumeIface *iface;
 209
 210   g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
 211
 212   iface = G_VOLUME_GET_IFACE (volume);
 213
 214   return (* iface->get_uuid) (volume);
 215 }
 216
 217 /**
 218  * g_volume_get_drive:
 219  * @volume: a #GVolume.
 220  *
 221  * Gets the drive for the @volume.
 222  *
 223  * Returns: a #GDrive or %NULL if @volume is not associated with a drive.
 224  **/
 225 GDrive *
 226 g_volume_get_drive (GVolume *volume)
 227 {
 228   GVolumeIface *iface;
 229
 230   g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
 231
 232   iface = G_VOLUME_GET_IFACE (volume);
 233
 234   return (* iface->get_drive) (volume);
 235 }
 236
 237 /**
 238  * g_volume_get_mount:
 239  * @volume: a #GVolume.
 240  *
 241  * Gets the mount for the @volume.
 242  *
 243  * Returns: a #GMount or %NULL if @volume isn't mounted.
 244  **/
 245 GMount *
 246 g_volume_get_mount (GVolume *volume)
 247 {
 248   GVolumeIface *iface;
 249
 250   g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
 251
 252   iface = G_VOLUME_GET_IFACE (volume);
 253
 254   return (* iface->get_mount) (volume);
 255 }
 256
 257
 258 /**
 259  * g_volume_can_mount:
 260  * @volume: a #GVolume.
 261  *
 262  * Checks if a volume can be mounted.
 263  *
 264  * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise.
 265  **/
 266 gboolean
 267 g_volume_can_mount (GVolume *volume)
 268 {
 269   GVolumeIface *iface;
 270
 271   g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
 272
 273   iface = G_VOLUME_GET_IFACE (volume);
 274
 275   if (iface->can_mount == NULL)
 276     return FALSE;
 277
 278   return (* iface->can_mount) (volume);
 279 }
 280
 281 /**
 282  * g_volume_can_eject:
 283  * @volume: a #GVolume.
 284  *
 285  * Checks if a volume can be ejected.
 286  *
 287  * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise.
 288  **/
 289 gboolean
 290 g_volume_can_eject (GVolume *volume)
 291 {
 292   GVolumeIface *iface;
 293
 294   g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
 295
 296   iface = G_VOLUME_GET_IFACE (volume);
 297
 298   if (iface->can_eject == NULL)
 299     return FALSE;
 300
 301   return (* iface->can_eject) (volume);
 302 }
 303
 304 /**
 305  * g_volume_should_automount:
 306  * @volume: a #GVolume
 307  *
 308  * Returns whether the volume should be automatically mounted.
 309  *
 310  * Returns: %TRUE if the volume should be automatically mounted.
 311  */
 312 gboolean
 313 g_volume_should_automount (GVolume *volume)
 314 {
 315   GVolumeIface *iface;
 316
 317   g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
 318
 319   iface = G_VOLUME_GET_IFACE (volume);
 320
 321   if (iface->should_automount == NULL)
 322     return FALSE;
 323
 324   return (* iface->should_automount) (volume);
 325 }
 326
 327
 328 /**
 329  * g_volume_mount:
 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.
 335  *
 336  * Mounts a volume.
 337  **/
 338 void
 339 g_volume_mount (GVolume    *volume,
 340                 GMountOperation     *mount_operation,
 341                 GCancellable        *cancellable,
 342                 GAsyncReadyCallback  callback,
 343                 gpointer             user_data)
 344 {
 345   GVolumeIface *iface;
 346
 347   g_return_if_fail (G_IS_VOLUME (volume));
 348
 349   iface = G_VOLUME_GET_IFACE (volume);
 350
 351   if (iface->mount_fn == NULL)
 352     {
 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"));
 356
 357       return;
 358     }
 359
 360   (* iface->mount_fn) (volume, mount_operation, cancellable, callback, user_data);
 361 }
 362
 363 /**
 364  * g_volume_mount_finish:
 365  * @volume: pointer to a #GVolume.
 366  * @result: a #GAsyncResult.
 367  * @error: a #GError.
 368  *
 369  * Finishes mounting a volume.
 370  *
 371  * Returns: %TRUE, %FALSE if operation failed.
 372  **/
 373 gboolean
 374 g_volume_mount_finish (GVolume  *volume,
 375                        GAsyncResult      *result,
 376                        GError           **error)
 377 {
 378   GVolumeIface *iface;
 379
 380   g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
 381   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
 382
 383   if (G_IS_SIMPLE_ASYNC_RESULT (result))
 384     {
 385       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
 386       if (g_simple_async_result_propagate_error (simple, error))
 387         return FALSE;
 388     }
 389
 390   iface = G_VOLUME_GET_IFACE (volume);
 391   return (* iface->mount_finish) (volume, result, error);
 392 }
 393
 394 /**
 395  * g_volume_eject:
 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.
 401  *
 402  * Ejects a volume.
 403  **/
 404 void
 405 g_volume_eject (GVolume    *volume,
 406                 GMountUnmountFlags   flags,
 407                 GCancellable        *cancellable,
 408                 GAsyncReadyCallback  callback,
 409                 gpointer             user_data)
 410 {
 411   GVolumeIface *iface;
 412
 413   g_return_if_fail (G_IS_VOLUME (volume));
 414
 415   iface = G_VOLUME_GET_IFACE (volume);
 416
 417   if (iface->eject == NULL)
 418     {
 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"));
 422
 423       return;
 424     }
 425
 426   (* iface->eject) (volume, flags, cancellable, callback, user_data);
 427 }
 428
 429 /**
 430  * g_volume_eject_finish:
 431  * @volume: pointer to a #GVolume.
 432  * @result: a #GAsyncResult.
 433  * @error: a #GError.
 434  *
 435  * Finishes ejecting a volume.
 436  *
 437  * Returns: %TRUE, %FALSE if operation failed.
 438  **/
 439 gboolean
 440 g_volume_eject_finish (GVolume  *volume,
 441                        GAsyncResult      *result,
 442                        GError           **error)
 443 {
 444   GVolumeIface *iface;
 445
 446   g_return_val_if_fail (G_IS_VOLUME (volume), FALSE);
 447   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
 448
 449   if (G_IS_SIMPLE_ASYNC_RESULT (result))
 450     {
 451       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
 452       if (g_simple_async_result_propagate_error (simple, error))
 453         return FALSE;
 454     }
 455
 456   iface = G_VOLUME_GET_IFACE (volume);
 457   return (* iface->eject_finish) (volume, result, error);
 458 }
 459
 460 /**
 461  * g_volume_get_identifier:
 462  * @volume: a #GVolume
 463  * @kind: the kind of identifier to return
 464  *
 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.
 468  *
 469  * Returns: a newly allocated string containing the
 470  *   requested identfier, or %NULL if the #GVolume
 471  *   doesn't have this kind of identifier
 472  */
 473 char *
 474 g_volume_get_identifier (GVolume    *volume,
 475                          const char *kind)
 476 {
 477   GVolumeIface *iface;
 478
 479   g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
 480   g_return_val_if_fail (kind != NULL, NULL);
 481
 482   iface = G_VOLUME_GET_IFACE (volume);
 483
 484   if (iface->get_identifier == NULL)
 485     return NULL;
 486
 487   return (* iface->get_identifier) (volume, kind);
 488 }
 489
 490 /**
 491  * g_volume_enumerate_identifiers:
 492  * @volume: a #GVolume
 493  *
 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.
 497  *
 498  * Returns: a %NULL-terminated array of strings containing
 499  *   kinds of identifiers. Use g_strfreev() to free.
 500  */
 501 char **
 502 g_volume_enumerate_identifiers (GVolume *volume)
 503 {
 504   GVolumeIface *iface;
 505
 506   g_return_val_if_fail (G_IS_VOLUME (volume), NULL);
 507   iface = G_VOLUME_GET_IFACE (volume);
 508
 509   if (iface->enumerate_identifiers == NULL)
 510     return NULL;
 511
 512   return (* iface->enumerate_identifiers) (volume);
 513 }
 514
 515
 516 #define __G_VOLUME_C__
 517 #include "gioaliasdef.c"