gio/gmount.c

   1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
   2
   3 /* GIO - GLib Input, Output and Streaming Library
   4  *
   5  * Copyright (C) 2006-2007 Red Hat, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General
  18  * Public License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  *
  22  * Author: Alexander Larsson <alexl@redhat.com>
  23  *         David Zeuthen <davidz@redhat.com>
  24  */
  25
  26 #include "config.h"
  27
  28 #include <string.h>
  29
  30 #include "gmount.h"
  31 #include "gmountprivate.h"
  32 #include "gsimpleasyncresult.h"
  33 #include "glibintl.h"
  34
  35 #include "gioalias.h"
  36
  37 /**
  38  * SECTION:gmount
  39  * @short_description: Mount management
  40  * @include: gio/gio.h
  41  * @see also: GVolume, GUnixMount
  42  *
  43  * The #GMount interface represents user-visible mounts. Note, when
  44  * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
  45  *
  46  * #GMount is a "mounted" filesystem that you can access. Mounted is in
  47  * quotes because it's not the same as a unix mount, it might be a gvfs
  48  * mount, but you can still access the files on it if you use GIO. Might or
  49  * might not be related to a volume object.
  50  *
  51  * Unmounting a #GMount instance is an asynchronous operation. For
  52  * more information about asynchronous operations, see #GAsyncReady
  53  * and #GSimpleAsyncReady. To unmount a #GMount instance, first call
  54  * g_mount_unmount() with (at least) the #GMount instance and a
  55  * #GAsyncReadyCallback.  The callback will be fired when the
  56  * operation has resolved (either with success or failure), and a
  57  * #GAsyncReady structure will be passed to the callback.  That
  58  * callback should then call g_mount_unmount_finish() with the #GMount
  59  * and the #GAsyncReady data to see if the operation was completed
  60  * successfully.  If an @error is present when g_mount_unmount_finish()
  61  * is called, then it will be filled with any error information.
  62  **/
  63
  64 static void g_mount_base_init (gpointer g_class);
  65 static void g_mount_class_init (gpointer g_class,
  66                                 gpointer class_data);
  67
  68 GType
  69 g_mount_get_type (void)
  70 {
  71   static GType mount_type = 0;
  72
  73   if (! mount_type)
  74     {
  75       static const GTypeInfo mount_info =
  76       {
  77         sizeof (GMountIface), /* class_size */
  78         g_mount_base_init,   /* base_init */
  79         NULL,           /* base_finalize */
  80         g_mount_class_init,
  81         NULL,           /* class_finalize */
  82         NULL,           /* class_data */
  83         0,
  84         0,              /* n_preallocs */
  85         NULL
  86       };
  87
  88       mount_type =
  89         g_type_register_static (G_TYPE_INTERFACE, I_("GMount"),
  90                                 &mount_info, 0);
  91
  92       g_type_interface_add_prerequisite (mount_type, G_TYPE_OBJECT);
  93     }
  94
  95   return mount_type;
  96 }
  97
  98 static void
  99 g_mount_class_init (gpointer g_class,
 100                     gpointer class_data)
 101 {
 102 }
 103
 104 static void
 105 g_mount_base_init (gpointer g_class)
 106 {
 107   static gboolean initialized = FALSE;
 108
 109   if (! initialized)
 110     {
 111      /**
 112       * GMount::changed:
 113       *
 114       * Emitted when the mount has been changed.
 115       **/
 116       g_signal_new (I_("changed"),
 117                     G_TYPE_MOUNT,
 118                     G_SIGNAL_RUN_LAST,
 119                     G_STRUCT_OFFSET (GMountIface, changed),
 120                     NULL, NULL,
 121                     g_cclosure_marshal_VOID__VOID,
 122                     G_TYPE_NONE, 0);
 123
 124      /**
 125       * GMount::unmounted:
 126       *
 127       * This signal is emitted when the #GMount have been
 128       * unmounted. If the recipient is holding references to the
 129       * object they should release them so the object can be
 130       * finalized.
 131       **/
 132       g_signal_new (I_("unmounted"),
 133                     G_TYPE_MOUNT,
 134                     G_SIGNAL_RUN_LAST,
 135                     G_STRUCT_OFFSET (GMountIface, unmounted),
 136                     NULL, NULL,
 137                     g_cclosure_marshal_VOID__VOID,
 138                     G_TYPE_NONE, 0);
 139
 140       initialized = TRUE;
 141     }
 142 }
 143
 144 /**
 145  * g_mount_get_root:
 146  * @mount: a #GMount.
 147  *
 148  * Gets the root directory on @mount.
 149  *
 150  * Returns: a #GFile.
 151  **/
 152 GFile *
 153 g_mount_get_root (GMount *mount)
 154 {
 155   GMountIface *iface;
 156
 157   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
 158
 159   iface = G_MOUNT_GET_IFACE (mount);
 160
 161   return (* iface->get_root) (mount);
 162 }
 163
 164 /**
 165  * g_mount_get_name:
 166  * @mount: a #GMount.
 167  *
 168  * Gets the name of @mount.
 169  *
 170  * Returns: the name for the given @mount. The returned string should
 171  * be freed when no longer needed.
 172  **/
 173 char *
 174 g_mount_get_name (GMount *mount)
 175 {
 176   GMountIface *iface;
 177
 178   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
 179
 180   iface = G_MOUNT_GET_IFACE (mount);
 181
 182   return (* iface->get_name) (mount);
 183 }
 184
 185 /**
 186  * g_mount_get_icon:
 187  * @mount: a #GMount.
 188  *
 189  * Gets the icon for @mount.
 190  *
 191  * Returns: a #GIcon.
 192  **/
 193 GIcon *
 194 g_mount_get_icon (GMount *mount)
 195 {
 196   GMountIface *iface;
 197
 198   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
 199
 200   iface = G_MOUNT_GET_IFACE (mount);
 201
 202   return (* iface->get_icon) (mount);
 203 }
 204
 205 /**
 206  * g_mount_get_uuid:
 207  * @mount: a #GMount.
 208  *
 209  * Gets the UUID for the @mount. The reference is typically based on
 210  * the file system UUID for the mount in question and should be
 211  * considered an opaque string. Returns %NULL if there is no UUID
 212  * available.
 213  *
 214  * Returns: the UUID for @mount or %NULL if no UUID can be computed.
 215  **/
 216 char *
 217 g_mount_get_uuid (GMount *mount)
 218 {
 219   GMountIface *iface;
 220
 221   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
 222
 223   iface = G_MOUNT_GET_IFACE (mount);
 224
 225   return (* iface->get_uuid) (mount);
 226 }
 227
 228 /**
 229  * g_mount_get_volume:
 230  * @mount: a #GMount.
 231  *
 232  * Gets the volume for the @mount.
 233  *
 234  * Returns: a #GVolume or %NULL if @mount is not associated with a volume.
 235  **/
 236 GVolume *
 237 g_mount_get_volume (GMount *mount)
 238 {
 239   GMountIface *iface;
 240
 241   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
 242
 243   iface = G_MOUNT_GET_IFACE (mount);
 244
 245   return (* iface->get_volume) (mount);
 246 }
 247
 248 /**
 249  * g_mount_get_drive:
 250  * @mount: a #GMount.
 251  *
 252  * Gets the drive for the @mount.
 253  *
 254  * This is a convenience method for getting the #GVolume and then
 255  * using that object to get the #GDrive.
 256  *
 257  * Returns: a #GDrive or %NULL if @mount is not associated with a volume or a drive.
 258  **/
 259 GDrive *
 260 g_mount_get_drive (GMount *mount)
 261 {
 262   GMountIface *iface;
 263
 264   g_return_val_if_fail (G_IS_MOUNT (mount), NULL);
 265
 266   iface = G_MOUNT_GET_IFACE (mount);
 267
 268   return (* iface->get_drive) (mount);
 269 }
 270
 271 /**
 272  * g_mount_can_unmount:
 273  * @mount: a #GMount.
 274  *
 275  * Checks if @mount can be mounted.
 276  *
 277  * Returns: %TRUE if the @mount can be unmounted.
 278  **/
 279 gboolean
 280 g_mount_can_unmount (GMount *mount)
 281 {
 282   GMountIface *iface;
 283
 284   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
 285
 286   iface = G_MOUNT_GET_IFACE (mount);
 287
 288   return (* iface->can_unmount) (mount);
 289 }
 290
 291 /**
 292  * g_mount_can_eject:
 293  * @mount: a #GMount.
 294  *
 295  * Checks if @mount can be eject.
 296  *
 297  * Returns: %TRUE if the @mount can be ejected.
 298  **/
 299 gboolean
 300 g_mount_can_eject (GMount *mount)
 301 {
 302   GMountIface *iface;
 303
 304   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
 305
 306   iface = G_MOUNT_GET_IFACE (mount);
 307
 308   return (* iface->can_eject) (mount);
 309 }
 310
 311 /**
 312  * g_mount_unmount:
 313  * @mount: a #GMount.
 314  * @flags: flags affecting the operation
 315  * @cancellable: optional #GCancellable object, %NULL to ignore.
 316  * @callback: a #GAsyncReadyCallback, or %NULL.
 317  * @user_data: user data passed to @callback.
 318  *
 319  * Unmounts a mount. This is an asynchronous operation, and is
 320  * finished by calling g_mount_unmount_finish() with the @mount
 321  * and #GAsyncResults data returned in the @callback.
 322  **/
 323 void
 324 g_mount_unmount (GMount *mount,
 325                  GMountUnmountFlags flags,
 326                  GCancellable *cancellable,
 327                  GAsyncReadyCallback callback,
 328                  gpointer user_data)
 329 {
 330   GMountIface *iface;
 331
 332   g_return_if_fail (G_IS_MOUNT (mount));
 333
 334   iface = G_MOUNT_GET_IFACE (mount);
 335
 336   if (iface->unmount == NULL)
 337     {
 338       g_simple_async_report_error_in_idle (G_OBJECT (mount),
 339                                            callback, user_data,
 340                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
 341                                            /* Translators: This is an error
 342                                             * message for mount objects that
 343                                             * don't implement unmount. */
 344                                            _("mount doesn't implement unmount"));
 345
 346       return;
 347     }
 348
 349   (* iface->unmount) (mount, flags, cancellable, callback, user_data);
 350 }
 351
 352 /**
 353  * g_mount_unmount_finish:
 354  * @mount: a #GMount.
 355  * @result: a #GAsyncResult.
 356  * @error: a #GError location to store the error occuring, or %NULL to
 357  * ignore.
 358  *
 359  * Finishes unmounting a mount. If any errors occurred during the operation,
 360  * @error will be set to contain the errors and %FALSE will be returned.
 361  *
 362  * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
 363  **/
 364 gboolean
 365 g_mount_unmount_finish (GMount       *mount,
 366                         GAsyncResult  *result,
 367                         GError       **error)
 368 {
 369   GMountIface *iface;
 370
 371   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
 372   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
 373
 374   if (G_IS_SIMPLE_ASYNC_RESULT (result))
 375     {
 376       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
 377       if (g_simple_async_result_propagate_error (simple, error))
 378         return FALSE;
 379     }
 380
 381   iface = G_MOUNT_GET_IFACE (mount);
 382   return (* iface->unmount_finish) (mount, result, error);
 383 }
 384
 385
 386 /**
 387  * g_mount_eject:
 388  * @mount: a #GMount.
 389  * @flags: flags affecting the unmount if required for eject
 390  * @cancellable: optional #GCancellable object, %NULL to ignore.
 391  * @callback: a #GAsyncReadyCallback, or %NULL.
 392  * @user_data: user data passed to @callback.
 393  *
 394  * Ejects a mount. This is an asynchronous operation, and is
 395  * finished by calling g_mount_eject_finish() with the @mount
 396  * and #GAsyncResults data returned in the @callback.
 397  **/
 398 void
 399 g_mount_eject (GMount *mount,
 400                GMountUnmountFlags flags,
 401                GCancellable *cancellable,
 402                GAsyncReadyCallback callback,
 403                gpointer user_data)
 404 {
 405   GMountIface *iface;
 406
 407   g_return_if_fail (G_IS_MOUNT (mount));
 408
 409   iface = G_MOUNT_GET_IFACE (mount);
 410
 411   if (iface->eject == NULL)
 412     {
 413       g_simple_async_report_error_in_idle (G_OBJECT (mount),
 414                                            callback, user_data,
 415                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
 416                                            /* Translators: This is an error
 417                                             * message for mount objects that
 418                                             * don't implement eject. */
 419                                            _("mount doesn't implement eject"));
 420
 421       return;
 422     }
 423
 424   (* iface->eject) (mount, flags, cancellable, callback, user_data);
 425 }
 426
 427 /**
 428  * g_mount_eject_finish:
 429  * @mount: a #GMount.
 430  * @result: a #GAsyncResult.
 431  * @error: a #GError location to store the error occuring, or %NULL to
 432  * ignore.
 433  *
 434  * Finishes ejecting a mount. If any errors occurred during the operation,
 435  * @error will be set to contain the errors and %FALSE will be returned.
 436  *
 437  * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
 438  **/
 439 gboolean
 440 g_mount_eject_finish (GMount       *mount,
 441                       GAsyncResult  *result,
 442                       GError       **error)
 443 {
 444   GMountIface *iface;
 445
 446   g_return_val_if_fail (G_IS_MOUNT (mount), 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_MOUNT_GET_IFACE (mount);
 457   return (* iface->eject_finish) (mount, result, error);
 458 }
 459
 460 /**
 461  * g_mount_remount:
 462  * @mount: a #GMount.
 463  * @flags: flags affecting the operation
 464  * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
 465  * @cancellable: optional #GCancellable object, %NULL to ignore.
 466  * @callback: a #GAsyncReadyCallback, or %NULL.
 467  * @user_data: user data passed to @callback.
 468  *
 469  * Remounts a mount. This is an asynchronous operation, and is
 470  * finished by calling g_mount_remount_finish() with the @mount
 471  * and #GAsyncResults data returned in the @callback.
 472  *
 473  * Remounting is useful when some setting affecting the operation
 474  * of the volume has been changed, as these may need a remount to
 475  * take affect. While this is semantically equivalent with unmounting
 476  * and then remounting not all backends might need to actually be
 477  * unmounted.
 478  **/
 479 void
 480 g_mount_remount (GMount *mount,
 481                  GMountMountFlags flags,
 482                  GMountOperation *mount_operation,
 483                  GCancellable *cancellable,
 484                  GAsyncReadyCallback callback,
 485                  gpointer user_data)
 486 {
 487   GMountIface *iface;
 488
 489   g_return_if_fail (G_IS_MOUNT (mount));
 490
 491   iface = G_MOUNT_GET_IFACE (mount);
 492
 493   if (iface->remount == NULL)
 494     {
 495      g_simple_async_report_error_in_idle (G_OBJECT (mount),
 496                                            callback, user_data,
 497                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
 498                                            /* Translators: This is an error
 499                                             * message for mount objects that
 500                                             * don't implement remount. */
 501                                            _("mount doesn't implement remount"));
 502
 503       return;
 504     }
 505
 506   (* iface->remount) (mount, flags, mount_operation, cancellable, callback, user_data);
 507 }
 508
 509 /**
 510  * g_mount_remount_finish:
 511  * @mount: a #GMount.
 512  * @result: a #GAsyncResult.
 513  * @error: a #GError location to store the error occuring, or %NULL to
 514  * ignore.
 515  *
 516  * Finishes remounting a mount. If any errors occurred during the operation,
 517  * @error will be set to contain the errors and %FALSE will be returned.
 518  *
 519  * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
 520  **/
 521 gboolean
 522 g_mount_remount_finish (GMount       *mount,
 523                         GAsyncResult  *result,
 524                         GError       **error)
 525 {
 526   GMountIface *iface;
 527
 528   g_return_val_if_fail (G_IS_MOUNT (mount), FALSE);
 529   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
 530
 531   if (G_IS_SIMPLE_ASYNC_RESULT (result))
 532     {
 533       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
 534       if (g_simple_async_result_propagate_error (simple, error))
 535         return FALSE;
 536     }
 537
 538   iface = G_MOUNT_GET_IFACE (mount);
 539   return (* iface->remount_finish) (mount, result, error);
 540 }
 541
 542
 543 #define __G_MOUNT_C__
 544 #include "gioaliasdef.c"