gio/gdrive.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 "gdrive.h"
  26 #include "gsimpleasyncresult.h"
  27 #include "glibintl.h"
  28
  29 #include "gioalias.h"
  30
  31 /**
  32  * SECTION:gdrive
  33  * @short_description: Virtual File System drive management
  34  * @include: gio.h
  35  *
  36  * #GDrive is a container class for #GVolume objects that stem from
  37  * the same piece of media. As such, #GDrive abstracts a drive with
  38  * (or without) removable media and provides operations for querying
  39  * whether media is available, determing whether media change is
  40  * automatically detected and ejecting the media.
  41  *
  42  * If the #GDrive reports that media isn't automatically detected, one
  43  * can poll for media; typically one should not do this periodically
  44  * as a poll for media operation is potententially expensive and may
  45  * spin up the drive creating noise.
  46  *
  47  * For porting from GnomeVFS note that there is no equivalent of
  48  * #GDrive in that API.
  49  **/
  50
  51 static void g_drive_base_init (gpointer g_class);
  52 static void g_drive_class_init (gpointer g_class,
  53                                  gpointer class_data);
  54
  55 GType
  56 g_drive_get_type (void)
  57 {
  58   static GType drive_type = 0;
  59
  60   if (! drive_type)
  61     {
  62       static const GTypeInfo drive_info =
  63       {
  64         sizeof (GDriveIface), /* class_size */
  65         g_drive_base_init,   /* base_init */
  66         NULL,           /* base_finalize */
  67         g_drive_class_init,
  68         NULL,           /* class_finalize */
  69         NULL,           /* class_data */
  70         0,
  71         0,              /* n_preallocs */
  72         NULL
  73       };
  74
  75       drive_type =
  76         g_type_register_static (G_TYPE_INTERFACE, I_("GDrive"),
  77                                 &drive_info, 0);
  78
  79       g_type_interface_add_prerequisite (drive_type, G_TYPE_OBJECT);
  80     }
  81
  82   return drive_type;
  83 }
  84
  85 static void
  86 g_drive_class_init (gpointer g_class,
  87                     gpointer class_data)
  88 {
  89 }
  90
  91 static void
  92 g_drive_base_init (gpointer g_class)
  93 {
  94   static gboolean initialized = FALSE;
  95
  96   if (! initialized)
  97     {
  98       /**
  99       * GDrive::changed:
 100       * @volume: a #GVolume.
 101       *
 102       * Emitted when the drive's state has changed.
 103       *
 104       **/
 105       g_signal_new (I_("changed"),
 106                     G_TYPE_DRIVE,
 107                     G_SIGNAL_RUN_LAST,
 108                     G_STRUCT_OFFSET (GDriveIface, changed),
 109                     NULL, NULL,
 110                     g_cclosure_marshal_VOID__VOID,
 111                     G_TYPE_NONE, 0);
 112
 113       initialized = TRUE;
 114     }
 115 }
 116
 117 /**
 118  * g_drive_get_name:
 119  * @drive: a #GDrive.
 120  *
 121  * Gets the name of @drive.
 122  *
 123  * Returns: a string containing @drive's name. The returned
 124  *     string should be freed when no longer needed.
 125  **/
 126 char *
 127 g_drive_get_name (GDrive *drive)
 128 {
 129   GDriveIface *iface;
 130
 131   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
 132
 133   iface = G_DRIVE_GET_IFACE (drive);
 134
 135   return (* iface->get_name) (drive);
 136 }
 137
 138 /**
 139  * g_drive_get_icon:
 140  * @drive: a #GDrive.
 141  *
 142  * Gets the icon for @drive.
 143  *
 144  * Returns: #GIcon for the @drive.
 145  **/
 146 GIcon *
 147 g_drive_get_icon (GDrive *drive)
 148 {
 149   GDriveIface *iface;
 150
 151   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
 152
 153   iface = G_DRIVE_GET_IFACE (drive);
 154
 155   return (* iface->get_icon) (drive);
 156 }
 157
 158 /**
 159  * g_drive_has_volumes:
 160  * @drive: a #GDrive.
 161  *
 162  * Check if @drive has any mountable volumes.
 163  *
 164  * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
 165  **/
 166 gboolean
 167 g_drive_has_volumes (GDrive *drive)
 168 {
 169   GDriveIface *iface;
 170
 171   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
 172
 173   iface = G_DRIVE_GET_IFACE (drive);
 174
 175   return (* iface->has_volumes) (drive);
 176 }
 177
 178 /**
 179  * g_drive_get_volumes:
 180  * @drive: a #GDrive.
 181  *
 182  * Get a list of mountable volumes for @drive.
 183  *
 184  * Returns: #GList containing any #GVolume<!---->s on the given @drive.
 185  **/
 186 GList *
 187 g_drive_get_volumes (GDrive *drive)
 188 {
 189   GDriveIface *iface;
 190
 191   g_return_val_if_fail (G_IS_DRIVE (drive), NULL);
 192
 193   iface = G_DRIVE_GET_IFACE (drive);
 194
 195   return (* iface->get_volumes) (drive);
 196 }
 197
 198 /**
 199  * g_drive_is_media_check_automatic:
 200  * @drive: a #GDrive.
 201  *
 202  * Checks if @drive is capabable of automatically detecting media changes.
 203  *
 204  * Returns: %TRUE if the @drive is capabable of automatically detecting media changes, %FALSE otherwise.
 205  **/
 206 gboolean
 207 g_drive_is_media_check_automatic (GDrive *drive)
 208 {
 209   GDriveIface *iface;
 210
 211   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
 212
 213   iface = G_DRIVE_GET_IFACE (drive);
 214
 215   return (* iface->is_media_check_automatic) (drive);
 216 }
 217
 218 /**
 219  * g_drive_is_media_removable:
 220  * @drive: a #GDrive.
 221  *
 222  * Checks if the @drive supports removable media.
 223  *
 224  * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
 225  **/
 226 gboolean
 227 g_drive_is_media_removable (GDrive *drive)
 228 {
 229   GDriveIface *iface;
 230
 231   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
 232
 233   iface = G_DRIVE_GET_IFACE (drive);
 234
 235   return (* iface->is_media_removable) (drive);
 236 }
 237
 238 /**
 239  * g_drive_has_media:
 240  * @drive: a #GDrive.
 241  *
 242  * Checks if the @drive has media. Note that the OS may not be polling
 243  * the drive for media changes; see g_drive_is_media_check_automatic()
 244  * for more details.
 245  *
 246  * Returns: %TRUE if @drive has media, %FALSE otherwise.
 247  **/
 248 gboolean
 249 g_drive_has_media (GDrive *drive)
 250 {
 251   GDriveIface *iface;
 252
 253   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
 254
 255   iface = G_DRIVE_GET_IFACE (drive);
 256
 257   return (* iface->has_media) (drive);
 258 }
 259
 260 /**
 261  * g_drive_can_eject:
 262  * @drive: pointer to a #GDrive.
 263  *
 264  * Checks if a drive can be ejected.
 265  *
 266  * Returns: %TRUE if the @drive can be ejected. %FALSE otherwise.
 267  **/
 268 gboolean
 269 g_drive_can_eject (GDrive *drive)
 270 {
 271   GDriveIface *iface;
 272
 273   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
 274
 275   iface = G_DRIVE_GET_IFACE (drive);
 276
 277   if (iface->can_eject == NULL)
 278     return FALSE;
 279
 280   return (* iface->can_eject) (drive);
 281 }
 282
 283 /**
 284  * g_drive_can_poll_for_media:
 285  * @drive: a #GDrive.
 286  *
 287  * Checks if a drive can be polled for media changes.
 288  *
 289  * Returns: %TRUE if the @drive can be polled for media changes. %FALSE otherwise.
 290  **/
 291 gboolean
 292 g_drive_can_poll_for_media (GDrive *drive)
 293 {
 294   GDriveIface *iface;
 295
 296   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
 297
 298   iface = G_DRIVE_GET_IFACE (drive);
 299
 300   if (iface->poll_for_media == NULL)
 301     return FALSE;
 302
 303   return (* iface->can_poll_for_media) (drive);
 304 }
 305
 306 /**
 307  * g_drive_eject:
 308  * @drive: a #GDrive.
 309  * @cancellable: optional #GCancellable object, %NULL to ignore.
 310  * @callback: a #GAsyncReadyCallback.
 311  * @user_data: a #gpointer.
 312  *
 313  * Ejects a drive.
 314  *
 315  **/
 316 void
 317 g_drive_eject (GDrive              *drive,
 318                GCancellable        *cancellable,
 319                GAsyncReadyCallback  callback,
 320                gpointer             user_data)
 321 {
 322   GDriveIface *iface;
 323
 324   g_return_if_fail (G_IS_DRIVE (drive));
 325
 326   iface = G_DRIVE_GET_IFACE (drive);
 327
 328   if (iface->eject == NULL)
 329     {
 330       g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
 331                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
 332                                            _("drive doesn't implement eject"));
 333
 334       return;
 335     }
 336
 337   (* iface->eject) (drive, cancellable, callback, user_data);
 338 }
 339
 340 /**
 341  * g_drive_eject_finish
 342  * @drive: a #GDrive.
 343  * @result: a #GAsyncResult.
 344  * @error: a #GError.
 345  *
 346  * Finishes ejecting a drive.
 347  *
 348  * Returns: %TRUE if the drive has been ejected successfully,
 349  * %FALSE otherwise.
 350  **/
 351 gboolean
 352 g_drive_eject_finish (GDrive        *drive,
 353                       GAsyncResult  *result,
 354                       GError       **error)
 355 {
 356   GDriveIface *iface;
 357
 358   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
 359   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
 360
 361   if (G_IS_SIMPLE_ASYNC_RESULT (result))
 362     {
 363       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
 364       if (g_simple_async_result_propagate_error (simple, error))
 365         return FALSE;
 366     }
 367
 368   iface = G_DRIVE_GET_IFACE (drive);
 369
 370   return (* iface->eject_finish) (drive, result, error);
 371 }
 372
 373 /**
 374  * g_drive_poll_for_media:
 375  * @drive: a #GDrive.
 376  * @cancellable: optional #GCancellable object, %NULL to ignore.
 377  * @callback: a #GAsyncReadyCallback.
 378  * @user_data: a #gpointer.
 379  *
 380  * Polls @drive to see if media has been inserted or removed.
 381  *
 382  **/
 383 void
 384 g_drive_poll_for_media (GDrive              *drive,
 385                         GCancellable        *cancellable,
 386                         GAsyncReadyCallback  callback,
 387                         gpointer             user_data)
 388 {
 389   GDriveIface *iface;
 390
 391   g_return_if_fail (G_IS_DRIVE (drive));
 392
 393   iface = G_DRIVE_GET_IFACE (drive);
 394
 395   if (iface->poll_for_media == NULL)
 396     {
 397       g_simple_async_report_error_in_idle (G_OBJECT (drive), callback, user_data,
 398                                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
 399                                            _("drive doesn't implement polling for media"));
 400
 401       return;
 402     }
 403
 404   (* iface->poll_for_media) (drive, cancellable, callback, user_data);
 405 }
 406
 407 /**
 408  * g_drive_poll_for_media_finish
 409  * @drive: a #GDrive.
 410  * @result: a #GAsyncResult.
 411  * @error: a #GError.
 412  *
 413  * Finishes poll_for_mediaing a drive.
 414  *
 415  * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
 416  * %FALSE otherwise.
 417  **/
 418 gboolean
 419 g_drive_poll_for_media_finish (GDrive        *drive,
 420                                GAsyncResult  *result,
 421                                GError       **error)
 422 {
 423   GDriveIface *iface;
 424
 425   g_return_val_if_fail (G_IS_DRIVE (drive), FALSE);
 426   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
 427
 428   if (G_IS_SIMPLE_ASYNC_RESULT (result))
 429     {
 430       GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (result);
 431       if (g_simple_async_result_propagate_error (simple, error))
 432         return FALSE;
 433     }
 434
 435   iface = G_DRIVE_GET_IFACE (drive);
 436
 437   return (* iface->poll_for_media_finish) (drive, result, error);
 438 }
 439
 440 #define __G_DRIVE_C__
 441 #include "gioaliasdef.c"