gio/gfile.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, see <http://www.gnu.org/licenses/>.
  19  *
  20  * Author: Alexander Larsson <alexl@redhat.com>
  21  */
  22
  23 #include "config.h"
  24
  25 #ifdef __linux__
  26 #include <sys/ioctl.h>
  27 #include <errno.h>
  28 /* See linux.git/fs/btrfs/ioctl.h */
  29 #define BTRFS_IOCTL_MAGIC 0x94
  30 #define BTRFS_IOC_CLONE _IOW(BTRFS_IOCTL_MAGIC, 9, int)
  31 #endif
  32
  33 #ifdef HAVE_SPLICE
  34 #include <sys/stat.h>
  35 #include <unistd.h>
  36 #include <fcntl.h>
  37 #include <errno.h>
  38 #endif
  39
  40 #include <string.h>
  41 #include <sys/types.h>
  42
  43 #include "gfile.h"
  44 #include "glib/gstdio.h"
  45 #ifdef G_OS_UNIX
  46 #include "glib-unix.h"
  47 #endif
  48 #include "gvfs.h"
  49 #include "gtask.h"
  50 #include "gfileattribute-priv.h"
  51 #include "gfiledescriptorbased.h"
  52 #include "gpollfilemonitor.h"
  53 #include "gappinfo.h"
  54 #include "gfileinputstream.h"
  55 #include "gfileoutputstream.h"
  56 #include "glocalfileoutputstream.h"
  57 #include "glocalfileiostream.h"
  58 #include "glocalfile.h"
  59 #include "gcancellable.h"
  60 #include "gasyncresult.h"
  61 #include "gioerror.h"
  62 #include "glibintl.h"
  63
  64
  65 /**
  66  * SECTION:gfile
  67  * @short_description: File and Directory Handling
  68  * @include: gio/gio.h
  69  * @see_also: #GFileInfo, #GFileEnumerator
  70  *
  71  * #GFile is a high level abstraction for manipulating files on a
  72  * virtual file system. #GFiles are lightweight, immutable objects
  73  * that do no I/O upon creation. It is necessary to understand that
  74  * #GFile objects do not represent files, merely an identifier for a
  75  * file. All file content I/O is implemented as streaming operations
  76  * (see #GInputStream and #GOutputStream).
  77  *
  78  * To construct a #GFile, you can use:
  79  * - g_file_new_for_path() if you have a path.
  80  * - g_file_new_for_uri() if you have a URI.
  81  * - g_file_new_for_commandline_arg() for a command line argument.
  82  * - g_file_new_tmp() to create a temporary file from a template.
  83  * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
  84  *
  85  * One way to think of a #GFile is as an abstraction of a pathname. For
  86  * normal files the system pathname is what is stored internally, but as
  87  * #GFiles are extensible it could also be something else that corresponds
  88  * to a pathname in a userspace implementation of a filesystem.
  89  *
  90  * #GFiles make up hierarchies of directories and files that correspond to
  91  * the files on a filesystem. You can move through the file system with
  92  * #GFile using g_file_get_parent() to get an identifier for the parent
  93  * directory, g_file_get_child() to get a child within a directory,
  94  * g_file_resolve_relative_path() to resolve a relative path between two
  95  * #GFiles. There can be multiple hierarchies, so you may not end up at
  96  * the same root if you repeatedly call g_file_get_parent() on two different
  97  * files.
  98  *
  99  * All #GFiles have a basename (get with g_file_get_basename()). These names
 100  * are byte strings that are used to identify the file on the filesystem
 101  * (relative to its parent directory) and there is no guarantees that they
 102  * have any particular charset encoding or even make any sense at all. If
 103  * you want to use filenames in a user interface you should use the display
 104  * name that you can get by requesting the
 105  * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
 106  * This is guaranteed to be in UTF-8 and can be used in a user interface.
 107  * But always store the real basename or the #GFile to use to actually
 108  * access the file, because there is no way to go from a display name to
 109  * the actual name.
 110  *
 111  * Using #GFile as an identifier has the same weaknesses as using a path
 112  * in that there may be multiple aliases for the same file. For instance,
 113  * hard or soft links may cause two different #GFiles to refer to the same
 114  * file. Other possible causes for aliases are: case insensitive filesystems,
 115  * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
 116  * check if two #GFiles point to the same file you can query for the
 117  * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
 118  * canonicalization of pathnames passed in, so that trivial differences in
 119  * the path string used at creation (duplicated slashes, slash at end of
 120  * path, "." or ".." path segments, etc) does not create different #GFiles.
 121  *
 122  * Many #GFile operations have both synchronous and asynchronous versions
 123  * to suit your application. Asynchronous versions of synchronous functions
 124  * simply have _async() appended to their function names. The asynchronous
 125  * I/O functions call a #GAsyncReadyCallback which is then used to finalize
 126  * the operation, producing a GAsyncResult which is then passed to the
 127  * function's matching _finish() operation.
 128  *
 129  * It is highly recommended to use asynchronous calls when running within a
 130  * shared main loop, such as in the main thread of an application. This avoids
 131  * I/O operations blocking other sources on the main loop from being dispatched.
 132  * Synchronous I/O operations should be performed from worker threads. See the
 133  * [introduction to asynchronous programming section][async-programming] for
 134  * more.
 135  *
 136  * Some #GFile operations almost always take a noticeable amount of time, and
 137  * so do not have synchronous analogs. Notable cases include:
 138  * - g_file_mount_mountable() to mount a mountable file.
 139  * - g_file_unmount_mountable_with_operation() to unmount a mountable file.
 140  * - g_file_eject_mountable_with_operation() to eject a mountable file.
 141  *
 142  * ## Entity Tags # {#gfile-etag}
 143  *
 144  * One notable feature of #GFiles are entity tags, or "etags" for
 145  * short. Entity tags are somewhat like a more abstract version of the
 146  * traditional mtime, and can be used to quickly determine if the file
 147  * has been modified from the version on the file system. See the
 148  * HTTP 1.1
 149  * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
 150  * for HTTP Etag headers, which are a very similar concept.
 151  */
 152
 153 static void               g_file_real_query_info_async            (GFile                  *file,
 154                                                                    const char             *attributes,
 155                                                                    GFileQueryInfoFlags     flags,
 156                                                                    int                     io_priority,
 157                                                                    GCancellable           *cancellable,
 158                                                                    GAsyncReadyCallback     callback,
 159                                                                    gpointer                user_data);
 160 static GFileInfo *        g_file_real_query_info_finish           (GFile                  *file,
 161                                                                    GAsyncResult           *res,
 162                                                                    GError                **error);
 163 static void               g_file_real_query_filesystem_info_async (GFile                  *file,
 164                                                                    const char             *attributes,
 165                                                                    int                     io_priority,
 166                                                                    GCancellable           *cancellable,
 167                                                                    GAsyncReadyCallback     callback,
 168                                                                    gpointer                user_data);
 169 static GFileInfo *        g_file_real_query_filesystem_info_finish (GFile                  *file,
 170                                                                    GAsyncResult           *res,
 171                                                                    GError                **error);
 172 static void               g_file_real_enumerate_children_async    (GFile                  *file,
 173                                                                    const char             *attributes,
 174                                                                    GFileQueryInfoFlags     flags,
 175                                                                    int                     io_priority,
 176                                                                    GCancellable           *cancellable,
 177                                                                    GAsyncReadyCallback     callback,
 178                                                                    gpointer                user_data);
 179 static GFileEnumerator *  g_file_real_enumerate_children_finish   (GFile                  *file,
 180                                                                    GAsyncResult           *res,
 181                                                                    GError                **error);
 182 static void               g_file_real_read_async                  (GFile                  *file,
 183                                                                    int                     io_priority,
 184                                                                    GCancellable           *cancellable,
 185                                                                    GAsyncReadyCallback     callback,
 186                                                                    gpointer                user_data);
 187 static GFileInputStream * g_file_real_read_finish                 (GFile                  *file,
 188                                                                    GAsyncResult           *res,
 189                                                                    GError                **error);
 190 static void               g_file_real_append_to_async             (GFile                  *file,
 191                                                                    GFileCreateFlags        flags,
 192                                                                    int                     io_priority,
 193                                                                    GCancellable           *cancellable,
 194                                                                    GAsyncReadyCallback     callback,
 195                                                                    gpointer                user_data);
 196 static GFileOutputStream *g_file_real_append_to_finish            (GFile                  *file,
 197                                                                    GAsyncResult           *res,
 198                                                                    GError                **error);
 199 static void               g_file_real_create_async                (GFile                  *file,
 200                                                                    GFileCreateFlags        flags,
 201                                                                    int                     io_priority,
 202                                                                    GCancellable           *cancellable,
 203                                                                    GAsyncReadyCallback     callback,
 204                                                                    gpointer                user_data);
 205 static GFileOutputStream *g_file_real_create_finish               (GFile                  *file,
 206                                                                    GAsyncResult           *res,
 207                                                                    GError                **error);
 208 static void               g_file_real_replace_async               (GFile                  *file,
 209                                                                    const char             *etag,
 210                                                                    gboolean                make_backup,
 211                                                                    GFileCreateFlags        flags,
 212                                                                    int                     io_priority,
 213                                                                    GCancellable           *cancellable,
 214                                                                    GAsyncReadyCallback     callback,
 215                                                                    gpointer                user_data);
 216 static GFileOutputStream *g_file_real_replace_finish              (GFile                  *file,
 217                                                                    GAsyncResult           *res,
 218                                                                    GError                **error);
 219 static void               g_file_real_delete_async                (GFile                  *file,
 220                                                                    int                     io_priority,
 221                                                                    GCancellable           *cancellable,
 222                                                                    GAsyncReadyCallback     callback,
 223                                                                    gpointer                user_data);
 224 static gboolean           g_file_real_delete_finish               (GFile                  *file,
 225                                                                    GAsyncResult           *res,
 226                                                                    GError                **error);
 227 static void               g_file_real_trash_async                 (GFile                  *file,
 228                                                                    int                     io_priority,
 229                                                                    GCancellable           *cancellable,
 230                                                                    GAsyncReadyCallback     callback,
 231                                                                    gpointer                user_data);
 232 static gboolean           g_file_real_trash_finish                (GFile                  *file,
 233                                                                    GAsyncResult           *res,
 234                                                                    GError                **error);
 235 static void               g_file_real_make_directory_async        (GFile                  *file,
 236                                                                    int                     io_priority,
 237                                                                    GCancellable           *cancellable,
 238                                                                    GAsyncReadyCallback     callback,
 239                                                                    gpointer                user_data);
 240 static gboolean           g_file_real_make_directory_finish       (GFile                  *file,
 241                                                                    GAsyncResult           *res,
 242                                                                    GError                **error);
 243 static void               g_file_real_open_readwrite_async        (GFile                  *file,
 244                                                                    int                  io_priority,
 245                                                                    GCancellable           *cancellable,
 246                                                                    GAsyncReadyCallback     callback,
 247                                                                    gpointer                user_data);
 248 static GFileIOStream *    g_file_real_open_readwrite_finish       (GFile                  *file,
 249                                                                    GAsyncResult           *res,
 250                                                                    GError                **error);
 251 static void               g_file_real_create_readwrite_async      (GFile                  *file,
 252                                                                    GFileCreateFlags        flags,
 253                                                                    int                     io_priority,
 254                                                                    GCancellable           *cancellable,
 255                                                                    GAsyncReadyCallback     callback,
 256                                                                    gpointer                user_data);
 257 static GFileIOStream *    g_file_real_create_readwrite_finish     (GFile                  *file,
 258                                                                    GAsyncResult           *res,
 259                                                                    GError                **error);
 260 static void               g_file_real_replace_readwrite_async     (GFile                  *file,
 261                                                                    const char             *etag,
 262                                                                    gboolean                make_backup,
 263                                                                    GFileCreateFlags        flags,
 264                                                                    int                     io_priority,
 265                                                                    GCancellable           *cancellable,
 266                                                                    GAsyncReadyCallback     callback,
 267                                                                    gpointer                user_data);
 268 static GFileIOStream *    g_file_real_replace_readwrite_finish    (GFile                  *file,
 269                                                                   GAsyncResult            *res,
 270                                                                   GError                 **error);
 271 static gboolean           g_file_real_set_attributes_from_info    (GFile                  *file,
 272                                                                    GFileInfo              *info,
 273                                                                    GFileQueryInfoFlags     flags,
 274                                                                    GCancellable           *cancellable,
 275                                                                    GError                **error);
 276 static void               g_file_real_set_display_name_async      (GFile                  *file,
 277                                                                    const char             *display_name,
 278                                                                    int                     io_priority,
 279                                                                    GCancellable           *cancellable,
 280                                                                    GAsyncReadyCallback     callback,
 281                                                                    gpointer                user_data);
 282 static GFile *            g_file_real_set_display_name_finish     (GFile                  *file,
 283                                                                    GAsyncResult           *res,
 284                                                                    GError                **error);
 285 static void               g_file_real_set_attributes_async        (GFile                  *file,
 286                                                                    GFileInfo              *info,
 287                                                                    GFileQueryInfoFlags     flags,
 288                                                                    int                     io_priority,
 289                                                                    GCancellable           *cancellable,
 290                                                                    GAsyncReadyCallback     callback,
 291                                                                    gpointer                user_data);
 292 static gboolean           g_file_real_set_attributes_finish       (GFile                  *file,
 293                                                                    GAsyncResult           *res,
 294                                                                    GFileInfo             **info,
 295                                                                    GError                **error);
 296 static void               g_file_real_find_enclosing_mount_async  (GFile                  *file,
 297                                                                    int                     io_priority,
 298                                                                    GCancellable           *cancellable,
 299                                                                    GAsyncReadyCallback     callback,
 300                                                                    gpointer                user_data);
 301 static GMount *           g_file_real_find_enclosing_mount_finish (GFile                  *file,
 302                                                                    GAsyncResult           *res,
 303                                                                    GError                **error);
 304 static void               g_file_real_copy_async                  (GFile                  *source,
 305                                                                    GFile                  *destination,
 306                                                                    GFileCopyFlags          flags,
 307                                                                    int                     io_priority,
 308                                                                    GCancellable           *cancellable,
 309                                                                    GFileProgressCallback   progress_callback,
 310                                                                    gpointer                progress_callback_data,
 311                                                                    GAsyncReadyCallback     callback,
 312                                                                    gpointer                user_data);
 313 static gboolean           g_file_real_copy_finish                 (GFile                  *file,
 314                                                                    GAsyncResult           *res,
 315                                                                    GError                **error);
 316
 317 static gboolean           g_file_real_measure_disk_usage          (GFile                         *file,
 318                                                                    GFileMeasureFlags              flags,
 319                                                                    GCancellable                  *cancellable,
 320                                                                    GFileMeasureProgressCallback   progress_callback,
 321                                                                    gpointer                       progress_data,
 322                                                                    guint64                       *disk_usage,
 323                                                                    guint64                       *num_dirs,
 324                                                                    guint64                       *num_files,
 325                                                                    GError                       **error);
 326 static void               g_file_real_measure_disk_usage_async    (GFile                         *file,
 327                                                                    GFileMeasureFlags              flags,
 328                                                                    gint                           io_priority,
 329                                                                    GCancellable                  *cancellable,
 330                                                                    GFileMeasureProgressCallback   progress_callback,
 331                                                                    gpointer                       progress_data,
 332                                                                    GAsyncReadyCallback            callback,
 333                                                                    gpointer                       user_data);
 334 static gboolean           g_file_real_measure_disk_usage_finish   (GFile                         *file,
 335                                                                    GAsyncResult                  *result,
 336                                                                    guint64                       *disk_usage,
 337                                                                    guint64                       *num_dirs,
 338                                                                    guint64                       *num_files,
 339                                                                    GError                       **error);
 340
 341 typedef GFileIface GFileInterface;
 342 G_DEFINE_INTERFACE (GFile, g_file, G_TYPE_OBJECT)
 343
 344 static void
 345 g_file_default_init (GFileIface *iface)
 346 {
 347   iface->enumerate_children_async = g_file_real_enumerate_children_async;
 348   iface->enumerate_children_finish = g_file_real_enumerate_children_finish;
 349   iface->set_display_name_async = g_file_real_set_display_name_async;
 350   iface->set_display_name_finish = g_file_real_set_display_name_finish;
 351   iface->query_info_async = g_file_real_query_info_async;
 352   iface->query_info_finish = g_file_real_query_info_finish;
 353   iface->query_filesystem_info_async = g_file_real_query_filesystem_info_async;
 354   iface->query_filesystem_info_finish = g_file_real_query_filesystem_info_finish;
 355   iface->set_attributes_async = g_file_real_set_attributes_async;
 356   iface->set_attributes_finish = g_file_real_set_attributes_finish;
 357   iface->read_async = g_file_real_read_async;
 358   iface->read_finish = g_file_real_read_finish;
 359   iface->append_to_async = g_file_real_append_to_async;
 360   iface->append_to_finish = g_file_real_append_to_finish;
 361   iface->create_async = g_file_real_create_async;
 362   iface->create_finish = g_file_real_create_finish;
 363   iface->replace_async = g_file_real_replace_async;
 364   iface->replace_finish = g_file_real_replace_finish;
 365   iface->delete_file_async = g_file_real_delete_async;
 366   iface->delete_file_finish = g_file_real_delete_finish;
 367   iface->trash_async = g_file_real_trash_async;
 368   iface->trash_finish = g_file_real_trash_finish;
 369   iface->make_directory_async = g_file_real_make_directory_async;
 370   iface->make_directory_finish = g_file_real_make_directory_finish;
 371   iface->open_readwrite_async = g_file_real_open_readwrite_async;
 372   iface->open_readwrite_finish = g_file_real_open_readwrite_finish;
 373   iface->create_readwrite_async = g_file_real_create_readwrite_async;
 374   iface->create_readwrite_finish = g_file_real_create_readwrite_finish;
 375   iface->replace_readwrite_async = g_file_real_replace_readwrite_async;
 376   iface->replace_readwrite_finish = g_file_real_replace_readwrite_finish;
 377   iface->find_enclosing_mount_async = g_file_real_find_enclosing_mount_async;
 378   iface->find_enclosing_mount_finish = g_file_real_find_enclosing_mount_finish;
 379   iface->set_attributes_from_info = g_file_real_set_attributes_from_info;
 380   iface->copy_async = g_file_real_copy_async;
 381   iface->copy_finish = g_file_real_copy_finish;
 382   iface->measure_disk_usage = g_file_real_measure_disk_usage;
 383   iface->measure_disk_usage_async = g_file_real_measure_disk_usage_async;
 384   iface->measure_disk_usage_finish = g_file_real_measure_disk_usage_finish;
 385 }
 386
 387
 388 /**
 389  * g_file_is_native:
 390  * @file: input #GFile
 391  *
 392  * Checks to see if a file is native to the platform.
 393  *
 394  * A native file s one expressed in the platform-native filename format,
 395  * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
 396  * as it might be on a locally mounted remote filesystem.
 397  *
 398  * On some systems non-native files may be available using the native
 399  * filesystem via a userspace filesystem (FUSE), in these cases this call
 400  * will return %FALSE, but g_file_get_path() will still return a native path.
 401  *
 402  * This call does no blocking I/O.
 403  *
 404  * Returns: %TRUE if @file is native
 405  */
 406 gboolean
 407 g_file_is_native (GFile *file)
 408 {
 409   GFileIface *iface;
 410
 411   g_return_val_if_fail (G_IS_FILE (file), FALSE);
 412
 413   iface = G_FILE_GET_IFACE (file);
 414
 415   return (* iface->is_native) (file);
 416 }
 417
 418
 419 /**
 420  * g_file_has_uri_scheme:
 421  * @file: input #GFile
 422  * @uri_scheme: a string containing a URI scheme
 423  *
 424  * Checks to see if a #GFile has a given URI scheme.
 425  *
 426  * This call does no blocking I/O.
 427  *
 428  * Returns: %TRUE if #GFile's backend supports the
 429  *     given URI scheme, %FALSE if URI scheme is %NULL,
 430  *     not supported, or #GFile is invalid.
 431  */
 432 gboolean
 433 g_file_has_uri_scheme (GFile      *file,
 434                        const char *uri_scheme)
 435 {
 436   GFileIface *iface;
 437
 438   g_return_val_if_fail (G_IS_FILE (file), FALSE);
 439   g_return_val_if_fail (uri_scheme != NULL, FALSE);
 440
 441   iface = G_FILE_GET_IFACE (file);
 442
 443   return (* iface->has_uri_scheme) (file, uri_scheme);
 444 }
 445
 446
 447 /**
 448  * g_file_get_uri_scheme:
 449  * @file: input #GFile
 450  *
 451  * Gets the URI scheme for a #GFile.
 452  * RFC 3986 decodes the scheme as:
 453  * |[
 454  * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
 455  * ]|
 456  * Common schemes include "file", "http", "ftp", etc.
 457  *
 458  * This call does no blocking I/O.
 459  *
 460  * Returns: a string containing the URI scheme for the given
 461  *     #GFile. The returned string should be freed with g_free()
 462  *     when no longer needed.
 463  */
 464 char *
 465 g_file_get_uri_scheme (GFile *file)
 466 {
 467   GFileIface *iface;
 468
 469   g_return_val_if_fail (G_IS_FILE (file), NULL);
 470
 471   iface = G_FILE_GET_IFACE (file);
 472
 473   return (* iface->get_uri_scheme) (file);
 474 }
 475
 476
 477 /**
 478  * g_file_get_basename:
 479  * @file: input #GFile
 480  *
 481  * Gets the base name (the last component of the path) for a given #GFile.
 482  *
 483  * If called for the top level of a system (such as the filesystem root
 484  * or a uri like sftp://host/) it will return a single directory separator
 485  * (and on Windows, possibly a drive letter).
 486  *
 487  * The base name is a byte string (not UTF-8). It has no defined encoding
 488  * or rules other than it may not contain zero bytes.  If you want to use
 489  * filenames in a user interface you should use the display name that you
 490  * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
 491  * attribute with g_file_query_info().
 492  *
 493  * This call does no blocking I/O.
 494  *
 495  * Returns: (nullable): string containing the #GFile's base name, or
 496  *     %NULL if given #GFile is invalid. The returned string should be
 497  *     freed with g_free() when no longer needed.
 498  */
 499 char *
 500 g_file_get_basename (GFile *file)
 501 {
 502   GFileIface *iface;
 503
 504   g_return_val_if_fail (G_IS_FILE (file), NULL);
 505
 506   iface = G_FILE_GET_IFACE (file);
 507
 508   return (* iface->get_basename) (file);
 509 }
 510
 511 /**
 512  * g_file_get_path:
 513  * @file: input #GFile
 514  *
 515  * Gets the local pathname for #GFile, if one exists. If non-%NULL, this is
 516  * guaranteed to be an absolute, canonical path. It might contain symlinks.
 517  *
 518  * This call does no blocking I/O.
 519  *
 520  * Returns: (nullable): string containing the #GFile's path, or %NULL
 521  *     if no such path exists. The returned string should be freed
 522  *     with g_free() when no longer needed.
 523  */
 524 char *
 525 g_file_get_path (GFile *file)
 526 {
 527   GFileIface *iface;
 528
 529   g_return_val_if_fail (G_IS_FILE (file), NULL);
 530
 531   iface = G_FILE_GET_IFACE (file);
 532
 533   return (* iface->get_path) (file);
 534 }
 535
 536 /**
 537  * g_file_get_uri:
 538  * @file: input #GFile
 539  *
 540  * Gets the URI for the @file.
 541  *
 542  * This call does no blocking I/O.
 543  *
 544  * Returns: a string containing the #GFile's URI.
 545  *     The returned string should be freed with g_free()
 546  *     when no longer needed.
 547  */
 548 char *
 549 g_file_get_uri (GFile *file)
 550 {
 551   GFileIface *iface;
 552
 553   g_return_val_if_fail (G_IS_FILE (file), NULL);
 554
 555   iface = G_FILE_GET_IFACE (file);
 556
 557   return (* iface->get_uri) (file);
 558 }
 559
 560 /**
 561  * g_file_get_parse_name:
 562  * @file: input #GFile
 563  *
 564  * Gets the parse name of the @file.
 565  * A parse name is a UTF-8 string that describes the
 566  * file such that one can get the #GFile back using
 567  * g_file_parse_name().
 568  *
 569  * This is generally used to show the #GFile as a nice
 570  * full-pathname kind of string in a user interface,
 571  * like in a location entry.
 572  *
 573  * For local files with names that can safely be converted
 574  * to UTF-8 the pathname is used, otherwise the IRI is used
 575  * (a form of URI that allows UTF-8 characters unescaped).
 576  *
 577  * This call does no blocking I/O.
 578  *
 579  * Returns: a string containing the #GFile's parse name.
 580  *     The returned string should be freed with g_free()
 581  *     when no longer needed.
 582  */
 583 char *
 584 g_file_get_parse_name (GFile *file)
 585 {
 586   GFileIface *iface;
 587
 588   g_return_val_if_fail (G_IS_FILE (file), NULL);
 589
 590   iface = G_FILE_GET_IFACE (file);
 591
 592   return (* iface->get_parse_name) (file);
 593 }
 594
 595 /**
 596  * g_file_dup:
 597  * @file: input #GFile
 598  *
 599  * Duplicates a #GFile handle. This operation does not duplicate
 600  * the actual file or directory represented by the #GFile; see
 601  * g_file_copy() if attempting to copy a file.
 602  *
 603  * This call does no blocking I/O.
 604  *
 605  * Returns: (transfer full): a new #GFile that is a duplicate
 606  *     of the given #GFile.
 607  */
 608 GFile *
 609 g_file_dup (GFile *file)
 610 {
 611   GFileIface *iface;
 612
 613   g_return_val_if_fail (G_IS_FILE (file), NULL);
 614
 615   iface = G_FILE_GET_IFACE (file);
 616
 617   return (* iface->dup) (file);
 618 }
 619
 620 /**
 621  * g_file_hash:
 622  * @file: (type GFile): #gconstpointer to a #GFile
 623  *
 624  * Creates a hash value for a #GFile.
 625  *
 626  * This call does no blocking I/O.
 627  *
 628  * Virtual: hash
 629  * Returns: 0 if @file is not a valid #GFile, otherwise an
 630  *     integer that can be used as hash value for the #GFile.
 631  *     This function is intended for easily hashing a #GFile to
 632  *     add to a #GHashTable or similar data structure.
 633  */
 634 guint
 635 g_file_hash (gconstpointer file)
 636 {
 637   GFileIface *iface;
 638
 639   g_return_val_if_fail (G_IS_FILE (file), 0);
 640
 641   iface = G_FILE_GET_IFACE (file);
 642
 643   return (* iface->hash) ((GFile *)file);
 644 }
 645
 646 /**
 647  * g_file_equal:
 648  * @file1: the first #GFile
 649  * @file2: the second #GFile
 650  *
 651  * Checks if the two given #GFiles refer to the same file.
 652  *
 653  * Note that two #GFiles that differ can still refer to the same
 654  * file on the filesystem due to various forms of filename
 655  * aliasing.
 656  *
 657  * This call does no blocking I/O.
 658  *
 659  * Returns: %TRUE if @file1 and @file2 are equal.
 660  */
 661 gboolean
 662 g_file_equal (GFile *file1,
 663               GFile *file2)
 664 {
 665   GFileIface *iface;
 666
 667   g_return_val_if_fail (G_IS_FILE (file1), FALSE);
 668   g_return_val_if_fail (G_IS_FILE (file2), FALSE);
 669
 670   if (file1 == file2)
 671     return TRUE;
 672
 673   if (G_TYPE_FROM_INSTANCE (file1) != G_TYPE_FROM_INSTANCE (file2))
 674     return FALSE;
 675
 676   iface = G_FILE_GET_IFACE (file1);
 677
 678   return (* iface->equal) (file1, file2);
 679 }
 680
 681
 682 /**
 683  * g_file_get_parent:
 684  * @file: input #GFile
 685  *
 686  * Gets the parent directory for the @file.
 687  * If the @file represents the root directory of the
 688  * file system, then %NULL will be returned.
 689  *
 690  * This call does no blocking I/O.
 691  *
 692  * Returns: (nullable) (transfer full): a #GFile structure to the
 693  *     parent of the given #GFile or %NULL if there is no parent. Free
 694  *     the returned object with g_object_unref().
 695  */
 696 GFile *
 697 g_file_get_parent (GFile *file)
 698 {
 699   GFileIface *iface;
 700
 701   g_return_val_if_fail (G_IS_FILE (file), NULL);
 702
 703   iface = G_FILE_GET_IFACE (file);
 704
 705   return (* iface->get_parent) (file);
 706 }
 707
 708 /**
 709  * g_file_has_parent:
 710  * @file: input #GFile
 711  * @parent: (allow-none): the parent to check for, or %NULL
 712  *
 713  * Checks if @file has a parent, and optionally, if it is @parent.
 714  *
 715  * If @parent is %NULL then this function returns %TRUE if @file has any
 716  * parent at all.  If @parent is non-%NULL then %TRUE is only returned
 717  * if @file is an immediate child of @parent.
 718  *
 719  * Returns: %TRUE if @file is an immediate child of @parent (or any parent in
 720  *          the case that @parent is %NULL).
 721  *
 722  * Since: 2.24
 723  */
 724 gboolean
 725 g_file_has_parent (GFile *file,
 726                    GFile *parent)
 727 {
 728   GFile *actual_parent;
 729   gboolean result;
 730
 731   g_return_val_if_fail (G_IS_FILE (file), FALSE);
 732   g_return_val_if_fail (parent == NULL || G_IS_FILE (parent), FALSE);
 733
 734   actual_parent = g_file_get_parent (file);
 735
 736   if (actual_parent != NULL)
 737     {
 738       if (parent != NULL)
 739         result = g_file_equal (parent, actual_parent);
 740       else
 741         result = TRUE;
 742
 743       g_object_unref (actual_parent);
 744     }
 745   else
 746     result = FALSE;
 747
 748   return result;
 749 }
 750
 751 /**
 752  * g_file_get_child:
 753  * @file: input #GFile
 754  * @name: string containing the child's basename
 755  *
 756  * Gets a child of @file with basename equal to @name.
 757  *
 758  * Note that the file with that specific name might not exist, but
 759  * you can still have a #GFile that points to it. You can use this
 760  * for instance to create that file.
 761  *
 762  * This call does no blocking I/O.
 763  *
 764  * Returns: (transfer full): a #GFile to a child specified by @name.
 765  *     Free the returned object with g_object_unref().
 766  */
 767 GFile *
 768 g_file_get_child (GFile      *file,
 769                   const char *name)
 770 {
 771   g_return_val_if_fail (G_IS_FILE (file), NULL);
 772   g_return_val_if_fail (name != NULL, NULL);
 773
 774   return g_file_resolve_relative_path (file, name);
 775 }
 776
 777 /**
 778  * g_file_get_child_for_display_name:
 779  * @file: input #GFile
 780  * @display_name: string to a possible child
 781  * @error: return location for an error
 782  *
 783  * Gets the child of @file for a given @display_name (i.e. a UTF-8
 784  * version of the name). If this function fails, it returns %NULL
 785  * and @error will be set. This is very useful when constructing a
 786  * #GFile for a new file and the user entered the filename in the
 787  * user interface, for instance when you select a directory and
 788  * type a filename in the file selector.
 789  *
 790  * This call does no blocking I/O.
 791  *
 792  * Returns: (transfer full): a #GFile to the specified child, or
 793  *     %NULL if the display name couldn't be converted.
 794  *     Free the returned object with g_object_unref().
 795  */
 796 GFile *
 797 g_file_get_child_for_display_name (GFile      *file,
 798                                    const char *display_name,
 799                                    GError **error)
 800 {
 801   GFileIface *iface;
 802
 803   g_return_val_if_fail (G_IS_FILE (file), NULL);
 804   g_return_val_if_fail (display_name != NULL, NULL);
 805
 806   iface = G_FILE_GET_IFACE (file);
 807
 808   return (* iface->get_child_for_display_name) (file, display_name, error);
 809 }
 810
 811 /**
 812  * g_file_has_prefix:
 813  * @file: input #GFile
 814  * @prefix: input #GFile
 815  *
 816  * Checks whether @file has the prefix specified by @prefix.
 817  *
 818  * In other words, if the names of initial elements of @file's
 819  * pathname match @prefix. Only full pathname elements are matched,
 820  * so a path like /foo is not considered a prefix of /foobar, only
 821  * of /foo/bar.
 822  *
 823  * A #GFile is not a prefix of itself. If you want to check for
 824  * equality, use g_file_equal().
 825  *
 826  * This call does no I/O, as it works purely on names. As such it can
 827  * sometimes return %FALSE even if @file is inside a @prefix (from a
 828  * filesystem point of view), because the prefix of @file is an alias
 829  * of @prefix.
 830  *
 831  * Virtual: prefix_matches
 832  * Returns:  %TRUE if the @files's parent, grandparent, etc is @prefix,
 833  *     %FALSE otherwise.
 834  */
 835 gboolean
 836 g_file_has_prefix (GFile *file,
 837                    GFile *prefix)
 838 {
 839   GFileIface *iface;
 840
 841   g_return_val_if_fail (G_IS_FILE (file), FALSE);
 842   g_return_val_if_fail (G_IS_FILE (prefix), FALSE);
 843
 844   if (G_TYPE_FROM_INSTANCE (file) != G_TYPE_FROM_INSTANCE (prefix))
 845     return FALSE;
 846
 847   iface = G_FILE_GET_IFACE (file);
 848
 849   /* The vtable function differs in arg order since
 850    * we're using the old contains_file call
 851    */
 852   return (* iface->prefix_matches) (prefix, file);
 853 }
 854
 855 /**
 856  * g_file_get_relative_path:
 857  * @parent: input #GFile
 858  * @descendant: input #GFile
 859  *
 860  * Gets the path for @descendant relative to @parent.
 861  *
 862  * This call does no blocking I/O.
 863  *
 864  * Returns: (nullable): string with the relative path from @descendant
 865  *     to @parent, or %NULL if @descendant doesn't have @parent as
 866  *     prefix. The returned string should be freed with g_free() when
 867  *     no longer needed.
 868  */
 869 char *
 870 g_file_get_relative_path (GFile *parent,
 871                           GFile *descendant)
 872 {
 873   GFileIface *iface;
 874
 875   g_return_val_if_fail (G_IS_FILE (parent), NULL);
 876   g_return_val_if_fail (G_IS_FILE (descendant), NULL);
 877
 878   if (G_TYPE_FROM_INSTANCE (parent) != G_TYPE_FROM_INSTANCE (descendant))
 879     return NULL;
 880
 881   iface = G_FILE_GET_IFACE (parent);
 882
 883   return (* iface->get_relative_path) (parent, descendant);
 884 }
 885
 886 /**
 887  * g_file_resolve_relative_path:
 888  * @file: input #GFile
 889  * @relative_path: a given relative path string
 890  *
 891  * Resolves a relative path for @file to an absolute path.
 892  *
 893  * This call does no blocking I/O.
 894  *
 895  * Returns: (transfer full): #GFile to the resolved path.
 896  *     %NULL if @relative_path is %NULL or if @file is invalid.
 897  *     Free the returned object with g_object_unref().
 898  */
 899 GFile *
 900 g_file_resolve_relative_path (GFile      *file,
 901                               const char *relative_path)
 902 {
 903   GFileIface *iface;
 904
 905   g_return_val_if_fail (G_IS_FILE (file), NULL);
 906   g_return_val_if_fail (relative_path != NULL, NULL);
 907
 908   iface = G_FILE_GET_IFACE (file);
 909
 910   return (* iface->resolve_relative_path) (file, relative_path);
 911 }
 912
 913 /**
 914  * g_file_enumerate_children:
 915  * @file: input #GFile
 916  * @attributes: an attribute query string
 917  * @flags: a set of #GFileQueryInfoFlags
 918  * @cancellable: (allow-none): optional #GCancellable object,
 919  *     %NULL to ignore
 920  * @error: #GError for error reporting
 921  *
 922  * Gets the requested information about the files in a directory.
 923  * The result is a #GFileEnumerator object that will give out
 924  * #GFileInfo objects for all the files in the directory.
 925  *
 926  * The @attributes value is a string that specifies the file
 927  * attributes that should be gathered. It is not an error if
 928  * it's not possible to read a particular requested attribute
 929  * from a file - it just won't be set. @attributes should
 930  * be a comma-separated list of attributes or attribute wildcards.
 931  * The wildcard "*" means all attributes, and a wildcard like
 932  * "standard::*" means all attributes in the standard namespace.
 933  * An example attribute query be "standard::*,owner::user".
 934  * The standard attributes are available as defines, like
 935  * #G_FILE_ATTRIBUTE_STANDARD_NAME.
 936  *
 937  * If @cancellable is not %NULL, then the operation can be cancelled
 938  * by triggering the cancellable object from another thread. If the
 939  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
 940  * returned.
 941  *
 942  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
 943  * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
 944  * error will be returned. Other errors are possible too.
 945  *
 946  * Returns: (transfer full): A #GFileEnumerator if successful,
 947  *     %NULL on error. Free the returned object with g_object_unref().
 948  */
 949 GFileEnumerator *
 950 g_file_enumerate_children (GFile                *file,
 951                            const char           *attributes,
 952                            GFileQueryInfoFlags   flags,
 953                            GCancellable         *cancellable,
 954                            GError              **error)
 955 {
 956   GFileIface *iface;
 957
 958   g_return_val_if_fail (G_IS_FILE (file), NULL);
 959
 960   if (g_cancellable_set_error_if_cancelled (cancellable, error))
 961     return NULL;
 962
 963   iface = G_FILE_GET_IFACE (file);
 964
 965   if (iface->enumerate_children == NULL)
 966     {
 967       g_set_error_literal (error, G_IO_ERROR,
 968                            G_IO_ERROR_NOT_SUPPORTED,
 969                            _("Operation not supported"));
 970       return NULL;
 971     }
 972
 973   return (* iface->enumerate_children) (file, attributes, flags,
 974                                         cancellable, error);
 975 }
 976
 977 /**
 978  * g_file_enumerate_children_async:
 979  * @file: input #GFile
 980  * @attributes: an attribute query string
 981  * @flags: a set of #GFileQueryInfoFlags
 982  * @io_priority: the [I/O priority][io-priority] of the request
 983  * @cancellable: (allow-none): optional #GCancellable object,
 984  *     %NULL to ignore
 985  * @callback: (scope async): a #GAsyncReadyCallback to call when the
 986  *     request is satisfied
 987  * @user_data: (closure): the data to pass to callback function
 988  *
 989  * Asynchronously gets the requested information about the files
 990  * in a directory. The result is a #GFileEnumerator object that will
 991  * give out #GFileInfo objects for all the files in the directory.
 992  *
 993  * For more details, see g_file_enumerate_children() which is
 994  * the synchronous version of this call.
 995  *
 996  * When the operation is finished, @callback will be called. You can
 997  * then call g_file_enumerate_children_finish() to get the result of
 998  * the operation.
 999  */
1000 void
1001 g_file_enumerate_children_async (GFile               *file,
1002                                  const char          *attributes,
1003                                  GFileQueryInfoFlags  flags,
1004                                  int                  io_priority,
1005                                  GCancellable        *cancellable,
1006                                  GAsyncReadyCallback  callback,
1007                                  gpointer             user_data)
1008 {
1009   GFileIface *iface;
1010
1011   g_return_if_fail (G_IS_FILE (file));
1012
1013   iface = G_FILE_GET_IFACE (file);
1014   (* iface->enumerate_children_async) (file,
1015                                        attributes,
1016                                        flags,
1017                                        io_priority,
1018                                        cancellable,
1019                                        callback,
1020                                        user_data);
1021 }
1022
1023 /**
1024  * g_file_enumerate_children_finish:
1025  * @file: input #GFile
1026  * @res: a #GAsyncResult
1027  * @error: a #GError
1028  *
1029  * Finishes an async enumerate children operation.
1030  * See g_file_enumerate_children_async().
1031  *
1032  * Returns: (transfer full): a #GFileEnumerator or %NULL
1033  *     if an error occurred.
1034  *     Free the returned object with g_object_unref().
1035  */
1036 GFileEnumerator *
1037 g_file_enumerate_children_finish (GFile         *file,
1038                                   GAsyncResult  *res,
1039                                   GError       **error)
1040 {
1041   GFileIface *iface;
1042
1043   g_return_val_if_fail (G_IS_FILE (file), NULL);
1044   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1045
1046   if (g_async_result_legacy_propagate_error (res, error))
1047     return NULL;
1048
1049   iface = G_FILE_GET_IFACE (file);
1050   return (* iface->enumerate_children_finish) (file, res, error);
1051 }
1052
1053 /**
1054  * g_file_query_exists:
1055  * @file: input #GFile
1056  * @cancellable: (allow-none): optional #GCancellable object,
1057  *     %NULL to ignore
1058  *
1059  * Utility function to check if a particular file exists. This is
1060  * implemented using g_file_query_info() and as such does blocking I/O.
1061  *
1062  * Note that in many cases it is racy to first check for file existence
1063  * and then execute something based on the outcome of that, because the
1064  * file might have been created or removed in between the operations. The
1065  * general approach to handling that is to not check, but just do the
1066  * operation and handle the errors as they come.
1067  *
1068  * As an example of race-free checking, take the case of reading a file,
1069  * and if it doesn't exist, creating it. There are two racy versions: read
1070  * it, and on error create it; and: check if it exists, if not create it.
1071  * These can both result in two processes creating the file (with perhaps
1072  * a partially written file as the result). The correct approach is to
1073  * always try to create the file with g_file_create() which will either
1074  * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
1075  *
1076  * However, in many cases an existence check is useful in a user interface,
1077  * for instance to make a menu item sensitive/insensitive, so that you don't
1078  * have to fool users that something is possible and then just show an error
1079  * dialog. If you do this, you should make sure to also handle the errors
1080  * that can happen due to races when you execute the operation.
1081  *
1082  * Returns: %TRUE if the file exists (and can be detected without error),
1083  *     %FALSE otherwise (or if cancelled).
1084  */
1085 gboolean
1086 g_file_query_exists (GFile        *file,
1087                      GCancellable *cancellable)
1088 {
1089   GFileInfo *info;
1090
1091   g_return_val_if_fail (G_IS_FILE(file), FALSE);
1092
1093   info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE,
1094                             G_FILE_QUERY_INFO_NONE, cancellable, NULL);
1095   if (info != NULL)
1096     {
1097       g_object_unref (info);
1098       return TRUE;
1099     }
1100
1101   return FALSE;
1102 }
1103
1104 /**
1105  * g_file_query_file_type:
1106  * @file: input #GFile
1107  * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
1108  * @cancellable: (allow-none): optional #GCancellable object,
1109  *     %NULL to ignore
1110  *
1111  * Utility function to inspect the #GFileType of a file. This is
1112  * implemented using g_file_query_info() and as such does blocking I/O.
1113  *
1114  * The primary use case of this method is to check if a file is
1115  * a regular file, directory, or symlink.
1116  *
1117  * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
1118  *     if the file does not exist
1119  *
1120  * Since: 2.18
1121  */
1122 GFileType
1123 g_file_query_file_type (GFile               *file,
1124                         GFileQueryInfoFlags  flags,
1125                         GCancellable        *cancellable)
1126 {
1127   GFileInfo *info;
1128   GFileType file_type;
1129
1130   g_return_val_if_fail (G_IS_FILE(file), G_FILE_TYPE_UNKNOWN);
1131   info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE, flags,
1132                             cancellable, NULL);
1133   if (info != NULL)
1134     {
1135       file_type = g_file_info_get_file_type (info);
1136       g_object_unref (info);
1137     }
1138   else
1139     file_type = G_FILE_TYPE_UNKNOWN;
1140
1141   return file_type;
1142 }
1143
1144 /**
1145  * g_file_query_info:
1146  * @file: input #GFile
1147  * @attributes: an attribute query string
1148  * @flags: a set of #GFileQueryInfoFlags
1149  * @cancellable: (allow-none): optional #GCancellable object,
1150  *     %NULL to ignore
1151  * @error: a #GError
1152  *
1153  * Gets the requested information about specified @file.
1154  * The result is a #GFileInfo object that contains key-value
1155  * attributes (such as the type or size of the file).
1156  *
1157  * The @attributes value is a string that specifies the file
1158  * attributes that should be gathered. It is not an error if
1159  * it's not possible to read a particular requested attribute
1160  * from a file - it just won't be set. @attributes should be a
1161  * comma-separated list of attributes or attribute wildcards.
1162  * The wildcard "*" means all attributes, and a wildcard like
1163  * "standard::*" means all attributes in the standard namespace.
1164  * An example attribute query be "standard::*,owner::user".
1165  * The standard attributes are available as defines, like
1166  * #G_FILE_ATTRIBUTE_STANDARD_NAME.
1167  *
1168  * If @cancellable is not %NULL, then the operation can be cancelled
1169  * by triggering the cancellable object from another thread. If the
1170  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1171  * returned.
1172  *
1173  * For symlinks, normally the information about the target of the
1174  * symlink is returned, rather than information about the symlink
1175  * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
1176  * in @flags the information about the symlink itself will be returned.
1177  * Also, for symlinks that point to non-existing files the information
1178  * about the symlink itself will be returned.
1179  *
1180  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
1181  * returned. Other errors are possible too, and depend on what kind of
1182  * filesystem the file is on.
1183  *
1184  * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
1185  *     on error. Free the returned object with g_object_unref().
1186  */
1187 GFileInfo *
1188 g_file_query_info (GFile                *file,
1189                    const char           *attributes,
1190                    GFileQueryInfoFlags   flags,
1191                    GCancellable         *cancellable,
1192                    GError              **error)
1193 {
1194   GFileIface *iface;
1195
1196   g_return_val_if_fail (G_IS_FILE (file), NULL);
1197
1198   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1199     return NULL;
1200
1201   iface = G_FILE_GET_IFACE (file);
1202
1203   if (iface->query_info == NULL)
1204     {
1205       g_set_error_literal (error, G_IO_ERROR,
1206                            G_IO_ERROR_NOT_SUPPORTED,
1207                            _("Operation not supported"));
1208       return NULL;
1209     }
1210
1211   return (* iface->query_info) (file, attributes, flags, cancellable, error);
1212 }
1213
1214 /**
1215  * g_file_query_info_async:
1216  * @file: input #GFile
1217  * @attributes: an attribute query string
1218  * @flags: a set of #GFileQueryInfoFlags
1219  * @io_priority: the [I/O priority][io-priority] of the request
1220  * @cancellable: (allow-none): optional #GCancellable object,
1221  *     %NULL to ignore
1222  * @callback: (scope async): a #GAsyncReadyCallback to call when the
1223  *     request is satisfied
1224  * @user_data: (closure): the data to pass to callback function
1225  *
1226  * Asynchronously gets the requested information about specified @file.
1227  * The result is a #GFileInfo object that contains key-value attributes
1228  * (such as type or size for the file).
1229  *
1230  * For more details, see g_file_query_info() which is the synchronous
1231  * version of this call.
1232  *
1233  * When the operation is finished, @callback will be called. You can
1234  * then call g_file_query_info_finish() to get the result of the operation.
1235  */
1236 void
1237 g_file_query_info_async (GFile               *file,
1238                          const char          *attributes,
1239                          GFileQueryInfoFlags  flags,
1240                          int                  io_priority,
1241                          GCancellable        *cancellable,
1242                          GAsyncReadyCallback  callback,
1243                          gpointer             user_data)
1244 {
1245   GFileIface *iface;
1246
1247   g_return_if_fail (G_IS_FILE (file));
1248
1249   iface = G_FILE_GET_IFACE (file);
1250   (* iface->query_info_async) (file,
1251                                attributes,
1252                                flags,
1253                                io_priority,
1254                                cancellable,
1255                                callback,
1256                                user_data);
1257 }
1258
1259 /**
1260  * g_file_query_info_finish:
1261  * @file: input #GFile
1262  * @res: a #GAsyncResult
1263  * @error: a #GError
1264  *
1265  * Finishes an asynchronous file info query.
1266  * See g_file_query_info_async().
1267  *
1268  * Returns: (transfer full): #GFileInfo for given @file
1269  *     or %NULL on error. Free the returned object with
1270  *     g_object_unref().
1271  */
1272 GFileInfo *
1273 g_file_query_info_finish (GFile         *file,
1274                           GAsyncResult  *res,
1275                           GError       **error)
1276 {
1277   GFileIface *iface;
1278
1279   g_return_val_if_fail (G_IS_FILE (file), NULL);
1280   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1281
1282   if (g_async_result_legacy_propagate_error (res, error))
1283     return NULL;
1284
1285   iface = G_FILE_GET_IFACE (file);
1286   return (* iface->query_info_finish) (file, res, error);
1287 }
1288
1289 /**
1290  * g_file_query_filesystem_info:
1291  * @file: input #GFile
1292  * @attributes:  an attribute query string
1293  * @cancellable: (allow-none): optional #GCancellable object,
1294  *     %NULL to ignore
1295  * @error: a #GError
1296  *
1297  * Similar to g_file_query_info(), but obtains information
1298  * about the filesystem the @file is on, rather than the file itself.
1299  * For instance the amount of space available and the type of
1300  * the filesystem.
1301  *
1302  * The @attributes value is a string that specifies the attributes
1303  * that should be gathered. It is not an error if it's not possible
1304  * to read a particular requested attribute from a file - it just
1305  * won't be set. @attributes should be a comma-separated list of
1306  * attributes or attribute wildcards. The wildcard "*" means all
1307  * attributes, and a wildcard like "filesystem::*" means all attributes
1308  * in the filesystem namespace. The standard namespace for filesystem
1309  * attributes is "filesystem". Common attributes of interest are
1310  * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
1311  * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
1312  * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
1313  *
1314  * If @cancellable is not %NULL, then the operation can be cancelled
1315  * by triggering the cancellable object from another thread. If the
1316  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1317  * returned.
1318  *
1319  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
1320  * be returned. Other errors are possible too, and depend on what
1321  * kind of filesystem the file is on.
1322  *
1323  * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
1324  *     Free the returned object with g_object_unref().
1325  */
1326 GFileInfo *
1327 g_file_query_filesystem_info (GFile         *file,
1328                               const char    *attributes,
1329                               GCancellable  *cancellable,
1330                               GError       **error)
1331 {
1332   GFileIface *iface;
1333
1334   g_return_val_if_fail (G_IS_FILE (file), NULL);
1335
1336   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1337     return NULL;
1338
1339   iface = G_FILE_GET_IFACE (file);
1340
1341   if (iface->query_filesystem_info == NULL)
1342     {
1343       g_set_error_literal (error, G_IO_ERROR,
1344                            G_IO_ERROR_NOT_SUPPORTED,
1345                            _("Operation not supported"));
1346       return NULL;
1347     }
1348
1349   return (* iface->query_filesystem_info) (file, attributes, cancellable, error);
1350 }
1351
1352 /**
1353  * g_file_query_filesystem_info_async:
1354  * @file: input #GFile
1355  * @attributes: an attribute query string
1356  * @io_priority: the [I/O priority][io-priority] of the request
1357  * @cancellable: (allow-none): optional #GCancellable object,
1358  *     %NULL to ignore
1359  * @callback: (scope async): a #GAsyncReadyCallback to call
1360  *     when the request is satisfied
1361  * @user_data: (closure): the data to pass to callback function
1362  *
1363  * Asynchronously gets the requested information about the filesystem
1364  * that the specified @file is on. The result is a #GFileInfo object
1365  * that contains key-value attributes (such as type or size for the
1366  * file).
1367  *
1368  * For more details, see g_file_query_filesystem_info() which is the
1369  * synchronous version of this call.
1370  *
1371  * When the operation is finished, @callback will be called. You can
1372  * then call g_file_query_info_finish() to get the result of the
1373  * operation.
1374  */
1375 void
1376 g_file_query_filesystem_info_async (GFile               *file,
1377                                     const char          *attributes,
1378                                     int                  io_priority,
1379                                     GCancellable        *cancellable,
1380                                     GAsyncReadyCallback  callback,
1381                                     gpointer             user_data)
1382 {
1383   GFileIface *iface;
1384
1385   g_return_if_fail (G_IS_FILE (file));
1386
1387   iface = G_FILE_GET_IFACE (file);
1388   (* iface->query_filesystem_info_async) (file,
1389                                           attributes,
1390                                           io_priority,
1391                                           cancellable,
1392                                           callback,
1393                                           user_data);
1394 }
1395
1396 /**
1397  * g_file_query_filesystem_info_finish:
1398  * @file: input #GFile
1399  * @res: a #GAsyncResult
1400  * @error: a #GError
1401  *
1402  * Finishes an asynchronous filesystem info query.
1403  * See g_file_query_filesystem_info_async().
1404  *
1405  * Returns: (transfer full): #GFileInfo for given @file
1406  *     or %NULL on error.
1407  *     Free the returned object with g_object_unref().
1408  */
1409 GFileInfo *
1410 g_file_query_filesystem_info_finish (GFile         *file,
1411                                      GAsyncResult  *res,
1412                                      GError       **error)
1413 {
1414   GFileIface *iface;
1415
1416   g_return_val_if_fail (G_IS_FILE (file), NULL);
1417   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1418
1419   if (g_async_result_legacy_propagate_error (res, error))
1420     return NULL;
1421
1422   iface = G_FILE_GET_IFACE (file);
1423   return (* iface->query_filesystem_info_finish) (file, res, error);
1424 }
1425
1426 /**
1427  * g_file_find_enclosing_mount:
1428  * @file: input #GFile
1429  * @cancellable: (allow-none): optional #GCancellable object,
1430  *     %NULL to ignore
1431  * @error: a #GError
1432  *
1433  * Gets a #GMount for the #GFile.
1434  *
1435  * If the #GFileIface for @file does not have a mount (e.g.
1436  * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
1437  * and %NULL will be returned.
1438  *
1439  * If @cancellable is not %NULL, then the operation can be cancelled by
1440  * triggering the cancellable object from another thread. If the operation
1441  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
1442  *
1443  * Returns: (transfer full): a #GMount where the @file is located
1444  *     or %NULL on error.
1445  *     Free the returned object with g_object_unref().
1446  */
1447 GMount *
1448 g_file_find_enclosing_mount (GFile         *file,
1449                              GCancellable  *cancellable,
1450                              GError       **error)
1451 {
1452   GFileIface *iface;
1453
1454   g_return_val_if_fail (G_IS_FILE (file), NULL);
1455
1456   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1457     return NULL;
1458
1459   iface = G_FILE_GET_IFACE (file);
1460   if (iface->find_enclosing_mount == NULL)
1461     {
1462
1463       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND,
1464                            /* Translators: This is an error message when
1465                             * trying to find the enclosing (user visible)
1466                             * mount of a file, but none exists.
1467                             */
1468                            _("Containing mount does not exist"));
1469       return NULL;
1470     }
1471
1472   return (* iface->find_enclosing_mount) (file, cancellable, error);
1473 }
1474
1475 /**
1476  * g_file_find_enclosing_mount_async:
1477  * @file: a #GFile
1478  * @io_priority: the [I/O priority][io-priority] of the request
1479  * @cancellable: (allow-none): optional #GCancellable object,
1480  *     %NULL to ignore
1481  * @callback: (scope async): a #GAsyncReadyCallback to call
1482  *     when the request is satisfied
1483  * @user_data: (closure): the data to pass to callback function
1484  *
1485  * Asynchronously gets the mount for the file.
1486  *
1487  * For more details, see g_file_find_enclosing_mount() which is
1488  * the synchronous version of this call.
1489  *
1490  * When the operation is finished, @callback will be called.
1491  * You can then call g_file_find_enclosing_mount_finish() to
1492  * get the result of the operation.
1493  */
1494 void
1495 g_file_find_enclosing_mount_async (GFile              *file,
1496                                    int                   io_priority,
1497                                    GCancellable         *cancellable,
1498                                    GAsyncReadyCallback   callback,
1499                                    gpointer              user_data)
1500 {
1501   GFileIface *iface;
1502
1503   g_return_if_fail (G_IS_FILE (file));
1504
1505   iface = G_FILE_GET_IFACE (file);
1506   (* iface->find_enclosing_mount_async) (file,
1507                                          io_priority,
1508                                          cancellable,
1509                                          callback,
1510                                          user_data);
1511 }
1512
1513 /**
1514  * g_file_find_enclosing_mount_finish:
1515  * @file: a #GFile
1516  * @res: a #GAsyncResult
1517  * @error: a #GError
1518  *
1519  * Finishes an asynchronous find mount request.
1520  * See g_file_find_enclosing_mount_async().
1521  *
1522  * Returns: (transfer full): #GMount for given @file or %NULL on error.
1523  *     Free the returned object with g_object_unref().
1524  */
1525 GMount *
1526 g_file_find_enclosing_mount_finish (GFile         *file,
1527                                     GAsyncResult  *res,
1528                                     GError       **error)
1529 {
1530   GFileIface *iface;
1531
1532   g_return_val_if_fail (G_IS_FILE (file), NULL);
1533   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
1534
1535   if (g_async_result_legacy_propagate_error (res, error))
1536     return NULL;
1537
1538   iface = G_FILE_GET_IFACE (file);
1539   return (* iface->find_enclosing_mount_finish) (file, res, error);
1540 }
1541
1542
1543 /**
1544  * g_file_read:
1545  * @file: #GFile to read
1546  * @cancellable: (allow-none): a #GCancellable
1547  * @error: a #GError, or %NULL
1548  *
1549  * Opens a file for reading. The result is a #GFileInputStream that
1550  * can be used to read the contents of the file.
1551  *
1552  * If @cancellable is not %NULL, then the operation can be cancelled by
1553  * triggering the cancellable object from another thread. If the operation
1554  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
1555  *
1556  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
1557  * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
1558  * error will be returned. Other errors are possible too, and depend
1559  * on what kind of filesystem the file is on.
1560  *
1561  * Virtual: read_fn
1562  * Returns: (transfer full): #GFileInputStream or %NULL on error.
1563  *     Free the returned object with g_object_unref().
1564  */
1565 GFileInputStream *
1566 g_file_read (GFile         *file,
1567              GCancellable  *cancellable,
1568              GError       **error)
1569 {
1570   GFileIface *iface;
1571
1572   g_return_val_if_fail (G_IS_FILE (file), NULL);
1573
1574   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1575     return NULL;
1576
1577   iface = G_FILE_GET_IFACE (file);
1578
1579   if (iface->read_fn == NULL)
1580     {
1581       g_set_error_literal (error, G_IO_ERROR,
1582                            G_IO_ERROR_NOT_SUPPORTED,
1583                            _("Operation not supported"));
1584       return NULL;
1585     }
1586
1587   return (* iface->read_fn) (file, cancellable, error);
1588 }
1589
1590 /**
1591  * g_file_append_to:
1592  * @file: input #GFile
1593  * @flags: a set of #GFileCreateFlags
1594  * @cancellable: (allow-none): optional #GCancellable object,
1595  *     %NULL to ignore
1596  * @error: a #GError, or %NULL
1597  *
1598  * Gets an output stream for appending data to the file.
1599  * If the file doesn't already exist it is created.
1600  *
1601  * By default files created are generally readable by everyone,
1602  * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1603  * will be made readable only to the current user, to the level that
1604  * is supported on the target filesystem.
1605  *
1606  * If @cancellable is not %NULL, then the operation can be cancelled
1607  * by triggering the cancellable object from another thread. If the
1608  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1609  * returned.
1610  *
1611  * Some file systems don't allow all file names, and may return an
1612  * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
1613  * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
1614  * possible too, and depend on what kind of filesystem the file is on.
1615  *
1616  * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
1617  *     Free the returned object with g_object_unref().
1618  */
1619 GFileOutputStream *
1620 g_file_append_to (GFile             *file,
1621                   GFileCreateFlags   flags,
1622                   GCancellable      *cancellable,
1623                   GError           **error)
1624 {
1625   GFileIface *iface;
1626
1627   g_return_val_if_fail (G_IS_FILE (file), NULL);
1628
1629   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1630     return NULL;
1631
1632   iface = G_FILE_GET_IFACE (file);
1633
1634   if (iface->append_to == NULL)
1635     {
1636       g_set_error_literal (error, G_IO_ERROR,
1637                            G_IO_ERROR_NOT_SUPPORTED,
1638                            _("Operation not supported"));
1639       return NULL;
1640     }
1641
1642   return (* iface->append_to) (file, flags, cancellable, error);
1643 }
1644
1645 /**
1646  * g_file_create:
1647  * @file: input #GFile
1648  * @flags: a set of #GFileCreateFlags
1649  * @cancellable: (allow-none): optional #GCancellable object,
1650  *     %NULL to ignore
1651  * @error: a #GError, or %NULL
1652  *
1653  * Creates a new file and returns an output stream for writing to it.
1654  * The file must not already exist.
1655  *
1656  * By default files created are generally readable by everyone,
1657  * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1658  * will be made readable only to the current user, to the level
1659  * that is supported on the target filesystem.
1660  *
1661  * If @cancellable is not %NULL, then the operation can be cancelled
1662  * by triggering the cancellable object from another thread. If the
1663  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1664  * returned.
1665  *
1666  * If a file or directory with this name already exists the
1667  * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
1668  * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
1669  * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
1670  * be returned. Other errors are possible too, and depend on what kind
1671  * of filesystem the file is on.
1672  *
1673  * Returns: (transfer full): a #GFileOutputStream for the newly created
1674  *     file, or %NULL on error.
1675  *     Free the returned object with g_object_unref().
1676  */
1677 GFileOutputStream *
1678 g_file_create (GFile             *file,
1679                GFileCreateFlags   flags,
1680                GCancellable      *cancellable,
1681                GError           **error)
1682 {
1683   GFileIface *iface;
1684
1685   g_return_val_if_fail (G_IS_FILE (file), NULL);
1686
1687   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1688     return NULL;
1689
1690   iface = G_FILE_GET_IFACE (file);
1691
1692   if (iface->create == NULL)
1693     {
1694       g_set_error_literal (error, G_IO_ERROR,
1695                            G_IO_ERROR_NOT_SUPPORTED,
1696                            _("Operation not supported"));
1697       return NULL;
1698     }
1699
1700   return (* iface->create) (file, flags, cancellable, error);
1701 }
1702
1703 /**
1704  * g_file_replace:
1705  * @file: input #GFile
1706  * @etag: (allow-none): an optional [entity tag][gfile-etag]
1707  *     for the current #GFile, or #NULL to ignore
1708  * @make_backup: %TRUE if a backup should be created
1709  * @flags: a set of #GFileCreateFlags
1710  * @cancellable: (allow-none): optional #GCancellable object,
1711  *     %NULL to ignore
1712  * @error: a #GError, or %NULL
1713  *
1714  * Returns an output stream for overwriting the file, possibly
1715  * creating a backup copy of the file first. If the file doesn't exist,
1716  * it will be created.
1717  *
1718  * This will try to replace the file in the safest way possible so
1719  * that any errors during the writing will not affect an already
1720  * existing copy of the file. For instance, for local files it
1721  * may write to a temporary file and then atomically rename over
1722  * the destination when the stream is closed.
1723  *
1724  * By default files created are generally readable by everyone,
1725  * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1726  * will be made readable only to the current user, to the level that
1727  * is supported on the target filesystem.
1728  *
1729  * If @cancellable is not %NULL, then the operation can be cancelled
1730  * by triggering the cancellable object from another thread. If the
1731  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1732  * returned.
1733  *
1734  * If you pass in a non-%NULL @etag value and @file already exists, then
1735  * this value is compared to the current entity tag of the file, and if
1736  * they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This
1737  * generally means that the file has been changed since you last read
1738  * it. You can get the new etag from g_file_output_stream_get_etag()
1739  * after you've finished writing and closed the #GFileOutputStream. When
1740  * you load a new file you can use g_file_input_stream_query_info() to
1741  * get the etag of the file.
1742  *
1743  * If @make_backup is %TRUE, this function will attempt to make a
1744  * backup of the current file before overwriting it. If this fails
1745  * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
1746  * want to replace anyway, try again with @make_backup set to %FALSE.
1747  *
1748  * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
1749  * be returned, and if the file is some other form of non-regular file
1750  * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
1751  * file systems don't allow all file names, and may return an
1752  * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
1753  * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
1754  * possible too, and depend on what kind of filesystem the file is on.
1755  *
1756  * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
1757  *     Free the returned object with g_object_unref().
1758  */
1759 GFileOutputStream *
1760 g_file_replace (GFile             *file,
1761                 const char        *etag,
1762                 gboolean           make_backup,
1763                 GFileCreateFlags   flags,
1764                 GCancellable      *cancellable,
1765                 GError           **error)
1766 {
1767   GFileIface *iface;
1768
1769   g_return_val_if_fail (G_IS_FILE (file), NULL);
1770
1771   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1772     return NULL;
1773
1774   iface = G_FILE_GET_IFACE (file);
1775
1776   if (iface->replace == NULL)
1777     {
1778       g_set_error_literal (error, G_IO_ERROR,
1779                            G_IO_ERROR_NOT_SUPPORTED,
1780                            _("Operation not supported"));
1781       return NULL;
1782     }
1783
1784   /* Handle empty tag string as NULL in consistent way. */
1785   if (etag && *etag == 0)
1786     etag = NULL;
1787
1788   return (* iface->replace) (file, etag, make_backup, flags, cancellable, error);
1789 }
1790
1791 /**
1792  * g_file_open_readwrite:
1793  * @file: #GFile to open
1794  * @cancellable: (allow-none): a #GCancellable
1795  * @error: a #GError, or %NULL
1796  *
1797  * Opens an existing file for reading and writing. The result is
1798  * a #GFileIOStream that can be used to read and write the contents
1799  * of the file.
1800  *
1801  * If @cancellable is not %NULL, then the operation can be cancelled
1802  * by triggering the cancellable object from another thread. If the
1803  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1804  * returned.
1805  *
1806  * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
1807  * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
1808  * error will be returned. Other errors are possible too, and depend on
1809  * what kind of filesystem the file is on. Note that in many non-local
1810  * file cases read and write streams are not supported, so make sure you
1811  * really need to do read and write streaming, rather than just opening
1812  * for reading or writing.
1813  *
1814  * Returns: (transfer full): #GFileIOStream or %NULL on error.
1815  *     Free the returned object with g_object_unref().
1816  *
1817  * Since: 2.22
1818  */
1819 GFileIOStream *
1820 g_file_open_readwrite (GFile         *file,
1821                        GCancellable  *cancellable,
1822                        GError       **error)
1823 {
1824   GFileIface *iface;
1825
1826   g_return_val_if_fail (G_IS_FILE (file), NULL);
1827
1828   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1829     return NULL;
1830
1831   iface = G_FILE_GET_IFACE (file);
1832
1833   if (iface->open_readwrite == NULL)
1834     {
1835       g_set_error_literal (error, G_IO_ERROR,
1836                            G_IO_ERROR_NOT_SUPPORTED,
1837                            _("Operation not supported"));
1838       return NULL;
1839     }
1840
1841   return (* iface->open_readwrite) (file, cancellable, error);
1842 }
1843
1844 /**
1845  * g_file_create_readwrite:
1846  * @file: a #GFile
1847  * @flags: a set of #GFileCreateFlags
1848  * @cancellable: (allow-none): optional #GCancellable object,
1849  *     %NULL to ignore
1850  * @error: return location for a #GError, or %NULL
1851  *
1852  * Creates a new file and returns a stream for reading and
1853  * writing to it. The file must not already exist.
1854  *
1855  * By default files created are generally readable by everyone,
1856  * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
1857  * will be made readable only to the current user, to the level
1858  * that is supported on the target filesystem.
1859  *
1860  * If @cancellable is not %NULL, then the operation can be cancelled
1861  * by triggering the cancellable object from another thread. If the
1862  * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
1863  * returned.
1864  *
1865  * If a file or directory with this name already exists, the
1866  * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
1867  * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
1868  * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
1869  * will be returned. Other errors are possible too, and depend on what
1870  * kind of filesystem the file is on.
1871  *
1872  * Note that in many non-local file cases read and write streams are
1873  * not supported, so make sure you really need to do read and write
1874  * streaming, rather than just opening for reading or writing.
1875  *
1876  * Returns: (transfer full): a #GFileIOStream for the newly created
1877  *     file, or %NULL on error.
1878  *     Free the returned object with g_object_unref().
1879  *
1880  * Since: 2.22
1881  */
1882 GFileIOStream *
1883 g_file_create_readwrite (GFile             *file,
1884                          GFileCreateFlags   flags,
1885                          GCancellable      *cancellable,
1886                          GError           **error)
1887 {
1888   GFileIface *iface;
1889
1890   g_return_val_if_fail (G_IS_FILE (file), NULL);
1891
1892   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1893     return NULL;
1894
1895   iface = G_FILE_GET_IFACE (file);
1896
1897   if (iface->create_readwrite == NULL)
1898     {
1899       g_set_error_literal (error, G_IO_ERROR,
1900                            G_IO_ERROR_NOT_SUPPORTED,
1901                            _("Operation not supported"));
1902       return NULL;
1903     }
1904
1905   return (* iface->create_readwrite) (file, flags, cancellable, error);
1906 }
1907
1908 /**
1909  * g_file_replace_readwrite:
1910  * @file: a #GFile
1911  * @etag: (allow-none): an optional [entity tag][gfile-etag]
1912  *     for the current #GFile, or #NULL to ignore
1913  * @make_backup: %TRUE if a backup should be created
1914  * @flags: a set of #GFileCreateFlags
1915  * @cancellable: (allow-none): optional #GCancellable object,
1916  *     %NULL to ignore
1917  * @error: return location for a #GError, or %NULL
1918  *
1919  * Returns an output stream for overwriting the file in readwrite mode,
1920  * possibly creating a backup copy of the file first. If the file doesn't
1921  * exist, it will be created.
1922  *
1923  * For details about the behaviour, see g_file_replace() which does the
1924  * same thing but returns an output stream only.
1925  *
1926  * Note that in many non-local file cases read and write streams are not
1927  * supported, so make sure you really need to do read and write streaming,
1928  * rather than just opening for reading or writing.
1929  *
1930  * Returns: (transfer full): a #GFileIOStream or %NULL on error.
1931  *     Free the returned object with g_object_unref().
1932  *
1933  * Since: 2.22
1934  */
1935 GFileIOStream *
1936 g_file_replace_readwrite (GFile             *file,
1937                           const char        *etag,
1938                           gboolean           make_backup,
1939                           GFileCreateFlags   flags,
1940                           GCancellable      *cancellable,
1941                           GError           **error)
1942 {
1943   GFileIface *iface;
1944
1945   g_return_val_if_fail (G_IS_FILE (file), NULL);
1946
1947   if (g_cancellable_set_error_if_cancelled (cancellable, error))
1948     return NULL;
1949
1950   iface = G_FILE_GET_IFACE (file);
1951
1952   if (iface->replace_readwrite == NULL)
1953     {
1954       g_set_error_literal (error, G_IO_ERROR,
1955                            G_IO_ERROR_NOT_SUPPORTED,
1956                            _("Operation not supported"));
1957       return NULL;
1958     }
1959
1960   return (* iface->replace_readwrite) (file, etag, make_backup, flags, cancellable, error);
1961 }
1962
1963 /**
1964  * g_file_read_async:
1965  * @file: input #GFile
1966  * @io_priority: the [I/O priority][io-priority] of the request
1967  * @cancellable: (allow-none): optional #GCancellable object,
1968  *     %NULL to ignore
1969  * @callback: (scope async): a #GAsyncReadyCallback to call
1970  *     when the request is satisfied
1971  * @user_data: (closure): the data to pass to callback function
1972  *
1973  * Asynchronously opens @file for reading.
1974  *
1975  * For more details, see g_file_read() which is
1976  * the synchronous version of this call.
1977  *
1978  * When the operation is finished, @callback will be called.
1979  * You can then call g_file_read_finish() to get the result
1980  * of the operation.
1981  */
1982 void
1983 g_file_read_async (GFile               *file,
1984                    int                  io_priority,
1985                    GCancellable        *cancellable,
1986                    GAsyncReadyCallback  callback,
1987                    gpointer             user_data)
1988 {
1989   GFileIface *iface;
1990
1991   g_return_if_fail (G_IS_FILE (file));
1992
1993   iface = G_FILE_GET_IFACE (file);
1994   (* iface->read_async) (file,
1995                          io_priority,
1996                          cancellable,
1997                          callback,
1998                          user_data);
1999 }
2000
2001 /**
2002  * g_file_read_finish:
2003  * @file: input #GFile
2004  * @res: a #GAsyncResult
2005  * @error: a #GError, or %NULL
2006  *
2007  * Finishes an asynchronous file read operation started with
2008  * g_file_read_async().
2009  *
2010  * Returns: (transfer full): a #GFileInputStream or %NULL on error.
2011  *     Free the returned object with g_object_unref().
2012  */
2013 GFileInputStream *
2014 g_file_read_finish (GFile         *file,
2015                     GAsyncResult  *res,
2016                     GError       **error)
2017 {
2018   GFileIface *iface;
2019
2020   g_return_val_if_fail (G_IS_FILE (file), NULL);
2021   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2022
2023   if (g_async_result_legacy_propagate_error (res, error))
2024     return NULL;
2025
2026   iface = G_FILE_GET_IFACE (file);
2027   return (* iface->read_finish) (file, res, error);
2028 }
2029
2030 /**
2031  * g_file_append_to_async:
2032  * @file: input #GFile
2033  * @flags: a set of #GFileCreateFlags
2034  * @io_priority: the [I/O priority][io-priority] of the request
2035  * @cancellable: (allow-none): optional #GCancellable object,
2036  *     %NULL to ignore
2037  * @callback: (scope async): a #GAsyncReadyCallback to call
2038  *     when the request is satisfied
2039  * @user_data: (closure): the data to pass to callback function
2040  *
2041  * Asynchronously opens @file for appending.
2042  *
2043  * For more details, see g_file_append_to() which is
2044  * the synchronous version of this call.
2045  *
2046  * When the operation is finished, @callback will be called.
2047  * You can then call g_file_append_to_finish() to get the result
2048  * of the operation.
2049  */
2050 void
2051 g_file_append_to_async (GFile               *file,
2052                         GFileCreateFlags     flags,
2053                         int                  io_priority,
2054                         GCancellable        *cancellable,
2055                         GAsyncReadyCallback  callback,
2056                         gpointer             user_data)
2057 {
2058   GFileIface *iface;
2059
2060   g_return_if_fail (G_IS_FILE (file));
2061
2062   iface = G_FILE_GET_IFACE (file);
2063   (* iface->append_to_async) (file,
2064                               flags,
2065                               io_priority,
2066                               cancellable,
2067                               callback,
2068                               user_data);
2069 }
2070
2071 /**
2072  * g_file_append_to_finish:
2073  * @file: input #GFile
2074  * @res: #GAsyncResult
2075  * @error: a #GError, or %NULL
2076  *
2077  * Finishes an asynchronous file append operation started with
2078  * g_file_append_to_async().
2079  *
2080  * Returns: (transfer full): a valid #GFileOutputStream
2081  *     or %NULL on error.
2082  *     Free the returned object with g_object_unref().
2083  */
2084 GFileOutputStream *
2085 g_file_append_to_finish (GFile         *file,
2086                          GAsyncResult  *res,
2087                          GError       **error)
2088 {
2089   GFileIface *iface;
2090
2091   g_return_val_if_fail (G_IS_FILE (file), NULL);
2092   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2093
2094   if (g_async_result_legacy_propagate_error (res, error))
2095     return NULL;
2096
2097   iface = G_FILE_GET_IFACE (file);
2098   return (* iface->append_to_finish) (file, res, error);
2099 }
2100
2101 /**
2102  * g_file_create_async:
2103  * @file: input #GFile
2104  * @flags: a set of #GFileCreateFlags
2105  * @io_priority: the [I/O priority][io-priority] of the request
2106  * @cancellable: (allow-none): optional #GCancellable object,
2107  *     %NULL to ignore
2108  * @callback: (scope async): a #GAsyncReadyCallback to call
2109  *     when the request is satisfied
2110  * @user_data: (closure): the data to pass to callback function
2111  *
2112  * Asynchronously creates a new file and returns an output stream
2113  * for writing to it. The file must not already exist.
2114  *
2115  * For more details, see g_file_create() which is
2116  * the synchronous version of this call.
2117  *
2118  * When the operation is finished, @callback will be called.
2119  * You can then call g_file_create_finish() to get the result
2120  * of the operation.
2121  */
2122 void
2123 g_file_create_async (GFile               *file,
2124                      GFileCreateFlags     flags,
2125                      int                  io_priority,
2126                      GCancellable        *cancellable,
2127                      GAsyncReadyCallback  callback,
2128                      gpointer             user_data)
2129 {
2130   GFileIface *iface;
2131
2132   g_return_if_fail (G_IS_FILE (file));
2133
2134   iface = G_FILE_GET_IFACE (file);
2135   (* iface->create_async) (file,
2136                            flags,
2137                            io_priority,
2138                            cancellable,
2139                            callback,
2140                            user_data);
2141 }
2142
2143 /**
2144  * g_file_create_finish:
2145  * @file: input #GFile
2146  * @res: a #GAsyncResult
2147  * @error: a #GError, or %NULL
2148  *
2149  * Finishes an asynchronous file create operation started with
2150  * g_file_create_async().
2151  *
2152  * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
2153  *     Free the returned object with g_object_unref().
2154  */
2155 GFileOutputStream *
2156 g_file_create_finish (GFile         *file,
2157                       GAsyncResult  *res,
2158                       GError       **error)
2159 {
2160   GFileIface *iface;
2161
2162   g_return_val_if_fail (G_IS_FILE (file), NULL);
2163   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2164
2165   if (g_async_result_legacy_propagate_error (res, error))
2166     return NULL;
2167
2168   iface = G_FILE_GET_IFACE (file);
2169   return (* iface->create_finish) (file, res, error);
2170 }
2171
2172 /**
2173  * g_file_replace_async:
2174  * @file: input #GFile
2175  * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
2176  *     or %NULL to ignore
2177  * @make_backup: %TRUE if a backup should be created
2178  * @flags: a set of #GFileCreateFlags
2179  * @io_priority: the [I/O priority][io-priority] of the request
2180  * @cancellable: (allow-none): optional #GCancellable object,
2181  *     %NULL to ignore
2182  * @callback: (scope async): a #GAsyncReadyCallback to call
2183  *     when the request is satisfied
2184  * @user_data: (closure): the data to pass to callback function
2185  *
2186  * Asynchronously overwrites the file, replacing the contents,
2187  * possibly creating a backup copy of the file first.
2188  *
2189  * For more details, see g_file_replace() which is
2190  * the synchronous version of this call.
2191  *
2192  * When the operation is finished, @callback will be called.
2193  * You can then call g_file_replace_finish() to get the result
2194  * of the operation.
2195  */
2196 void
2197 g_file_replace_async (GFile               *file,
2198                       const char          *etag,
2199                       gboolean             make_backup,
2200                       GFileCreateFlags     flags,
2201                       int                  io_priority,
2202                       GCancellable        *cancellable,
2203                       GAsyncReadyCallback  callback,
2204                       gpointer             user_data)
2205 {
2206   GFileIface *iface;
2207
2208   g_return_if_fail (G_IS_FILE (file));
2209
2210   iface = G_FILE_GET_IFACE (file);
2211   (* iface->replace_async) (file,
2212                             etag,
2213                             make_backup,
2214                             flags,
2215                             io_priority,
2216                             cancellable,
2217                             callback,
2218                             user_data);
2219 }
2220
2221 /**
2222  * g_file_replace_finish:
2223  * @file: input #GFile
2224  * @res: a #GAsyncResult
2225  * @error: a #GError, or %NULL
2226  *
2227  * Finishes an asynchronous file replace operation started with
2228  * g_file_replace_async().
2229  *
2230  * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
2231  *     Free the returned object with g_object_unref().
2232  */
2233 GFileOutputStream *
2234 g_file_replace_finish (GFile         *file,
2235                        GAsyncResult  *res,
2236                        GError       **error)
2237 {
2238   GFileIface *iface;
2239
2240   g_return_val_if_fail (G_IS_FILE (file), NULL);
2241   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2242
2243   if (g_async_result_legacy_propagate_error (res, error))
2244     return NULL;
2245
2246   iface = G_FILE_GET_IFACE (file);
2247   return (* iface->replace_finish) (file, res, error);
2248 }
2249
2250 /**
2251  * g_file_open_readwrite_async
2252  * @file: input #GFile
2253  * @io_priority: the [I/O priority][io-priority] of the request
2254  * @cancellable: (allow-none): optional #GCancellable object,
2255  *     %NULL to ignore
2256  * @callback: (scope async): a #GAsyncReadyCallback to call
2257  *     when the request is satisfied
2258  * @user_data: (closure): the data to pass to callback function
2259  *
2260  * Asynchronously opens @file for reading and writing.
2261  *
2262  * For more details, see g_file_open_readwrite() which is
2263  * the synchronous version of this call.
2264  *
2265  * When the operation is finished, @callback will be called.
2266  * You can then call g_file_open_readwrite_finish() to get
2267  * the result of the operation.
2268  *
2269  * Since: 2.22
2270  */
2271 void
2272 g_file_open_readwrite_async (GFile               *file,
2273                              int                  io_priority,
2274                              GCancellable        *cancellable,
2275                              GAsyncReadyCallback  callback,
2276                              gpointer             user_data)
2277 {
2278   GFileIface *iface;
2279
2280   g_return_if_fail (G_IS_FILE (file));
2281
2282   iface = G_FILE_GET_IFACE (file);
2283   (* iface->open_readwrite_async) (file,
2284                                    io_priority,
2285                                    cancellable,
2286                                    callback,
2287                                    user_data);
2288 }
2289
2290 /**
2291  * g_file_open_readwrite_finish:
2292  * @file: input #GFile
2293  * @res: a #GAsyncResult
2294  * @error: a #GError, or %NULL
2295  *
2296  * Finishes an asynchronous file read operation started with
2297  * g_file_open_readwrite_async().
2298  *
2299  * Returns: (transfer full): a #GFileIOStream or %NULL on error.
2300  *     Free the returned object with g_object_unref().
2301  *
2302  * Since: 2.22
2303  */
2304 GFileIOStream *
2305 g_file_open_readwrite_finish (GFile         *file,
2306                               GAsyncResult  *res,
2307                               GError       **error)
2308 {
2309   GFileIface *iface;
2310
2311   g_return_val_if_fail (G_IS_FILE (file), NULL);
2312   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2313
2314   if (g_async_result_legacy_propagate_error (res, error))
2315     return NULL;
2316
2317   iface = G_FILE_GET_IFACE (file);
2318   return (* iface->open_readwrite_finish) (file, res, error);
2319 }
2320
2321 /**
2322  * g_file_create_readwrite_async:
2323  * @file: input #GFile
2324  * @flags: a set of #GFileCreateFlags
2325  * @io_priority: the [I/O priority][io-priority] of the request
2326  * @cancellable: (allow-none): optional #GCancellable object,
2327  *     %NULL to ignore
2328  * @callback: (scope async): a #GAsyncReadyCallback to call
2329  *     when the request is satisfied
2330  * @user_data: (closure): the data to pass to callback function
2331  *
2332  * Asynchronously creates a new file and returns a stream
2333  * for reading and writing to it. The file must not already exist.
2334  *
2335  * For more details, see g_file_create_readwrite() which is
2336  * the synchronous version of this call.
2337  *
2338  * When the operation is finished, @callback will be called.
2339  * You can then call g_file_create_readwrite_finish() to get
2340  * the result of the operation.
2341  *
2342  * Since: 2.22
2343  */
2344 void
2345 g_file_create_readwrite_async (GFile               *file,
2346                                GFileCreateFlags     flags,
2347                                int                  io_priority,
2348                                GCancellable        *cancellable,
2349                                GAsyncReadyCallback  callback,
2350                                gpointer             user_data)
2351 {
2352   GFileIface *iface;
2353
2354   g_return_if_fail (G_IS_FILE (file));
2355
2356   iface = G_FILE_GET_IFACE (file);
2357   (* iface->create_readwrite_async) (file,
2358                                      flags,
2359                                      io_priority,
2360                                      cancellable,
2361                                      callback,
2362                                      user_data);
2363 }
2364
2365 /**
2366  * g_file_create_readwrite_finish:
2367  * @file: input #GFile
2368  * @res: a #GAsyncResult
2369  * @error: a #GError, or %NULL
2370  *
2371  * Finishes an asynchronous file create operation started with
2372  * g_file_create_readwrite_async().
2373  *
2374  * Returns: (transfer full): a #GFileIOStream or %NULL on error.
2375  *     Free the returned object with g_object_unref().
2376  *
2377  * Since: 2.22
2378  */
2379 GFileIOStream *
2380 g_file_create_readwrite_finish (GFile         *file,
2381                                 GAsyncResult  *res,
2382                                 GError       **error)
2383 {
2384   GFileIface *iface;
2385
2386   g_return_val_if_fail (G_IS_FILE (file), NULL);
2387   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2388
2389   if (g_async_result_legacy_propagate_error (res, error))
2390     return NULL;
2391
2392   iface = G_FILE_GET_IFACE (file);
2393   return (* iface->create_readwrite_finish) (file, res, error);
2394 }
2395
2396 /**
2397  * g_file_replace_readwrite_async:
2398  * @file: input #GFile
2399  * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
2400  *     or %NULL to ignore
2401  * @make_backup: %TRUE if a backup should be created
2402  * @flags: a set of #GFileCreateFlags
2403  * @io_priority: the [I/O priority][io-priority] of the request
2404  * @cancellable: (allow-none): optional #GCancellable object,
2405  *     %NULL to ignore
2406  * @callback: (scope async): a #GAsyncReadyCallback to call
2407  *     when the request is satisfied
2408  * @user_data: (closure): the data to pass to callback function
2409  *
2410  * Asynchronously overwrites the file in read-write mode,
2411  * replacing the contents, possibly creating a backup copy
2412  * of the file first.
2413  *
2414  * For more details, see g_file_replace_readwrite() which is
2415  * the synchronous version of this call.
2416  *
2417  * When the operation is finished, @callback will be called.
2418  * You can then call g_file_replace_readwrite_finish() to get
2419  * the result of the operation.
2420  *
2421  * Since: 2.22
2422  */
2423 void
2424 g_file_replace_readwrite_async (GFile               *file,
2425                                 const char          *etag,
2426                                 gboolean             make_backup,
2427                                 GFileCreateFlags     flags,
2428                                 int                  io_priority,
2429                                 GCancellable        *cancellable,
2430                                 GAsyncReadyCallback  callback,
2431                                 gpointer             user_data)
2432 {
2433   GFileIface *iface;
2434
2435   g_return_if_fail (G_IS_FILE (file));
2436
2437   iface = G_FILE_GET_IFACE (file);
2438   (* iface->replace_readwrite_async) (file,
2439                                       etag,
2440                                       make_backup,
2441                                       flags,
2442                                       io_priority,
2443                                       cancellable,
2444                                       callback,
2445                                       user_data);
2446 }
2447
2448 /**
2449  * g_file_replace_readwrite_finish:
2450  * @file: input #GFile
2451  * @res: a #GAsyncResult
2452  * @error: a #GError, or %NULL
2453  *
2454  * Finishes an asynchronous file replace operation started with
2455  * g_file_replace_readwrite_async().
2456  *
2457  * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
2458  *     Free the returned object with g_object_unref().
2459  *
2460  * Since: 2.22
2461  */
2462 GFileIOStream *
2463 g_file_replace_readwrite_finish (GFile         *file,
2464                                  GAsyncResult  *res,
2465                                  GError       **error)
2466 {
2467   GFileIface *iface;
2468
2469   g_return_val_if_fail (G_IS_FILE (file), NULL);
2470   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
2471
2472   if (g_async_result_legacy_propagate_error (res, error))
2473     return NULL;
2474
2475   iface = G_FILE_GET_IFACE (file);
2476   return (* iface->replace_readwrite_finish) (file, res, error);
2477 }
2478
2479 static gboolean
2480 copy_symlink (GFile           *destination,
2481               GFileCopyFlags   flags,
2482               GCancellable    *cancellable,
2483               const char      *target,
2484               GError         **error)
2485 {
2486   GError *my_error;
2487   gboolean tried_delete;
2488   GFileInfo *info;
2489   GFileType file_type;
2490
2491   tried_delete = FALSE;
2492
2493  retry:
2494   my_error = NULL;
2495   if (!g_file_make_symbolic_link (destination, target, cancellable, &my_error))
2496     {
2497       /* Maybe it already existed, and we want to overwrite? */
2498       if (!tried_delete && (flags & G_FILE_COPY_OVERWRITE) &&
2499           my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_EXISTS)
2500         {
2501           g_clear_error (&my_error);
2502
2503           /* Don't overwrite if the destination is a directory */
2504           info = g_file_query_info (destination, G_FILE_ATTRIBUTE_STANDARD_TYPE,
2505                                     G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2506                                     cancellable, &my_error);
2507           if (info != NULL)
2508             {
2509               file_type = g_file_info_get_file_type (info);
2510               g_object_unref (info);
2511
2512               if (file_type == G_FILE_TYPE_DIRECTORY)
2513                 {
2514                   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_IS_DIRECTORY,
2515                                        _("Can't copy over directory"));
2516                   return FALSE;
2517                 }
2518             }
2519
2520           if (!g_file_delete (destination, cancellable, error))
2521             return FALSE;
2522
2523           tried_delete = TRUE;
2524           goto retry;
2525         }
2526             /* Nah, fail */
2527       g_propagate_error (error, my_error);
2528       return FALSE;
2529     }
2530
2531   return TRUE;
2532 }
2533
2534 static GFileInputStream *
2535 open_source_for_copy (GFile           *source,
2536                       GFile           *destination,
2537                       GFileCopyFlags   flags,
2538                       GCancellable    *cancellable,
2539                       GError         **error)
2540 {
2541   GError *my_error;
2542   GFileInputStream *ret;
2543   GFileInfo *info;
2544   GFileType file_type;
2545
2546   my_error = NULL;
2547   ret = g_file_read (source, cancellable, &my_error);
2548   if (ret != NULL)
2549     return ret;
2550
2551   /* There was an error opening the source, try to set a good error for it: */
2552   if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_IS_DIRECTORY)
2553     {
2554       /* The source is a directory, don't fail with WOULD_RECURSE immediately,
2555        * as that is less useful to the app. Better check for errors on the
2556        * target instead.
2557        */
2558       g_error_free (my_error);
2559       my_error = NULL;
2560
2561       info = g_file_query_info (destination, G_FILE_ATTRIBUTE_STANDARD_TYPE,
2562                                 G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2563                                 cancellable, &my_error);
2564       if (info != NULL &&
2565           g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_STANDARD_TYPE))
2566         {
2567           file_type = g_file_info_get_file_type (info);
2568           g_object_unref (info);
2569
2570           if (flags & G_FILE_COPY_OVERWRITE)
2571             {
2572               if (file_type == G_FILE_TYPE_DIRECTORY)
2573                 {
2574                   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_MERGE,
2575                                        _("Can't copy directory over directory"));
2576                   return NULL;
2577                 }
2578               /* continue to would_recurse error */
2579             }
2580           else
2581             {
2582               g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_EXISTS,
2583                                    _("Target file exists"));
2584               return NULL;
2585             }
2586         }
2587       else
2588         {
2589           /* Error getting info from target, return that error
2590            * (except for NOT_FOUND, which is no error here)
2591            */
2592           g_clear_object (&info);
2593           if (my_error != NULL && !g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
2594             {
2595               g_propagate_error (error, my_error);
2596               return NULL;
2597             }
2598           g_clear_error (&my_error);
2599         }
2600
2601       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_WOULD_RECURSE,
2602                            _("Can't recursively copy directory"));
2603       return NULL;
2604     }
2605
2606   g_propagate_error (error, my_error);
2607   return NULL;
2608 }
2609
2610 static gboolean
2611 should_copy (GFileAttributeInfo *info,
2612              gboolean            copy_all_attributes,
2613              gboolean            skip_perms)
2614 {
2615   if (skip_perms && strcmp(info->name, "unix::mode") == 0)
2616         return FALSE;
2617
2618   if (copy_all_attributes)
2619     return info->flags & G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED;
2620   return info->flags & G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE;
2621 }
2622
2623 static gboolean
2624 build_attribute_list_for_copy (GFile                  *file,
2625                                GFileCopyFlags          flags,
2626                                char                  **out_attributes,
2627                                GCancellable           *cancellable,
2628                                GError                **error)
2629 {
2630   gboolean ret = FALSE;
2631   GFileAttributeInfoList *attributes = NULL, *namespaces = NULL;
2632   GString *s = NULL;
2633   gboolean first;
2634   int i;
2635   gboolean copy_all_attributes;
2636   gboolean skip_perms;
2637
2638   copy_all_attributes = flags & G_FILE_COPY_ALL_METADATA;
2639   skip_perms = (flags & G_FILE_COPY_TARGET_DEFAULT_PERMS) != 0;
2640
2641   /* Ignore errors here, if the target supports no attributes there is
2642    * nothing to copy.  We still honor the cancellable though.
2643    */
2644   attributes = g_file_query_settable_attributes (file, cancellable, NULL);
2645   if (g_cancellable_set_error_if_cancelled (cancellable, error))
2646     goto out;
2647
2648   namespaces = g_file_query_writable_namespaces (file, cancellable, NULL);
2649   if (g_cancellable_set_error_if_cancelled (cancellable, error))
2650     goto out;
2651
2652   if (attributes == NULL && namespaces == NULL)
2653     goto out;
2654
2655   first = TRUE;
2656   s = g_string_new ("");
2657
2658   if (attributes)
2659     {
2660       for (i = 0; i < attributes->n_infos; i++)
2661         {
2662           if (should_copy (&attributes->infos[i], copy_all_attributes, skip_perms))
2663             {
2664               if (first)
2665                 first = FALSE;
2666               else
2667                 g_string_append_c (s, ',');
2668
2669               g_string_append (s, attributes->infos[i].name);
2670             }
2671         }
2672     }
2673
2674   if (namespaces)
2675     {
2676       for (i = 0; i < namespaces->n_infos; i++)
2677         {
2678           if (should_copy (&namespaces->infos[i], copy_all_attributes, FALSE))
2679             {
2680               if (first)
2681                 first = FALSE;
2682               else
2683                 g_string_append_c (s, ',');
2684
2685               g_string_append (s, namespaces->infos[i].name);
2686               g_string_append (s, "::*");
2687             }
2688         }
2689     }
2690
2691   ret = TRUE;
2692   *out_attributes = g_string_free (s, FALSE);
2693   s = NULL;
2694  out:
2695   if (s)
2696     g_string_free (s, TRUE);
2697   if (attributes)
2698     g_file_attribute_info_list_unref (attributes);
2699   if (namespaces)
2700     g_file_attribute_info_list_unref (namespaces);
2701
2702   return ret;
2703 }
2704
2705 /**
2706  * g_file_copy_attributes:
2707  * @source: a #GFile with attributes
2708  * @destination: a #GFile to copy attributes to
2709  * @flags: a set of #GFileCopyFlags
2710  * @cancellable: (allow-none): optional #GCancellable object,
2711  *     %NULL to ignore
2712  * @error: a #GError, %NULL to ignore
2713  *
2714  * Copies the file attributes from @source to @destination.
2715  *
2716  * Normally only a subset of the file attributes are copied,
2717  * those that are copies in a normal file copy operation
2718  * (which for instance does not include e.g. owner). However
2719  * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
2720  * all the metadata that is possible to copy is copied. This
2721  * is useful when implementing move by copy + delete source.
2722  *
2723  * Returns: %TRUE if the attributes were copied successfully,
2724  *     %FALSE otherwise.
2725  */
2726 gboolean
2727 g_file_copy_attributes (GFile           *source,
2728                         GFile           *destination,
2729                         GFileCopyFlags   flags,
2730                         GCancellable    *cancellable,
2731                         GError         **error)
2732 {
2733   char *attrs_to_read;
2734   gboolean res;
2735   GFileInfo *info;
2736   gboolean source_nofollow_symlinks;
2737
2738   if (!build_attribute_list_for_copy (destination, flags, &attrs_to_read,
2739                                       cancellable, error))
2740     return FALSE;
2741
2742   source_nofollow_symlinks = flags & G_FILE_COPY_NOFOLLOW_SYMLINKS;
2743
2744   /* Ignore errors here, if we can't read some info (e.g. if it doesn't exist)
2745    * we just don't copy it.
2746    */
2747   info = g_file_query_info (source, attrs_to_read,
2748                             source_nofollow_symlinks ? G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS:0,
2749                             cancellable,
2750                             NULL);
2751
2752   g_free (attrs_to_read);
2753
2754   res = TRUE;
2755   if  (info)
2756     {
2757       res = g_file_set_attributes_from_info (destination,
2758                                              info,
2759                                              G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
2760                                              cancellable,
2761                                              error);
2762       g_object_unref (info);
2763     }
2764
2765   return res;
2766 }
2767
2768 static gboolean
2769 copy_stream_with_progress (GInputStream           *in,
2770                            GOutputStream          *out,
2771                            GFile                  *source,
2772                            GCancellable           *cancellable,
2773                            GFileProgressCallback   progress_callback,
2774                            gpointer                progress_callback_data,
2775                            GError                **error)
2776 {
2777   gssize n_read, n_written;
2778   goffset current_size;
2779   char buffer[1024*64], *p;
2780   gboolean res;
2781   goffset total_size;
2782   GFileInfo *info;
2783
2784   total_size = -1;
2785   /* avoid performance impact of querying total size when it's not needed */
2786   if (progress_callback)
2787     {
2788       info = g_file_input_stream_query_info (G_FILE_INPUT_STREAM (in),
2789                                              G_FILE_ATTRIBUTE_STANDARD_SIZE,
2790                                              cancellable, NULL);
2791       if (info)
2792         {
2793           if (g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_STANDARD_SIZE))
2794             total_size = g_file_info_get_size (info);
2795           g_object_unref (info);
2796         }
2797
2798       if (total_size == -1)
2799         {
2800           info = g_file_query_info (source,
2801                                     G_FILE_ATTRIBUTE_STANDARD_SIZE,
2802                                     G_FILE_QUERY_INFO_NONE,
2803                                     cancellable, NULL);
2804           if (info)
2805             {
2806               if (g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_STANDARD_SIZE))
2807                 total_size = g_file_info_get_size (info);
2808               g_object_unref (info);
2809             }
2810         }
2811     }
2812
2813   if (total_size == -1)
2814     total_size = 0;
2815
2816   current_size = 0;
2817   res = TRUE;
2818   while (TRUE)
2819     {
2820       n_read = g_input_stream_read (in, buffer, sizeof (buffer), cancellable, error);
2821       if (n_read == -1)
2822         {
2823           res = FALSE;
2824           break;
2825         }
2826
2827       if (n_read == 0)
2828         break;
2829
2830       current_size += n_read;
2831
2832       p = buffer;
2833       while (n_read > 0)
2834         {
2835           n_written = g_output_stream_write (out, p, n_read, cancellable, error);
2836           if (n_written == -1)
2837             {
2838               res = FALSE;
2839               break;
2840             }
2841
2842           p += n_written;
2843           n_read -= n_written;
2844         }
2845
2846       if (!res)
2847         break;
2848
2849       if (progress_callback)
2850         progress_callback (current_size, total_size, progress_callback_data);
2851     }
2852
2853   /* Make sure we send full copied size */
2854   if (progress_callback)
2855     progress_callback (current_size, total_size, progress_callback_data);
2856
2857   return res;
2858 }
2859
2860 #ifdef HAVE_SPLICE
2861
2862 static gboolean
2863 do_splice (int     fd_in,
2864            loff_t *off_in,
2865            int     fd_out,
2866            loff_t *off_out,
2867            size_t  len,
2868            long   *bytes_transferd,
2869            GError **error)
2870 {
2871   long result;
2872
2873 retry:
2874   result = splice (fd_in, off_in, fd_out, off_out, len, SPLICE_F_MORE);
2875
2876   if (result == -1)
2877     {
2878       int errsv = errno;
2879
2880       if (errsv == EINTR)
2881         goto retry;
2882       else if (errsv == ENOSYS || errsv == EINVAL)
2883         g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
2884                              _("Splice not supported"));
2885       else
2886         g_set_error (error, G_IO_ERROR,
2887                      g_io_error_from_errno (errsv),
2888                      _("Error splicing file: %s"),
2889                      g_strerror (errsv));
2890
2891       return FALSE;
2892     }
2893
2894   *bytes_transferd = result;
2895   return TRUE;
2896 }
2897
2898 static gboolean
2899 splice_stream_with_progress (GInputStream           *in,
2900                              GOutputStream          *out,
2901                              GCancellable           *cancellable,
2902                              GFileProgressCallback   progress_callback,
2903                              gpointer                progress_callback_data,
2904                              GError                **error)
2905 {
2906   int buffer[2] = { -1, -1 };
2907   gboolean res;
2908   goffset total_size;
2909   loff_t offset_in;
2910   loff_t offset_out;
2911   int fd_in, fd_out;
2912
2913   fd_in = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (in));
2914   fd_out = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (out));
2915
2916   if (!g_unix_open_pipe (buffer, FD_CLOEXEC, error))
2917     return FALSE;
2918
2919   total_size = -1;
2920   /* avoid performance impact of querying total size when it's not needed */
2921   if (progress_callback)
2922     {
2923       struct stat sbuf;
2924
2925       if (fstat (fd_in, &sbuf) == 0)
2926         total_size = sbuf.st_size;
2927     }
2928
2929   if (total_size == -1)
2930     total_size = 0;
2931
2932   offset_in = offset_out = 0;
2933   res = FALSE;
2934   while (TRUE)
2935     {
2936       long n_read;
2937       long n_written;
2938
2939       if (g_cancellable_set_error_if_cancelled (cancellable, error))
2940         break;
2941
2942       if (!do_splice (fd_in, &offset_in, buffer[1], NULL, 1024*64, &n_read, error))
2943         break;
2944
2945       if (n_read == 0)
2946         {
2947           res = TRUE;
2948           break;
2949         }
2950
2951       while (n_read > 0)
2952         {
2953           if (g_cancellable_set_error_if_cancelled (cancellable, error))
2954             goto out;
2955
2956           if (!do_splice (buffer[0], NULL, fd_out, &offset_out, n_read, &n_written, error))
2957             goto out;
2958
2959           n_read -= n_written;
2960         }
2961
2962       if (progress_callback)
2963         progress_callback (offset_in, total_size, progress_callback_data);
2964     }
2965
2966   /* Make sure we send full copied size */
2967   if (progress_callback)
2968     progress_callback (offset_in, total_size, progress_callback_data);
2969
2970   if (!g_close (buffer[0], error))
2971     goto out;
2972   buffer[0] = -1;
2973   if (!g_close (buffer[1], error))
2974     goto out;
2975   buffer[1] = -1;
2976  out:
2977   if (buffer[0] != -1)
2978     (void) g_close (buffer[0], NULL);
2979   if (buffer[1] != -1)
2980     (void) g_close (buffer[1], NULL);
2981
2982   return res;
2983 }
2984 #endif
2985
2986 #ifdef __linux__
2987 static gboolean
2988 btrfs_reflink_with_progress (GInputStream           *in,
2989                              GOutputStream          *out,
2990                              GFileInfo              *info,
2991                              GCancellable           *cancellable,
2992                              GFileProgressCallback   progress_callback,
2993                              gpointer                progress_callback_data,
2994                              GError                **error)
2995 {
2996   goffset source_size;
2997   int fd_in, fd_out;
2998   int ret;
2999
3000   fd_in = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (in));
3001   fd_out = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (out));
3002
3003   if (progress_callback)
3004     source_size = g_file_info_get_size (info);
3005
3006   /* Btrfs clone ioctl properties:
3007    *  - Works at the inode level
3008    *  - Doesn't work with directories
3009    *  - Always follows symlinks (source and destination)
3010    *
3011    * By the time we get here, *in and *out are both regular files */
3012   ret = ioctl (fd_out, BTRFS_IOC_CLONE, fd_in);
3013
3014   if (ret < 0)
3015     {
3016       if (errno == EXDEV)
3017         g_set_error_literal (error, G_IO_ERROR,
3018                              G_IO_ERROR_NOT_SUPPORTED,
3019                              _("Copy (reflink/clone) between mounts is not supported"));
3020       else if (errno == EINVAL)
3021         g_set_error_literal (error, G_IO_ERROR,
3022                              G_IO_ERROR_NOT_SUPPORTED,
3023                              _("Copy (reflink/clone) is not supported or invalid"));
3024       else
3025         /* Most probably something odd happened; retry with fallback */
3026         g_set_error_literal (error, G_IO_ERROR,
3027                              G_IO_ERROR_NOT_SUPPORTED,
3028                              _("Copy (reflink/clone) is not supported or didn't work"));
3029       /* We retry with fallback for all error cases because Btrfs is currently
3030        * unstable, and so we can't trust it to do clone properly.
3031        * In addition, any hard errors here would cause the same failure in the
3032        * fallback manual copy as well. */
3033       return FALSE;
3034     }
3035
3036   /* Make sure we send full copied size */
3037   if (progress_callback)
3038     progress_callback (source_size, source_size, progress_callback_data);
3039
3040   return TRUE;
3041 }
3042 #endif
3043
3044 static gboolean
3045 file_copy_fallback (GFile                  *source,
3046                     GFile                  *destination,
3047                     GFileCopyFlags          flags,
3048                     GCancellable           *cancellable,
3049                     GFileProgressCallback   progress_callback,
3050                     gpointer                progress_callback_data,
3051                     GError                **error)
3052 {
3053   gboolean ret = FALSE;
3054   GFileInputStream *file_in = NULL;
3055   GInputStream *in = NULL;
3056   GOutputStream *out = NULL;
3057   GFileInfo *info = NULL;
3058   const char *target;
3059   char *attrs_to_read;
3060   gboolean do_set_attributes = FALSE;
3061
3062   /* need to know the file type */
3063   info = g_file_query_info (source,
3064                             G_FILE_ATTRIBUTE_STANDARD_TYPE "," G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET,
3065                             G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3066                             cancellable,
3067                             error);
3068   if (!info)
3069     goto out;
3070
3071   /* Maybe copy the symlink? */
3072   if ((flags & G_FILE_COPY_NOFOLLOW_SYMLINKS) &&
3073       g_file_info_get_file_type (info) == G_FILE_TYPE_SYMBOLIC_LINK)
3074     {
3075       target = g_file_info_get_symlink_target (info);
3076       if (target)
3077         {
3078           if (!copy_symlink (destination, flags, cancellable, target, error))
3079             goto out;
3080
3081           ret = TRUE;
3082           goto out;
3083         }
3084         /* ... else fall back on a regular file copy */
3085     }
3086   /* Handle "special" files (pipes, device nodes, ...)? */
3087   else if (g_file_info_get_file_type (info) == G_FILE_TYPE_SPECIAL)
3088     {
3089       /* FIXME: could try to recreate device nodes and others? */
3090       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
3091                            _("Can't copy special file"));
3092       goto out;
3093     }
3094
3095   /* Everything else should just fall back on a regular copy. */
3096
3097   file_in = open_source_for_copy (source, destination, flags, cancellable, error);
3098   if (!file_in)
3099     goto out;
3100   in = G_INPUT_STREAM (file_in);
3101
3102   if (!build_attribute_list_for_copy (destination, flags, &attrs_to_read,
3103                                       cancellable, error))
3104     goto out;
3105
3106   if (attrs_to_read != NULL)
3107     {
3108       GError *tmp_error = NULL;
3109
3110       /* Ok, ditch the previous lightweight info (on Unix we just
3111        * called lstat()); at this point we gather all the information
3112        * we need about the source from the opened file descriptor.
3113        */
3114       g_object_unref (info);
3115
3116       info = g_file_input_stream_query_info (file_in, attrs_to_read,
3117                                              cancellable, &tmp_error);
3118       if (!info)
3119         {
3120           /* Not all gvfs backends implement query_info_on_read(), we
3121            * can just fall back to the pathname again.
3122            * https://bugzilla.gnome.org/706254
3123            */
3124           if (g_error_matches (tmp_error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3125             {
3126               g_clear_error (&tmp_error);
3127               info = g_file_query_info (source, attrs_to_read, G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3128                                         cancellable, error);
3129             }
3130           else
3131             {
3132               g_free (attrs_to_read);
3133               g_propagate_error (error, tmp_error);
3134               goto out;
3135             }
3136         }
3137       g_free (attrs_to_read);
3138       if (!info)
3139         goto out;
3140
3141       do_set_attributes = TRUE;
3142     }
3143
3144   /* In the local file path, we pass down the source info which
3145    * includes things like unix::mode, to ensure that the target file
3146    * is not created with different permissions from the source file.
3147    *
3148    * If a future API like g_file_replace_with_info() is added, switch
3149    * this code to use that.
3150    */
3151   if (G_IS_LOCAL_FILE (destination))
3152     {
3153       if (flags & G_FILE_COPY_OVERWRITE)
3154         out = (GOutputStream*)_g_local_file_output_stream_replace (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3155                                                                    FALSE, NULL,
3156                                                                    flags & G_FILE_COPY_BACKUP,
3157                                                                    G_FILE_CREATE_REPLACE_DESTINATION,
3158                                                                    info,
3159                                                                    cancellable, error);
3160       else
3161         out = (GOutputStream*)_g_local_file_output_stream_create (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3162                                                                   FALSE, 0, info,
3163                                                                   cancellable, error);
3164     }
3165   else if (flags & G_FILE_COPY_OVERWRITE)
3166     {
3167       out = (GOutputStream *)g_file_replace (destination,
3168                                              NULL,
3169                                              flags & G_FILE_COPY_BACKUP,
3170                                              G_FILE_CREATE_REPLACE_DESTINATION,
3171                                              cancellable, error);
3172     }
3173   else
3174     {
3175       out = (GOutputStream *)g_file_create (destination, 0, cancellable, error);
3176     }
3177
3178   if (!out)
3179     goto out;
3180
3181 #ifdef __linux__
3182   if (G_IS_FILE_DESCRIPTOR_BASED (in) && G_IS_FILE_DESCRIPTOR_BASED (out))
3183     {
3184       GError *reflink_err = NULL;
3185
3186       if (!btrfs_reflink_with_progress (in, out, info, cancellable,
3187                                         progress_callback, progress_callback_data,
3188                                         &reflink_err))
3189         {
3190           if (g_error_matches (reflink_err, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3191             {
3192               g_clear_error (&reflink_err);
3193             }
3194           else
3195             {
3196               g_propagate_error (error, reflink_err);
3197               goto out;
3198             }
3199         }
3200       else
3201         {
3202           ret = TRUE;
3203           goto out;
3204         }
3205     }
3206 #endif
3207
3208 #ifdef HAVE_SPLICE
3209   if (G_IS_FILE_DESCRIPTOR_BASED (in) && G_IS_FILE_DESCRIPTOR_BASED (out))
3210     {
3211       GError *splice_err = NULL;
3212
3213       if (!splice_stream_with_progress (in, out, cancellable,
3214                                         progress_callback, progress_callback_data,
3215                                         &splice_err))
3216         {
3217           if (g_error_matches (splice_err, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3218             {
3219               g_clear_error (&splice_err);
3220             }
3221           else
3222             {
3223               g_propagate_error (error, splice_err);
3224               goto out;
3225             }
3226         }
3227       else
3228         {
3229           ret = TRUE;
3230           goto out;
3231         }
3232     }
3233
3234 #endif
3235
3236   /* A plain read/write loop */
3237   if (!copy_stream_with_progress (in, out, source, cancellable,
3238                                   progress_callback, progress_callback_data,
3239                                   error))
3240     goto out;
3241
3242   ret = TRUE;
3243  out:
3244   if (in)
3245     {
3246       /* Don't care about errors in source here */
3247       (void) g_input_stream_close (in, cancellable, NULL);
3248       g_object_unref (in);
3249     }
3250
3251   if (out)
3252     {
3253       /* But write errors on close are bad! */
3254       if (!g_output_stream_close (out, cancellable, ret ? error : NULL))
3255         ret = FALSE;
3256       g_object_unref (out);
3257     }
3258
3259   /* Ignore errors here. Failure to copy metadata is not a hard error */
3260   /* TODO: set these attributes /before/ we do the rename() on Unix */
3261   if (ret && do_set_attributes)
3262     {
3263       g_file_set_attributes_from_info (destination,
3264                                        info,
3265                                        G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3266                                        cancellable,
3267                                        NULL);
3268     }
3269
3270   g_clear_object (&info);
3271
3272   return ret;
3273 }
3274
3275 /**
3276  * g_file_copy:
3277  * @source: input #GFile
3278  * @destination: destination #GFile
3279  * @flags: set of #GFileCopyFlags
3280  * @cancellable: (allow-none): optional #GCancellable object,
3281  *     %NULL to ignore
3282  * @progress_callback: (allow-none) (scope call): function to callback with
3283  *     progress information, or %NULL if progress information is not needed
3284  * @progress_callback_data: (closure): user data to pass to @progress_callback
3285  * @error: #GError to set on error, or %NULL
3286  *
3287  * Copies the file @source to the location specified by @destination.
3288  * Can not handle recursive copies of directories.
3289  *
3290  * If the flag #G_FILE_COPY_OVERWRITE is specified an already
3291  * existing @destination file is overwritten.
3292  *
3293  * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
3294  * will be copied as symlinks, otherwise the target of the
3295  * @source symlink will be copied.
3296  *
3297  * If @cancellable is not %NULL, then the operation can be cancelled by
3298  * triggering the cancellable object from another thread. If the operation
3299  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3300  *
3301  * If @progress_callback is not %NULL, then the operation can be monitored
3302  * by setting this to a #GFileProgressCallback function.
3303  * @progress_callback_data will be passed to this function. It is guaranteed
3304  * that this callback will be called after all data has been transferred with
3305  * the total number of bytes copied during the operation.
3306  *
3307  * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
3308  * is returned, independent on the status of the @destination.
3309  *
3310  * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
3311  * the error %G_IO_ERROR_EXISTS is returned.
3312  *
3313  * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3314  * error is returned. If trying to overwrite a directory with a directory the
3315  * %G_IO_ERROR_WOULD_MERGE error is returned.
3316  *
3317  * If the source is a directory and the target does not exist, or
3318  * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
3319  * %G_IO_ERROR_WOULD_RECURSE error is returned.
3320  *
3321  * If you are interested in copying the #GFile object itself (not the on-disk
3322  * file), see g_file_dup().
3323  *
3324  * Returns: %TRUE on success, %FALSE otherwise.
3325  */
3326 gboolean
3327 g_file_copy (GFile                  *source,
3328              GFile                  *destination,
3329              GFileCopyFlags          flags,
3330              GCancellable           *cancellable,
3331              GFileProgressCallback   progress_callback,
3332              gpointer                progress_callback_data,
3333              GError                **error)
3334 {
3335   GFileIface *iface;
3336   GError *my_error;
3337   gboolean res;
3338
3339   g_return_val_if_fail (G_IS_FILE (source), FALSE);
3340   g_return_val_if_fail (G_IS_FILE (destination), FALSE);
3341
3342   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3343     return FALSE;
3344
3345   iface = G_FILE_GET_IFACE (destination);
3346   if (iface->copy)
3347     {
3348       my_error = NULL;
3349       res = (* iface->copy) (source, destination,
3350                              flags, cancellable,
3351                              progress_callback, progress_callback_data,
3352                              &my_error);
3353
3354       if (res)
3355         return TRUE;
3356
3357       if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3358         {
3359           g_propagate_error (error, my_error);
3360               return FALSE;
3361         }
3362       else
3363         g_clear_error (&my_error);
3364     }
3365
3366   /* If the types are different, and the destination method failed
3367    * also try the source method
3368    */
3369   if (G_OBJECT_TYPE (source) != G_OBJECT_TYPE (destination))
3370     {
3371       iface = G_FILE_GET_IFACE (source);
3372
3373       if (iface->copy)
3374         {
3375           my_error = NULL;
3376           res = (* iface->copy) (source, destination,
3377                                  flags, cancellable,
3378                                  progress_callback, progress_callback_data,
3379                                  &my_error);
3380
3381           if (res)
3382             return TRUE;
3383
3384           if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3385             {
3386               g_propagate_error (error, my_error);
3387               return FALSE;
3388             }
3389           else
3390             g_clear_error (&my_error);
3391         }
3392     }
3393
3394   return file_copy_fallback (source, destination, flags, cancellable,
3395                              progress_callback, progress_callback_data,
3396                              error);
3397 }
3398
3399 /**
3400  * g_file_copy_async: (skip)
3401  * @source: input #GFile
3402  * @destination: destination #GFile
3403  * @flags: set of #GFileCopyFlags
3404  * @io_priority: the [I/O priority][io-priority] of the request
3405  * @cancellable: (allow-none): optional #GCancellable object,
3406  *     %NULL to ignore
3407  * @progress_callback: (allow-none): function to callback with progress
3408  *     information, or %NULL if progress information is not needed
3409  * @progress_callback_data: (closure): user data to pass to @progress_callback
3410  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
3411  * @user_data: the data to pass to callback function
3412  *
3413  * Copies the file @source to the location specified by @destination
3414  * asynchronously. For details of the behaviour, see g_file_copy().
3415  *
3416  * If @progress_callback is not %NULL, then that function that will be called
3417  * just like in g_file_copy(). The callback will run in the default main context
3418  * of the thread calling g_file_copy_async() — the same context as @callback is
3419  * run in.
3420  *
3421  * When the operation is finished, @callback will be called. You can then call
3422  * g_file_copy_finish() to get the result of the operation.
3423  */
3424 void
3425 g_file_copy_async (GFile                  *source,
3426                    GFile                  *destination,
3427                    GFileCopyFlags          flags,
3428                    int                     io_priority,
3429                    GCancellable           *cancellable,
3430                    GFileProgressCallback   progress_callback,
3431                    gpointer                progress_callback_data,
3432                    GAsyncReadyCallback     callback,
3433                    gpointer                user_data)
3434 {
3435   GFileIface *iface;
3436
3437   g_return_if_fail (G_IS_FILE (source));
3438   g_return_if_fail (G_IS_FILE (destination));
3439
3440   iface = G_FILE_GET_IFACE (source);
3441   (* iface->copy_async) (source,
3442                          destination,
3443                          flags,
3444                          io_priority,
3445                          cancellable,
3446                          progress_callback,
3447                          progress_callback_data,
3448                          callback,
3449                          user_data);
3450 }
3451
3452 /**
3453  * g_file_copy_finish:
3454  * @file: input #GFile
3455  * @res: a #GAsyncResult
3456  * @error: a #GError, or %NULL
3457  *
3458  * Finishes copying the file started with g_file_copy_async().
3459  *
3460  * Returns: a %TRUE on success, %FALSE on error.
3461  */
3462 gboolean
3463 g_file_copy_finish (GFile         *file,
3464                     GAsyncResult  *res,
3465                     GError       **error)
3466 {
3467   GFileIface *iface;
3468
3469   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3470   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), FALSE);
3471
3472   if (g_async_result_legacy_propagate_error (res, error))
3473     return FALSE;
3474
3475   iface = G_FILE_GET_IFACE (file);
3476   return (* iface->copy_finish) (file, res, error);
3477 }
3478
3479 /**
3480  * g_file_move:
3481  * @source: #GFile pointing to the source location
3482  * @destination: #GFile pointing to the destination location
3483  * @flags: set of #GFileCopyFlags
3484  * @cancellable: (allow-none): optional #GCancellable object,
3485  *     %NULL to ignore
3486  * @progress_callback: (allow-none) (scope call): #GFileProgressCallback
3487  *     function for updates
3488  * @progress_callback_data: (closure): gpointer to user data for
3489  *     the callback function
3490  * @error: #GError for returning error conditions, or %NULL
3491  *
3492  * Tries to move the file or directory @source to the location specified
3493  * by @destination. If native move operations are supported then this is
3494  * used, otherwise a copy + delete fallback is used. The native
3495  * implementation may support moving directories (for instance on moves
3496  * inside the same filesystem), but the fallback code does not.
3497  *
3498  * If the flag #G_FILE_COPY_OVERWRITE is specified an already
3499  * existing @destination file is overwritten.
3500  *
3501  * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
3502  * will be copied as symlinks, otherwise the target of the
3503  * @source symlink will be copied.
3504  *
3505  * If @cancellable is not %NULL, then the operation can be cancelled by
3506  * triggering the cancellable object from another thread. If the operation
3507  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3508  *
3509  * If @progress_callback is not %NULL, then the operation can be monitored
3510  * by setting this to a #GFileProgressCallback function.
3511  * @progress_callback_data will be passed to this function. It is
3512  * guaranteed that this callback will be called after all data has been
3513  * transferred with the total number of bytes copied during the operation.
3514  *
3515  * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
3516  * error is returned, independent on the status of the @destination.
3517  *
3518  * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
3519  * then the error %G_IO_ERROR_EXISTS is returned.
3520  *
3521  * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3522  * error is returned. If trying to overwrite a directory with a directory the
3523  * %G_IO_ERROR_WOULD_MERGE error is returned.
3524  *
3525  * If the source is a directory and the target does not exist, or
3526  * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
3527  * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
3528  * move operation isn't available).
3529  *
3530  * Returns: %TRUE on successful move, %FALSE otherwise.
3531  */
3532 gboolean
3533 g_file_move (GFile                  *source,
3534              GFile                  *destination,
3535              GFileCopyFlags          flags,
3536              GCancellable           *cancellable,
3537              GFileProgressCallback   progress_callback,
3538              gpointer                progress_callback_data,
3539              GError                **error)
3540 {
3541   GFileIface *iface;
3542   GError *my_error;
3543   gboolean res;
3544
3545   g_return_val_if_fail (G_IS_FILE (source), FALSE);
3546   g_return_val_if_fail (G_IS_FILE (destination), FALSE);
3547
3548   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3549     return FALSE;
3550
3551   iface = G_FILE_GET_IFACE (destination);
3552   if (iface->move)
3553     {
3554       my_error = NULL;
3555       res = (* iface->move) (source, destination,
3556                              flags, cancellable,
3557                              progress_callback, progress_callback_data,
3558                              &my_error);
3559
3560       if (res)
3561         return TRUE;
3562
3563       if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3564         {
3565           g_propagate_error (error, my_error);
3566           return FALSE;
3567         }
3568       else
3569         g_clear_error (&my_error);
3570     }
3571
3572   /* If the types are different, and the destination method failed
3573    * also try the source method
3574    */
3575   if (G_OBJECT_TYPE (source) != G_OBJECT_TYPE (destination))
3576     {
3577       iface = G_FILE_GET_IFACE (source);
3578
3579       if (iface->move)
3580         {
3581           my_error = NULL;
3582           res = (* iface->move) (source, destination,
3583                                  flags, cancellable,
3584                                  progress_callback, progress_callback_data,
3585                                  &my_error);
3586
3587           if (res)
3588             return TRUE;
3589
3590           if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3591             {
3592               g_propagate_error (error, my_error);
3593               return FALSE;
3594             }
3595           else
3596             g_clear_error (&my_error);
3597         }
3598     }
3599
3600   if (flags & G_FILE_COPY_NO_FALLBACK_FOR_MOVE)
3601     {
3602       g_set_error_literal (error, G_IO_ERROR,
3603                            G_IO_ERROR_NOT_SUPPORTED,
3604                            _("Operation not supported"));
3605       return FALSE;
3606     }
3607
3608   flags |= G_FILE_COPY_ALL_METADATA;
3609   if (!g_file_copy (source, destination, flags, cancellable,
3610                     progress_callback, progress_callback_data,
3611                     error))
3612     return FALSE;
3613
3614   return g_file_delete (source, cancellable, error);
3615 }
3616
3617 /**
3618  * g_file_make_directory:
3619  * @file: input #GFile
3620  * @cancellable: (allow-none): optional #GCancellable object,
3621  *     %NULL to ignore
3622  * @error: a #GError, or %NULL
3623  *
3624  * Creates a directory. Note that this will only create a child directory
3625  * of the immediate parent directory of the path or URI given by the #GFile.
3626  * To recursively create directories, see g_file_make_directory_with_parents().
3627  * This function will fail if the parent directory does not exist, setting
3628  * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
3629  * creating directories, this function will fail, setting @error to
3630  * %G_IO_ERROR_NOT_SUPPORTED.
3631  *
3632  * For a local #GFile the newly created directory will have the default
3633  * (current) ownership and permissions of the current process.
3634  *
3635  * If @cancellable is not %NULL, then the operation can be cancelled by
3636  * triggering the cancellable object from another thread. If the operation
3637  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3638  *
3639  * Returns: %TRUE on successful creation, %FALSE otherwise.
3640  */
3641 gboolean
3642 g_file_make_directory (GFile         *file,
3643                        GCancellable  *cancellable,
3644                        GError       **error)
3645 {
3646   GFileIface *iface;
3647
3648   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3649
3650   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3651     return FALSE;
3652
3653   iface = G_FILE_GET_IFACE (file);
3654
3655   if (iface->make_directory == NULL)
3656     {
3657       g_set_error_literal (error, G_IO_ERROR,
3658                            G_IO_ERROR_NOT_SUPPORTED,
3659                            _("Operation not supported"));
3660       return FALSE;
3661     }
3662
3663   return (* iface->make_directory) (file, cancellable, error);
3664 }
3665
3666 /**
3667  * g_file_make_directory_async:
3668  * @file: input #GFile
3669  * @io_priority: the [I/O priority][io-priority] of the request
3670  * @cancellable: (allow-none): optional #GCancellable object,
3671  *     %NULL to ignore
3672  * @callback: a #GAsyncReadyCallback to call
3673  *     when the request is satisfied
3674  * @user_data: the data to pass to callback function
3675  *
3676  * Asynchronously creates a directory.
3677  *
3678  * Virtual: make_directory_async
3679  * Since: 2.38
3680  */
3681 void
3682 g_file_make_directory_async (GFile               *file,
3683                              int                  io_priority,
3684                              GCancellable        *cancellable,
3685                              GAsyncReadyCallback  callback,
3686                              gpointer             user_data)
3687 {
3688   GFileIface *iface;
3689
3690   g_return_if_fail (G_IS_FILE (file));
3691
3692   iface = G_FILE_GET_IFACE (file);
3693   (* iface->make_directory_async) (file,
3694                                    io_priority,
3695                                    cancellable,
3696                                    callback,
3697                                    user_data);
3698 }
3699
3700 /**
3701  * g_file_make_directory_finish:
3702  * @file: input #GFile
3703  * @result: a #GAsyncResult
3704  * @error: a #GError, or %NULL
3705  *
3706  * Finishes an asynchronous directory creation, started with
3707  * g_file_make_directory_async().
3708  *
3709  * Virtual: make_directory_finish
3710  * Returns: %TRUE on successful directory creation, %FALSE otherwise.
3711  * Since: 2.38
3712  */
3713 gboolean
3714 g_file_make_directory_finish (GFile         *file,
3715                               GAsyncResult  *result,
3716                               GError       **error)
3717 {
3718   GFileIface *iface;
3719
3720   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3721   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
3722
3723   iface = G_FILE_GET_IFACE (file);
3724   return (* iface->make_directory_finish) (file, result, error);
3725 }
3726
3727 /**
3728  * g_file_make_directory_with_parents:
3729  * @file: input #GFile
3730  * @cancellable: (allow-none): optional #GCancellable object,
3731  *     %NULL to ignore
3732  * @error: a #GError, or %NULL
3733  *
3734  * Creates a directory and any parent directories that may not
3735  * exist similar to 'mkdir -p'. If the file system does not support
3736  * creating directories, this function will fail, setting @error to
3737  * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
3738  * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
3739  * the similar g_mkdir_with_parents().
3740  *
3741  * For a local #GFile the newly created directories will have the default
3742  * (current) ownership and permissions of the current process.
3743  *
3744  * If @cancellable is not %NULL, then the operation can be cancelled by
3745  * triggering the cancellable object from another thread. If the operation
3746  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3747  *
3748  * Returns: %TRUE if all directories have been successfully created, %FALSE
3749  * otherwise.
3750  *
3751  * Since: 2.18
3752  */
3753 gboolean
3754 g_file_make_directory_with_parents (GFile         *file,
3755                                     GCancellable  *cancellable,
3756                                     GError       **error)
3757 {
3758   GFile *work_file = NULL;
3759   GList *list = NULL, *l;
3760   GError *my_error = NULL;
3761
3762   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3763
3764   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3765     return FALSE;
3766
3767   /* Try for the simple case of not having to create any parent
3768    * directories.  If any parent directory needs to be created, this
3769    * call will fail with NOT_FOUND. If that happens, then that value of
3770    * my_error persists into the while loop below.
3771    */
3772   g_file_make_directory (file, cancellable, &my_error);
3773   if (!g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
3774     {
3775       if (my_error)
3776         g_propagate_error (error, my_error);
3777       return my_error == NULL;
3778     }
3779
3780   work_file = g_object_ref (file);
3781
3782   /* Creates the parent directories as needed. In case any particular
3783    * creation operation fails for lack of other parent directories
3784    * (NOT_FOUND), the directory is added to a list of directories to
3785    * create later, and the value of my_error is retained until the next
3786    * iteration of the loop.  After the loop my_error should either be
3787    * empty or contain a real failure condition.
3788    */
3789   while (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
3790     {
3791       GFile *parent_file;
3792
3793       parent_file = g_file_get_parent (work_file);
3794       if (parent_file == NULL)
3795         break;
3796
3797       g_clear_error (&my_error);
3798       g_file_make_directory (parent_file, cancellable, &my_error);
3799       /* Another process may have created the directory in between the
3800        * G_IO_ERROR_NOT_FOUND and now
3801        */
3802       if (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_EXISTS))
3803         g_clear_error (&my_error);
3804
3805       g_object_unref (work_file);
3806       work_file = g_object_ref (parent_file);
3807
3808       if (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
3809         list = g_list_prepend (list, parent_file);  /* Transfer ownership of ref */
3810       else
3811         g_object_unref (parent_file);
3812     }
3813
3814   /* All directories should be able to be created now, so an error at
3815    * this point means the whole operation must fail -- except an EXISTS
3816    * error, which means that another process already created the
3817    * directory in between the previous failure and now.
3818    */
3819   for (l = list; my_error == NULL && l; l = l->next)
3820     {
3821       g_file_make_directory ((GFile *) l->data, cancellable, &my_error);
3822       if (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_EXISTS))
3823         g_clear_error (&my_error);
3824     }
3825
3826   if (work_file)
3827     g_object_unref (work_file);
3828
3829   /* Clean up */
3830   while (list != NULL)
3831     {
3832       g_object_unref ((GFile *) list->data);
3833       list = g_list_remove (list, list->data);
3834     }
3835
3836   /* At this point an error in my_error means a that something
3837    * unexpected failed in either of the loops above, so the whole
3838    * operation must fail.
3839    */
3840   if (my_error != NULL)
3841     {
3842       g_propagate_error (error, my_error);
3843       return FALSE;
3844     }
3845
3846   return g_file_make_directory (file, cancellable, error);
3847 }
3848
3849 /**
3850  * g_file_make_symbolic_link:
3851  * @file: a #GFile with the name of the symlink to create
3852  * @symlink_value: a string with the path for the target of the new symlink
3853  * @cancellable: (allow-none): optional #GCancellable object,
3854  *     %NULL to ignore
3855  * @error: a #GError
3856  *
3857  * Creates a symbolic link named @file which contains the string
3858  * @symlink_value.
3859  *
3860  * If @cancellable is not %NULL, then the operation can be cancelled by
3861  * triggering the cancellable object from another thread. If the operation
3862  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3863  *
3864  * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
3865  */
3866 gboolean
3867 g_file_make_symbolic_link (GFile         *file,
3868                            const char    *symlink_value,
3869                            GCancellable  *cancellable,
3870                            GError       **error)
3871 {
3872   GFileIface *iface;
3873
3874   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3875   g_return_val_if_fail (symlink_value != NULL, FALSE);
3876
3877   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3878     return FALSE;
3879
3880   if (*symlink_value == '\0')
3881     {
3882       g_set_error_literal (error, G_IO_ERROR,
3883                            G_IO_ERROR_INVALID_ARGUMENT,
3884                            _("Invalid symlink value given"));
3885       return FALSE;
3886     }
3887
3888   iface = G_FILE_GET_IFACE (file);
3889
3890   if (iface->make_symbolic_link == NULL)
3891     {
3892       g_set_error_literal (error, G_IO_ERROR,
3893                            G_IO_ERROR_NOT_SUPPORTED,
3894                            _("Operation not supported"));
3895       return FALSE;
3896     }
3897
3898   return (* iface->make_symbolic_link) (file, symlink_value, cancellable, error);
3899 }
3900
3901 /**
3902  * g_file_delete:
3903  * @file: input #GFile
3904  * @cancellable: (allow-none): optional #GCancellable object,
3905  *     %NULL to ignore
3906  * @error: a #GError, or %NULL
3907  *
3908  * Deletes a file. If the @file is a directory, it will only be
3909  * deleted if it is empty. This has the same semantics as g_unlink().
3910  *
3911  * If @cancellable is not %NULL, then the operation can be cancelled by
3912  * triggering the cancellable object from another thread. If the operation
3913  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3914  *
3915  * Virtual: delete_file
3916  * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3917  */
3918 gboolean
3919 g_file_delete (GFile         *file,
3920                GCancellable  *cancellable,
3921                GError       **error)
3922 {
3923   GFileIface *iface;
3924
3925   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3926
3927   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3928     return FALSE;
3929
3930   iface = G_FILE_GET_IFACE (file);
3931
3932   if (iface->delete_file == NULL)
3933     {
3934       g_set_error_literal (error, G_IO_ERROR,
3935                            G_IO_ERROR_NOT_SUPPORTED,
3936                            _("Operation not supported"));
3937       return FALSE;
3938     }
3939
3940   return (* iface->delete_file) (file, cancellable, error);
3941 }
3942
3943 /**
3944  * g_file_delete_async:
3945  * @file: input #GFile
3946  * @io_priority: the [I/O priority][io-priority] of the request
3947  * @cancellable: (allow-none): optional #GCancellable object,
3948  *     %NULL to ignore
3949  * @callback: a #GAsyncReadyCallback to call
3950  *     when the request is satisfied
3951  * @user_data: the data to pass to callback function
3952  *
3953  * Asynchronously delete a file. If the @file is a directory, it will
3954  * only be deleted if it is empty.  This has the same semantics as
3955  * g_unlink().
3956  *
3957  * Virtual: delete_file_async
3958  * Since: 2.34
3959  */
3960 void
3961 g_file_delete_async (GFile               *file,
3962                      int                  io_priority,
3963                      GCancellable        *cancellable,
3964                      GAsyncReadyCallback  callback,
3965                      gpointer             user_data)
3966 {
3967   GFileIface *iface;
3968
3969   g_return_if_fail (G_IS_FILE (file));
3970
3971   iface = G_FILE_GET_IFACE (file);
3972   (* iface->delete_file_async) (file,
3973                                 io_priority,
3974                                 cancellable,
3975                                 callback,
3976                                 user_data);
3977 }
3978
3979 /**
3980  * g_file_delete_finish:
3981  * @file: input #GFile
3982  * @result: a #GAsyncResult
3983  * @error: a #GError, or %NULL
3984  *
3985  * Finishes deleting a file started with g_file_delete_async().
3986  *
3987  * Virtual: delete_file_finish
3988  * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3989  * Since: 2.34
3990  **/
3991 gboolean
3992 g_file_delete_finish (GFile         *file,
3993                       GAsyncResult  *result,
3994                       GError       **error)
3995 {
3996   GFileIface *iface;
3997
3998   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3999   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4000
4001   if (g_async_result_legacy_propagate_error (result, error))
4002     return FALSE;
4003
4004   iface = G_FILE_GET_IFACE (file);
4005   return (* iface->delete_file_finish) (file, result, error);
4006 }
4007
4008 /**
4009  * g_file_trash:
4010  * @file: #GFile to send to trash
4011  * @cancellable: (allow-none): optional #GCancellable object,
4012  *     %NULL to ignore
4013  * @error: a #GError, or %NULL
4014  *
4015  * Sends @file to the "Trashcan", if possible. This is similar to
4016  * deleting it, but the user can recover it before emptying the trashcan.
4017  * Not all file systems support trashing, so this call can return the
4018  * %G_IO_ERROR_NOT_SUPPORTED error.
4019  *
4020  * If @cancellable is not %NULL, then the operation can be cancelled by
4021  * triggering the cancellable object from another thread. If the operation
4022  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4023  *
4024  * Virtual: trash
4025  * Returns: %TRUE on successful trash, %FALSE otherwise.
4026  */
4027 gboolean
4028 g_file_trash (GFile         *file,
4029               GCancellable  *cancellable,
4030               GError       **error)
4031 {
4032   GFileIface *iface;
4033
4034   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4035
4036   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4037     return FALSE;
4038
4039   iface = G_FILE_GET_IFACE (file);
4040
4041   if (iface->trash == NULL)
4042     {
4043       g_set_error_literal (error,
4044                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4045                            _("Trash not supported"));
4046       return FALSE;
4047     }
4048
4049   return (* iface->trash) (file, cancellable, error);
4050 }
4051
4052 /**
4053  * g_file_trash_async:
4054  * @file: input #GFile
4055  * @io_priority: the [I/O priority][io-priority] of the request
4056  * @cancellable: (allow-none): optional #GCancellable object,
4057  *     %NULL to ignore
4058  * @callback: a #GAsyncReadyCallback to call
4059  *     when the request is satisfied
4060  * @user_data: the data to pass to callback function
4061  *
4062  * Asynchronously sends @file to the Trash location, if possible.
4063  *
4064  * Virtual: trash_async
4065  * Since: 2.38
4066  */
4067 void
4068 g_file_trash_async (GFile               *file,
4069                     int                  io_priority,
4070                     GCancellable        *cancellable,
4071                     GAsyncReadyCallback  callback,
4072                     gpointer             user_data)
4073 {
4074   GFileIface *iface;
4075
4076   g_return_if_fail (G_IS_FILE (file));
4077
4078   iface = G_FILE_GET_IFACE (file);
4079   (* iface->trash_async) (file,
4080                           io_priority,
4081                           cancellable,
4082                           callback,
4083                           user_data);
4084 }
4085
4086 /**
4087  * g_file_trash_finish:
4088  * @file: input #GFile
4089  * @result: a #GAsyncResult
4090  * @error: a #GError, or %NULL
4091  *
4092  * Finishes an asynchronous file trashing operation, started with
4093  * g_file_trash_async().
4094  *
4095  * Virtual: trash_finish
4096  * Returns: %TRUE on successful trash, %FALSE otherwise.
4097  * Since: 2.38
4098  */
4099 gboolean
4100 g_file_trash_finish (GFile         *file,
4101                      GAsyncResult  *result,
4102                      GError       **error)
4103 {
4104   GFileIface *iface;
4105
4106   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4107   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4108
4109   iface = G_FILE_GET_IFACE (file);
4110   return (* iface->trash_finish) (file, result, error);
4111 }
4112
4113 /**
4114  * g_file_set_display_name:
4115  * @file: input #GFile
4116  * @display_name: a string
4117  * @cancellable: (allow-none): optional #GCancellable object,
4118  *     %NULL to ignore
4119  * @error: a #GError, or %NULL
4120  *
4121  * Renames @file to the specified display name.
4122  *
4123  * The display name is converted from UTF-8 to the correct encoding
4124  * for the target filesystem if possible and the @file is renamed to this.
4125  *
4126  * If you want to implement a rename operation in the user interface the
4127  * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
4128  * initial value in the rename widget, and then the result after editing
4129  * should be passed to g_file_set_display_name().
4130  *
4131  * On success the resulting converted filename is returned.
4132  *
4133  * If @cancellable is not %NULL, then the operation can be cancelled by
4134  * triggering the cancellable object from another thread. If the operation
4135  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4136  *
4137  * Returns: (transfer full): a #GFile specifying what @file was renamed to,
4138  *     or %NULL if there was an error.
4139  *     Free the returned object with g_object_unref().
4140  */
4141 GFile *
4142 g_file_set_display_name (GFile         *file,
4143                          const gchar   *display_name,
4144                          GCancellable  *cancellable,
4145                          GError       **error)
4146 {
4147   GFileIface *iface;
4148
4149   g_return_val_if_fail (G_IS_FILE (file), NULL);
4150   g_return_val_if_fail (display_name != NULL, NULL);
4151
4152   if (strchr (display_name, G_DIR_SEPARATOR) != NULL)
4153     {
4154       g_set_error (error,
4155                    G_IO_ERROR,
4156                    G_IO_ERROR_INVALID_ARGUMENT,
4157                    _("File names cannot contain '%c'"), G_DIR_SEPARATOR);
4158       return NULL;
4159     }
4160
4161   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4162     return NULL;
4163
4164   iface = G_FILE_GET_IFACE (file);
4165
4166   return (* iface->set_display_name) (file, display_name, cancellable, error);
4167 }
4168
4169 /**
4170  * g_file_set_display_name_async:
4171  * @file: input #GFile
4172  * @display_name: a string
4173  * @io_priority: the [I/O priority][io-priority] of the request
4174  * @cancellable: (allow-none): optional #GCancellable object,
4175  *     %NULL to ignore
4176  * @callback: (scope async): a #GAsyncReadyCallback to call
4177  *     when the request is satisfied
4178  * @user_data: (closure): the data to pass to callback function
4179  *
4180  * Asynchronously sets the display name for a given #GFile.
4181  *
4182  * For more details, see g_file_set_display_name() which is
4183  * the synchronous version of this call.
4184  *
4185  * When the operation is finished, @callback will be called.
4186  * You can then call g_file_set_display_name_finish() to get
4187  * the result of the operation.
4188  */
4189 void
4190 g_file_set_display_name_async (GFile               *file,
4191                                const gchar         *display_name,
4192                                gint                 io_priority,
4193                                GCancellable        *cancellable,
4194                                GAsyncReadyCallback  callback,
4195                                gpointer             user_data)
4196 {
4197   GFileIface *iface;
4198
4199   g_return_if_fail (G_IS_FILE (file));
4200   g_return_if_fail (display_name != NULL);
4201
4202   iface = G_FILE_GET_IFACE (file);
4203   (* iface->set_display_name_async) (file,
4204                                      display_name,
4205                                      io_priority,
4206                                      cancellable,
4207                                      callback,
4208                                      user_data);
4209 }
4210
4211 /**
4212  * g_file_set_display_name_finish:
4213  * @file: input #GFile
4214  * @res: a #GAsyncResult
4215  * @error: a #GError, or %NULL
4216  *
4217  * Finishes setting a display name started with
4218  * g_file_set_display_name_async().
4219  *
4220  * Returns: (transfer full): a #GFile or %NULL on error.
4221  *     Free the returned object with g_object_unref().
4222  */
4223 GFile *
4224 g_file_set_display_name_finish (GFile         *file,
4225                                 GAsyncResult  *res,
4226                                 GError       **error)
4227 {
4228   GFileIface *iface;
4229
4230   g_return_val_if_fail (G_IS_FILE (file), NULL);
4231   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
4232
4233   if (g_async_result_legacy_propagate_error (res, error))
4234     return NULL;
4235
4236   iface = G_FILE_GET_IFACE (file);
4237   return (* iface->set_display_name_finish) (file, res, error);
4238 }
4239
4240 /**
4241  * g_file_query_settable_attributes:
4242  * @file: input #GFile
4243  * @cancellable: (allow-none): optional #GCancellable object,
4244  *     %NULL to ignore
4245  * @error: a #GError, or %NULL
4246  *
4247  * Obtain the list of settable attributes for the file.
4248  *
4249  * Returns the type and full attribute name of all the attributes
4250  * that can be set on this file. This doesn't mean setting it will
4251  * always succeed though, you might get an access failure, or some
4252  * specific file may not support a specific attribute.
4253  *
4254  * If @cancellable is not %NULL, then the operation can be cancelled by
4255  * triggering the cancellable object from another thread. If the operation
4256  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4257  *
4258  * Returns: a #GFileAttributeInfoList describing the settable attributes.
4259  *     When you are done with it, release it with
4260  *     g_file_attribute_info_list_unref()
4261  */
4262 GFileAttributeInfoList *
4263 g_file_query_settable_attributes (GFile         *file,
4264                                   GCancellable  *cancellable,
4265                                   GError       **error)
4266 {
4267   GFileIface *iface;
4268   GError *my_error;
4269   GFileAttributeInfoList *list;
4270
4271   g_return_val_if_fail (G_IS_FILE (file), NULL);
4272
4273   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4274     return NULL;
4275
4276   iface = G_FILE_GET_IFACE (file);
4277
4278   if (iface->query_settable_attributes == NULL)
4279     return g_file_attribute_info_list_new ();
4280
4281   my_error = NULL;
4282   list = (* iface->query_settable_attributes) (file, cancellable, &my_error);
4283
4284   if (list == NULL)
4285     {
4286       if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_NOT_SUPPORTED)
4287         {
4288           list = g_file_attribute_info_list_new ();
4289           g_error_free (my_error);
4290         }
4291       else
4292         g_propagate_error (error, my_error);
4293     }
4294
4295   return list;
4296 }
4297
4298 /**
4299  * g_file_query_writable_namespaces:
4300  * @file: input #GFile
4301  * @cancellable: (allow-none): optional #GCancellable object,
4302  *     %NULL to ignore
4303  * @error: a #GError, or %NULL
4304  *
4305  * Obtain the list of attribute namespaces where new attributes
4306  * can be created by a user. An example of this is extended
4307  * attributes (in the "xattr" namespace).
4308  *
4309  * If @cancellable is not %NULL, then the operation can be cancelled by
4310  * triggering the cancellable object from another thread. If the operation
4311  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4312  *
4313  * Returns: a #GFileAttributeInfoList describing the writable namespaces.
4314  *     When you are done with it, release it with
4315  *     g_file_attribute_info_list_unref()
4316  */
4317 GFileAttributeInfoList *
4318 g_file_query_writable_namespaces (GFile         *file,
4319                                   GCancellable  *cancellable,
4320                                   GError       **error)
4321 {
4322   GFileIface *iface;
4323   GError *my_error;
4324   GFileAttributeInfoList *list;
4325
4326   g_return_val_if_fail (G_IS_FILE (file), NULL);
4327
4328   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4329     return NULL;
4330
4331   iface = G_FILE_GET_IFACE (file);
4332
4333   if (iface->query_writable_namespaces == NULL)
4334     return g_file_attribute_info_list_new ();
4335
4336   my_error = NULL;
4337   list = (* iface->query_writable_namespaces) (file, cancellable, &my_error);
4338
4339   if (list == NULL)
4340     {
4341       g_warn_if_reached();
4342       list = g_file_attribute_info_list_new ();
4343     }
4344
4345   if (my_error != NULL)
4346     {
4347       if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_NOT_SUPPORTED)
4348         {
4349           g_error_free (my_error);
4350         }
4351       else
4352         g_propagate_error (error, my_error);
4353     }
4354
4355   return list;
4356 }
4357
4358 /**
4359  * g_file_set_attribute:
4360  * @file: input #GFile
4361  * @attribute: a string containing the attribute's name
4362  * @type: The type of the attribute
4363  * @value_p: (allow-none): a pointer to the value (or the pointer
4364  *     itself if the type is a pointer type)
4365  * @flags: a set of #GFileQueryInfoFlags
4366  * @cancellable: (allow-none): optional #GCancellable object,
4367  *     %NULL to ignore
4368  * @error: a #GError, or %NULL
4369  *
4370  * Sets an attribute in the file with attribute name @attribute to @value.
4371  *
4372  * Some attributes can be unset by setting @attribute to
4373  * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
4374  *
4375  * If @cancellable is not %NULL, then the operation can be cancelled by
4376  * triggering the cancellable object from another thread. If the operation
4377  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4378  *
4379  * Returns: %TRUE if the attribute was set, %FALSE otherwise.
4380  */
4381 gboolean
4382 g_file_set_attribute (GFile                *file,
4383                       const gchar          *attribute,
4384                       GFileAttributeType    type,
4385                       gpointer              value_p,
4386                       GFileQueryInfoFlags   flags,
4387                       GCancellable         *cancellable,
4388                       GError              **error)
4389 {
4390   GFileIface *iface;
4391
4392   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4393   g_return_val_if_fail (attribute != NULL && *attribute != '\0', FALSE);
4394
4395   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4396     return FALSE;
4397
4398   iface = G_FILE_GET_IFACE (file);
4399
4400   if (iface->set_attribute == NULL)
4401     {
4402       g_set_error_literal (error, G_IO_ERROR,
4403                            G_IO_ERROR_NOT_SUPPORTED,
4404                            _("Operation not supported"));
4405       return FALSE;
4406     }
4407
4408   return (* iface->set_attribute) (file, attribute, type, value_p, flags, cancellable, error);
4409 }
4410
4411 /**
4412  * g_file_set_attributes_from_info:
4413  * @file: input #GFile
4414  * @info: a #GFileInfo
4415  * @flags: #GFileQueryInfoFlags
4416  * @cancellable: (allow-none): optional #GCancellable object,
4417  *     %NULL to ignore
4418  * @error: a #GError, or %NULL
4419  *
4420  * Tries to set all attributes in the #GFileInfo on the target
4421  * values, not stopping on the first error.
4422  *
4423  * If there is any error during this operation then @error will
4424  * be set to the first error. Error on particular fields are flagged
4425  * by setting the "status" field in the attribute value to
4426  * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
4427  * also detect further errors.
4428  *
4429  * If @cancellable is not %NULL, then the operation can be cancelled by
4430  * triggering the cancellable object from another thread. If the operation
4431  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4432  *
4433  * Returns: %FALSE if there was any error, %TRUE otherwise.
4434  */
4435 gboolean
4436 g_file_set_attributes_from_info (GFile                *file,
4437                                  GFileInfo            *info,
4438                                  GFileQueryInfoFlags   flags,
4439                                  GCancellable         *cancellable,
4440                                  GError              **error)
4441 {
4442   GFileIface *iface;
4443
4444   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4445   g_return_val_if_fail (G_IS_FILE_INFO (info), FALSE);
4446
4447   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4448     return FALSE;
4449
4450   g_file_info_clear_status (info);
4451
4452   iface = G_FILE_GET_IFACE (file);
4453
4454   return (* iface->set_attributes_from_info) (file,
4455                                               info,
4456                                               flags,
4457                                               cancellable,
4458                                               error);
4459 }
4460
4461 static gboolean
4462 g_file_real_set_attributes_from_info (GFile                *file,
4463                                       GFileInfo            *info,
4464                                       GFileQueryInfoFlags   flags,
4465                                       GCancellable         *cancellable,
4466                                       GError              **error)
4467 {
4468   char **attributes;
4469   int i;
4470   gboolean res;
4471   GFileAttributeValue *value;
4472
4473   res = TRUE;
4474
4475   attributes = g_file_info_list_attributes (info, NULL);
4476
4477   for (i = 0; attributes[i] != NULL; i++)
4478     {
4479       value = _g_file_info_get_attribute_value (info, attributes[i]);
4480
4481       if (value->status != G_FILE_ATTRIBUTE_STATUS_UNSET)
4482         continue;
4483
4484       if (!g_file_set_attribute (file, attributes[i],
4485                                  value->type, _g_file_attribute_value_peek_as_pointer (value),
4486                                  flags, cancellable, error))
4487         {
4488           value->status = G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING;
4489           res = FALSE;
4490           /* Don't set error multiple times */
4491           error = NULL;
4492         }
4493       else
4494         value->status = G_FILE_ATTRIBUTE_STATUS_SET;
4495     }
4496
4497   g_strfreev (attributes);
4498
4499   return res;
4500 }
4501
4502 /**
4503  * g_file_set_attributes_async:
4504  * @file: input #GFile
4505  * @info: a #GFileInfo
4506  * @flags: a #GFileQueryInfoFlags
4507  * @io_priority: the [I/O priority][io-priority] of the request
4508  * @cancellable: (allow-none): optional #GCancellable object,
4509  *     %NULL to ignore
4510  * @callback: (scope async): a #GAsyncReadyCallback
4511  * @user_data: (closure): a #gpointer
4512  *
4513  * Asynchronously sets the attributes of @file with @info.
4514  *
4515  * For more details, see g_file_set_attributes_from_info(),
4516  * which is the synchronous version of this call.
4517  *
4518  * When the operation is finished, @callback will be called.
4519  * You can then call g_file_set_attributes_finish() to get
4520  * the result of the operation.
4521  */
4522 void
4523 g_file_set_attributes_async (GFile               *file,
4524                              GFileInfo           *info,
4525                              GFileQueryInfoFlags  flags,
4526                              int                  io_priority,
4527                              GCancellable        *cancellable,
4528                              GAsyncReadyCallback  callback,
4529                              gpointer             user_data)
4530 {
4531   GFileIface *iface;
4532
4533   g_return_if_fail (G_IS_FILE (file));
4534   g_return_if_fail (G_IS_FILE_INFO (info));
4535
4536   iface = G_FILE_GET_IFACE (file);
4537   (* iface->set_attributes_async) (file,
4538                                    info,
4539                                    flags,
4540                                    io_priority,
4541                                    cancellable,
4542                                    callback,
4543                                    user_data);
4544 }
4545
4546 /**
4547  * g_file_set_attributes_finish:
4548  * @file: input #GFile
4549  * @result: a #GAsyncResult
4550  * @info: (out) (transfer full): a #GFileInfo
4551  * @error: a #GError, or %NULL
4552  *
4553  * Finishes setting an attribute started in g_file_set_attributes_async().
4554  *
4555  * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
4556  */
4557 gboolean
4558 g_file_set_attributes_finish (GFile         *file,
4559                               GAsyncResult  *result,
4560                               GFileInfo    **info,
4561                               GError       **error)
4562 {
4563   GFileIface *iface;
4564
4565   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4566   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4567
4568   /* No standard handling of errors here, as we must set info even
4569    * on errors
4570    */
4571   iface = G_FILE_GET_IFACE (file);
4572   return (* iface->set_attributes_finish) (file, result, info, error);
4573 }
4574
4575 /**
4576  * g_file_set_attribute_string:
4577  * @file: input #GFile
4578  * @attribute: a string containing the attribute's name
4579  * @value: a string containing the attribute's value
4580  * @flags: #GFileQueryInfoFlags
4581  * @cancellable: (allow-none): optional #GCancellable object,
4582  *     %NULL to ignore
4583  * @error: a #GError, or %NULL
4584  *
4585  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
4586  * If @attribute is of a different type, this operation will fail.
4587  *
4588  * If @cancellable is not %NULL, then the operation can be cancelled by
4589  * triggering the cancellable object from another thread. If the operation
4590  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4591  *
4592  * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4593  */
4594 gboolean
4595 g_file_set_attribute_string (GFile                *file,
4596                              const char           *attribute,
4597                              const char           *value,
4598                              GFileQueryInfoFlags   flags,
4599                              GCancellable         *cancellable,
4600                              GError              **error)
4601 {
4602   return g_file_set_attribute (file, attribute,
4603                                G_FILE_ATTRIBUTE_TYPE_STRING, (gpointer)value,
4604                                flags, cancellable, error);
4605 }
4606
4607 /**
4608  * g_file_set_attribute_byte_string:
4609  * @file: input #GFile
4610  * @attribute: a string containing the attribute's name
4611  * @value: a string containing the attribute's new value
4612  * @flags: a #GFileQueryInfoFlags
4613  * @cancellable: (allow-none): optional #GCancellable object,
4614  *     %NULL to ignore
4615  * @error: a #GError, or %NULL
4616  *
4617  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
4618  * If @attribute is of a different type, this operation will fail,
4619  * returning %FALSE.
4620  *
4621  * If @cancellable is not %NULL, then the operation can be cancelled by
4622  * triggering the cancellable object from another thread. If the operation
4623  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4624  *
4625  * Returns: %TRUE if the @attribute was successfully set to @value
4626  *     in the @file, %FALSE otherwise.
4627  */
4628 gboolean
4629 g_file_set_attribute_byte_string  (GFile                *file,
4630                                    const gchar          *attribute,
4631                                    const gchar          *value,
4632                                    GFileQueryInfoFlags   flags,
4633                                    GCancellable         *cancellable,
4634                                    GError              **error)
4635 {
4636   return g_file_set_attribute (file, attribute,
4637                                G_FILE_ATTRIBUTE_TYPE_BYTE_STRING, (gpointer)value,
4638                                flags, cancellable, error);
4639 }
4640
4641 /**
4642  * g_file_set_attribute_uint32:
4643  * @file: input #GFile
4644  * @attribute: a string containing the attribute's name
4645  * @value: a #guint32 containing the attribute's new value
4646  * @flags: a #GFileQueryInfoFlags
4647  * @cancellable: (allow-none): optional #GCancellable object,
4648  *     %NULL to ignore
4649  * @error: a #GError, or %NULL
4650  *
4651  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
4652  * If @attribute is of a different type, this operation will fail.
4653  *
4654  * If @cancellable is not %NULL, then the operation can be cancelled by
4655  * triggering the cancellable object from another thread. If the operation
4656  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4657  *
4658  * Returns: %TRUE if the @attribute was successfully set to @value
4659  *     in the @file, %FALSE otherwise.
4660  */
4661 gboolean
4662 g_file_set_attribute_uint32 (GFile                *file,
4663                              const gchar          *attribute,
4664                              guint32               value,
4665                              GFileQueryInfoFlags   flags,
4666                              GCancellable         *cancellable,
4667                              GError              **error)
4668 {
4669   return g_file_set_attribute (file, attribute,
4670                                G_FILE_ATTRIBUTE_TYPE_UINT32, &value,
4671                                flags, cancellable, error);
4672 }
4673
4674 /**
4675  * g_file_set_attribute_int32:
4676  * @file: input #GFile
4677  * @attribute: a string containing the attribute's name
4678  * @value: a #gint32 containing the attribute's new value
4679  * @flags: a #GFileQueryInfoFlags
4680  * @cancellable: (allow-none): optional #GCancellable object,
4681  *     %NULL to ignore
4682  * @error: a #GError, or %NULL
4683  *
4684  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
4685  * If @attribute is of a different type, this operation will fail.
4686  *
4687  * If @cancellable is not %NULL, then the operation can be cancelled by
4688  * triggering the cancellable object from another thread. If the operation
4689  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4690  *
4691  * Returns: %TRUE if the @attribute was successfully set to @value
4692  *     in the @file, %FALSE otherwise.
4693  */
4694 gboolean
4695 g_file_set_attribute_int32 (GFile                *file,
4696                             const gchar          *attribute,
4697                             gint32                value,
4698                             GFileQueryInfoFlags   flags,
4699                             GCancellable         *cancellable,
4700                             GError              **error)
4701 {
4702   return g_file_set_attribute (file, attribute,
4703                                G_FILE_ATTRIBUTE_TYPE_INT32, &value,
4704                                flags, cancellable, error);
4705 }
4706
4707 /**
4708  * g_file_set_attribute_uint64:
4709  * @file: input #GFile
4710  * @attribute: a string containing the attribute's name
4711  * @value: a #guint64 containing the attribute's new value
4712  * @flags: a #GFileQueryInfoFlags
4713  * @cancellable: (allow-none): optional #GCancellable object,
4714  *     %NULL to ignore
4715  * @error: a #GError, or %NULL
4716  *
4717  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
4718  * If @attribute is of a different type, this operation will fail.
4719  *
4720  * If @cancellable is not %NULL, then the operation can be cancelled by
4721  * triggering the cancellable object from another thread. If the operation
4722  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4723  *
4724  * Returns: %TRUE if the @attribute was successfully set to @value
4725  *     in the @file, %FALSE otherwise.
4726  */
4727 gboolean
4728 g_file_set_attribute_uint64 (GFile                *file,
4729                              const gchar          *attribute,
4730                              guint64               value,
4731                              GFileQueryInfoFlags   flags,
4732                              GCancellable         *cancellable,
4733                              GError              **error)
4734  {
4735   return g_file_set_attribute (file, attribute,
4736                                G_FILE_ATTRIBUTE_TYPE_UINT64, &value,
4737                                flags, cancellable, error);
4738 }
4739
4740 /**
4741  * g_file_set_attribute_int64:
4742  * @file: input #GFile
4743  * @attribute: a string containing the attribute's name
4744  * @value: a #guint64 containing the attribute's new value
4745  * @flags: a #GFileQueryInfoFlags
4746  * @cancellable: (allow-none): optional #GCancellable object,
4747  *     %NULL to ignore
4748  * @error: a #GError, or %NULL
4749  *
4750  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
4751  * If @attribute is of a different type, this operation will fail.
4752  *
4753  * If @cancellable is not %NULL, then the operation can be cancelled by
4754  * triggering the cancellable object from another thread. If the operation
4755  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4756  *
4757  * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4758  */
4759 gboolean
4760 g_file_set_attribute_int64 (GFile                *file,
4761                             const gchar          *attribute,
4762                             gint64                value,
4763                             GFileQueryInfoFlags   flags,
4764                             GCancellable         *cancellable,
4765                             GError              **error)
4766 {
4767   return g_file_set_attribute (file, attribute,
4768                                G_FILE_ATTRIBUTE_TYPE_INT64, &value,
4769                                flags, cancellable, error);
4770 }
4771
4772 /**
4773  * g_file_mount_mountable:
4774  * @file: input #GFile
4775  * @flags: flags affecting the operation
4776  * @mount_operation: (allow-none): a #GMountOperation,
4777  *     or %NULL to avoid user interaction
4778  * @cancellable: (allow-none): optional #GCancellable object,
4779  *     %NULL to ignore
4780  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4781  *     when the request is satisfied, or %NULL
4782  * @user_data: (closure): the data to pass to callback function
4783  *
4784  * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
4785  * Using @mount_operation, you can request callbacks when, for instance,
4786  * passwords are needed during authentication.
4787  *
4788  * If @cancellable is not %NULL, then the operation can be cancelled by
4789  * triggering the cancellable object from another thread. If the operation
4790  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4791  *
4792  * When the operation is finished, @callback will be called.
4793  * You can then call g_file_mount_mountable_finish() to get
4794  * the result of the operation.
4795  */
4796 void
4797 g_file_mount_mountable (GFile               *file,
4798                         GMountMountFlags     flags,
4799                         GMountOperation     *mount_operation,
4800                         GCancellable        *cancellable,
4801                         GAsyncReadyCallback  callback,
4802                         gpointer             user_data)
4803 {
4804   GFileIface *iface;
4805
4806   g_return_if_fail (G_IS_FILE (file));
4807
4808   iface = G_FILE_GET_IFACE (file);
4809
4810   if (iface->mount_mountable == NULL)
4811     {
4812       g_task_report_new_error (file, callback, user_data,
4813                                g_file_mount_mountable,
4814                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4815                                _("Operation not supported"));
4816       return;
4817     }
4818
4819   (* iface->mount_mountable) (file,
4820                               flags,
4821                               mount_operation,
4822                               cancellable,
4823                               callback,
4824                               user_data);
4825 }
4826
4827 /**
4828  * g_file_mount_mountable_finish:
4829  * @file: input #GFile
4830  * @result: a #GAsyncResult
4831  * @error: a #GError, or %NULL
4832  *
4833  * Finishes a mount operation. See g_file_mount_mountable() for details.
4834  *
4835  * Finish an asynchronous mount operation that was started
4836  * with g_file_mount_mountable().
4837  *
4838  * Returns: (transfer full): a #GFile or %NULL on error.
4839  *     Free the returned object with g_object_unref().
4840  */
4841 GFile *
4842 g_file_mount_mountable_finish (GFile         *file,
4843                                GAsyncResult  *result,
4844                                GError       **error)
4845 {
4846   GFileIface *iface;
4847
4848   g_return_val_if_fail (G_IS_FILE (file), NULL);
4849   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
4850
4851   if (g_async_result_legacy_propagate_error (result, error))
4852     return NULL;
4853   else if (g_async_result_is_tagged (result, g_file_mount_mountable))
4854     return g_task_propagate_pointer (G_TASK (result), error);
4855
4856   iface = G_FILE_GET_IFACE (file);
4857   return (* iface->mount_mountable_finish) (file, result, error);
4858 }
4859
4860 /**
4861  * g_file_unmount_mountable:
4862  * @file: input #GFile
4863  * @flags: flags affecting the operation
4864  * @cancellable: (allow-none): optional #GCancellable object,
4865  *     %NULL to ignore
4866  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4867  *     when the request is satisfied, or %NULL
4868  * @user_data: (closure): the data to pass to callback function
4869  *
4870  * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
4871  *
4872  * If @cancellable is not %NULL, then the operation can be cancelled by
4873  * triggering the cancellable object from another thread. If the operation
4874  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4875  *
4876  * When the operation is finished, @callback will be called.
4877  * You can then call g_file_unmount_mountable_finish() to get
4878  * the result of the operation.
4879  *
4880  * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
4881  */
4882 void
4883 g_file_unmount_mountable (GFile               *file,
4884                           GMountUnmountFlags   flags,
4885                           GCancellable        *cancellable,
4886                           GAsyncReadyCallback  callback,
4887                           gpointer             user_data)
4888 {
4889   GFileIface *iface;
4890
4891   g_return_if_fail (G_IS_FILE (file));
4892
4893   iface = G_FILE_GET_IFACE (file);
4894
4895   if (iface->unmount_mountable == NULL)
4896     {
4897       g_task_report_new_error (file, callback, user_data,
4898                                g_file_unmount_mountable_with_operation,
4899                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4900                                _("Operation not supported"));
4901       return;
4902     }
4903
4904   (* iface->unmount_mountable) (file,
4905                                 flags,
4906                                 cancellable,
4907                                 callback,
4908                                 user_data);
4909 }
4910
4911 /**
4912  * g_file_unmount_mountable_finish:
4913  * @file: input #GFile
4914  * @result: a #GAsyncResult
4915  * @error: a #GError, or %NULL
4916  *
4917  * Finishes an unmount operation, see g_file_unmount_mountable() for details.
4918  *
4919  * Finish an asynchronous unmount operation that was started
4920  * with g_file_unmount_mountable().
4921  *
4922  * Returns: %TRUE if the operation finished successfully.
4923  *     %FALSE otherwise.
4924  *
4925  * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
4926  *     instead.
4927  */
4928 gboolean
4929 g_file_unmount_mountable_finish (GFile         *file,
4930                                  GAsyncResult  *result,
4931                                  GError       **error)
4932 {
4933   GFileIface *iface;
4934
4935   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4936   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4937
4938   if (g_async_result_legacy_propagate_error (result, error))
4939     return FALSE;
4940   else if (g_async_result_is_tagged (result, g_file_unmount_mountable_with_operation))
4941     return g_task_propagate_boolean (G_TASK (result), error);
4942
4943   iface = G_FILE_GET_IFACE (file);
4944   return (* iface->unmount_mountable_finish) (file, result, error);
4945 }
4946
4947 /**
4948  * g_file_unmount_mountable_with_operation:
4949  * @file: input #GFile
4950  * @flags: flags affecting the operation
4951  * @mount_operation: (allow-none): a #GMountOperation,
4952  *     or %NULL to avoid user interaction
4953  * @cancellable: (allow-none): optional #GCancellable object,
4954  *     %NULL to ignore
4955  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4956  *     when the request is satisfied, or %NULL
4957  * @user_data: (closure): the data to pass to callback function
4958  *
4959  * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
4960  *
4961  * If @cancellable is not %NULL, then the operation can be cancelled by
4962  * triggering the cancellable object from another thread. If the operation
4963  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4964  *
4965  * When the operation is finished, @callback will be called.
4966  * You can then call g_file_unmount_mountable_finish() to get
4967  * the result of the operation.
4968  *
4969  * Since: 2.22
4970  */
4971 void
4972 g_file_unmount_mountable_with_operation (GFile               *file,
4973                                          GMountUnmountFlags   flags,
4974                                          GMountOperation     *mount_operation,
4975                                          GCancellable        *cancellable,
4976                                          GAsyncReadyCallback  callback,
4977                                          gpointer             user_data)
4978 {
4979   GFileIface *iface;
4980
4981   g_return_if_fail (G_IS_FILE (file));
4982
4983   iface = G_FILE_GET_IFACE (file);
4984
4985   if (iface->unmount_mountable == NULL && iface->unmount_mountable_with_operation == NULL)
4986     {
4987       g_task_report_new_error (file, callback, user_data,
4988                                g_file_unmount_mountable_with_operation,
4989                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4990                                _("Operation not supported"));
4991       return;
4992     }
4993
4994   if (iface->unmount_mountable_with_operation != NULL)
4995     (* iface->unmount_mountable_with_operation) (file,
4996                                                  flags,
4997                                                  mount_operation,
4998                                                  cancellable,
4999                                                  callback,
5000                                                  user_data);
5001   else
5002     (* iface->unmount_mountable) (file,
5003                                   flags,
5004                                   cancellable,
5005                                   callback,
5006                                   user_data);
5007 }
5008
5009 /**
5010  * g_file_unmount_mountable_with_operation_finish:
5011  * @file: input #GFile
5012  * @result: a #GAsyncResult
5013  * @error: a #GError, or %NULL
5014  *
5015  * Finishes an unmount operation,
5016  * see g_file_unmount_mountable_with_operation() for details.
5017  *
5018  * Finish an asynchronous unmount operation that was started
5019  * with g_file_unmount_mountable_with_operation().
5020  *
5021  * Returns: %TRUE if the operation finished successfully.
5022  *     %FALSE otherwise.
5023  *
5024  * Since: 2.22
5025  */
5026 gboolean
5027 g_file_unmount_mountable_with_operation_finish (GFile         *file,
5028                                                 GAsyncResult  *result,
5029                                                 GError       **error)
5030 {
5031   GFileIface *iface;
5032
5033   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5034   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5035
5036   if (g_async_result_legacy_propagate_error (result, error))
5037     return FALSE;
5038   else if (g_async_result_is_tagged (result, g_file_unmount_mountable_with_operation))
5039     return g_task_propagate_boolean (G_TASK (result), error);
5040
5041   iface = G_FILE_GET_IFACE (file);
5042   if (iface->unmount_mountable_with_operation_finish != NULL)
5043     return (* iface->unmount_mountable_with_operation_finish) (file, result, error);
5044   else
5045     return (* iface->unmount_mountable_finish) (file, result, error);
5046 }
5047
5048 /**
5049  * g_file_eject_mountable:
5050  * @file: input #GFile
5051  * @flags: flags affecting the operation
5052  * @cancellable: (allow-none): optional #GCancellable object,
5053  *     %NULL to ignore
5054  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
5055  *     when the request is satisfied, or %NULL
5056  * @user_data: (closure): the data to pass to callback function
5057  *
5058  * Starts an asynchronous eject on a mountable.
5059  * When this operation has completed, @callback will be called with
5060  * @user_user data, and the operation can be finalized with
5061  * g_file_eject_mountable_finish().
5062  *
5063  * If @cancellable is not %NULL, then the operation can be cancelled by
5064  * triggering the cancellable object from another thread. If the operation
5065  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5066  *
5067  * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
5068  */
5069 void
5070 g_file_eject_mountable (GFile               *file,
5071                         GMountUnmountFlags   flags,
5072                         GCancellable        *cancellable,
5073                         GAsyncReadyCallback  callback,
5074                         gpointer             user_data)
5075 {
5076   GFileIface *iface;
5077
5078   g_return_if_fail (G_IS_FILE (file));
5079
5080   iface = G_FILE_GET_IFACE (file);
5081
5082   if (iface->eject_mountable == NULL)
5083     {
5084       g_task_report_new_error (file, callback, user_data,
5085                                g_file_eject_mountable_with_operation,
5086                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5087                                _("Operation not supported"));
5088       return;
5089     }
5090
5091   (* iface->eject_mountable) (file,
5092                               flags,
5093                               cancellable,
5094                               callback,
5095                               user_data);
5096 }
5097
5098 /**
5099  * g_file_eject_mountable_finish:
5100  * @file: input #GFile
5101  * @result: a #GAsyncResult
5102  * @error: a #GError, or %NULL
5103  *
5104  * Finishes an asynchronous eject operation started by
5105  * g_file_eject_mountable().
5106  *
5107  * Returns: %TRUE if the @file was ejected successfully.
5108  *     %FALSE otherwise.
5109  *
5110  * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
5111  *     instead.
5112  */
5113 gboolean
5114 g_file_eject_mountable_finish (GFile         *file,
5115                                GAsyncResult  *result,
5116                                GError       **error)
5117 {
5118   GFileIface *iface;
5119
5120   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5121   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5122
5123   if (g_async_result_legacy_propagate_error (result, error))
5124     return FALSE;
5125   else if (g_async_result_is_tagged (result, g_file_eject_mountable_with_operation))
5126     return g_task_propagate_boolean (G_TASK (result), error);
5127
5128   iface = G_FILE_GET_IFACE (file);
5129   return (* iface->eject_mountable_finish) (file, result, error);
5130 }
5131
5132 /**
5133  * g_file_eject_mountable_with_operation:
5134  * @file: input #GFile
5135  * @flags: flags affecting the operation
5136  * @mount_operation: (allow-none): a #GMountOperation,
5137  *     or %NULL to avoid user interaction
5138  * @cancellable: (allow-none): optional #GCancellable object,
5139  *     %NULL to ignore
5140  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
5141  *     when the request is satisfied, or %NULL
5142  * @user_data: (closure): the data to pass to callback function
5143  *
5144  * Starts an asynchronous eject on a mountable.
5145  * When this operation has completed, @callback will be called with
5146  * @user_user data, and the operation can be finalized with
5147  * g_file_eject_mountable_with_operation_finish().
5148  *
5149  * If @cancellable is not %NULL, then the operation can be cancelled by
5150  * triggering the cancellable object from another thread. If the operation
5151  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5152  *
5153  * Since: 2.22
5154  */
5155 void
5156 g_file_eject_mountable_with_operation (GFile               *file,
5157                                        GMountUnmountFlags   flags,
5158                                        GMountOperation     *mount_operation,
5159                                        GCancellable        *cancellable,
5160                                        GAsyncReadyCallback  callback,
5161                                        gpointer             user_data)
5162 {
5163   GFileIface *iface;
5164
5165   g_return_if_fail (G_IS_FILE (file));
5166
5167   iface = G_FILE_GET_IFACE (file);
5168
5169   if (iface->eject_mountable == NULL && iface->eject_mountable_with_operation == NULL)
5170     {
5171       g_task_report_new_error (file, callback, user_data,
5172                                g_file_eject_mountable_with_operation,
5173                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5174                                _("Operation not supported"));
5175       return;
5176     }
5177
5178   if (iface->eject_mountable_with_operation != NULL)
5179     (* iface->eject_mountable_with_operation) (file,
5180                                                flags,
5181                                                mount_operation,
5182                                                cancellable,
5183                                                callback,
5184                                                user_data);
5185   else
5186     (* iface->eject_mountable) (file,
5187                                 flags,
5188                                 cancellable,
5189                                 callback,
5190                                 user_data);
5191 }
5192
5193 /**
5194  * g_file_eject_mountable_with_operation_finish:
5195  * @file: input #GFile
5196  * @result: a #GAsyncResult
5197  * @error: a #GError, or %NULL
5198  *
5199  * Finishes an asynchronous eject operation started by
5200  * g_file_eject_mountable_with_operation().
5201  *
5202  * Returns: %TRUE if the @file was ejected successfully.
5203  *     %FALSE otherwise.
5204  *
5205  * Since: 2.22
5206  */
5207 gboolean
5208 g_file_eject_mountable_with_operation_finish (GFile         *file,
5209                                               GAsyncResult  *result,
5210                                               GError       **error)
5211 {
5212   GFileIface *iface;
5213
5214   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5215   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5216
5217   if (g_async_result_legacy_propagate_error (result, error))
5218     return FALSE;
5219   else if (g_async_result_is_tagged (result, g_file_eject_mountable_with_operation))
5220     return g_task_propagate_boolean (G_TASK (result), error);
5221
5222   iface = G_FILE_GET_IFACE (file);
5223   if (iface->eject_mountable_with_operation_finish != NULL)
5224     return (* iface->eject_mountable_with_operation_finish) (file, result, error);
5225   else
5226     return (* iface->eject_mountable_finish) (file, result, error);
5227 }
5228
5229 /**
5230  * g_file_monitor_directory:
5231  * @file: input #GFile
5232  * @flags: a set of #GFileMonitorFlags
5233  * @cancellable: (allow-none): optional #GCancellable object,
5234  *     %NULL to ignore
5235  * @error: a #GError, or %NULL
5236  *
5237  * Obtains a directory monitor for the given file.
5238  * This may fail if directory monitoring is not supported.
5239  *
5240  * If @cancellable is not %NULL, then the operation can be cancelled by
5241  * triggering the cancellable object from another thread. If the operation
5242  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5243  *
5244  * It does not make sense for @flags to contain
5245  * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
5246  * directories.  It is not possible to monitor all the files in a
5247  * directory for changes made via hard links; if you want to do this then
5248  * you must register individual watches with g_file_monitor().
5249  *
5250  * Virtual: monitor_dir
5251  * Returns: (transfer full): a #GFileMonitor for the given @file,
5252  *     or %NULL on error.
5253  *     Free the returned object with g_object_unref().
5254  */
5255 GFileMonitor *
5256 g_file_monitor_directory (GFile              *file,
5257                           GFileMonitorFlags   flags,
5258                           GCancellable       *cancellable,
5259                           GError            **error)
5260 {
5261   GFileIface *iface;
5262
5263   g_return_val_if_fail (G_IS_FILE (file), NULL);
5264   g_return_val_if_fail (~flags & G_FILE_MONITOR_WATCH_HARD_LINKS, NULL);
5265
5266   if (g_cancellable_set_error_if_cancelled (cancellable, error))
5267     return NULL;
5268
5269   iface = G_FILE_GET_IFACE (file);
5270
5271   if (iface->monitor_dir == NULL)
5272     {
5273       g_set_error_literal (error, G_IO_ERROR,
5274                            G_IO_ERROR_NOT_SUPPORTED,
5275                            _("Operation not supported"));
5276       return NULL;
5277     }
5278
5279   return (* iface->monitor_dir) (file, flags, cancellable, error);
5280 }
5281
5282 /**
5283  * g_file_monitor_file:
5284  * @file: input #GFile
5285  * @flags: a set of #GFileMonitorFlags
5286  * @cancellable: (allow-none): optional #GCancellable object,
5287  *     %NULL to ignore
5288  * @error: a #GError, or %NULL
5289  *
5290  * Obtains a file monitor for the given file. If no file notification
5291  * mechanism exists, then regular polling of the file is used.
5292  *
5293  * If @cancellable is not %NULL, then the operation can be cancelled by
5294  * triggering the cancellable object from another thread. If the operation
5295  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5296  *
5297  * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
5298  * will also attempt to report changes made to the file via another
5299  * filename (ie, a hard link). Without this flag, you can only rely on
5300  * changes made through the filename contained in @file to be
5301  * reported. Using this flag may result in an increase in resource
5302  * usage, and may not have any effect depending on the #GFileMonitor
5303  * backend and/or filesystem type.
5304  *
5305  * Returns: (transfer full): a #GFileMonitor for the given @file,
5306  *     or %NULL on error.
5307  *     Free the returned object with g_object_unref().
5308  */
5309 GFileMonitor *
5310 g_file_monitor_file (GFile              *file,
5311                      GFileMonitorFlags   flags,
5312                      GCancellable       *cancellable,
5313                      GError            **error)
5314 {
5315   GFileIface *iface;
5316   GFileMonitor *monitor;
5317
5318   g_return_val_if_fail (G_IS_FILE (file), NULL);
5319
5320   if (g_cancellable_set_error_if_cancelled (cancellable, error))
5321     return NULL;
5322
5323   iface = G_FILE_GET_IFACE (file);
5324
5325   monitor = NULL;
5326
5327   if (iface->monitor_file)
5328     monitor = (* iface->monitor_file) (file, flags, cancellable, NULL);
5329
5330   /* Fallback to polling */
5331   if (monitor == NULL)
5332     monitor = _g_poll_file_monitor_new (file);
5333
5334   return monitor;
5335 }
5336
5337 /**
5338  * g_file_monitor:
5339  * @file: input #GFile
5340  * @flags: a set of #GFileMonitorFlags
5341  * @cancellable: (allow-none): optional #GCancellable object,
5342  *     %NULL to ignore
5343  * @error: a #GError, or %NULL
5344  *
5345  * Obtains a file or directory monitor for the given file,
5346  * depending on the type of the file.
5347  *
5348  * If @cancellable is not %NULL, then the operation can be cancelled by
5349  * triggering the cancellable object from another thread. If the operation
5350  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5351  *
5352  * Returns: (transfer full): a #GFileMonitor for the given @file,
5353  *     or %NULL on error.
5354  *     Free the returned object with g_object_unref().
5355  *
5356  * Since: 2.18
5357  */
5358 GFileMonitor *
5359 g_file_monitor (GFile              *file,
5360                 GFileMonitorFlags   flags,
5361                 GCancellable       *cancellable,
5362                 GError            **error)
5363 {
5364   if (g_file_query_file_type (file, 0, cancellable) == G_FILE_TYPE_DIRECTORY)
5365     return g_file_monitor_directory (file,
5366                                      flags & ~G_FILE_MONITOR_WATCH_HARD_LINKS,
5367                                      cancellable, error);
5368   else
5369     return g_file_monitor_file (file, flags, cancellable, error);
5370 }
5371
5372 /********************************************
5373  *   Default implementation of async ops    *
5374  ********************************************/
5375
5376 typedef struct {
5377   char *attributes;
5378   GFileQueryInfoFlags flags;
5379 } QueryInfoAsyncData;
5380
5381 static void
5382 query_info_data_free (QueryInfoAsyncData *data)
5383 {
5384   g_free (data->attributes);
5385   g_free (data);
5386 }
5387
5388 static void
5389 query_info_async_thread (GTask         *task,
5390                          gpointer       object,
5391                          gpointer       task_data,
5392                          GCancellable  *cancellable)
5393 {
5394   QueryInfoAsyncData *data = task_data;
5395   GFileInfo *info;
5396   GError *error = NULL;
5397
5398   info = g_file_query_info (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5399   if (info)
5400     g_task_return_pointer (task, info, g_object_unref);
5401   else
5402     g_task_return_error (task, error);
5403 }
5404
5405 static void
5406 g_file_real_query_info_async (GFile               *file,
5407                               const char          *attributes,
5408                               GFileQueryInfoFlags  flags,
5409                               int                  io_priority,
5410                               GCancellable        *cancellable,
5411                               GAsyncReadyCallback  callback,
5412                               gpointer             user_data)
5413 {
5414   GTask *task;
5415   QueryInfoAsyncData *data;
5416
5417   data = g_new0 (QueryInfoAsyncData, 1);
5418   data->attributes = g_strdup (attributes);
5419   data->flags = flags;
5420
5421   task = g_task_new (file, cancellable, callback, user_data);
5422   g_task_set_task_data (task, data, (GDestroyNotify)query_info_data_free);
5423   g_task_set_priority (task, io_priority);
5424   g_task_run_in_thread (task, query_info_async_thread);
5425   g_object_unref (task);
5426 }
5427
5428 static GFileInfo *
5429 g_file_real_query_info_finish (GFile         *file,
5430                                GAsyncResult  *res,
5431                                GError       **error)
5432 {
5433   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5434
5435   return g_task_propagate_pointer (G_TASK (res), error);
5436 }
5437
5438 static void
5439 query_filesystem_info_async_thread (GTask         *task,
5440                                     gpointer       object,
5441                                     gpointer       task_data,
5442                                     GCancellable  *cancellable)
5443 {
5444   const char *attributes = task_data;
5445   GFileInfo *info;
5446   GError *error = NULL;
5447
5448   info = g_file_query_filesystem_info (G_FILE (object), attributes, cancellable, &error);
5449   if (info)
5450     g_task_return_pointer (task, info, g_object_unref);
5451   else
5452     g_task_return_error (task, error);
5453 }
5454
5455 static void
5456 g_file_real_query_filesystem_info_async (GFile               *file,
5457                                          const char          *attributes,
5458                                          int                  io_priority,
5459                                          GCancellable        *cancellable,
5460                                          GAsyncReadyCallback  callback,
5461                                          gpointer             user_data)
5462 {
5463   GTask *task;
5464
5465   task = g_task_new (file, cancellable, callback, user_data);
5466   g_task_set_task_data (task, g_strdup (attributes), g_free);
5467   g_task_set_priority (task, io_priority);
5468   g_task_run_in_thread (task, query_filesystem_info_async_thread);
5469   g_object_unref (task);
5470 }
5471
5472 static GFileInfo *
5473 g_file_real_query_filesystem_info_finish (GFile         *file,
5474                                           GAsyncResult  *res,
5475                                           GError       **error)
5476 {
5477   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5478
5479   return g_task_propagate_pointer (G_TASK (res), error);
5480 }
5481
5482 static void
5483 enumerate_children_async_thread (GTask         *task,
5484                                  gpointer       object,
5485                                  gpointer       task_data,
5486                                  GCancellable  *cancellable)
5487 {
5488   QueryInfoAsyncData *data = task_data;
5489   GFileEnumerator *enumerator;
5490   GError *error = NULL;
5491
5492   enumerator = g_file_enumerate_children (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5493   if (error)
5494     g_task_return_error (task, error);
5495   else
5496     g_task_return_pointer (task, enumerator, g_object_unref);
5497 }
5498
5499 static void
5500 g_file_real_enumerate_children_async (GFile               *file,
5501                                       const char          *attributes,
5502                                       GFileQueryInfoFlags  flags,
5503                                       int                  io_priority,
5504                                       GCancellable        *cancellable,
5505                                       GAsyncReadyCallback  callback,
5506                                       gpointer             user_data)
5507 {
5508   GTask *task;
5509   QueryInfoAsyncData *data;
5510
5511   data = g_new0 (QueryInfoAsyncData, 1);
5512   data->attributes = g_strdup (attributes);
5513   data->flags = flags;
5514
5515   task = g_task_new (file, cancellable, callback, user_data);
5516   g_task_set_task_data (task, data, (GDestroyNotify)query_info_data_free);
5517   g_task_set_priority (task, io_priority);
5518   g_task_run_in_thread (task, enumerate_children_async_thread);
5519   g_object_unref (task);
5520 }
5521
5522 static GFileEnumerator *
5523 g_file_real_enumerate_children_finish (GFile         *file,
5524                                        GAsyncResult  *res,
5525                                        GError       **error)
5526 {
5527   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5528
5529   return g_task_propagate_pointer (G_TASK (res), error);
5530 }
5531
5532 static void
5533 open_read_async_thread (GTask         *task,
5534                         gpointer       object,
5535                         gpointer       task_data,
5536                         GCancellable  *cancellable)
5537 {
5538   GFileInputStream *stream;
5539   GError *error = NULL;
5540
5541   stream = g_file_read (G_FILE (object), cancellable, &error);
5542   if (stream)
5543     g_task_return_pointer (task, stream, g_object_unref);
5544   else
5545     g_task_return_error (task, error);
5546 }
5547
5548 static void
5549 g_file_real_read_async (GFile               *file,
5550                         int                  io_priority,
5551                         GCancellable        *cancellable,
5552                         GAsyncReadyCallback  callback,
5553                         gpointer             user_data)
5554 {
5555   GTask *task;
5556
5557   task = g_task_new (file, cancellable, callback, user_data);
5558   g_task_set_priority (task, io_priority);
5559   g_task_run_in_thread (task, open_read_async_thread);
5560   g_object_unref (task);
5561 }
5562
5563 static GFileInputStream *
5564 g_file_real_read_finish (GFile         *file,
5565                          GAsyncResult  *res,
5566                          GError       **error)
5567 {
5568   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5569
5570   return g_task_propagate_pointer (G_TASK (res), error);
5571 }
5572
5573 static void
5574 append_to_async_thread (GTask         *task,
5575                         gpointer       source_object,
5576                         gpointer       task_data,
5577                         GCancellable  *cancellable)
5578 {
5579   GFileCreateFlags *data = task_data;
5580   GFileOutputStream *stream;
5581   GError *error = NULL;
5582
5583   stream = g_file_append_to (G_FILE (source_object), *data, cancellable, &error);
5584   if (stream)
5585     g_task_return_pointer (task, stream, g_object_unref);
5586   else
5587     g_task_return_error (task, error);
5588 }
5589
5590 static void
5591 g_file_real_append_to_async (GFile               *file,
5592                              GFileCreateFlags     flags,
5593                              int                  io_priority,
5594                              GCancellable        *cancellable,
5595                              GAsyncReadyCallback  callback,
5596                              gpointer             user_data)
5597 {
5598   GFileCreateFlags *data;
5599   GTask *task;
5600
5601   data = g_new0 (GFileCreateFlags, 1);
5602   *data = flags;
5603
5604   task = g_task_new (file, cancellable, callback, user_data);
5605   g_task_set_task_data (task, data, g_free);
5606   g_task_set_priority (task, io_priority);
5607
5608   g_task_run_in_thread (task, append_to_async_thread);
5609   g_object_unref (task);
5610 }
5611
5612 static GFileOutputStream *
5613 g_file_real_append_to_finish (GFile         *file,
5614                               GAsyncResult  *res,
5615                               GError       **error)
5616 {
5617   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5618
5619   return g_task_propagate_pointer (G_TASK (res), error);
5620 }
5621
5622 static void
5623 create_async_thread (GTask         *task,
5624                      gpointer       source_object,
5625                      gpointer       task_data,
5626                      GCancellable  *cancellable)
5627 {
5628   GFileCreateFlags *data = task_data;
5629   GFileOutputStream *stream;
5630   GError *error = NULL;
5631
5632   stream = g_file_create (G_FILE (source_object), *data, cancellable, &error);
5633   if (stream)
5634     g_task_return_pointer (task, stream, g_object_unref);
5635   else
5636     g_task_return_error (task, error);
5637 }
5638
5639 static void
5640 g_file_real_create_async (GFile               *file,
5641                           GFileCreateFlags     flags,
5642                           int                  io_priority,
5643                           GCancellable        *cancellable,
5644                           GAsyncReadyCallback  callback,
5645                           gpointer             user_data)
5646 {
5647   GFileCreateFlags *data;
5648   GTask *task;
5649
5650   data = g_new0 (GFileCreateFlags, 1);
5651   *data = flags;
5652
5653   task = g_task_new (file, cancellable, callback, user_data);
5654   g_task_set_task_data (task, data, g_free);
5655   g_task_set_priority (task, io_priority);
5656
5657   g_task_run_in_thread (task, create_async_thread);
5658   g_object_unref (task);
5659 }
5660
5661 static GFileOutputStream *
5662 g_file_real_create_finish (GFile         *file,
5663                            GAsyncResult  *res,
5664                            GError       **error)
5665 {
5666   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5667
5668   return g_task_propagate_pointer (G_TASK (res), error);
5669 }
5670
5671 typedef struct {
5672   GFileOutputStream *stream;
5673   char *etag;
5674   gboolean make_backup;
5675   GFileCreateFlags flags;
5676 } ReplaceAsyncData;
5677
5678 static void
5679 replace_async_data_free (ReplaceAsyncData *data)
5680 {
5681   if (data->stream)
5682     g_object_unref (data->stream);
5683   g_free (data->etag);
5684   g_free (data);
5685 }
5686
5687 static void
5688 replace_async_thread (GTask         *task,
5689                       gpointer       source_object,
5690                       gpointer       task_data,
5691                       GCancellable  *cancellable)
5692 {
5693   GFileOutputStream *stream;
5694   ReplaceAsyncData *data = task_data;
5695   GError *error = NULL;
5696
5697   stream = g_file_replace (G_FILE (source_object),
5698                            data->etag,
5699                            data->make_backup,
5700                            data->flags,
5701                            cancellable,
5702                            &error);
5703
5704   if (stream)
5705     g_task_return_pointer (task, stream, g_object_unref);
5706   else
5707     g_task_return_error (task, error);
5708 }
5709
5710 static void
5711 g_file_real_replace_async (GFile               *file,
5712                            const char          *etag,
5713                            gboolean             make_backup,
5714                            GFileCreateFlags     flags,
5715                            int                  io_priority,
5716                            GCancellable        *cancellable,
5717                            GAsyncReadyCallback  callback,
5718                            gpointer             user_data)
5719 {
5720   GTask *task;
5721   ReplaceAsyncData *data;
5722
5723   data = g_new0 (ReplaceAsyncData, 1);
5724   data->etag = g_strdup (etag);
5725   data->make_backup = make_backup;
5726   data->flags = flags;
5727
5728   task = g_task_new (file, cancellable, callback, user_data);
5729   g_task_set_task_data (task, data, (GDestroyNotify)replace_async_data_free);
5730   g_task_set_priority (task, io_priority);
5731
5732   g_task_run_in_thread (task, replace_async_thread);
5733   g_object_unref (task);
5734 }
5735
5736 static GFileOutputStream *
5737 g_file_real_replace_finish (GFile         *file,
5738                             GAsyncResult  *res,
5739                             GError       **error)
5740 {
5741   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5742
5743   return g_task_propagate_pointer (G_TASK (res), error);
5744 }
5745
5746 static void
5747 delete_async_thread (GTask        *task,
5748                      gpointer      object,
5749                      gpointer      task_data,
5750                      GCancellable *cancellable)
5751 {
5752   GError *error = NULL;
5753
5754   if (g_file_delete (G_FILE (object), cancellable, &error))
5755     g_task_return_boolean (task, TRUE);
5756   else
5757     g_task_return_error (task, error);
5758 }
5759
5760 static void
5761 g_file_real_delete_async (GFile               *file,
5762                           int                  io_priority,
5763                           GCancellable        *cancellable,
5764                           GAsyncReadyCallback  callback,
5765                           gpointer             user_data)
5766 {
5767   GTask *task;
5768
5769   task = g_task_new (file, cancellable, callback, user_data);
5770   g_task_set_priority (task, io_priority);
5771   g_task_run_in_thread (task, delete_async_thread);
5772   g_object_unref (task);
5773 }
5774
5775 static gboolean
5776 g_file_real_delete_finish (GFile         *file,
5777                            GAsyncResult  *res,
5778                            GError       **error)
5779 {
5780   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
5781
5782   return g_task_propagate_boolean (G_TASK (res), error);
5783 }
5784
5785 static void
5786 trash_async_thread (GTask        *task,
5787                     gpointer      object,
5788                     gpointer      task_data,
5789                     GCancellable *cancellable)
5790 {
5791   GError *error = NULL;
5792
5793   if (g_file_trash (G_FILE (object), cancellable, &error))
5794     g_task_return_boolean (task, TRUE);
5795   else
5796     g_task_return_error (task, error);
5797 }
5798
5799 static void
5800 g_file_real_trash_async (GFile               *file,
5801                          int                  io_priority,
5802                          GCancellable        *cancellable,
5803                          GAsyncReadyCallback  callback,
5804                          gpointer             user_data)
5805 {
5806   GTask *task;
5807
5808   task = g_task_new (file, cancellable, callback, user_data);
5809   g_task_set_priority (task, io_priority);
5810   g_task_run_in_thread (task, trash_async_thread);
5811   g_object_unref (task);
5812 }
5813
5814 static gboolean
5815 g_file_real_trash_finish (GFile         *file,
5816                           GAsyncResult  *res,
5817                           GError       **error)
5818 {
5819   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
5820
5821   return g_task_propagate_boolean (G_TASK (res), error);
5822 }
5823
5824 static void
5825 make_directory_async_thread (GTask        *task,
5826                              gpointer      object,
5827                              gpointer      task_data,
5828                              GCancellable *cancellable)
5829 {
5830   GError *error = NULL;
5831
5832   if (g_file_make_directory (G_FILE (object), cancellable, &error))
5833     g_task_return_boolean (task, TRUE);
5834   else
5835     g_task_return_error (task, error);
5836 }
5837
5838 static void
5839 g_file_real_make_directory_async (GFile               *file,
5840                                   int                  io_priority,
5841                                   GCancellable        *cancellable,
5842                                   GAsyncReadyCallback  callback,
5843                                   gpointer             user_data)
5844 {
5845   GTask *task;
5846
5847   task = g_task_new (file, cancellable, callback, user_data);
5848   g_task_set_priority (task, io_priority);
5849   g_task_run_in_thread (task, make_directory_async_thread);
5850   g_object_unref (task);
5851 }
5852
5853 static gboolean
5854 g_file_real_make_directory_finish (GFile         *file,
5855                                    GAsyncResult  *res,
5856                                    GError       **error)
5857 {
5858   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
5859
5860   return g_task_propagate_boolean (G_TASK (res), error);
5861 }
5862
5863 static void
5864 open_readwrite_async_thread (GTask        *task,
5865                              gpointer      object,
5866                              gpointer      task_data,
5867                              GCancellable *cancellable)
5868 {
5869   GFileIOStream *stream;
5870   GError *error = NULL;
5871
5872   stream = g_file_open_readwrite (G_FILE (object), cancellable, &error);
5873
5874   if (stream == NULL)
5875     g_task_return_error (task, error);
5876   else
5877     g_task_return_pointer (task, stream, g_object_unref);
5878 }
5879
5880 static void
5881 g_file_real_open_readwrite_async (GFile               *file,
5882                                   int                  io_priority,
5883                                   GCancellable        *cancellable,
5884                                   GAsyncReadyCallback  callback,
5885                                   gpointer             user_data)
5886 {
5887   GTask *task;
5888
5889   task = g_task_new (file, cancellable, callback, user_data);
5890   g_task_set_priority (task, io_priority);
5891
5892   g_task_run_in_thread (task, open_readwrite_async_thread);
5893   g_object_unref (task);
5894 }
5895
5896 static GFileIOStream *
5897 g_file_real_open_readwrite_finish (GFile         *file,
5898                                    GAsyncResult  *res,
5899                                    GError       **error)
5900 {
5901   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5902
5903   return g_task_propagate_pointer (G_TASK (res), error);
5904 }
5905
5906 static void
5907 create_readwrite_async_thread (GTask        *task,
5908                                gpointer      object,
5909                                gpointer      task_data,
5910                                GCancellable *cancellable)
5911 {
5912   GFileCreateFlags *data = task_data;
5913   GFileIOStream *stream;
5914   GError *error = NULL;
5915
5916   stream = g_file_create_readwrite (G_FILE (object), *data, cancellable, &error);
5917
5918   if (stream == NULL)
5919     g_task_return_error (task, error);
5920   else
5921     g_task_return_pointer (task, stream, g_object_unref);
5922 }
5923
5924 static void
5925 g_file_real_create_readwrite_async (GFile               *file,
5926                                     GFileCreateFlags     flags,
5927                                     int                  io_priority,
5928                                     GCancellable        *cancellable,
5929                                     GAsyncReadyCallback  callback,
5930                                     gpointer             user_data)
5931 {
5932   GFileCreateFlags *data;
5933   GTask *task;
5934
5935   data = g_new0 (GFileCreateFlags, 1);
5936   *data = flags;
5937
5938   task = g_task_new (file, cancellable, callback, user_data);
5939   g_task_set_task_data (task, data, g_free);
5940   g_task_set_priority (task, io_priority);
5941
5942   g_task_run_in_thread (task, create_readwrite_async_thread);
5943   g_object_unref (task);
5944 }
5945
5946 static GFileIOStream *
5947 g_file_real_create_readwrite_finish (GFile         *file,
5948                                      GAsyncResult  *res,
5949                                      GError       **error)
5950 {
5951   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5952
5953   return g_task_propagate_pointer (G_TASK (res), error);
5954 }
5955
5956 typedef struct {
5957   char *etag;
5958   gboolean make_backup;
5959   GFileCreateFlags flags;
5960 } ReplaceRWAsyncData;
5961
5962 static void
5963 replace_rw_async_data_free (ReplaceRWAsyncData *data)
5964 {
5965   g_free (data->etag);
5966   g_free (data);
5967 }
5968
5969 static void
5970 replace_readwrite_async_thread (GTask        *task,
5971                                 gpointer      object,
5972                                 gpointer      task_data,
5973                                 GCancellable *cancellable)
5974 {
5975   GFileIOStream *stream;
5976   GError *error = NULL;
5977   ReplaceRWAsyncData *data = task_data;
5978
5979   stream = g_file_replace_readwrite (G_FILE (object),
5980                                      data->etag,
5981                                      data->make_backup,
5982                                      data->flags,
5983                                      cancellable,
5984                                      &error);
5985
5986   if (stream == NULL)
5987     g_task_return_error (task, error);
5988   else
5989     g_task_return_pointer (task, stream, g_object_unref);
5990 }
5991
5992 static void
5993 g_file_real_replace_readwrite_async (GFile               *file,
5994                                      const char          *etag,
5995                                      gboolean             make_backup,
5996                                      GFileCreateFlags     flags,
5997                                      int                  io_priority,
5998                                      GCancellable        *cancellable,
5999                                      GAsyncReadyCallback  callback,
6000                                      gpointer             user_data)
6001 {
6002   GTask *task;
6003   ReplaceRWAsyncData *data;
6004
6005   data = g_new0 (ReplaceRWAsyncData, 1);
6006   data->etag = g_strdup (etag);
6007   data->make_backup = make_backup;
6008   data->flags = flags;
6009
6010   task = g_task_new (file, cancellable, callback, user_data);
6011   g_task_set_task_data (task, data, (GDestroyNotify)replace_rw_async_data_free);
6012   g_task_set_priority (task, io_priority);
6013
6014   g_task_run_in_thread (task, replace_readwrite_async_thread);
6015   g_object_unref (task);
6016 }
6017
6018 static GFileIOStream *
6019 g_file_real_replace_readwrite_finish (GFile         *file,
6020                                       GAsyncResult  *res,
6021                                       GError       **error)
6022 {
6023   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6024
6025   return g_task_propagate_pointer (G_TASK (res), error);
6026 }
6027
6028 static void
6029 set_display_name_async_thread (GTask        *task,
6030                                gpointer      object,
6031                                gpointer      task_data,
6032                                GCancellable *cancellable)
6033 {
6034   GError *error = NULL;
6035   char *name = task_data;
6036   GFile *file;
6037
6038   file = g_file_set_display_name (G_FILE (object), name, cancellable, &error);
6039
6040   if (file == NULL)
6041     g_task_return_error (task, error);
6042   else
6043     g_task_return_pointer (task, file, g_object_unref);
6044 }
6045
6046 static void
6047 g_file_real_set_display_name_async (GFile               *file,
6048                                     const char          *display_name,
6049                                     int                  io_priority,
6050                                     GCancellable        *cancellable,
6051                                     GAsyncReadyCallback  callback,
6052                                     gpointer             user_data)
6053 {
6054   GTask *task;
6055
6056   task = g_task_new (file, cancellable, callback, user_data);
6057   g_task_set_task_data (task, g_strdup (display_name), g_free);
6058   g_task_set_priority (task, io_priority);
6059
6060   g_task_run_in_thread (task, set_display_name_async_thread);
6061   g_object_unref (task);
6062 }
6063
6064 static GFile *
6065 g_file_real_set_display_name_finish (GFile         *file,
6066                                      GAsyncResult  *res,
6067                                      GError       **error)
6068 {
6069   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6070
6071   return g_task_propagate_pointer (G_TASK (res), error);
6072 }
6073
6074 typedef struct {
6075   GFileQueryInfoFlags flags;
6076   GFileInfo *info;
6077   gboolean res;
6078   GError *error;
6079 } SetInfoAsyncData;
6080
6081 static void
6082 set_info_data_free (SetInfoAsyncData *data)
6083 {
6084   if (data->info)
6085     g_object_unref (data->info);
6086   if (data->error)
6087     g_error_free (data->error);
6088   g_free (data);
6089 }
6090
6091 static void
6092 set_info_async_thread (GTask        *task,
6093                        gpointer      object,
6094                        gpointer      task_data,
6095                        GCancellable *cancellable)
6096 {
6097   SetInfoAsyncData *data = task_data;
6098
6099   data->error = NULL;
6100   data->res = g_file_set_attributes_from_info (G_FILE (object),
6101                                                data->info,
6102                                                data->flags,
6103                                                cancellable,
6104                                                &data->error);
6105 }
6106
6107 static void
6108 g_file_real_set_attributes_async (GFile               *file,
6109                                   GFileInfo           *info,
6110                                   GFileQueryInfoFlags  flags,
6111                                   int                  io_priority,
6112                                   GCancellable        *cancellable,
6113                                   GAsyncReadyCallback  callback,
6114                                   gpointer             user_data)
6115 {
6116   GTask *task;
6117   SetInfoAsyncData *data;
6118
6119   data = g_new0 (SetInfoAsyncData, 1);
6120   data->info = g_file_info_dup (info);
6121   data->flags = flags;
6122
6123   task = g_task_new (file, cancellable, callback, user_data);
6124   g_task_set_task_data (task, data, (GDestroyNotify)set_info_data_free);
6125   g_task_set_priority (task, io_priority);
6126
6127   g_task_run_in_thread (task, set_info_async_thread);
6128   g_object_unref (task);
6129 }
6130
6131 static gboolean
6132 g_file_real_set_attributes_finish (GFile         *file,
6133                                    GAsyncResult  *res,
6134                                    GFileInfo    **info,
6135                                    GError       **error)
6136 {
6137   SetInfoAsyncData *data;
6138
6139   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6140
6141   data = g_task_get_task_data (G_TASK (res));
6142
6143   if (info)
6144     *info = g_object_ref (data->info);
6145
6146   if (error != NULL && data->error)
6147     *error = g_error_copy (data->error);
6148
6149   return data->res;
6150 }
6151
6152 static void
6153 find_enclosing_mount_async_thread (GTask        *task,
6154                                    gpointer      object,
6155                                    gpointer      task_data,
6156                                    GCancellable *cancellable)
6157 {
6158   GError *error = NULL;
6159   GMount *mount;
6160
6161   mount = g_file_find_enclosing_mount (G_FILE (object), cancellable, &error);
6162
6163   if (mount == NULL)
6164     g_task_return_error (task, error);
6165   else
6166     g_task_return_pointer (task, mount, g_object_unref);
6167 }
6168
6169 static void
6170 g_file_real_find_enclosing_mount_async (GFile               *file,
6171                                         int                  io_priority,
6172                                         GCancellable        *cancellable,
6173                                         GAsyncReadyCallback  callback,
6174                                         gpointer             user_data)
6175 {
6176   GTask *task;
6177
6178   task = g_task_new (file, cancellable, callback, user_data);
6179   g_task_set_priority (task, io_priority);
6180
6181   g_task_run_in_thread (task, find_enclosing_mount_async_thread);
6182   g_object_unref (task);
6183 }
6184
6185 static GMount *
6186 g_file_real_find_enclosing_mount_finish (GFile         *file,
6187                                          GAsyncResult  *res,
6188                                          GError       **error)
6189 {
6190   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6191
6192   return g_task_propagate_pointer (G_TASK (res), error);
6193 }
6194
6195
6196 typedef struct {
6197   GFile *source;
6198   GFile *destination;
6199   GFileCopyFlags flags;
6200   GFileProgressCallback progress_cb;
6201   gpointer progress_cb_data;
6202 } CopyAsyncData;
6203
6204 static void
6205 copy_async_data_free (CopyAsyncData *data)
6206 {
6207   g_object_unref (data->source);
6208   g_object_unref (data->destination);
6209   g_slice_free (CopyAsyncData, data);
6210 }
6211
6212 typedef struct {
6213   CopyAsyncData *data;
6214   goffset current_num_bytes;
6215   goffset total_num_bytes;
6216 } ProgressData;
6217
6218 static gboolean
6219 copy_async_progress_in_main (gpointer user_data)
6220 {
6221   ProgressData *progress = user_data;
6222   CopyAsyncData *data = progress->data;
6223
6224   data->progress_cb (progress->current_num_bytes,
6225                      progress->total_num_bytes,
6226                      data->progress_cb_data);
6227
6228   return FALSE;
6229 }
6230
6231 static void
6232 copy_async_progress_callback (goffset  current_num_bytes,
6233                               goffset  total_num_bytes,
6234                               gpointer user_data)
6235 {
6236   GTask *task = user_data;
6237   CopyAsyncData *data = g_task_get_task_data (task);
6238   ProgressData *progress;
6239
6240   progress = g_new (ProgressData, 1);
6241   progress->data = data;
6242   progress->current_num_bytes = current_num_bytes;
6243   progress->total_num_bytes = total_num_bytes;
6244
6245   g_main_context_invoke_full (g_task_get_context (task),
6246                               g_task_get_priority (task),
6247                               copy_async_progress_in_main,
6248                               progress,
6249                               g_free);
6250 }
6251
6252 static void
6253 copy_async_thread (GTask        *task,
6254                    gpointer      source,
6255                    gpointer      task_data,
6256                    GCancellable *cancellable)
6257 {
6258   CopyAsyncData *data = task_data;
6259   gboolean result;
6260   GError *error = NULL;
6261
6262   result = g_file_copy (data->source,
6263                         data->destination,
6264                         data->flags,
6265                         cancellable,
6266                         (data->progress_cb != NULL) ? copy_async_progress_callback : NULL,
6267                         task,
6268                         &error);
6269   if (result)
6270     g_task_return_boolean (task, TRUE);
6271   else
6272     g_task_return_error (task, error);
6273 }
6274
6275 static void
6276 g_file_real_copy_async (GFile                  *source,
6277                         GFile                  *destination,
6278                         GFileCopyFlags          flags,
6279                         int                     io_priority,
6280                         GCancellable           *cancellable,
6281                         GFileProgressCallback   progress_callback,
6282                         gpointer                progress_callback_data,
6283                         GAsyncReadyCallback     callback,
6284                         gpointer                user_data)
6285 {
6286   GTask *task;
6287   CopyAsyncData *data;
6288
6289   data = g_slice_new (CopyAsyncData);
6290   data->source = g_object_ref (source);
6291   data->destination = g_object_ref (destination);
6292   data->flags = flags;
6293   data->progress_cb = progress_callback;
6294   data->progress_cb_data = progress_callback_data;
6295
6296   task = g_task_new (source, cancellable, callback, user_data);
6297   g_task_set_task_data (task, data, (GDestroyNotify)copy_async_data_free);
6298   g_task_set_priority (task, io_priority);
6299   g_task_run_in_thread (task, copy_async_thread);
6300   g_object_unref (task);
6301 }
6302
6303 static gboolean
6304 g_file_real_copy_finish (GFile        *file,
6305                          GAsyncResult *res,
6306                          GError      **error)
6307 {
6308   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6309
6310   return g_task_propagate_boolean (G_TASK (res), error);
6311 }
6312
6313
6314 /********************************************
6315  *   Default VFS operations                 *
6316  ********************************************/
6317
6318 /**
6319  * g_file_new_for_path:
6320  * @path: a string containing a relative or absolute path.
6321  *     The string must be encoded in the glib filename encoding.
6322  *
6323  * Constructs a #GFile for a given path. This operation never
6324  * fails, but the returned object might not support any I/O
6325  * operation if @path is malformed.
6326  *
6327  * Returns: (transfer full): a new #GFile for the given @path.
6328  *   Free the returned object with g_object_unref().
6329  */
6330 GFile *
6331 g_file_new_for_path (const char *path)
6332 {
6333   g_return_val_if_fail (path != NULL, NULL);
6334
6335   return g_vfs_get_file_for_path (g_vfs_get_default (), path);
6336 }
6337
6338 /**
6339  * g_file_new_for_uri:
6340  * @uri: a UTF-8 string containing a URI
6341  *
6342  * Constructs a #GFile for a given URI. This operation never
6343  * fails, but the returned object might not support any I/O
6344  * operation if @uri is malformed or if the uri type is
6345  * not supported.
6346  *
6347  * Returns: (transfer full): a new #GFile for the given @uri.
6348  *     Free the returned object with g_object_unref().
6349  */
6350 GFile *
6351 g_file_new_for_uri (const char *uri)
6352 {
6353   g_return_val_if_fail (uri != NULL, NULL);
6354
6355   return g_vfs_get_file_for_uri (g_vfs_get_default (), uri);
6356 }
6357
6358 /**
6359  * g_file_new_tmp:
6360  * @tmpl: (type filename) (allow-none): Template for the file
6361  *   name, as in g_file_open_tmp(), or %NULL for a default template
6362  * @iostream: (out): on return, a #GFileIOStream for the created file
6363  * @error: a #GError, or %NULL
6364  *
6365  * Opens a file in the preferred directory for temporary files (as
6366  * returned by g_get_tmp_dir()) and returns a #GFile and
6367  * #GFileIOStream pointing to it.
6368  *
6369  * @tmpl should be a string in the GLib file name encoding
6370  * containing a sequence of six 'X' characters, and containing no
6371  * directory components. If it is %NULL, a default template is used.
6372  *
6373  * Unlike the other #GFile constructors, this will return %NULL if
6374  * a temporary file could not be created.
6375  *
6376  * Returns: (transfer full): a new #GFile.
6377  *     Free the returned object with g_object_unref().
6378  *
6379  * Since: 2.32
6380  */
6381 GFile *
6382 g_file_new_tmp (const char     *tmpl,
6383                 GFileIOStream **iostream,
6384                 GError        **error)
6385 {
6386   gint fd;
6387   gchar *path;
6388   GFile *file;
6389   GFileOutputStream *output;
6390
6391   g_return_val_if_fail (iostream != NULL, NULL);
6392
6393   fd = g_file_open_tmp (tmpl, &path, error);
6394   if (fd == -1)
6395     return NULL;
6396
6397   file = g_file_new_for_path (path);
6398
6399   output = _g_local_file_output_stream_new (fd);
6400   *iostream = _g_local_file_io_stream_new (G_LOCAL_FILE_OUTPUT_STREAM (output));
6401
6402   g_object_unref (output);
6403   g_free (path);
6404
6405   return file;
6406 }
6407
6408 /**
6409  * g_file_parse_name:
6410  * @parse_name: a file name or path to be parsed
6411  *
6412  * Constructs a #GFile with the given @parse_name (i.e. something
6413  * given by g_file_get_parse_name()). This operation never fails,
6414  * but the returned object might not support any I/O operation if
6415  * the @parse_name cannot be parsed.
6416  *
6417  * Returns: (transfer full): a new #GFile.
6418  */
6419 GFile *
6420 g_file_parse_name (const char *parse_name)
6421 {
6422   g_return_val_if_fail (parse_name != NULL, NULL);
6423
6424   return g_vfs_parse_name (g_vfs_get_default (), parse_name);
6425 }
6426
6427 static gboolean
6428 is_valid_scheme_character (char c)
6429 {
6430   return g_ascii_isalnum (c) || c == '+' || c == '-' || c == '.';
6431 }
6432
6433 /* Following RFC 2396, valid schemes are built like:
6434  *       scheme        = alpha *( alpha | digit | "+" | "-" | "." )
6435  */
6436 static gboolean
6437 has_valid_scheme (const char *uri)
6438 {
6439   const char *p;
6440
6441   p = uri;
6442
6443   if (!g_ascii_isalpha (*p))
6444     return FALSE;
6445
6446   do {
6447     p++;
6448   } while (is_valid_scheme_character (*p));
6449
6450   return *p == ':';
6451 }
6452
6453 static GFile *
6454 new_for_cmdline_arg (const gchar *arg,
6455                      const gchar *cwd)
6456 {
6457   GFile *file;
6458   char *filename;
6459
6460   if (g_path_is_absolute (arg))
6461     return g_file_new_for_path (arg);
6462
6463   if (has_valid_scheme (arg))
6464     return g_file_new_for_uri (arg);
6465
6466   if (cwd == NULL)
6467     {
6468       char *current_dir;
6469
6470       current_dir = g_get_current_dir ();
6471       filename = g_build_filename (current_dir, arg, NULL);
6472       g_free (current_dir);
6473     }
6474   else
6475     filename = g_build_filename (cwd, arg, NULL);
6476
6477   file = g_file_new_for_path (filename);
6478   g_free (filename);
6479
6480   return file;
6481 }
6482
6483 /**
6484  * g_file_new_for_commandline_arg:
6485  * @arg: a command line string
6486  *
6487  * Creates a #GFile with the given argument from the command line.
6488  * The value of @arg can be either a URI, an absolute path or a
6489  * relative path resolved relative to the current working directory.
6490  * This operation never fails, but the returned object might not
6491  * support any I/O operation if @arg points to a malformed path.
6492  *
6493  * Note that on Windows, this function expects its argument to be in
6494  * UTF-8 -- not the system code page.  This means that you
6495  * should not use this function with string from argv as it is passed
6496  * to main().  g_win32_get_command_line() will return a UTF-8 version of
6497  * the commandline.  #GApplication also uses UTF-8 but
6498  * g_application_command_line_create_file_for_arg() may be more useful
6499  * for you there.  It is also always possible to use this function with
6500  * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
6501  *
6502  * Returns: (transfer full): a new #GFile.
6503  *    Free the returned object with g_object_unref().
6504  */
6505 GFile *
6506 g_file_new_for_commandline_arg (const char *arg)
6507 {
6508   g_return_val_if_fail (arg != NULL, NULL);
6509
6510   return new_for_cmdline_arg (arg, NULL);
6511 }
6512
6513 /**
6514  * g_file_new_for_commandline_arg_and_cwd:
6515  * @arg: a command line string
6516  * @cwd: the current working directory of the commandline
6517  *
6518  * Creates a #GFile with the given argument from the command line.
6519  *
6520  * This function is similar to g_file_new_for_commandline_arg() except
6521  * that it allows for passing the current working directory as an
6522  * argument instead of using the current working directory of the
6523  * process.
6524  *
6525  * This is useful if the commandline argument was given in a context
6526  * other than the invocation of the current process.
6527  *
6528  * See also g_application_command_line_create_file_for_arg().
6529  *
6530  * Returns: (transfer full): a new #GFile
6531  *
6532  * Since: 2.36
6533  **/
6534 GFile *
6535 g_file_new_for_commandline_arg_and_cwd (const gchar *arg,
6536                                         const gchar *cwd)
6537 {
6538   g_return_val_if_fail (arg != NULL, NULL);
6539   g_return_val_if_fail (cwd != NULL, NULL);
6540
6541   return new_for_cmdline_arg (arg, cwd);
6542 }
6543
6544 /**
6545  * g_file_mount_enclosing_volume:
6546  * @location: input #GFile
6547  * @flags: flags affecting the operation
6548  * @mount_operation: (allow-none): a #GMountOperation
6549  *     or %NULL to avoid user interaction
6550  * @cancellable: (allow-none): optional #GCancellable object,
6551  *     %NULL to ignore
6552  * @callback: (allow-none): a #GAsyncReadyCallback to call
6553  *     when the request is satisfied, or %NULL
6554  * @user_data: the data to pass to callback function
6555  *
6556  * Starts a @mount_operation, mounting the volume that contains
6557  * the file @location.
6558  *
6559  * When this operation has completed, @callback will be called with
6560  * @user_user data, and the operation can be finalized with
6561  * g_file_mount_enclosing_volume_finish().
6562  *
6563  * If @cancellable is not %NULL, then the operation can be cancelled by
6564  * triggering the cancellable object from another thread. If the operation
6565  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6566  */
6567 void
6568 g_file_mount_enclosing_volume (GFile               *location,
6569                                GMountMountFlags     flags,
6570                                GMountOperation     *mount_operation,
6571                                GCancellable        *cancellable,
6572                                GAsyncReadyCallback  callback,
6573                                gpointer             user_data)
6574 {
6575   GFileIface *iface;
6576
6577   g_return_if_fail (G_IS_FILE (location));
6578
6579   iface = G_FILE_GET_IFACE (location);
6580
6581   if (iface->mount_enclosing_volume == NULL)
6582     {
6583       g_task_report_new_error (location, callback, user_data,
6584                                g_file_mount_enclosing_volume,
6585                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
6586                                _("volume doesn't implement mount"));
6587       return;
6588     }
6589
6590   (* iface->mount_enclosing_volume) (location, flags, mount_operation, cancellable, callback, user_data);
6591
6592 }
6593
6594 /**
6595  * g_file_mount_enclosing_volume_finish:
6596  * @location: input #GFile
6597  * @result: a #GAsyncResult
6598  * @error: a #GError, or %NULL
6599  *
6600  * Finishes a mount operation started by g_file_mount_enclosing_volume().
6601  *
6602  * Returns: %TRUE if successful. If an error has occurred,
6603  *     this function will return %FALSE and set @error
6604  *     appropriately if present.
6605  */
6606 gboolean
6607 g_file_mount_enclosing_volume_finish (GFile         *location,
6608                                       GAsyncResult  *result,
6609                                       GError       **error)
6610 {
6611   GFileIface *iface;
6612
6613   g_return_val_if_fail (G_IS_FILE (location), FALSE);
6614   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
6615
6616   if (g_async_result_legacy_propagate_error (result, error))
6617     return FALSE;
6618   else if (g_async_result_is_tagged (result, g_file_mount_enclosing_volume))
6619     return g_task_propagate_boolean (G_TASK (result), error);
6620
6621   iface = G_FILE_GET_IFACE (location);
6622
6623   return (* iface->mount_enclosing_volume_finish) (location, result, error);
6624 }
6625
6626 /********************************************
6627  *   Utility functions                      *
6628  ********************************************/
6629
6630 /**
6631  * g_file_query_default_handler:
6632  * @file: a #GFile to open
6633  * @cancellable: optional #GCancellable object, %NULL to ignore
6634  * @error: a #GError, or %NULL
6635  *
6636  * Returns the #GAppInfo that is registered as the default
6637  * application to handle the file specified by @file.
6638  *
6639  * If @cancellable is not %NULL, then the operation can be cancelled by
6640  * triggering the cancellable object from another thread. If the operation
6641  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6642  *
6643  * Returns: (transfer full): a #GAppInfo if the handle was found,
6644  *     %NULL if there were errors.
6645  *     When you are done with it, release it with g_object_unref()
6646  */
6647 GAppInfo *
6648 g_file_query_default_handler (GFile         *file,
6649                               GCancellable  *cancellable,
6650                               GError       **error)
6651 {
6652   char *uri_scheme;
6653   const char *content_type;
6654   GAppInfo *appinfo;
6655   GFileInfo *info;
6656   char *path;
6657
6658   uri_scheme = g_file_get_uri_scheme (file);
6659   if (uri_scheme && uri_scheme[0] != '\0')
6660     {
6661       appinfo = g_app_info_get_default_for_uri_scheme (uri_scheme);
6662       g_free (uri_scheme);
6663
6664       if (appinfo != NULL)
6665         return appinfo;
6666     }
6667
6668   info = g_file_query_info (file,
6669                             G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE,
6670                             0,
6671                             cancellable,
6672                             error);
6673   if (info == NULL)
6674     return NULL;
6675
6676   appinfo = NULL;
6677
6678   content_type = g_file_info_get_content_type (info);
6679   if (content_type)
6680     {
6681       /* Don't use is_native(), as we want to support fuse paths if available */
6682       path = g_file_get_path (file);
6683       appinfo = g_app_info_get_default_for_type (content_type,
6684                                                  path == NULL);
6685       g_free (path);
6686     }
6687
6688   g_object_unref (info);
6689
6690   if (appinfo != NULL)
6691     return appinfo;
6692
6693   g_set_error_literal (error, G_IO_ERROR,
6694                        G_IO_ERROR_NOT_SUPPORTED,
6695                        _("No application is registered as handling this file"));
6696   return NULL;
6697 }
6698
6699 #define GET_CONTENT_BLOCK_SIZE 8192
6700
6701 /**
6702  * g_file_load_contents:
6703  * @file: input #GFile
6704  * @cancellable: optional #GCancellable object, %NULL to ignore
6705  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
6706  * @length: (out) (allow-none): a location to place the length of the contents of the file,
6707  *    or %NULL if the length is not needed
6708  * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
6709  *    or %NULL if the entity tag is not needed
6710  * @error: a #GError, or %NULL
6711  *
6712  * Loads the content of the file into memory. The data is always
6713  * zero-terminated, but this is not included in the resultant @length.
6714  * The returned @content should be freed with g_free() when no longer
6715  * needed.
6716  *
6717  * If @cancellable is not %NULL, then the operation can be cancelled by
6718  * triggering the cancellable object from another thread. If the operation
6719  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6720  *
6721  * Returns: %TRUE if the @file's contents were successfully loaded.
6722  *     %FALSE if there were errors.
6723  */
6724 gboolean
6725 g_file_load_contents (GFile         *file,
6726                       GCancellable  *cancellable,
6727                       char         **contents,
6728                       gsize         *length,
6729                       char         **etag_out,
6730                       GError       **error)
6731 {
6732   GFileInputStream *in;
6733   GByteArray *content;
6734   gsize pos;
6735   gssize res;
6736   GFileInfo *info;
6737
6738   g_return_val_if_fail (G_IS_FILE (file), FALSE);
6739   g_return_val_if_fail (contents != NULL, FALSE);
6740
6741   in = g_file_read (file, cancellable, error);
6742   if (in == NULL)
6743     return FALSE;
6744
6745   content = g_byte_array_new ();
6746   pos = 0;
6747
6748   g_byte_array_set_size (content, pos + GET_CONTENT_BLOCK_SIZE + 1);
6749   while ((res = g_input_stream_read (G_INPUT_STREAM (in),
6750                                      content->data + pos,
6751                                      GET_CONTENT_BLOCK_SIZE,
6752                                      cancellable, error)) > 0)
6753     {
6754       pos += res;
6755       g_byte_array_set_size (content, pos + GET_CONTENT_BLOCK_SIZE + 1);
6756     }
6757
6758   if (etag_out)
6759     {
6760       *etag_out = NULL;
6761
6762       info = g_file_input_stream_query_info (in,
6763                                              G_FILE_ATTRIBUTE_ETAG_VALUE,
6764                                              cancellable,
6765                                              NULL);
6766       if (info)
6767         {
6768           *etag_out = g_strdup (g_file_info_get_etag (info));
6769           g_object_unref (info);
6770         }
6771     }
6772
6773   /* Ignore errors on close */
6774   g_input_stream_close (G_INPUT_STREAM (in), cancellable, NULL);
6775   g_object_unref (in);
6776
6777   if (res < 0)
6778     {
6779       /* error is set already */
6780       g_byte_array_free (content, TRUE);
6781       return FALSE;
6782     }
6783
6784   if (length)
6785     *length = pos;
6786
6787   /* Zero terminate (we got an extra byte allocated for this */
6788   content->data[pos] = 0;
6789
6790   *contents = (char *)g_byte_array_free (content, FALSE);
6791
6792   return TRUE;
6793 }
6794
6795 typedef struct {
6796   GTask *task;
6797   GFileReadMoreCallback read_more_callback;
6798   GByteArray *content;
6799   gsize pos;
6800   char *etag;
6801 } LoadContentsData;
6802
6803
6804 static void
6805 load_contents_data_free (LoadContentsData *data)
6806 {
6807   if (data->content)
6808     g_byte_array_free (data->content, TRUE);
6809   g_free (data->etag);
6810   g_free (data);
6811 }
6812
6813 static void
6814 load_contents_close_callback (GObject      *obj,
6815                               GAsyncResult *close_res,
6816                               gpointer      user_data)
6817 {
6818   GInputStream *stream = G_INPUT_STREAM (obj);
6819   LoadContentsData *data = user_data;
6820
6821   /* Ignore errors here, we're only reading anyway */
6822   g_input_stream_close_finish (stream, close_res, NULL);
6823   g_object_unref (stream);
6824
6825   g_task_return_boolean (data->task, TRUE);
6826   g_object_unref (data->task);
6827 }
6828
6829 static void
6830 load_contents_fstat_callback (GObject      *obj,
6831                               GAsyncResult *stat_res,
6832                               gpointer      user_data)
6833 {
6834   GInputStream *stream = G_INPUT_STREAM (obj);
6835   LoadContentsData *data = user_data;
6836   GFileInfo *info;
6837
6838   info = g_file_input_stream_query_info_finish (G_FILE_INPUT_STREAM (stream),
6839                                                 stat_res, NULL);
6840   if (info)
6841     {
6842       data->etag = g_strdup (g_file_info_get_etag (info));
6843       g_object_unref (info);
6844     }
6845
6846   g_input_stream_close_async (stream, 0,
6847                               g_task_get_cancellable (data->task),
6848                               load_contents_close_callback, data);
6849 }
6850
6851 static void
6852 load_contents_read_callback (GObject      *obj,
6853                              GAsyncResult *read_res,
6854                              gpointer      user_data)
6855 {
6856   GInputStream *stream = G_INPUT_STREAM (obj);
6857   LoadContentsData *data = user_data;
6858   GError *error = NULL;
6859   gssize read_size;
6860
6861   read_size = g_input_stream_read_finish (stream, read_res, &error);
6862
6863   if (read_size < 0)
6864     {
6865       g_task_return_error (data->task, error);
6866       g_object_unref (data->task);
6867
6868       /* Close the file ignoring any error */
6869       g_input_stream_close_async (stream, 0, NULL, NULL, NULL);
6870       g_object_unref (stream);
6871     }
6872   else if (read_size == 0)
6873     {
6874       g_file_input_stream_query_info_async (G_FILE_INPUT_STREAM (stream),
6875                                             G_FILE_ATTRIBUTE_ETAG_VALUE,
6876                                             0,
6877                                             g_task_get_cancellable (data->task),
6878                                             load_contents_fstat_callback,
6879                                             data);
6880     }
6881   else if (read_size > 0)
6882     {
6883       data->pos += read_size;
6884
6885       g_byte_array_set_size (data->content,
6886                              data->pos + GET_CONTENT_BLOCK_SIZE);
6887
6888
6889       if (data->read_more_callback &&
6890           !data->read_more_callback ((char *)data->content->data, data->pos,
6891                                      g_async_result_get_user_data (G_ASYNC_RESULT (data->task))))
6892         g_file_input_stream_query_info_async (G_FILE_INPUT_STREAM (stream),
6893                                               G_FILE_ATTRIBUTE_ETAG_VALUE,
6894                                               0,
6895                                               g_task_get_cancellable (data->task),
6896                                               load_contents_fstat_callback,
6897                                               data);
6898       else
6899         g_input_stream_read_async (stream,
6900                                    data->content->data + data->pos,
6901                                    GET_CONTENT_BLOCK_SIZE,
6902                                    0,
6903                                    g_task_get_cancellable (data->task),
6904                                    load_contents_read_callback,
6905                                    data);
6906     }
6907 }
6908
6909 static void
6910 load_contents_open_callback (GObject      *obj,
6911                              GAsyncResult *open_res,
6912                              gpointer      user_data)
6913 {
6914   GFile *file = G_FILE (obj);
6915   GFileInputStream *stream;
6916   LoadContentsData *data = user_data;
6917   GError *error = NULL;
6918
6919   stream = g_file_read_finish (file, open_res, &error);
6920
6921   if (stream)
6922     {
6923       g_byte_array_set_size (data->content,
6924                              data->pos + GET_CONTENT_BLOCK_SIZE);
6925       g_input_stream_read_async (G_INPUT_STREAM (stream),
6926                                  data->content->data + data->pos,
6927                                  GET_CONTENT_BLOCK_SIZE,
6928                                  0,
6929                                  g_task_get_cancellable (data->task),
6930                                  load_contents_read_callback,
6931                                  data);
6932     }
6933   else
6934     {
6935       g_task_return_error (data->task, error);
6936       g_object_unref (data->task);
6937     }
6938 }
6939
6940 /**
6941  * g_file_load_partial_contents_async: (skip)
6942  * @file: input #GFile
6943  * @cancellable: optional #GCancellable object, %NULL to ignore
6944  * @read_more_callback: a #GFileReadMoreCallback to receive partial data
6945  *     and to specify whether further data should be read
6946  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
6947  * @user_data: the data to pass to the callback functions
6948  *
6949  * Reads the partial contents of a file. A #GFileReadMoreCallback should
6950  * be used to stop reading from the file when appropriate, else this
6951  * function will behave exactly as g_file_load_contents_async(). This
6952  * operation can be finished by g_file_load_partial_contents_finish().
6953  *
6954  * Users of this function should be aware that @user_data is passed to
6955  * both the @read_more_callback and the @callback.
6956  *
6957  * If @cancellable is not %NULL, then the operation can be cancelled by
6958  * triggering the cancellable object from another thread. If the operation
6959  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6960  */
6961 void
6962 g_file_load_partial_contents_async (GFile                 *file,
6963                                     GCancellable          *cancellable,
6964                                     GFileReadMoreCallback  read_more_callback,
6965                                     GAsyncReadyCallback    callback,
6966                                     gpointer               user_data)
6967 {
6968   LoadContentsData *data;
6969
6970   g_return_if_fail (G_IS_FILE (file));
6971
6972   data = g_new0 (LoadContentsData, 1);
6973   data->read_more_callback = read_more_callback;
6974   data->content = g_byte_array_new ();
6975
6976   data->task = g_task_new (file, cancellable, callback, user_data);
6977   g_task_set_task_data (data->task, data, (GDestroyNotify)load_contents_data_free);
6978
6979   g_file_read_async (file,
6980                      0,
6981                      g_task_get_cancellable (data->task),
6982                      load_contents_open_callback,
6983                      data);
6984 }
6985
6986 /**
6987  * g_file_load_partial_contents_finish:
6988  * @file: input #GFile
6989  * @res: a #GAsyncResult
6990  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
6991  * @length: (out) (allow-none): a location to place the length of the contents of the file,
6992  *     or %NULL if the length is not needed
6993  * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
6994  *     or %NULL if the entity tag is not needed
6995  * @error: a #GError, or %NULL
6996  *
6997  * Finishes an asynchronous partial load operation that was started
6998  * with g_file_load_partial_contents_async(). The data is always
6999  * zero-terminated, but this is not included in the resultant @length.
7000  * The returned @content should be freed with g_free() when no longer
7001  * needed.
7002  *
7003  * Returns: %TRUE if the load was successful. If %FALSE and @error is
7004  *     present, it will be set appropriately.
7005  */
7006 gboolean
7007 g_file_load_partial_contents_finish (GFile         *file,
7008                                      GAsyncResult  *res,
7009                                      char         **contents,
7010                                      gsize         *length,
7011                                      char         **etag_out,
7012                                      GError       **error)
7013 {
7014   GTask *task;
7015   LoadContentsData *data;
7016
7017   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7018   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
7019   g_return_val_if_fail (contents != NULL, FALSE);
7020
7021   task = G_TASK (res);
7022
7023   if (!g_task_propagate_boolean (task, error))
7024     {
7025       if (length)
7026         *length = 0;
7027       return FALSE;
7028     }
7029
7030   data = g_task_get_task_data (task);
7031
7032   if (length)
7033     *length = data->pos;
7034
7035   if (etag_out)
7036     {
7037       *etag_out = data->etag;
7038       data->etag = NULL;
7039     }
7040
7041   /* Zero terminate */
7042   g_byte_array_set_size (data->content, data->pos + 1);
7043   data->content->data[data->pos] = 0;
7044
7045   *contents = (char *)g_byte_array_free (data->content, FALSE);
7046   data->content = NULL;
7047
7048   return TRUE;
7049 }
7050
7051 /**
7052  * g_file_load_contents_async:
7053  * @file: input #GFile
7054  * @cancellable: optional #GCancellable object, %NULL to ignore
7055  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7056  * @user_data: the data to pass to callback function
7057  *
7058  * Starts an asynchronous load of the @file's contents.
7059  *
7060  * For more details, see g_file_load_contents() which is
7061  * the synchronous version of this call.
7062  *
7063  * When the load operation has completed, @callback will be called
7064  * with @user data. To finish the operation, call
7065  * g_file_load_contents_finish() with the #GAsyncResult returned by
7066  * the @callback.
7067  *
7068  * If @cancellable is not %NULL, then the operation can be cancelled by
7069  * triggering the cancellable object from another thread. If the operation
7070  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7071  */
7072 void
7073 g_file_load_contents_async (GFile               *file,
7074                            GCancellable        *cancellable,
7075                            GAsyncReadyCallback  callback,
7076                            gpointer             user_data)
7077 {
7078   g_file_load_partial_contents_async (file,
7079                                       cancellable,
7080                                       NULL,
7081                                       callback, user_data);
7082 }
7083
7084 /**
7085  * g_file_load_contents_finish:
7086  * @file: input #GFile
7087  * @res: a #GAsyncResult
7088  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
7089  * @length: (out) (allow-none): a location to place the length of the contents of the file,
7090  *     or %NULL if the length is not needed
7091  * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
7092  *     or %NULL if the entity tag is not needed
7093  * @error: a #GError, or %NULL
7094  *
7095  * Finishes an asynchronous load of the @file's contents.
7096  * The contents are placed in @contents, and @length is set to the
7097  * size of the @contents string. The @content should be freed with
7098  * g_free() when no longer needed. If @etag_out is present, it will be
7099  * set to the new entity tag for the @file.
7100  *
7101  * Returns: %TRUE if the load was successful. If %FALSE and @error is
7102  *     present, it will be set appropriately.
7103  */
7104 gboolean
7105 g_file_load_contents_finish (GFile         *file,
7106                              GAsyncResult  *res,
7107                              char         **contents,
7108                              gsize         *length,
7109                              char         **etag_out,
7110                              GError       **error)
7111 {
7112   return g_file_load_partial_contents_finish (file,
7113                                               res,
7114                                               contents,
7115                                               length,
7116                                               etag_out,
7117                                               error);
7118 }
7119
7120 /**
7121  * g_file_replace_contents:
7122  * @file: input #GFile
7123  * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
7124  * @length: the length of @contents in bytes
7125  * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document,
7126  *     or %NULL
7127  * @make_backup: %TRUE if a backup should be created
7128  * @flags: a set of #GFileCreateFlags
7129  * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag]
7130  *      for the document. This should be freed with g_free() when no longer
7131  *      needed, or %NULL
7132  * @cancellable: optional #GCancellable object, %NULL to ignore
7133  * @error: a #GError, or %NULL
7134  *
7135  * Replaces the contents of @file with @contents of @length bytes.
7136  *
7137  * If @etag is specified (not %NULL), any existing file must have that etag,
7138  * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
7139  *
7140  * If @make_backup is %TRUE, this function will attempt to make a backup
7141  * of @file. Internally, it uses g_file_replace(), so will try to replace the
7142  * file contents in the safest way possible. For example, atomic renames are
7143  * used when replacing local files’ contents.
7144  *
7145  * If @cancellable is not %NULL, then the operation can be cancelled by
7146  * triggering the cancellable object from another thread. If the operation
7147  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7148  *
7149  * The returned @new_etag can be used to verify that the file hasn't
7150  * changed the next time it is saved over.
7151  *
7152  * Returns: %TRUE if successful. If an error has occurred, this function
7153  *     will return %FALSE and set @error appropriately if present.
7154  */
7155 gboolean
7156 g_file_replace_contents (GFile             *file,
7157                          const char        *contents,
7158                          gsize              length,
7159                          const char        *etag,
7160                          gboolean           make_backup,
7161                          GFileCreateFlags   flags,
7162                          char             **new_etag,
7163                          GCancellable      *cancellable,
7164                          GError           **error)
7165 {
7166   GFileOutputStream *out;
7167   gsize pos, remainder;
7168   gssize res;
7169   gboolean ret;
7170
7171   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7172   g_return_val_if_fail (contents != NULL, FALSE);
7173
7174   out = g_file_replace (file, etag, make_backup, flags, cancellable, error);
7175   if (out == NULL)
7176     return FALSE;
7177
7178   pos = 0;
7179   remainder = length;
7180   while (remainder > 0 &&
7181          (res = g_output_stream_write (G_OUTPUT_STREAM (out),
7182                                        contents + pos,
7183                                        MIN (remainder, GET_CONTENT_BLOCK_SIZE),
7184                                        cancellable,
7185                                        error)) > 0)
7186     {
7187       pos += res;
7188       remainder -= res;
7189     }
7190
7191   if (remainder > 0 && res < 0)
7192     {
7193       /* Ignore errors on close */
7194       g_output_stream_close (G_OUTPUT_STREAM (out), cancellable, NULL);
7195       g_object_unref (out);
7196
7197       /* error is set already */
7198       return FALSE;
7199     }
7200
7201   ret = g_output_stream_close (G_OUTPUT_STREAM (out), cancellable, error);
7202
7203   if (new_etag)
7204     *new_etag = g_file_output_stream_get_etag (out);
7205
7206   g_object_unref (out);
7207
7208   return ret;
7209 }
7210
7211 typedef struct {
7212   GTask *task;
7213   GBytes *content;
7214   gsize pos;
7215   char *etag;
7216   gboolean failed;
7217 } ReplaceContentsData;
7218
7219 static void
7220 replace_contents_data_free (ReplaceContentsData *data)
7221 {
7222   g_bytes_unref (data->content);
7223   g_free (data->etag);
7224   g_free (data);
7225 }
7226
7227 static void
7228 replace_contents_close_callback (GObject      *obj,
7229                                  GAsyncResult *close_res,
7230                                  gpointer      user_data)
7231 {
7232   GOutputStream *stream = G_OUTPUT_STREAM (obj);
7233   ReplaceContentsData *data = user_data;
7234
7235   /* Ignore errors here, we're only reading anyway */
7236   g_output_stream_close_finish (stream, close_res, NULL);
7237   g_object_unref (stream);
7238
7239   if (!data->failed)
7240     {
7241       data->etag = g_file_output_stream_get_etag (G_FILE_OUTPUT_STREAM (stream));
7242       g_task_return_boolean (data->task, TRUE);
7243     }
7244   g_object_unref (data->task);
7245 }
7246
7247 static void
7248 replace_contents_write_callback (GObject      *obj,
7249                                  GAsyncResult *read_res,
7250                                  gpointer      user_data)
7251 {
7252   GOutputStream *stream = G_OUTPUT_STREAM (obj);
7253   ReplaceContentsData *data = user_data;
7254   GError *error = NULL;
7255   gssize write_size;
7256
7257   write_size = g_output_stream_write_finish (stream, read_res, &error);
7258
7259   if (write_size <= 0)
7260     {
7261       /* Error or EOF, close the file */
7262       if (write_size < 0)
7263         {
7264           data->failed = TRUE;
7265           g_task_return_error (data->task, error);
7266         }
7267       g_output_stream_close_async (stream, 0,
7268                                    g_task_get_cancellable (data->task),
7269                                    replace_contents_close_callback, data);
7270     }
7271   else if (write_size > 0)
7272     {
7273       const gchar *content;
7274       gsize length;
7275
7276       content = g_bytes_get_data (data->content, &length);
7277       data->pos += write_size;
7278
7279       if (data->pos >= length)
7280         g_output_stream_close_async (stream, 0,
7281                                      g_task_get_cancellable (data->task),
7282                                      replace_contents_close_callback, data);
7283       else
7284         g_output_stream_write_async (stream,
7285                                      content + data->pos,
7286                                      length - data->pos,
7287                                      0,
7288                                      g_task_get_cancellable (data->task),
7289                                      replace_contents_write_callback,
7290                                      data);
7291     }
7292 }
7293
7294 static void
7295 replace_contents_open_callback (GObject      *obj,
7296                                 GAsyncResult *open_res,
7297                                 gpointer      user_data)
7298 {
7299   GFile *file = G_FILE (obj);
7300   GFileOutputStream *stream;
7301   ReplaceContentsData *data = user_data;
7302   GError *error = NULL;
7303
7304   stream = g_file_replace_finish (file, open_res, &error);
7305
7306   if (stream)
7307     {
7308       const gchar *content;
7309       gsize length;
7310
7311       content = g_bytes_get_data (data->content, &length);
7312       g_output_stream_write_async (G_OUTPUT_STREAM (stream),
7313                                    content + data->pos,
7314                                    length - data->pos,
7315                                    0,
7316                                    g_task_get_cancellable (data->task),
7317                                    replace_contents_write_callback,
7318                                    data);
7319     }
7320   else
7321     {
7322       g_task_return_error (data->task, error);
7323       g_object_unref (data->task);
7324     }
7325 }
7326
7327 /**
7328  * g_file_replace_contents_async:
7329  * @file: input #GFile
7330  * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
7331  * @length: the length of @contents in bytes
7332  * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
7333  * @make_backup: %TRUE if a backup should be created
7334  * @flags: a set of #GFileCreateFlags
7335  * @cancellable: optional #GCancellable object, %NULL to ignore
7336  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7337  * @user_data: the data to pass to callback function
7338  *
7339  * Starts an asynchronous replacement of @file with the given
7340  * @contents of @length bytes. @etag will replace the document's
7341  * current entity tag.
7342  *
7343  * When this operation has completed, @callback will be called with
7344  * @user_user data, and the operation can be finalized with
7345  * g_file_replace_contents_finish().
7346  *
7347  * If @cancellable is not %NULL, then the operation can be cancelled by
7348  * triggering the cancellable object from another thread. If the operation
7349  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7350  *
7351  * If @make_backup is %TRUE, this function will attempt to
7352  * make a backup of @file.
7353  *
7354  * Note that no copy of @content will be made, so it must stay valid
7355  * until @callback is called. See g_file_replace_contents_bytes_async()
7356  * for a #GBytes version that will automatically hold a reference to the
7357  * contents (without copying) for the duration of the call.
7358  */
7359 void
7360 g_file_replace_contents_async  (GFile               *file,
7361                                 const char          *contents,
7362                                 gsize                length,
7363                                 const char          *etag,
7364                                 gboolean             make_backup,
7365                                 GFileCreateFlags     flags,
7366                                 GCancellable        *cancellable,
7367                                 GAsyncReadyCallback  callback,
7368                                 gpointer             user_data)
7369 {
7370   GBytes *bytes;
7371
7372   bytes = g_bytes_new_static (contents, length);
7373   g_file_replace_contents_bytes_async (file, bytes, etag, make_backup, flags,
7374       cancellable, callback, user_data);
7375   g_bytes_unref (bytes);
7376 }
7377
7378 /**
7379  * g_file_replace_contents_bytes_async:
7380  * @file: input #GFile
7381  * @contents: a #GBytes
7382  * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
7383  * @make_backup: %TRUE if a backup should be created
7384  * @flags: a set of #GFileCreateFlags
7385  * @cancellable: optional #GCancellable object, %NULL to ignore
7386  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7387  * @user_data: the data to pass to callback function
7388  *
7389  * Same as g_file_replace_contents_async() but takes a #GBytes input instead.
7390  * This function will keep a ref on @contents until the operation is done.
7391  * Unlike g_file_replace_contents_async() this allows forgetting about the
7392  * content without waiting for the callback.
7393  *
7394  * When this operation has completed, @callback will be called with
7395  * @user_user data, and the operation can be finalized with
7396  * g_file_replace_contents_finish().
7397  *
7398  * Since: 2.40
7399  */
7400 void
7401 g_file_replace_contents_bytes_async  (GFile               *file,
7402                                       GBytes              *contents,
7403                                       const char          *etag,
7404                                       gboolean             make_backup,
7405                                       GFileCreateFlags     flags,
7406                                       GCancellable        *cancellable,
7407                                       GAsyncReadyCallback  callback,
7408                                       gpointer             user_data)
7409 {
7410   ReplaceContentsData *data;
7411
7412   g_return_if_fail (G_IS_FILE (file));
7413   g_return_if_fail (contents != NULL);
7414
7415   data = g_new0 (ReplaceContentsData, 1);
7416
7417   data->content = g_bytes_ref (contents);
7418
7419   data->task = g_task_new (file, cancellable, callback, user_data);
7420   g_task_set_task_data (data->task, data, (GDestroyNotify)replace_contents_data_free);
7421
7422   g_file_replace_async (file,
7423                         etag,
7424                         make_backup,
7425                         flags,
7426                         0,
7427                         g_task_get_cancellable (data->task),
7428                         replace_contents_open_callback,
7429                         data);
7430 }
7431
7432 /**
7433  * g_file_replace_contents_finish:
7434  * @file: input #GFile
7435  * @res: a #GAsyncResult
7436  * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag]
7437  *     for the document. This should be freed with g_free() when it is no
7438  *     longer needed, or %NULL
7439  * @error: a #GError, or %NULL
7440  *
7441  * Finishes an asynchronous replace of the given @file. See
7442  * g_file_replace_contents_async(). Sets @new_etag to the new entity
7443  * tag for the document, if present.
7444  *
7445  * Returns: %TRUE on success, %FALSE on failure.
7446  */
7447 gboolean
7448 g_file_replace_contents_finish (GFile         *file,
7449                                 GAsyncResult  *res,
7450                                 char         **new_etag,
7451                                 GError       **error)
7452 {
7453   GTask *task;
7454   ReplaceContentsData *data;
7455
7456   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7457   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
7458
7459   task = G_TASK (res);
7460
7461   if (!g_task_propagate_boolean (task, error))
7462     return FALSE;
7463
7464   data = g_task_get_task_data (task);
7465
7466   if (new_etag)
7467     {
7468       *new_etag = data->etag;
7469       data->etag = NULL; /* Take ownership */
7470     }
7471
7472   return TRUE;
7473 }
7474
7475 gboolean
7476 g_file_real_measure_disk_usage (GFile                         *file,
7477                                 GFileMeasureFlags              flags,
7478                                 GCancellable                  *cancellable,
7479                                 GFileMeasureProgressCallback   progress_callback,
7480                                 gpointer                       progress_data,
7481                                 guint64                       *disk_usage,
7482                                 guint64                       *num_dirs,
7483                                 guint64                       *num_files,
7484                                 GError                       **error)
7485 {
7486   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7487                        "Operation not supported for the current backend.");
7488   return FALSE;
7489 }
7490
7491 typedef struct
7492 {
7493   GFileMeasureFlags             flags;
7494   GFileMeasureProgressCallback  progress_callback;
7495   gpointer                      progress_data;
7496 } MeasureTaskData;
7497
7498 typedef struct
7499 {
7500   guint64 disk_usage;
7501   guint64 num_dirs;
7502   guint64 num_files;
7503 } MeasureResult;
7504
7505 typedef struct
7506 {
7507   GFileMeasureProgressCallback callback;
7508   gpointer                     user_data;
7509   gboolean                     reporting;
7510   guint64                      current_size;
7511   guint64                      num_dirs;
7512   guint64                      num_files;
7513 } MeasureProgress;
7514
7515 static gboolean
7516 measure_disk_usage_invoke_progress (gpointer user_data)
7517 {
7518   MeasureProgress *progress = user_data;
7519
7520   (* progress->callback) (progress->reporting,
7521                           progress->current_size, progress->num_dirs, progress->num_files,
7522                           progress->user_data);
7523
7524   return FALSE;
7525 }
7526
7527 static void
7528 measure_disk_usage_progress (gboolean reporting,
7529                              guint64  current_size,
7530                              guint64  num_dirs,
7531                              guint64  num_files,
7532                              gpointer user_data)
7533 {
7534   MeasureProgress progress;
7535   GTask *task = user_data;
7536   MeasureTaskData *data;
7537
7538   data = g_task_get_task_data (task);
7539
7540   progress.callback = data->progress_callback;
7541   progress.user_data = data->progress_data;
7542   progress.reporting = reporting;
7543   progress.current_size = current_size;
7544   progress.num_dirs = num_dirs;
7545   progress.num_files = num_files;
7546
7547   g_main_context_invoke_full (g_task_get_context (task),
7548                               g_task_get_priority (task),
7549                               measure_disk_usage_invoke_progress,
7550                               g_memdup (&progress, sizeof progress),
7551                               g_free);
7552 }
7553
7554 static void
7555 measure_disk_usage_thread (GTask        *task,
7556                            gpointer      source_object,
7557                            gpointer      task_data,
7558                            GCancellable *cancellable)
7559 {
7560   MeasureTaskData *data = task_data;
7561   GError *error = NULL;
7562   MeasureResult result = { 0, };
7563
7564   if (g_file_measure_disk_usage (source_object, data->flags, cancellable,
7565                                  data->progress_callback ? measure_disk_usage_progress : NULL, task,
7566                                  &result.disk_usage, &result.num_dirs, &result.num_files,
7567                                  &error))
7568     g_task_return_pointer (task, g_memdup (&result, sizeof result), g_free);
7569   else
7570     g_task_return_error (task, error);
7571 }
7572
7573 static void
7574 g_file_real_measure_disk_usage_async (GFile                        *file,
7575                                       GFileMeasureFlags             flags,
7576                                       gint                          io_priority,
7577                                       GCancellable                 *cancellable,
7578                                       GFileMeasureProgressCallback  progress_callback,
7579                                       gpointer                      progress_data,
7580                                       GAsyncReadyCallback           callback,
7581                                       gpointer                      user_data)
7582 {
7583   MeasureTaskData data;
7584   GTask *task;
7585
7586   data.flags = flags;
7587   data.progress_callback = progress_callback;
7588   data.progress_data = progress_data;
7589
7590   task = g_task_new (file, cancellable, callback, user_data);
7591   g_task_set_task_data (task, g_memdup (&data, sizeof data), g_free);
7592   g_task_set_priority (task, io_priority);
7593
7594   g_task_run_in_thread (task, measure_disk_usage_thread);
7595   g_object_unref (task);
7596 }
7597
7598 static gboolean
7599 g_file_real_measure_disk_usage_finish (GFile         *file,
7600                                        GAsyncResult  *result,
7601                                        guint64       *disk_usage,
7602                                        guint64       *num_dirs,
7603                                        guint64       *num_files,
7604                                        GError       **error)
7605 {
7606   MeasureResult *measure_result;
7607
7608   g_return_val_if_fail (g_task_is_valid (result, file), FALSE);
7609
7610   measure_result = g_task_propagate_pointer (G_TASK (result), error);
7611
7612   if (measure_result == NULL)
7613     return FALSE;
7614
7615   if (disk_usage)
7616     *disk_usage = measure_result->disk_usage;
7617
7618   if (num_dirs)
7619     *num_dirs = measure_result->num_dirs;
7620
7621   if (num_files)
7622     *num_files = measure_result->num_files;
7623
7624   g_free (measure_result);
7625
7626   return TRUE;
7627 }
7628
7629 /**
7630  * g_file_measure_disk_usage:
7631  * @file: a #GFile
7632  * @flags: #GFileMeasureFlags
7633  * @cancellable: (allow-none): optional #GCancellable
7634  * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
7635  * @progress_data: user_data for @progress_callback
7636  * @disk_usage: (allow-none) (out): the number of bytes of disk space used
7637  * @num_dirs: (allow-none) (out): the number of directories encountered
7638  * @num_files: (allow-none) (out): the number of non-directories encountered
7639  * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
7640  *
7641  * Recursively measures the disk usage of @file.
7642  *
7643  * This is essentially an analog of the 'du' command, but it also
7644  * reports the number of directories and non-directory files encountered
7645  * (including things like symbolic links).
7646  *
7647  * By default, errors are only reported against the toplevel file
7648  * itself.  Errors found while recursing are silently ignored, unless
7649  * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
7650  *
7651  * The returned size, @disk_usage, is in bytes and should be formatted
7652  * with g_format_size() in order to get something reasonable for showing
7653  * in a user interface.
7654  *
7655  * @progress_callback and @progress_data can be given to request
7656  * periodic progress updates while scanning.  See the documentation for
7657  * #GFileMeasureProgressCallback for information about when and how the
7658  * callback will be invoked.
7659  *
7660  * Returns: %TRUE if successful, with the out parameters set.
7661  *          %FALSE otherwise, with @error set.
7662  *
7663  * Since: 2.38
7664  **/
7665 gboolean
7666 g_file_measure_disk_usage (GFile                         *file,
7667                            GFileMeasureFlags              flags,
7668                            GCancellable                  *cancellable,
7669                            GFileMeasureProgressCallback   progress_callback,
7670                            gpointer                       progress_data,
7671                            guint64                       *disk_usage,
7672                            guint64                       *num_dirs,
7673                            guint64                       *num_files,
7674                            GError                       **error)
7675 {
7676   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7677   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
7678   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
7679
7680   return G_FILE_GET_IFACE (file)->measure_disk_usage (file, flags, cancellable,
7681                                                       progress_callback, progress_data,
7682                                                       disk_usage, num_dirs, num_files,
7683                                                       error);
7684 }
7685
7686 /**
7687  * g_file_measure_disk_usage_async:
7688  * @file: a #GFile
7689  * @flags: #GFileMeasureFlags
7690  * @io_priority: the [I/O priority][io-priority] of the request
7691  * @cancellable: (allow-none): optional #GCancellable
7692  * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
7693  * @progress_data: user_data for @progress_callback
7694  * @callback: (allow-none): a #GAsyncReadyCallback to call when complete
7695  * @user_data: the data to pass to callback function
7696  *
7697  * Recursively measures the disk usage of @file.
7698  *
7699  * This is the asynchronous version of g_file_measure_disk_usage().  See
7700  * there for more information.
7701  *
7702  * Since: 2.38
7703  **/
7704 void
7705 g_file_measure_disk_usage_async (GFile                        *file,
7706                                  GFileMeasureFlags             flags,
7707                                  gint                          io_priority,
7708                                  GCancellable                 *cancellable,
7709                                  GFileMeasureProgressCallback  progress_callback,
7710                                  gpointer                      progress_data,
7711                                  GAsyncReadyCallback           callback,
7712                                  gpointer                      user_data)
7713 {
7714   g_return_if_fail (G_IS_FILE (file));
7715   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
7716
7717   G_FILE_GET_IFACE (file)->measure_disk_usage_async (file, flags, io_priority, cancellable,
7718                                                      progress_callback, progress_data,
7719                                                      callback, user_data);
7720 }
7721
7722 /**
7723  * g_file_measure_disk_usage_finish:
7724  * @file: a #GFile
7725  * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
7726  * @disk_usage: (allow-none) (out): the number of bytes of disk space used
7727  * @num_dirs: (allow-none) (out): the number of directories encountered
7728  * @num_files: (allow-none) (out): the number of non-directories encountered
7729  * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
7730  *
7731  * Collects the results from an earlier call to
7732  * g_file_measure_disk_usage_async().  See g_file_measure_disk_usage() for
7733  * more information.
7734  *
7735  * Returns: %TRUE if successful, with the out parameters set.
7736  *          %FALSE otherwise, with @error set.
7737  *
7738  * Since: 2.38
7739  **/
7740 gboolean
7741 g_file_measure_disk_usage_finish (GFile         *file,
7742                                   GAsyncResult  *result,
7743                                   guint64       *disk_usage,
7744                                   guint64       *num_dirs,
7745                                   guint64       *num_files,
7746                                   GError       **error)
7747 {
7748   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7749   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
7750
7751   return G_FILE_GET_IFACE (file)->measure_disk_usage_finish (file, result, disk_usage, num_dirs, num_files, error);
7752 }
7753
7754 /**
7755  * g_file_start_mountable:
7756  * @file: input #GFile
7757  * @flags: flags affecting the operation
7758  * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
7759  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
7760  * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
7761  * @user_data: the data to pass to callback function
7762  *
7763  * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
7764  * Using @start_operation, you can request callbacks when, for instance,
7765  * passwords are needed during authentication.
7766  *
7767  * If @cancellable is not %NULL, then the operation can be cancelled by
7768  * triggering the cancellable object from another thread. If the operation
7769  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7770  *
7771  * When the operation is finished, @callback will be called.
7772  * You can then call g_file_mount_mountable_finish() to get
7773  * the result of the operation.
7774  *
7775  * Since: 2.22
7776  */
7777 void
7778 g_file_start_mountable (GFile               *file,
7779                         GDriveStartFlags     flags,
7780                         GMountOperation     *start_operation,
7781                         GCancellable        *cancellable,
7782                         GAsyncReadyCallback  callback,
7783                         gpointer             user_data)
7784 {
7785   GFileIface *iface;
7786
7787   g_return_if_fail (G_IS_FILE (file));
7788
7789   iface = G_FILE_GET_IFACE (file);
7790
7791   if (iface->start_mountable == NULL)
7792     {
7793       g_task_report_new_error (file, callback, user_data,
7794                                g_file_start_mountable,
7795                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7796                                _("Operation not supported"));
7797       return;
7798     }
7799
7800   (* iface->start_mountable) (file,
7801                               flags,
7802                               start_operation,
7803                               cancellable,
7804                               callback,
7805                               user_data);
7806 }
7807
7808 /**
7809  * g_file_start_mountable_finish:
7810  * @file: input #GFile
7811  * @result: a #GAsyncResult
7812  * @error: a #GError, or %NULL
7813  *
7814  * Finishes a start operation. See g_file_start_mountable() for details.
7815  *
7816  * Finish an asynchronous start operation that was started
7817  * with g_file_start_mountable().
7818  *
7819  * Returns: %TRUE if the operation finished successfully. %FALSE
7820  * otherwise.
7821  *
7822  * Since: 2.22
7823  */
7824 gboolean
7825 g_file_start_mountable_finish (GFile         *file,
7826                                GAsyncResult  *result,
7827                                GError       **error)
7828 {
7829   GFileIface *iface;
7830
7831   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7832   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
7833
7834   if (g_async_result_legacy_propagate_error (result, error))
7835     return FALSE;
7836   else if (g_async_result_is_tagged (result, g_file_start_mountable))
7837     return g_task_propagate_boolean (G_TASK (result), error);
7838
7839   iface = G_FILE_GET_IFACE (file);
7840   return (* iface->start_mountable_finish) (file, result, error);
7841 }
7842
7843 /**
7844  * g_file_stop_mountable:
7845  * @file: input #GFile
7846  * @flags: flags affecting the operation
7847  * @mount_operation: (allow-none): a #GMountOperation,
7848  *     or %NULL to avoid user interaction.
7849  * @cancellable: (allow-none): optional #GCancellable object,
7850  *     %NULL to ignore
7851  * @callback: (allow-none): a #GAsyncReadyCallback to call
7852  *     when the request is satisfied, or %NULL
7853  * @user_data: the data to pass to callback function
7854  *
7855  * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
7856  *
7857  * If @cancellable is not %NULL, then the operation can be cancelled by
7858  * triggering the cancellable object from another thread. If the operation
7859  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7860  *
7861  * When the operation is finished, @callback will be called.
7862  * You can then call g_file_stop_mountable_finish() to get
7863  * the result of the operation.
7864  *
7865  * Since: 2.22
7866  */
7867 void
7868 g_file_stop_mountable (GFile               *file,
7869                        GMountUnmountFlags   flags,
7870                        GMountOperation     *mount_operation,
7871                        GCancellable        *cancellable,
7872                        GAsyncReadyCallback  callback,
7873                        gpointer             user_data)
7874 {
7875   GFileIface *iface;
7876
7877   g_return_if_fail (G_IS_FILE (file));
7878
7879   iface = G_FILE_GET_IFACE (file);
7880
7881   if (iface->stop_mountable == NULL)
7882     {
7883       g_task_report_new_error (file, callback, user_data,
7884                                g_file_stop_mountable,
7885                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7886                                _("Operation not supported"));
7887       return;
7888     }
7889
7890   (* iface->stop_mountable) (file,
7891                              flags,
7892                              mount_operation,
7893                              cancellable,
7894                              callback,
7895                              user_data);
7896 }
7897
7898 /**
7899  * g_file_stop_mountable_finish:
7900  * @file: input #GFile
7901  * @result: a #GAsyncResult
7902  * @error: a #GError, or %NULL
7903  *
7904  * Finishes an stop operation, see g_file_stop_mountable() for details.
7905  *
7906  * Finish an asynchronous stop operation that was started
7907  * with g_file_stop_mountable().
7908  *
7909  * Returns: %TRUE if the operation finished successfully.
7910  *     %FALSE otherwise.
7911  *
7912  * Since: 2.22
7913  */
7914 gboolean
7915 g_file_stop_mountable_finish (GFile         *file,
7916                               GAsyncResult  *result,
7917                               GError       **error)
7918 {
7919   GFileIface *iface;
7920
7921   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7922   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
7923
7924   if (g_async_result_legacy_propagate_error (result, error))
7925     return FALSE;
7926   else if (g_async_result_is_tagged (result, g_file_stop_mountable))
7927     return g_task_propagate_boolean (G_TASK (result), error);
7928
7929   iface = G_FILE_GET_IFACE (file);
7930   return (* iface->stop_mountable_finish) (file, result, error);
7931 }
7932
7933 /**
7934  * g_file_poll_mountable:
7935  * @file: input #GFile
7936  * @cancellable: optional #GCancellable object, %NULL to ignore
7937  * @callback: (allow-none): a #GAsyncReadyCallback to call
7938  *     when the request is satisfied, or %NULL
7939  * @user_data: the data to pass to callback function
7940  *
7941  * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
7942  *
7943  * If @cancellable is not %NULL, then the operation can be cancelled by
7944  * triggering the cancellable object from another thread. If the operation
7945  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7946  *
7947  * When the operation is finished, @callback will be called.
7948  * You can then call g_file_mount_mountable_finish() to get
7949  * the result of the operation.
7950  *
7951  * Since: 2.22
7952  */
7953 void
7954 g_file_poll_mountable (GFile               *file,
7955                        GCancellable        *cancellable,
7956                        GAsyncReadyCallback  callback,
7957                        gpointer             user_data)
7958 {
7959   GFileIface *iface;
7960
7961   g_return_if_fail (G_IS_FILE (file));
7962
7963   iface = G_FILE_GET_IFACE (file);
7964
7965   if (iface->poll_mountable == NULL)
7966     {
7967       g_task_report_new_error (file, callback, user_data,
7968                                g_file_poll_mountable,
7969                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7970                                _("Operation not supported"));
7971       return;
7972     }
7973
7974   (* iface->poll_mountable) (file,
7975                              cancellable,
7976                              callback,
7977                              user_data);
7978 }
7979
7980 /**
7981  * g_file_poll_mountable_finish:
7982  * @file: input #GFile
7983  * @result: a #GAsyncResult
7984  * @error: a #GError, or %NULL
7985  *
7986  * Finishes a poll operation. See g_file_poll_mountable() for details.
7987  *
7988  * Finish an asynchronous poll operation that was polled
7989  * with g_file_poll_mountable().
7990  *
7991  * Returns: %TRUE if the operation finished successfully. %FALSE
7992  * otherwise.
7993  *
7994  * Since: 2.22
7995  */
7996 gboolean
7997 g_file_poll_mountable_finish (GFile         *file,
7998                               GAsyncResult  *result,
7999                               GError       **error)
8000 {
8001   GFileIface *iface;
8002
8003   g_return_val_if_fail (G_IS_FILE (file), FALSE);
8004   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
8005
8006   if (g_async_result_legacy_propagate_error (result, error))
8007     return FALSE;
8008   else if (g_async_result_is_tagged (result, g_file_poll_mountable))
8009     return g_task_propagate_boolean (G_TASK (result), error);
8010
8011   iface = G_FILE_GET_IFACE (file);
8012   return (* iface->poll_mountable_finish) (file, result, error);
8013 }
8014
8015 /**
8016  * g_file_supports_thread_contexts:
8017  * @file: a #GFile
8018  *
8019  * Checks if @file supports
8020  * [thread-default contexts][g-main-context-push-thread-default-context].
8021  * If this returns %FALSE, you cannot perform asynchronous operations on
8022  * @file in a thread that has a thread-default context.
8023  *
8024  * Returns: Whether or not @file supports thread-default contexts.
8025  *
8026  * Since: 2.22
8027  */
8028 gboolean
8029 g_file_supports_thread_contexts (GFile *file)
8030 {
8031  GFileIface *iface;
8032
8033  g_return_val_if_fail (G_IS_FILE (file), FALSE);
8034
8035  iface = G_FILE_GET_IFACE (file);
8036  return iface->supports_thread_contexts;
8037 }