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: (type filename) (nullable): string containing the #GFile's
 496  *     base name, or %NULL if given #GFile is invalid. The returned string
 497  *     should be 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: (type filename) (nullable): string containing the #GFile's path,
 521  *     or %NULL 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: (type filename): 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: (type filename) (nullable): string with the relative path from
 865  *     @descendant 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: (type filename): 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: (type filename): a string with the path for the target
3853  *     of the new symlink
3854  * @cancellable: (allow-none): optional #GCancellable object,
3855  *     %NULL to ignore
3856  * @error: a #GError
3857  *
3858  * Creates a symbolic link named @file which contains the string
3859  * @symlink_value.
3860  *
3861  * If @cancellable is not %NULL, then the operation can be cancelled by
3862  * triggering the cancellable object from another thread. If the operation
3863  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3864  *
3865  * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
3866  */
3867 gboolean
3868 g_file_make_symbolic_link (GFile         *file,
3869                            const char    *symlink_value,
3870                            GCancellable  *cancellable,
3871                            GError       **error)
3872 {
3873   GFileIface *iface;
3874
3875   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3876   g_return_val_if_fail (symlink_value != NULL, FALSE);
3877
3878   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3879     return FALSE;
3880
3881   if (*symlink_value == '\0')
3882     {
3883       g_set_error_literal (error, G_IO_ERROR,
3884                            G_IO_ERROR_INVALID_ARGUMENT,
3885                            _("Invalid symlink value given"));
3886       return FALSE;
3887     }
3888
3889   iface = G_FILE_GET_IFACE (file);
3890
3891   if (iface->make_symbolic_link == NULL)
3892     {
3893       g_set_error_literal (error, G_IO_ERROR,
3894                            G_IO_ERROR_NOT_SUPPORTED,
3895                            _("Operation not supported"));
3896       return FALSE;
3897     }
3898
3899   return (* iface->make_symbolic_link) (file, symlink_value, cancellable, error);
3900 }
3901
3902 /**
3903  * g_file_delete:
3904  * @file: input #GFile
3905  * @cancellable: (allow-none): optional #GCancellable object,
3906  *     %NULL to ignore
3907  * @error: a #GError, or %NULL
3908  *
3909  * Deletes a file. If the @file is a directory, it will only be
3910  * deleted if it is empty. This has the same semantics as g_unlink().
3911  *
3912  * If @cancellable is not %NULL, then the operation can be cancelled by
3913  * triggering the cancellable object from another thread. If the operation
3914  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3915  *
3916  * Virtual: delete_file
3917  * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3918  */
3919 gboolean
3920 g_file_delete (GFile         *file,
3921                GCancellable  *cancellable,
3922                GError       **error)
3923 {
3924   GFileIface *iface;
3925
3926   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3927
3928   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3929     return FALSE;
3930
3931   iface = G_FILE_GET_IFACE (file);
3932
3933   if (iface->delete_file == NULL)
3934     {
3935       g_set_error_literal (error, G_IO_ERROR,
3936                            G_IO_ERROR_NOT_SUPPORTED,
3937                            _("Operation not supported"));
3938       return FALSE;
3939     }
3940
3941   return (* iface->delete_file) (file, cancellable, error);
3942 }
3943
3944 /**
3945  * g_file_delete_async:
3946  * @file: input #GFile
3947  * @io_priority: the [I/O priority][io-priority] of the request
3948  * @cancellable: (allow-none): optional #GCancellable object,
3949  *     %NULL to ignore
3950  * @callback: a #GAsyncReadyCallback to call
3951  *     when the request is satisfied
3952  * @user_data: the data to pass to callback function
3953  *
3954  * Asynchronously delete a file. If the @file is a directory, it will
3955  * only be deleted if it is empty.  This has the same semantics as
3956  * g_unlink().
3957  *
3958  * Virtual: delete_file_async
3959  * Since: 2.34
3960  */
3961 void
3962 g_file_delete_async (GFile               *file,
3963                      int                  io_priority,
3964                      GCancellable        *cancellable,
3965                      GAsyncReadyCallback  callback,
3966                      gpointer             user_data)
3967 {
3968   GFileIface *iface;
3969
3970   g_return_if_fail (G_IS_FILE (file));
3971
3972   iface = G_FILE_GET_IFACE (file);
3973   (* iface->delete_file_async) (file,
3974                                 io_priority,
3975                                 cancellable,
3976                                 callback,
3977                                 user_data);
3978 }
3979
3980 /**
3981  * g_file_delete_finish:
3982  * @file: input #GFile
3983  * @result: a #GAsyncResult
3984  * @error: a #GError, or %NULL
3985  *
3986  * Finishes deleting a file started with g_file_delete_async().
3987  *
3988  * Virtual: delete_file_finish
3989  * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3990  * Since: 2.34
3991  **/
3992 gboolean
3993 g_file_delete_finish (GFile         *file,
3994                       GAsyncResult  *result,
3995                       GError       **error)
3996 {
3997   GFileIface *iface;
3998
3999   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4000   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4001
4002   if (g_async_result_legacy_propagate_error (result, error))
4003     return FALSE;
4004
4005   iface = G_FILE_GET_IFACE (file);
4006   return (* iface->delete_file_finish) (file, result, error);
4007 }
4008
4009 /**
4010  * g_file_trash:
4011  * @file: #GFile to send to trash
4012  * @cancellable: (allow-none): optional #GCancellable object,
4013  *     %NULL to ignore
4014  * @error: a #GError, or %NULL
4015  *
4016  * Sends @file to the "Trashcan", if possible. This is similar to
4017  * deleting it, but the user can recover it before emptying the trashcan.
4018  * Not all file systems support trashing, so this call can return the
4019  * %G_IO_ERROR_NOT_SUPPORTED error.
4020  *
4021  * If @cancellable is not %NULL, then the operation can be cancelled by
4022  * triggering the cancellable object from another thread. If the operation
4023  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4024  *
4025  * Virtual: trash
4026  * Returns: %TRUE on successful trash, %FALSE otherwise.
4027  */
4028 gboolean
4029 g_file_trash (GFile         *file,
4030               GCancellable  *cancellable,
4031               GError       **error)
4032 {
4033   GFileIface *iface;
4034
4035   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4036
4037   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4038     return FALSE;
4039
4040   iface = G_FILE_GET_IFACE (file);
4041
4042   if (iface->trash == NULL)
4043     {
4044       g_set_error_literal (error,
4045                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4046                            _("Trash not supported"));
4047       return FALSE;
4048     }
4049
4050   return (* iface->trash) (file, cancellable, error);
4051 }
4052
4053 /**
4054  * g_file_trash_async:
4055  * @file: input #GFile
4056  * @io_priority: the [I/O priority][io-priority] of the request
4057  * @cancellable: (allow-none): optional #GCancellable object,
4058  *     %NULL to ignore
4059  * @callback: a #GAsyncReadyCallback to call
4060  *     when the request is satisfied
4061  * @user_data: the data to pass to callback function
4062  *
4063  * Asynchronously sends @file to the Trash location, if possible.
4064  *
4065  * Virtual: trash_async
4066  * Since: 2.38
4067  */
4068 void
4069 g_file_trash_async (GFile               *file,
4070                     int                  io_priority,
4071                     GCancellable        *cancellable,
4072                     GAsyncReadyCallback  callback,
4073                     gpointer             user_data)
4074 {
4075   GFileIface *iface;
4076
4077   g_return_if_fail (G_IS_FILE (file));
4078
4079   iface = G_FILE_GET_IFACE (file);
4080   (* iface->trash_async) (file,
4081                           io_priority,
4082                           cancellable,
4083                           callback,
4084                           user_data);
4085 }
4086
4087 /**
4088  * g_file_trash_finish:
4089  * @file: input #GFile
4090  * @result: a #GAsyncResult
4091  * @error: a #GError, or %NULL
4092  *
4093  * Finishes an asynchronous file trashing operation, started with
4094  * g_file_trash_async().
4095  *
4096  * Virtual: trash_finish
4097  * Returns: %TRUE on successful trash, %FALSE otherwise.
4098  * Since: 2.38
4099  */
4100 gboolean
4101 g_file_trash_finish (GFile         *file,
4102                      GAsyncResult  *result,
4103                      GError       **error)
4104 {
4105   GFileIface *iface;
4106
4107   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4108   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4109
4110   iface = G_FILE_GET_IFACE (file);
4111   return (* iface->trash_finish) (file, result, error);
4112 }
4113
4114 /**
4115  * g_file_set_display_name:
4116  * @file: input #GFile
4117  * @display_name: a string
4118  * @cancellable: (allow-none): optional #GCancellable object,
4119  *     %NULL to ignore
4120  * @error: a #GError, or %NULL
4121  *
4122  * Renames @file to the specified display name.
4123  *
4124  * The display name is converted from UTF-8 to the correct encoding
4125  * for the target filesystem if possible and the @file is renamed to this.
4126  *
4127  * If you want to implement a rename operation in the user interface the
4128  * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
4129  * initial value in the rename widget, and then the result after editing
4130  * should be passed to g_file_set_display_name().
4131  *
4132  * On success the resulting converted filename is returned.
4133  *
4134  * If @cancellable is not %NULL, then the operation can be cancelled by
4135  * triggering the cancellable object from another thread. If the operation
4136  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4137  *
4138  * Returns: (transfer full): a #GFile specifying what @file was renamed to,
4139  *     or %NULL if there was an error.
4140  *     Free the returned object with g_object_unref().
4141  */
4142 GFile *
4143 g_file_set_display_name (GFile         *file,
4144                          const gchar   *display_name,
4145                          GCancellable  *cancellable,
4146                          GError       **error)
4147 {
4148   GFileIface *iface;
4149
4150   g_return_val_if_fail (G_IS_FILE (file), NULL);
4151   g_return_val_if_fail (display_name != NULL, NULL);
4152
4153   if (strchr (display_name, G_DIR_SEPARATOR) != NULL)
4154     {
4155       g_set_error (error,
4156                    G_IO_ERROR,
4157                    G_IO_ERROR_INVALID_ARGUMENT,
4158                    _("File names cannot contain '%c'"), G_DIR_SEPARATOR);
4159       return NULL;
4160     }
4161
4162   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4163     return NULL;
4164
4165   iface = G_FILE_GET_IFACE (file);
4166
4167   return (* iface->set_display_name) (file, display_name, cancellable, error);
4168 }
4169
4170 /**
4171  * g_file_set_display_name_async:
4172  * @file: input #GFile
4173  * @display_name: a string
4174  * @io_priority: the [I/O priority][io-priority] of the request
4175  * @cancellable: (allow-none): optional #GCancellable object,
4176  *     %NULL to ignore
4177  * @callback: (scope async): a #GAsyncReadyCallback to call
4178  *     when the request is satisfied
4179  * @user_data: (closure): the data to pass to callback function
4180  *
4181  * Asynchronously sets the display name for a given #GFile.
4182  *
4183  * For more details, see g_file_set_display_name() which is
4184  * the synchronous version of this call.
4185  *
4186  * When the operation is finished, @callback will be called.
4187  * You can then call g_file_set_display_name_finish() to get
4188  * the result of the operation.
4189  */
4190 void
4191 g_file_set_display_name_async (GFile               *file,
4192                                const gchar         *display_name,
4193                                gint                 io_priority,
4194                                GCancellable        *cancellable,
4195                                GAsyncReadyCallback  callback,
4196                                gpointer             user_data)
4197 {
4198   GFileIface *iface;
4199
4200   g_return_if_fail (G_IS_FILE (file));
4201   g_return_if_fail (display_name != NULL);
4202
4203   iface = G_FILE_GET_IFACE (file);
4204   (* iface->set_display_name_async) (file,
4205                                      display_name,
4206                                      io_priority,
4207                                      cancellable,
4208                                      callback,
4209                                      user_data);
4210 }
4211
4212 /**
4213  * g_file_set_display_name_finish:
4214  * @file: input #GFile
4215  * @res: a #GAsyncResult
4216  * @error: a #GError, or %NULL
4217  *
4218  * Finishes setting a display name started with
4219  * g_file_set_display_name_async().
4220  *
4221  * Returns: (transfer full): a #GFile or %NULL on error.
4222  *     Free the returned object with g_object_unref().
4223  */
4224 GFile *
4225 g_file_set_display_name_finish (GFile         *file,
4226                                 GAsyncResult  *res,
4227                                 GError       **error)
4228 {
4229   GFileIface *iface;
4230
4231   g_return_val_if_fail (G_IS_FILE (file), NULL);
4232   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
4233
4234   if (g_async_result_legacy_propagate_error (res, error))
4235     return NULL;
4236
4237   iface = G_FILE_GET_IFACE (file);
4238   return (* iface->set_display_name_finish) (file, res, error);
4239 }
4240
4241 /**
4242  * g_file_query_settable_attributes:
4243  * @file: input #GFile
4244  * @cancellable: (allow-none): optional #GCancellable object,
4245  *     %NULL to ignore
4246  * @error: a #GError, or %NULL
4247  *
4248  * Obtain the list of settable attributes for the file.
4249  *
4250  * Returns the type and full attribute name of all the attributes
4251  * that can be set on this file. This doesn't mean setting it will
4252  * always succeed though, you might get an access failure, or some
4253  * specific file may not support a specific attribute.
4254  *
4255  * If @cancellable is not %NULL, then the operation can be cancelled by
4256  * triggering the cancellable object from another thread. If the operation
4257  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4258  *
4259  * Returns: a #GFileAttributeInfoList describing the settable attributes.
4260  *     When you are done with it, release it with
4261  *     g_file_attribute_info_list_unref()
4262  */
4263 GFileAttributeInfoList *
4264 g_file_query_settable_attributes (GFile         *file,
4265                                   GCancellable  *cancellable,
4266                                   GError       **error)
4267 {
4268   GFileIface *iface;
4269   GError *my_error;
4270   GFileAttributeInfoList *list;
4271
4272   g_return_val_if_fail (G_IS_FILE (file), NULL);
4273
4274   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4275     return NULL;
4276
4277   iface = G_FILE_GET_IFACE (file);
4278
4279   if (iface->query_settable_attributes == NULL)
4280     return g_file_attribute_info_list_new ();
4281
4282   my_error = NULL;
4283   list = (* iface->query_settable_attributes) (file, cancellable, &my_error);
4284
4285   if (list == NULL)
4286     {
4287       if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_NOT_SUPPORTED)
4288         {
4289           list = g_file_attribute_info_list_new ();
4290           g_error_free (my_error);
4291         }
4292       else
4293         g_propagate_error (error, my_error);
4294     }
4295
4296   return list;
4297 }
4298
4299 /**
4300  * g_file_query_writable_namespaces:
4301  * @file: input #GFile
4302  * @cancellable: (allow-none): optional #GCancellable object,
4303  *     %NULL to ignore
4304  * @error: a #GError, or %NULL
4305  *
4306  * Obtain the list of attribute namespaces where new attributes
4307  * can be created by a user. An example of this is extended
4308  * attributes (in the "xattr" namespace).
4309  *
4310  * If @cancellable is not %NULL, then the operation can be cancelled by
4311  * triggering the cancellable object from another thread. If the operation
4312  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4313  *
4314  * Returns: a #GFileAttributeInfoList describing the writable namespaces.
4315  *     When you are done with it, release it with
4316  *     g_file_attribute_info_list_unref()
4317  */
4318 GFileAttributeInfoList *
4319 g_file_query_writable_namespaces (GFile         *file,
4320                                   GCancellable  *cancellable,
4321                                   GError       **error)
4322 {
4323   GFileIface *iface;
4324   GError *my_error;
4325   GFileAttributeInfoList *list;
4326
4327   g_return_val_if_fail (G_IS_FILE (file), NULL);
4328
4329   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4330     return NULL;
4331
4332   iface = G_FILE_GET_IFACE (file);
4333
4334   if (iface->query_writable_namespaces == NULL)
4335     return g_file_attribute_info_list_new ();
4336
4337   my_error = NULL;
4338   list = (* iface->query_writable_namespaces) (file, cancellable, &my_error);
4339
4340   if (list == NULL)
4341     {
4342       g_warn_if_reached();
4343       list = g_file_attribute_info_list_new ();
4344     }
4345
4346   if (my_error != NULL)
4347     {
4348       if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_NOT_SUPPORTED)
4349         {
4350           g_error_free (my_error);
4351         }
4352       else
4353         g_propagate_error (error, my_error);
4354     }
4355
4356   return list;
4357 }
4358
4359 /**
4360  * g_file_set_attribute:
4361  * @file: input #GFile
4362  * @attribute: a string containing the attribute's name
4363  * @type: The type of the attribute
4364  * @value_p: (allow-none): a pointer to the value (or the pointer
4365  *     itself if the type is a pointer type)
4366  * @flags: a set of #GFileQueryInfoFlags
4367  * @cancellable: (allow-none): optional #GCancellable object,
4368  *     %NULL to ignore
4369  * @error: a #GError, or %NULL
4370  *
4371  * Sets an attribute in the file with attribute name @attribute to @value.
4372  *
4373  * Some attributes can be unset by setting @attribute to
4374  * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
4375  *
4376  * If @cancellable is not %NULL, then the operation can be cancelled by
4377  * triggering the cancellable object from another thread. If the operation
4378  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4379  *
4380  * Returns: %TRUE if the attribute was set, %FALSE otherwise.
4381  */
4382 gboolean
4383 g_file_set_attribute (GFile                *file,
4384                       const gchar          *attribute,
4385                       GFileAttributeType    type,
4386                       gpointer              value_p,
4387                       GFileQueryInfoFlags   flags,
4388                       GCancellable         *cancellable,
4389                       GError              **error)
4390 {
4391   GFileIface *iface;
4392
4393   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4394   g_return_val_if_fail (attribute != NULL && *attribute != '\0', FALSE);
4395
4396   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4397     return FALSE;
4398
4399   iface = G_FILE_GET_IFACE (file);
4400
4401   if (iface->set_attribute == NULL)
4402     {
4403       g_set_error_literal (error, G_IO_ERROR,
4404                            G_IO_ERROR_NOT_SUPPORTED,
4405                            _("Operation not supported"));
4406       return FALSE;
4407     }
4408
4409   return (* iface->set_attribute) (file, attribute, type, value_p, flags, cancellable, error);
4410 }
4411
4412 /**
4413  * g_file_set_attributes_from_info:
4414  * @file: input #GFile
4415  * @info: a #GFileInfo
4416  * @flags: #GFileQueryInfoFlags
4417  * @cancellable: (allow-none): optional #GCancellable object,
4418  *     %NULL to ignore
4419  * @error: a #GError, or %NULL
4420  *
4421  * Tries to set all attributes in the #GFileInfo on the target
4422  * values, not stopping on the first error.
4423  *
4424  * If there is any error during this operation then @error will
4425  * be set to the first error. Error on particular fields are flagged
4426  * by setting the "status" field in the attribute value to
4427  * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
4428  * also detect further errors.
4429  *
4430  * If @cancellable is not %NULL, then the operation can be cancelled by
4431  * triggering the cancellable object from another thread. If the operation
4432  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4433  *
4434  * Returns: %FALSE if there was any error, %TRUE otherwise.
4435  */
4436 gboolean
4437 g_file_set_attributes_from_info (GFile                *file,
4438                                  GFileInfo            *info,
4439                                  GFileQueryInfoFlags   flags,
4440                                  GCancellable         *cancellable,
4441                                  GError              **error)
4442 {
4443   GFileIface *iface;
4444
4445   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4446   g_return_val_if_fail (G_IS_FILE_INFO (info), FALSE);
4447
4448   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4449     return FALSE;
4450
4451   g_file_info_clear_status (info);
4452
4453   iface = G_FILE_GET_IFACE (file);
4454
4455   return (* iface->set_attributes_from_info) (file,
4456                                               info,
4457                                               flags,
4458                                               cancellable,
4459                                               error);
4460 }
4461
4462 static gboolean
4463 g_file_real_set_attributes_from_info (GFile                *file,
4464                                       GFileInfo            *info,
4465                                       GFileQueryInfoFlags   flags,
4466                                       GCancellable         *cancellable,
4467                                       GError              **error)
4468 {
4469   char **attributes;
4470   int i;
4471   gboolean res;
4472   GFileAttributeValue *value;
4473
4474   res = TRUE;
4475
4476   attributes = g_file_info_list_attributes (info, NULL);
4477
4478   for (i = 0; attributes[i] != NULL; i++)
4479     {
4480       value = _g_file_info_get_attribute_value (info, attributes[i]);
4481
4482       if (value->status != G_FILE_ATTRIBUTE_STATUS_UNSET)
4483         continue;
4484
4485       if (!g_file_set_attribute (file, attributes[i],
4486                                  value->type, _g_file_attribute_value_peek_as_pointer (value),
4487                                  flags, cancellable, error))
4488         {
4489           value->status = G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING;
4490           res = FALSE;
4491           /* Don't set error multiple times */
4492           error = NULL;
4493         }
4494       else
4495         value->status = G_FILE_ATTRIBUTE_STATUS_SET;
4496     }
4497
4498   g_strfreev (attributes);
4499
4500   return res;
4501 }
4502
4503 /**
4504  * g_file_set_attributes_async:
4505  * @file: input #GFile
4506  * @info: a #GFileInfo
4507  * @flags: a #GFileQueryInfoFlags
4508  * @io_priority: the [I/O priority][io-priority] of the request
4509  * @cancellable: (allow-none): optional #GCancellable object,
4510  *     %NULL to ignore
4511  * @callback: (scope async): a #GAsyncReadyCallback
4512  * @user_data: (closure): a #gpointer
4513  *
4514  * Asynchronously sets the attributes of @file with @info.
4515  *
4516  * For more details, see g_file_set_attributes_from_info(),
4517  * which is the synchronous version of this call.
4518  *
4519  * When the operation is finished, @callback will be called.
4520  * You can then call g_file_set_attributes_finish() to get
4521  * the result of the operation.
4522  */
4523 void
4524 g_file_set_attributes_async (GFile               *file,
4525                              GFileInfo           *info,
4526                              GFileQueryInfoFlags  flags,
4527                              int                  io_priority,
4528                              GCancellable        *cancellable,
4529                              GAsyncReadyCallback  callback,
4530                              gpointer             user_data)
4531 {
4532   GFileIface *iface;
4533
4534   g_return_if_fail (G_IS_FILE (file));
4535   g_return_if_fail (G_IS_FILE_INFO (info));
4536
4537   iface = G_FILE_GET_IFACE (file);
4538   (* iface->set_attributes_async) (file,
4539                                    info,
4540                                    flags,
4541                                    io_priority,
4542                                    cancellable,
4543                                    callback,
4544                                    user_data);
4545 }
4546
4547 /**
4548  * g_file_set_attributes_finish:
4549  * @file: input #GFile
4550  * @result: a #GAsyncResult
4551  * @info: (out) (transfer full): a #GFileInfo
4552  * @error: a #GError, or %NULL
4553  *
4554  * Finishes setting an attribute started in g_file_set_attributes_async().
4555  *
4556  * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
4557  */
4558 gboolean
4559 g_file_set_attributes_finish (GFile         *file,
4560                               GAsyncResult  *result,
4561                               GFileInfo    **info,
4562                               GError       **error)
4563 {
4564   GFileIface *iface;
4565
4566   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4567   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4568
4569   /* No standard handling of errors here, as we must set info even
4570    * on errors
4571    */
4572   iface = G_FILE_GET_IFACE (file);
4573   return (* iface->set_attributes_finish) (file, result, info, error);
4574 }
4575
4576 /**
4577  * g_file_set_attribute_string:
4578  * @file: input #GFile
4579  * @attribute: a string containing the attribute's name
4580  * @value: a string containing the attribute's value
4581  * @flags: #GFileQueryInfoFlags
4582  * @cancellable: (allow-none): optional #GCancellable object,
4583  *     %NULL to ignore
4584  * @error: a #GError, or %NULL
4585  *
4586  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
4587  * If @attribute is of a different type, this operation will fail.
4588  *
4589  * If @cancellable is not %NULL, then the operation can be cancelled by
4590  * triggering the cancellable object from another thread. If the operation
4591  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4592  *
4593  * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4594  */
4595 gboolean
4596 g_file_set_attribute_string (GFile                *file,
4597                              const char           *attribute,
4598                              const char           *value,
4599                              GFileQueryInfoFlags   flags,
4600                              GCancellable         *cancellable,
4601                              GError              **error)
4602 {
4603   return g_file_set_attribute (file, attribute,
4604                                G_FILE_ATTRIBUTE_TYPE_STRING, (gpointer)value,
4605                                flags, cancellable, error);
4606 }
4607
4608 /**
4609  * g_file_set_attribute_byte_string:
4610  * @file: input #GFile
4611  * @attribute: a string containing the attribute's name
4612  * @value: a string containing the attribute's new value
4613  * @flags: a #GFileQueryInfoFlags
4614  * @cancellable: (allow-none): optional #GCancellable object,
4615  *     %NULL to ignore
4616  * @error: a #GError, or %NULL
4617  *
4618  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
4619  * If @attribute is of a different type, this operation will fail,
4620  * returning %FALSE.
4621  *
4622  * If @cancellable is not %NULL, then the operation can be cancelled by
4623  * triggering the cancellable object from another thread. If the operation
4624  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4625  *
4626  * Returns: %TRUE if the @attribute was successfully set to @value
4627  *     in the @file, %FALSE otherwise.
4628  */
4629 gboolean
4630 g_file_set_attribute_byte_string  (GFile                *file,
4631                                    const gchar          *attribute,
4632                                    const gchar          *value,
4633                                    GFileQueryInfoFlags   flags,
4634                                    GCancellable         *cancellable,
4635                                    GError              **error)
4636 {
4637   return g_file_set_attribute (file, attribute,
4638                                G_FILE_ATTRIBUTE_TYPE_BYTE_STRING, (gpointer)value,
4639                                flags, cancellable, error);
4640 }
4641
4642 /**
4643  * g_file_set_attribute_uint32:
4644  * @file: input #GFile
4645  * @attribute: a string containing the attribute's name
4646  * @value: a #guint32 containing the attribute's new value
4647  * @flags: a #GFileQueryInfoFlags
4648  * @cancellable: (allow-none): optional #GCancellable object,
4649  *     %NULL to ignore
4650  * @error: a #GError, or %NULL
4651  *
4652  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
4653  * If @attribute is of a different type, this operation will fail.
4654  *
4655  * If @cancellable is not %NULL, then the operation can be cancelled by
4656  * triggering the cancellable object from another thread. If the operation
4657  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4658  *
4659  * Returns: %TRUE if the @attribute was successfully set to @value
4660  *     in the @file, %FALSE otherwise.
4661  */
4662 gboolean
4663 g_file_set_attribute_uint32 (GFile                *file,
4664                              const gchar          *attribute,
4665                              guint32               value,
4666                              GFileQueryInfoFlags   flags,
4667                              GCancellable         *cancellable,
4668                              GError              **error)
4669 {
4670   return g_file_set_attribute (file, attribute,
4671                                G_FILE_ATTRIBUTE_TYPE_UINT32, &value,
4672                                flags, cancellable, error);
4673 }
4674
4675 /**
4676  * g_file_set_attribute_int32:
4677  * @file: input #GFile
4678  * @attribute: a string containing the attribute's name
4679  * @value: a #gint32 containing the attribute's new value
4680  * @flags: a #GFileQueryInfoFlags
4681  * @cancellable: (allow-none): optional #GCancellable object,
4682  *     %NULL to ignore
4683  * @error: a #GError, or %NULL
4684  *
4685  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
4686  * If @attribute is of a different type, this operation will fail.
4687  *
4688  * If @cancellable is not %NULL, then the operation can be cancelled by
4689  * triggering the cancellable object from another thread. If the operation
4690  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4691  *
4692  * Returns: %TRUE if the @attribute was successfully set to @value
4693  *     in the @file, %FALSE otherwise.
4694  */
4695 gboolean
4696 g_file_set_attribute_int32 (GFile                *file,
4697                             const gchar          *attribute,
4698                             gint32                value,
4699                             GFileQueryInfoFlags   flags,
4700                             GCancellable         *cancellable,
4701                             GError              **error)
4702 {
4703   return g_file_set_attribute (file, attribute,
4704                                G_FILE_ATTRIBUTE_TYPE_INT32, &value,
4705                                flags, cancellable, error);
4706 }
4707
4708 /**
4709  * g_file_set_attribute_uint64:
4710  * @file: input #GFile
4711  * @attribute: a string containing the attribute's name
4712  * @value: a #guint64 containing the attribute's new value
4713  * @flags: a #GFileQueryInfoFlags
4714  * @cancellable: (allow-none): optional #GCancellable object,
4715  *     %NULL to ignore
4716  * @error: a #GError, or %NULL
4717  *
4718  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
4719  * If @attribute is of a different type, this operation will fail.
4720  *
4721  * If @cancellable is not %NULL, then the operation can be cancelled by
4722  * triggering the cancellable object from another thread. If the operation
4723  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4724  *
4725  * Returns: %TRUE if the @attribute was successfully set to @value
4726  *     in the @file, %FALSE otherwise.
4727  */
4728 gboolean
4729 g_file_set_attribute_uint64 (GFile                *file,
4730                              const gchar          *attribute,
4731                              guint64               value,
4732                              GFileQueryInfoFlags   flags,
4733                              GCancellable         *cancellable,
4734                              GError              **error)
4735  {
4736   return g_file_set_attribute (file, attribute,
4737                                G_FILE_ATTRIBUTE_TYPE_UINT64, &value,
4738                                flags, cancellable, error);
4739 }
4740
4741 /**
4742  * g_file_set_attribute_int64:
4743  * @file: input #GFile
4744  * @attribute: a string containing the attribute's name
4745  * @value: a #guint64 containing the attribute's new value
4746  * @flags: a #GFileQueryInfoFlags
4747  * @cancellable: (allow-none): optional #GCancellable object,
4748  *     %NULL to ignore
4749  * @error: a #GError, or %NULL
4750  *
4751  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
4752  * If @attribute is of a different type, this operation will fail.
4753  *
4754  * If @cancellable is not %NULL, then the operation can be cancelled by
4755  * triggering the cancellable object from another thread. If the operation
4756  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4757  *
4758  * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4759  */
4760 gboolean
4761 g_file_set_attribute_int64 (GFile                *file,
4762                             const gchar          *attribute,
4763                             gint64                value,
4764                             GFileQueryInfoFlags   flags,
4765                             GCancellable         *cancellable,
4766                             GError              **error)
4767 {
4768   return g_file_set_attribute (file, attribute,
4769                                G_FILE_ATTRIBUTE_TYPE_INT64, &value,
4770                                flags, cancellable, error);
4771 }
4772
4773 /**
4774  * g_file_mount_mountable:
4775  * @file: input #GFile
4776  * @flags: flags affecting the operation
4777  * @mount_operation: (allow-none): a #GMountOperation,
4778  *     or %NULL to avoid user interaction
4779  * @cancellable: (allow-none): optional #GCancellable object,
4780  *     %NULL to ignore
4781  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4782  *     when the request is satisfied, or %NULL
4783  * @user_data: (closure): the data to pass to callback function
4784  *
4785  * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
4786  * Using @mount_operation, you can request callbacks when, for instance,
4787  * passwords are needed during authentication.
4788  *
4789  * If @cancellable is not %NULL, then the operation can be cancelled by
4790  * triggering the cancellable object from another thread. If the operation
4791  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4792  *
4793  * When the operation is finished, @callback will be called.
4794  * You can then call g_file_mount_mountable_finish() to get
4795  * the result of the operation.
4796  */
4797 void
4798 g_file_mount_mountable (GFile               *file,
4799                         GMountMountFlags     flags,
4800                         GMountOperation     *mount_operation,
4801                         GCancellable        *cancellable,
4802                         GAsyncReadyCallback  callback,
4803                         gpointer             user_data)
4804 {
4805   GFileIface *iface;
4806
4807   g_return_if_fail (G_IS_FILE (file));
4808
4809   iface = G_FILE_GET_IFACE (file);
4810
4811   if (iface->mount_mountable == NULL)
4812     {
4813       g_task_report_new_error (file, callback, user_data,
4814                                g_file_mount_mountable,
4815                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4816                                _("Operation not supported"));
4817       return;
4818     }
4819
4820   (* iface->mount_mountable) (file,
4821                               flags,
4822                               mount_operation,
4823                               cancellable,
4824                               callback,
4825                               user_data);
4826 }
4827
4828 /**
4829  * g_file_mount_mountable_finish:
4830  * @file: input #GFile
4831  * @result: a #GAsyncResult
4832  * @error: a #GError, or %NULL
4833  *
4834  * Finishes a mount operation. See g_file_mount_mountable() for details.
4835  *
4836  * Finish an asynchronous mount operation that was started
4837  * with g_file_mount_mountable().
4838  *
4839  * Returns: (transfer full): a #GFile or %NULL on error.
4840  *     Free the returned object with g_object_unref().
4841  */
4842 GFile *
4843 g_file_mount_mountable_finish (GFile         *file,
4844                                GAsyncResult  *result,
4845                                GError       **error)
4846 {
4847   GFileIface *iface;
4848
4849   g_return_val_if_fail (G_IS_FILE (file), NULL);
4850   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
4851
4852   if (g_async_result_legacy_propagate_error (result, error))
4853     return NULL;
4854   else if (g_async_result_is_tagged (result, g_file_mount_mountable))
4855     return g_task_propagate_pointer (G_TASK (result), error);
4856
4857   iface = G_FILE_GET_IFACE (file);
4858   return (* iface->mount_mountable_finish) (file, result, error);
4859 }
4860
4861 /**
4862  * g_file_unmount_mountable:
4863  * @file: input #GFile
4864  * @flags: flags affecting the operation
4865  * @cancellable: (allow-none): optional #GCancellable object,
4866  *     %NULL to ignore
4867  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4868  *     when the request is satisfied, or %NULL
4869  * @user_data: (closure): the data to pass to callback function
4870  *
4871  * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
4872  *
4873  * If @cancellable is not %NULL, then the operation can be cancelled by
4874  * triggering the cancellable object from another thread. If the operation
4875  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4876  *
4877  * When the operation is finished, @callback will be called.
4878  * You can then call g_file_unmount_mountable_finish() to get
4879  * the result of the operation.
4880  *
4881  * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
4882  */
4883 void
4884 g_file_unmount_mountable (GFile               *file,
4885                           GMountUnmountFlags   flags,
4886                           GCancellable        *cancellable,
4887                           GAsyncReadyCallback  callback,
4888                           gpointer             user_data)
4889 {
4890   GFileIface *iface;
4891
4892   g_return_if_fail (G_IS_FILE (file));
4893
4894   iface = G_FILE_GET_IFACE (file);
4895
4896   if (iface->unmount_mountable == NULL)
4897     {
4898       g_task_report_new_error (file, callback, user_data,
4899                                g_file_unmount_mountable_with_operation,
4900                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4901                                _("Operation not supported"));
4902       return;
4903     }
4904
4905   (* iface->unmount_mountable) (file,
4906                                 flags,
4907                                 cancellable,
4908                                 callback,
4909                                 user_data);
4910 }
4911
4912 /**
4913  * g_file_unmount_mountable_finish:
4914  * @file: input #GFile
4915  * @result: a #GAsyncResult
4916  * @error: a #GError, or %NULL
4917  *
4918  * Finishes an unmount operation, see g_file_unmount_mountable() for details.
4919  *
4920  * Finish an asynchronous unmount operation that was started
4921  * with g_file_unmount_mountable().
4922  *
4923  * Returns: %TRUE if the operation finished successfully.
4924  *     %FALSE otherwise.
4925  *
4926  * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
4927  *     instead.
4928  */
4929 gboolean
4930 g_file_unmount_mountable_finish (GFile         *file,
4931                                  GAsyncResult  *result,
4932                                  GError       **error)
4933 {
4934   GFileIface *iface;
4935
4936   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4937   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4938
4939   if (g_async_result_legacy_propagate_error (result, error))
4940     return FALSE;
4941   else if (g_async_result_is_tagged (result, g_file_unmount_mountable_with_operation))
4942     return g_task_propagate_boolean (G_TASK (result), error);
4943
4944   iface = G_FILE_GET_IFACE (file);
4945   return (* iface->unmount_mountable_finish) (file, result, error);
4946 }
4947
4948 /**
4949  * g_file_unmount_mountable_with_operation:
4950  * @file: input #GFile
4951  * @flags: flags affecting the operation
4952  * @mount_operation: (allow-none): a #GMountOperation,
4953  *     or %NULL to avoid user interaction
4954  * @cancellable: (allow-none): optional #GCancellable object,
4955  *     %NULL to ignore
4956  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
4957  *     when the request is satisfied, or %NULL
4958  * @user_data: (closure): the data to pass to callback function
4959  *
4960  * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
4961  *
4962  * If @cancellable is not %NULL, then the operation can be cancelled by
4963  * triggering the cancellable object from another thread. If the operation
4964  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4965  *
4966  * When the operation is finished, @callback will be called.
4967  * You can then call g_file_unmount_mountable_finish() to get
4968  * the result of the operation.
4969  *
4970  * Since: 2.22
4971  */
4972 void
4973 g_file_unmount_mountable_with_operation (GFile               *file,
4974                                          GMountUnmountFlags   flags,
4975                                          GMountOperation     *mount_operation,
4976                                          GCancellable        *cancellable,
4977                                          GAsyncReadyCallback  callback,
4978                                          gpointer             user_data)
4979 {
4980   GFileIface *iface;
4981
4982   g_return_if_fail (G_IS_FILE (file));
4983
4984   iface = G_FILE_GET_IFACE (file);
4985
4986   if (iface->unmount_mountable == NULL && iface->unmount_mountable_with_operation == NULL)
4987     {
4988       g_task_report_new_error (file, callback, user_data,
4989                                g_file_unmount_mountable_with_operation,
4990                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4991                                _("Operation not supported"));
4992       return;
4993     }
4994
4995   if (iface->unmount_mountable_with_operation != NULL)
4996     (* iface->unmount_mountable_with_operation) (file,
4997                                                  flags,
4998                                                  mount_operation,
4999                                                  cancellable,
5000                                                  callback,
5001                                                  user_data);
5002   else
5003     (* iface->unmount_mountable) (file,
5004                                   flags,
5005                                   cancellable,
5006                                   callback,
5007                                   user_data);
5008 }
5009
5010 /**
5011  * g_file_unmount_mountable_with_operation_finish:
5012  * @file: input #GFile
5013  * @result: a #GAsyncResult
5014  * @error: a #GError, or %NULL
5015  *
5016  * Finishes an unmount operation,
5017  * see g_file_unmount_mountable_with_operation() for details.
5018  *
5019  * Finish an asynchronous unmount operation that was started
5020  * with g_file_unmount_mountable_with_operation().
5021  *
5022  * Returns: %TRUE if the operation finished successfully.
5023  *     %FALSE otherwise.
5024  *
5025  * Since: 2.22
5026  */
5027 gboolean
5028 g_file_unmount_mountable_with_operation_finish (GFile         *file,
5029                                                 GAsyncResult  *result,
5030                                                 GError       **error)
5031 {
5032   GFileIface *iface;
5033
5034   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5035   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5036
5037   if (g_async_result_legacy_propagate_error (result, error))
5038     return FALSE;
5039   else if (g_async_result_is_tagged (result, g_file_unmount_mountable_with_operation))
5040     return g_task_propagate_boolean (G_TASK (result), error);
5041
5042   iface = G_FILE_GET_IFACE (file);
5043   if (iface->unmount_mountable_with_operation_finish != NULL)
5044     return (* iface->unmount_mountable_with_operation_finish) (file, result, error);
5045   else
5046     return (* iface->unmount_mountable_finish) (file, result, error);
5047 }
5048
5049 /**
5050  * g_file_eject_mountable:
5051  * @file: input #GFile
5052  * @flags: flags affecting the operation
5053  * @cancellable: (allow-none): optional #GCancellable object,
5054  *     %NULL to ignore
5055  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
5056  *     when the request is satisfied, or %NULL
5057  * @user_data: (closure): the data to pass to callback function
5058  *
5059  * Starts an asynchronous eject on a mountable.
5060  * When this operation has completed, @callback will be called with
5061  * @user_user data, and the operation can be finalized with
5062  * g_file_eject_mountable_finish().
5063  *
5064  * If @cancellable is not %NULL, then the operation can be cancelled by
5065  * triggering the cancellable object from another thread. If the operation
5066  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5067  *
5068  * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
5069  */
5070 void
5071 g_file_eject_mountable (GFile               *file,
5072                         GMountUnmountFlags   flags,
5073                         GCancellable        *cancellable,
5074                         GAsyncReadyCallback  callback,
5075                         gpointer             user_data)
5076 {
5077   GFileIface *iface;
5078
5079   g_return_if_fail (G_IS_FILE (file));
5080
5081   iface = G_FILE_GET_IFACE (file);
5082
5083   if (iface->eject_mountable == NULL)
5084     {
5085       g_task_report_new_error (file, callback, user_data,
5086                                g_file_eject_mountable_with_operation,
5087                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5088                                _("Operation not supported"));
5089       return;
5090     }
5091
5092   (* iface->eject_mountable) (file,
5093                               flags,
5094                               cancellable,
5095                               callback,
5096                               user_data);
5097 }
5098
5099 /**
5100  * g_file_eject_mountable_finish:
5101  * @file: input #GFile
5102  * @result: a #GAsyncResult
5103  * @error: a #GError, or %NULL
5104  *
5105  * Finishes an asynchronous eject operation started by
5106  * g_file_eject_mountable().
5107  *
5108  * Returns: %TRUE if the @file was ejected successfully.
5109  *     %FALSE otherwise.
5110  *
5111  * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
5112  *     instead.
5113  */
5114 gboolean
5115 g_file_eject_mountable_finish (GFile         *file,
5116                                GAsyncResult  *result,
5117                                GError       **error)
5118 {
5119   GFileIface *iface;
5120
5121   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5122   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5123
5124   if (g_async_result_legacy_propagate_error (result, error))
5125     return FALSE;
5126   else if (g_async_result_is_tagged (result, g_file_eject_mountable_with_operation))
5127     return g_task_propagate_boolean (G_TASK (result), error);
5128
5129   iface = G_FILE_GET_IFACE (file);
5130   return (* iface->eject_mountable_finish) (file, result, error);
5131 }
5132
5133 /**
5134  * g_file_eject_mountable_with_operation:
5135  * @file: input #GFile
5136  * @flags: flags affecting the operation
5137  * @mount_operation: (allow-none): a #GMountOperation,
5138  *     or %NULL to avoid user interaction
5139  * @cancellable: (allow-none): optional #GCancellable object,
5140  *     %NULL to ignore
5141  * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
5142  *     when the request is satisfied, or %NULL
5143  * @user_data: (closure): the data to pass to callback function
5144  *
5145  * Starts an asynchronous eject on a mountable.
5146  * When this operation has completed, @callback will be called with
5147  * @user_user data, and the operation can be finalized with
5148  * g_file_eject_mountable_with_operation_finish().
5149  *
5150  * If @cancellable is not %NULL, then the operation can be cancelled by
5151  * triggering the cancellable object from another thread. If the operation
5152  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5153  *
5154  * Since: 2.22
5155  */
5156 void
5157 g_file_eject_mountable_with_operation (GFile               *file,
5158                                        GMountUnmountFlags   flags,
5159                                        GMountOperation     *mount_operation,
5160                                        GCancellable        *cancellable,
5161                                        GAsyncReadyCallback  callback,
5162                                        gpointer             user_data)
5163 {
5164   GFileIface *iface;
5165
5166   g_return_if_fail (G_IS_FILE (file));
5167
5168   iface = G_FILE_GET_IFACE (file);
5169
5170   if (iface->eject_mountable == NULL && iface->eject_mountable_with_operation == NULL)
5171     {
5172       g_task_report_new_error (file, callback, user_data,
5173                                g_file_eject_mountable_with_operation,
5174                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5175                                _("Operation not supported"));
5176       return;
5177     }
5178
5179   if (iface->eject_mountable_with_operation != NULL)
5180     (* iface->eject_mountable_with_operation) (file,
5181                                                flags,
5182                                                mount_operation,
5183                                                cancellable,
5184                                                callback,
5185                                                user_data);
5186   else
5187     (* iface->eject_mountable) (file,
5188                                 flags,
5189                                 cancellable,
5190                                 callback,
5191                                 user_data);
5192 }
5193
5194 /**
5195  * g_file_eject_mountable_with_operation_finish:
5196  * @file: input #GFile
5197  * @result: a #GAsyncResult
5198  * @error: a #GError, or %NULL
5199  *
5200  * Finishes an asynchronous eject operation started by
5201  * g_file_eject_mountable_with_operation().
5202  *
5203  * Returns: %TRUE if the @file was ejected successfully.
5204  *     %FALSE otherwise.
5205  *
5206  * Since: 2.22
5207  */
5208 gboolean
5209 g_file_eject_mountable_with_operation_finish (GFile         *file,
5210                                               GAsyncResult  *result,
5211                                               GError       **error)
5212 {
5213   GFileIface *iface;
5214
5215   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5216   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5217
5218   if (g_async_result_legacy_propagate_error (result, error))
5219     return FALSE;
5220   else if (g_async_result_is_tagged (result, g_file_eject_mountable_with_operation))
5221     return g_task_propagate_boolean (G_TASK (result), error);
5222
5223   iface = G_FILE_GET_IFACE (file);
5224   if (iface->eject_mountable_with_operation_finish != NULL)
5225     return (* iface->eject_mountable_with_operation_finish) (file, result, error);
5226   else
5227     return (* iface->eject_mountable_finish) (file, result, error);
5228 }
5229
5230 /**
5231  * g_file_monitor_directory:
5232  * @file: input #GFile
5233  * @flags: a set of #GFileMonitorFlags
5234  * @cancellable: (allow-none): optional #GCancellable object,
5235  *     %NULL to ignore
5236  * @error: a #GError, or %NULL
5237  *
5238  * Obtains a directory monitor for the given file.
5239  * This may fail if directory monitoring is not supported.
5240  *
5241  * If @cancellable is not %NULL, then the operation can be cancelled by
5242  * triggering the cancellable object from another thread. If the operation
5243  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5244  *
5245  * It does not make sense for @flags to contain
5246  * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
5247  * directories.  It is not possible to monitor all the files in a
5248  * directory for changes made via hard links; if you want to do this then
5249  * you must register individual watches with g_file_monitor().
5250  *
5251  * Virtual: monitor_dir
5252  * Returns: (transfer full): a #GFileMonitor for the given @file,
5253  *     or %NULL on error.
5254  *     Free the returned object with g_object_unref().
5255  */
5256 GFileMonitor *
5257 g_file_monitor_directory (GFile              *file,
5258                           GFileMonitorFlags   flags,
5259                           GCancellable       *cancellable,
5260                           GError            **error)
5261 {
5262   GFileIface *iface;
5263
5264   g_return_val_if_fail (G_IS_FILE (file), NULL);
5265   g_return_val_if_fail (~flags & G_FILE_MONITOR_WATCH_HARD_LINKS, NULL);
5266
5267   if (g_cancellable_set_error_if_cancelled (cancellable, error))
5268     return NULL;
5269
5270   iface = G_FILE_GET_IFACE (file);
5271
5272   if (iface->monitor_dir == NULL)
5273     {
5274       g_set_error_literal (error, G_IO_ERROR,
5275                            G_IO_ERROR_NOT_SUPPORTED,
5276                            _("Operation not supported"));
5277       return NULL;
5278     }
5279
5280   return (* iface->monitor_dir) (file, flags, cancellable, error);
5281 }
5282
5283 /**
5284  * g_file_monitor_file:
5285  * @file: input #GFile
5286  * @flags: a set of #GFileMonitorFlags
5287  * @cancellable: (allow-none): optional #GCancellable object,
5288  *     %NULL to ignore
5289  * @error: a #GError, or %NULL
5290  *
5291  * Obtains a file monitor for the given file. If no file notification
5292  * mechanism exists, then regular polling of the file is used.
5293  *
5294  * If @cancellable is not %NULL, then the operation can be cancelled by
5295  * triggering the cancellable object from another thread. If the operation
5296  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5297  *
5298  * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
5299  * will also attempt to report changes made to the file via another
5300  * filename (ie, a hard link). Without this flag, you can only rely on
5301  * changes made through the filename contained in @file to be
5302  * reported. Using this flag may result in an increase in resource
5303  * usage, and may not have any effect depending on the #GFileMonitor
5304  * backend and/or filesystem type.
5305  *
5306  * Returns: (transfer full): a #GFileMonitor for the given @file,
5307  *     or %NULL on error.
5308  *     Free the returned object with g_object_unref().
5309  */
5310 GFileMonitor *
5311 g_file_monitor_file (GFile              *file,
5312                      GFileMonitorFlags   flags,
5313                      GCancellable       *cancellable,
5314                      GError            **error)
5315 {
5316   GFileIface *iface;
5317   GFileMonitor *monitor;
5318
5319   g_return_val_if_fail (G_IS_FILE (file), NULL);
5320
5321   if (g_cancellable_set_error_if_cancelled (cancellable, error))
5322     return NULL;
5323
5324   iface = G_FILE_GET_IFACE (file);
5325
5326   monitor = NULL;
5327
5328   if (iface->monitor_file)
5329     monitor = (* iface->monitor_file) (file, flags, cancellable, NULL);
5330
5331   /* Fallback to polling */
5332   if (monitor == NULL)
5333     monitor = _g_poll_file_monitor_new (file);
5334
5335   return monitor;
5336 }
5337
5338 /**
5339  * g_file_monitor:
5340  * @file: input #GFile
5341  * @flags: a set of #GFileMonitorFlags
5342  * @cancellable: (allow-none): optional #GCancellable object,
5343  *     %NULL to ignore
5344  * @error: a #GError, or %NULL
5345  *
5346  * Obtains a file or directory monitor for the given file,
5347  * depending on the type of the file.
5348  *
5349  * If @cancellable is not %NULL, then the operation can be cancelled by
5350  * triggering the cancellable object from another thread. If the operation
5351  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5352  *
5353  * Returns: (transfer full): a #GFileMonitor for the given @file,
5354  *     or %NULL on error.
5355  *     Free the returned object with g_object_unref().
5356  *
5357  * Since: 2.18
5358  */
5359 GFileMonitor *
5360 g_file_monitor (GFile              *file,
5361                 GFileMonitorFlags   flags,
5362                 GCancellable       *cancellable,
5363                 GError            **error)
5364 {
5365   if (g_file_query_file_type (file, 0, cancellable) == G_FILE_TYPE_DIRECTORY)
5366     return g_file_monitor_directory (file,
5367                                      flags & ~G_FILE_MONITOR_WATCH_HARD_LINKS,
5368                                      cancellable, error);
5369   else
5370     return g_file_monitor_file (file, flags, cancellable, error);
5371 }
5372
5373 /********************************************
5374  *   Default implementation of async ops    *
5375  ********************************************/
5376
5377 typedef struct {
5378   char *attributes;
5379   GFileQueryInfoFlags flags;
5380 } QueryInfoAsyncData;
5381
5382 static void
5383 query_info_data_free (QueryInfoAsyncData *data)
5384 {
5385   g_free (data->attributes);
5386   g_free (data);
5387 }
5388
5389 static void
5390 query_info_async_thread (GTask         *task,
5391                          gpointer       object,
5392                          gpointer       task_data,
5393                          GCancellable  *cancellable)
5394 {
5395   QueryInfoAsyncData *data = task_data;
5396   GFileInfo *info;
5397   GError *error = NULL;
5398
5399   info = g_file_query_info (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5400   if (info)
5401     g_task_return_pointer (task, info, g_object_unref);
5402   else
5403     g_task_return_error (task, error);
5404 }
5405
5406 static void
5407 g_file_real_query_info_async (GFile               *file,
5408                               const char          *attributes,
5409                               GFileQueryInfoFlags  flags,
5410                               int                  io_priority,
5411                               GCancellable        *cancellable,
5412                               GAsyncReadyCallback  callback,
5413                               gpointer             user_data)
5414 {
5415   GTask *task;
5416   QueryInfoAsyncData *data;
5417
5418   data = g_new0 (QueryInfoAsyncData, 1);
5419   data->attributes = g_strdup (attributes);
5420   data->flags = flags;
5421
5422   task = g_task_new (file, cancellable, callback, user_data);
5423   g_task_set_source_tag (task, g_file_real_query_info_async);
5424   g_task_set_task_data (task, data, (GDestroyNotify)query_info_data_free);
5425   g_task_set_priority (task, io_priority);
5426   g_task_run_in_thread (task, query_info_async_thread);
5427   g_object_unref (task);
5428 }
5429
5430 static GFileInfo *
5431 g_file_real_query_info_finish (GFile         *file,
5432                                GAsyncResult  *res,
5433                                GError       **error)
5434 {
5435   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5436
5437   return g_task_propagate_pointer (G_TASK (res), error);
5438 }
5439
5440 static void
5441 query_filesystem_info_async_thread (GTask         *task,
5442                                     gpointer       object,
5443                                     gpointer       task_data,
5444                                     GCancellable  *cancellable)
5445 {
5446   const char *attributes = task_data;
5447   GFileInfo *info;
5448   GError *error = NULL;
5449
5450   info = g_file_query_filesystem_info (G_FILE (object), attributes, cancellable, &error);
5451   if (info)
5452     g_task_return_pointer (task, info, g_object_unref);
5453   else
5454     g_task_return_error (task, error);
5455 }
5456
5457 static void
5458 g_file_real_query_filesystem_info_async (GFile               *file,
5459                                          const char          *attributes,
5460                                          int                  io_priority,
5461                                          GCancellable        *cancellable,
5462                                          GAsyncReadyCallback  callback,
5463                                          gpointer             user_data)
5464 {
5465   GTask *task;
5466
5467   task = g_task_new (file, cancellable, callback, user_data);
5468   g_task_set_source_tag (task, g_file_real_query_filesystem_info_async);
5469   g_task_set_task_data (task, g_strdup (attributes), g_free);
5470   g_task_set_priority (task, io_priority);
5471   g_task_run_in_thread (task, query_filesystem_info_async_thread);
5472   g_object_unref (task);
5473 }
5474
5475 static GFileInfo *
5476 g_file_real_query_filesystem_info_finish (GFile         *file,
5477                                           GAsyncResult  *res,
5478                                           GError       **error)
5479 {
5480   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5481
5482   return g_task_propagate_pointer (G_TASK (res), error);
5483 }
5484
5485 static void
5486 enumerate_children_async_thread (GTask         *task,
5487                                  gpointer       object,
5488                                  gpointer       task_data,
5489                                  GCancellable  *cancellable)
5490 {
5491   QueryInfoAsyncData *data = task_data;
5492   GFileEnumerator *enumerator;
5493   GError *error = NULL;
5494
5495   enumerator = g_file_enumerate_children (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5496   if (error)
5497     g_task_return_error (task, error);
5498   else
5499     g_task_return_pointer (task, enumerator, g_object_unref);
5500 }
5501
5502 static void
5503 g_file_real_enumerate_children_async (GFile               *file,
5504                                       const char          *attributes,
5505                                       GFileQueryInfoFlags  flags,
5506                                       int                  io_priority,
5507                                       GCancellable        *cancellable,
5508                                       GAsyncReadyCallback  callback,
5509                                       gpointer             user_data)
5510 {
5511   GTask *task;
5512   QueryInfoAsyncData *data;
5513
5514   data = g_new0 (QueryInfoAsyncData, 1);
5515   data->attributes = g_strdup (attributes);
5516   data->flags = flags;
5517
5518   task = g_task_new (file, cancellable, callback, user_data);
5519   g_task_set_source_tag (task, g_file_real_enumerate_children_async);
5520   g_task_set_task_data (task, data, (GDestroyNotify)query_info_data_free);
5521   g_task_set_priority (task, io_priority);
5522   g_task_run_in_thread (task, enumerate_children_async_thread);
5523   g_object_unref (task);
5524 }
5525
5526 static GFileEnumerator *
5527 g_file_real_enumerate_children_finish (GFile         *file,
5528                                        GAsyncResult  *res,
5529                                        GError       **error)
5530 {
5531   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5532
5533   return g_task_propagate_pointer (G_TASK (res), error);
5534 }
5535
5536 static void
5537 open_read_async_thread (GTask         *task,
5538                         gpointer       object,
5539                         gpointer       task_data,
5540                         GCancellable  *cancellable)
5541 {
5542   GFileInputStream *stream;
5543   GError *error = NULL;
5544
5545   stream = g_file_read (G_FILE (object), cancellable, &error);
5546   if (stream)
5547     g_task_return_pointer (task, stream, g_object_unref);
5548   else
5549     g_task_return_error (task, error);
5550 }
5551
5552 static void
5553 g_file_real_read_async (GFile               *file,
5554                         int                  io_priority,
5555                         GCancellable        *cancellable,
5556                         GAsyncReadyCallback  callback,
5557                         gpointer             user_data)
5558 {
5559   GTask *task;
5560
5561   task = g_task_new (file, cancellable, callback, user_data);
5562   g_task_set_source_tag (task, g_file_real_read_async);
5563   g_task_set_priority (task, io_priority);
5564   g_task_run_in_thread (task, open_read_async_thread);
5565   g_object_unref (task);
5566 }
5567
5568 static GFileInputStream *
5569 g_file_real_read_finish (GFile         *file,
5570                          GAsyncResult  *res,
5571                          GError       **error)
5572 {
5573   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5574
5575   return g_task_propagate_pointer (G_TASK (res), error);
5576 }
5577
5578 static void
5579 append_to_async_thread (GTask         *task,
5580                         gpointer       source_object,
5581                         gpointer       task_data,
5582                         GCancellable  *cancellable)
5583 {
5584   GFileCreateFlags *data = task_data;
5585   GFileOutputStream *stream;
5586   GError *error = NULL;
5587
5588   stream = g_file_append_to (G_FILE (source_object), *data, cancellable, &error);
5589   if (stream)
5590     g_task_return_pointer (task, stream, g_object_unref);
5591   else
5592     g_task_return_error (task, error);
5593 }
5594
5595 static void
5596 g_file_real_append_to_async (GFile               *file,
5597                              GFileCreateFlags     flags,
5598                              int                  io_priority,
5599                              GCancellable        *cancellable,
5600                              GAsyncReadyCallback  callback,
5601                              gpointer             user_data)
5602 {
5603   GFileCreateFlags *data;
5604   GTask *task;
5605
5606   data = g_new0 (GFileCreateFlags, 1);
5607   *data = flags;
5608
5609   task = g_task_new (file, cancellable, callback, user_data);
5610   g_task_set_source_tag (task, g_file_real_append_to_async);
5611   g_task_set_task_data (task, data, g_free);
5612   g_task_set_priority (task, io_priority);
5613
5614   g_task_run_in_thread (task, append_to_async_thread);
5615   g_object_unref (task);
5616 }
5617
5618 static GFileOutputStream *
5619 g_file_real_append_to_finish (GFile         *file,
5620                               GAsyncResult  *res,
5621                               GError       **error)
5622 {
5623   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5624
5625   return g_task_propagate_pointer (G_TASK (res), error);
5626 }
5627
5628 static void
5629 create_async_thread (GTask         *task,
5630                      gpointer       source_object,
5631                      gpointer       task_data,
5632                      GCancellable  *cancellable)
5633 {
5634   GFileCreateFlags *data = task_data;
5635   GFileOutputStream *stream;
5636   GError *error = NULL;
5637
5638   stream = g_file_create (G_FILE (source_object), *data, cancellable, &error);
5639   if (stream)
5640     g_task_return_pointer (task, stream, g_object_unref);
5641   else
5642     g_task_return_error (task, error);
5643 }
5644
5645 static void
5646 g_file_real_create_async (GFile               *file,
5647                           GFileCreateFlags     flags,
5648                           int                  io_priority,
5649                           GCancellable        *cancellable,
5650                           GAsyncReadyCallback  callback,
5651                           gpointer             user_data)
5652 {
5653   GFileCreateFlags *data;
5654   GTask *task;
5655
5656   data = g_new0 (GFileCreateFlags, 1);
5657   *data = flags;
5658
5659   task = g_task_new (file, cancellable, callback, user_data);
5660   g_task_set_source_tag (task, g_file_real_create_async);
5661   g_task_set_task_data (task, data, g_free);
5662   g_task_set_priority (task, io_priority);
5663
5664   g_task_run_in_thread (task, create_async_thread);
5665   g_object_unref (task);
5666 }
5667
5668 static GFileOutputStream *
5669 g_file_real_create_finish (GFile         *file,
5670                            GAsyncResult  *res,
5671                            GError       **error)
5672 {
5673   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5674
5675   return g_task_propagate_pointer (G_TASK (res), error);
5676 }
5677
5678 typedef struct {
5679   GFileOutputStream *stream;
5680   char *etag;
5681   gboolean make_backup;
5682   GFileCreateFlags flags;
5683 } ReplaceAsyncData;
5684
5685 static void
5686 replace_async_data_free (ReplaceAsyncData *data)
5687 {
5688   if (data->stream)
5689     g_object_unref (data->stream);
5690   g_free (data->etag);
5691   g_free (data);
5692 }
5693
5694 static void
5695 replace_async_thread (GTask         *task,
5696                       gpointer       source_object,
5697                       gpointer       task_data,
5698                       GCancellable  *cancellable)
5699 {
5700   GFileOutputStream *stream;
5701   ReplaceAsyncData *data = task_data;
5702   GError *error = NULL;
5703
5704   stream = g_file_replace (G_FILE (source_object),
5705                            data->etag,
5706                            data->make_backup,
5707                            data->flags,
5708                            cancellable,
5709                            &error);
5710
5711   if (stream)
5712     g_task_return_pointer (task, stream, g_object_unref);
5713   else
5714     g_task_return_error (task, error);
5715 }
5716
5717 static void
5718 g_file_real_replace_async (GFile               *file,
5719                            const char          *etag,
5720                            gboolean             make_backup,
5721                            GFileCreateFlags     flags,
5722                            int                  io_priority,
5723                            GCancellable        *cancellable,
5724                            GAsyncReadyCallback  callback,
5725                            gpointer             user_data)
5726 {
5727   GTask *task;
5728   ReplaceAsyncData *data;
5729
5730   data = g_new0 (ReplaceAsyncData, 1);
5731   data->etag = g_strdup (etag);
5732   data->make_backup = make_backup;
5733   data->flags = flags;
5734
5735   task = g_task_new (file, cancellable, callback, user_data);
5736   g_task_set_source_tag (task, g_file_real_replace_async);
5737   g_task_set_task_data (task, data, (GDestroyNotify)replace_async_data_free);
5738   g_task_set_priority (task, io_priority);
5739
5740   g_task_run_in_thread (task, replace_async_thread);
5741   g_object_unref (task);
5742 }
5743
5744 static GFileOutputStream *
5745 g_file_real_replace_finish (GFile         *file,
5746                             GAsyncResult  *res,
5747                             GError       **error)
5748 {
5749   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5750
5751   return g_task_propagate_pointer (G_TASK (res), error);
5752 }
5753
5754 static void
5755 delete_async_thread (GTask        *task,
5756                      gpointer      object,
5757                      gpointer      task_data,
5758                      GCancellable *cancellable)
5759 {
5760   GError *error = NULL;
5761
5762   if (g_file_delete (G_FILE (object), cancellable, &error))
5763     g_task_return_boolean (task, TRUE);
5764   else
5765     g_task_return_error (task, error);
5766 }
5767
5768 static void
5769 g_file_real_delete_async (GFile               *file,
5770                           int                  io_priority,
5771                           GCancellable        *cancellable,
5772                           GAsyncReadyCallback  callback,
5773                           gpointer             user_data)
5774 {
5775   GTask *task;
5776
5777   task = g_task_new (file, cancellable, callback, user_data);
5778   g_task_set_source_tag (task, g_file_real_delete_async);
5779   g_task_set_priority (task, io_priority);
5780   g_task_run_in_thread (task, delete_async_thread);
5781   g_object_unref (task);
5782 }
5783
5784 static gboolean
5785 g_file_real_delete_finish (GFile         *file,
5786                            GAsyncResult  *res,
5787                            GError       **error)
5788 {
5789   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
5790
5791   return g_task_propagate_boolean (G_TASK (res), error);
5792 }
5793
5794 static void
5795 trash_async_thread (GTask        *task,
5796                     gpointer      object,
5797                     gpointer      task_data,
5798                     GCancellable *cancellable)
5799 {
5800   GError *error = NULL;
5801
5802   if (g_file_trash (G_FILE (object), cancellable, &error))
5803     g_task_return_boolean (task, TRUE);
5804   else
5805     g_task_return_error (task, error);
5806 }
5807
5808 static void
5809 g_file_real_trash_async (GFile               *file,
5810                          int                  io_priority,
5811                          GCancellable        *cancellable,
5812                          GAsyncReadyCallback  callback,
5813                          gpointer             user_data)
5814 {
5815   GTask *task;
5816
5817   task = g_task_new (file, cancellable, callback, user_data);
5818   g_task_set_source_tag (task, g_file_real_trash_async);
5819   g_task_set_priority (task, io_priority);
5820   g_task_run_in_thread (task, trash_async_thread);
5821   g_object_unref (task);
5822 }
5823
5824 static gboolean
5825 g_file_real_trash_finish (GFile         *file,
5826                           GAsyncResult  *res,
5827                           GError       **error)
5828 {
5829   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
5830
5831   return g_task_propagate_boolean (G_TASK (res), error);
5832 }
5833
5834 static void
5835 make_directory_async_thread (GTask        *task,
5836                              gpointer      object,
5837                              gpointer      task_data,
5838                              GCancellable *cancellable)
5839 {
5840   GError *error = NULL;
5841
5842   if (g_file_make_directory (G_FILE (object), cancellable, &error))
5843     g_task_return_boolean (task, TRUE);
5844   else
5845     g_task_return_error (task, error);
5846 }
5847
5848 static void
5849 g_file_real_make_directory_async (GFile               *file,
5850                                   int                  io_priority,
5851                                   GCancellable        *cancellable,
5852                                   GAsyncReadyCallback  callback,
5853                                   gpointer             user_data)
5854 {
5855   GTask *task;
5856
5857   task = g_task_new (file, cancellable, callback, user_data);
5858   g_task_set_source_tag (task, g_file_real_make_directory_async);
5859   g_task_set_priority (task, io_priority);
5860   g_task_run_in_thread (task, make_directory_async_thread);
5861   g_object_unref (task);
5862 }
5863
5864 static gboolean
5865 g_file_real_make_directory_finish (GFile         *file,
5866                                    GAsyncResult  *res,
5867                                    GError       **error)
5868 {
5869   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
5870
5871   return g_task_propagate_boolean (G_TASK (res), error);
5872 }
5873
5874 static void
5875 open_readwrite_async_thread (GTask        *task,
5876                              gpointer      object,
5877                              gpointer      task_data,
5878                              GCancellable *cancellable)
5879 {
5880   GFileIOStream *stream;
5881   GError *error = NULL;
5882
5883   stream = g_file_open_readwrite (G_FILE (object), cancellable, &error);
5884
5885   if (stream == NULL)
5886     g_task_return_error (task, error);
5887   else
5888     g_task_return_pointer (task, stream, g_object_unref);
5889 }
5890
5891 static void
5892 g_file_real_open_readwrite_async (GFile               *file,
5893                                   int                  io_priority,
5894                                   GCancellable        *cancellable,
5895                                   GAsyncReadyCallback  callback,
5896                                   gpointer             user_data)
5897 {
5898   GTask *task;
5899
5900   task = g_task_new (file, cancellable, callback, user_data);
5901   g_task_set_source_tag (task, g_file_real_open_readwrite_async);
5902   g_task_set_priority (task, io_priority);
5903
5904   g_task_run_in_thread (task, open_readwrite_async_thread);
5905   g_object_unref (task);
5906 }
5907
5908 static GFileIOStream *
5909 g_file_real_open_readwrite_finish (GFile         *file,
5910                                    GAsyncResult  *res,
5911                                    GError       **error)
5912 {
5913   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5914
5915   return g_task_propagate_pointer (G_TASK (res), error);
5916 }
5917
5918 static void
5919 create_readwrite_async_thread (GTask        *task,
5920                                gpointer      object,
5921                                gpointer      task_data,
5922                                GCancellable *cancellable)
5923 {
5924   GFileCreateFlags *data = task_data;
5925   GFileIOStream *stream;
5926   GError *error = NULL;
5927
5928   stream = g_file_create_readwrite (G_FILE (object), *data, cancellable, &error);
5929
5930   if (stream == NULL)
5931     g_task_return_error (task, error);
5932   else
5933     g_task_return_pointer (task, stream, g_object_unref);
5934 }
5935
5936 static void
5937 g_file_real_create_readwrite_async (GFile               *file,
5938                                     GFileCreateFlags     flags,
5939                                     int                  io_priority,
5940                                     GCancellable        *cancellable,
5941                                     GAsyncReadyCallback  callback,
5942                                     gpointer             user_data)
5943 {
5944   GFileCreateFlags *data;
5945   GTask *task;
5946
5947   data = g_new0 (GFileCreateFlags, 1);
5948   *data = flags;
5949
5950   task = g_task_new (file, cancellable, callback, user_data);
5951   g_task_set_source_tag (task, g_file_real_create_readwrite_async);
5952   g_task_set_task_data (task, data, g_free);
5953   g_task_set_priority (task, io_priority);
5954
5955   g_task_run_in_thread (task, create_readwrite_async_thread);
5956   g_object_unref (task);
5957 }
5958
5959 static GFileIOStream *
5960 g_file_real_create_readwrite_finish (GFile         *file,
5961                                      GAsyncResult  *res,
5962                                      GError       **error)
5963 {
5964   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5965
5966   return g_task_propagate_pointer (G_TASK (res), error);
5967 }
5968
5969 typedef struct {
5970   char *etag;
5971   gboolean make_backup;
5972   GFileCreateFlags flags;
5973 } ReplaceRWAsyncData;
5974
5975 static void
5976 replace_rw_async_data_free (ReplaceRWAsyncData *data)
5977 {
5978   g_free (data->etag);
5979   g_free (data);
5980 }
5981
5982 static void
5983 replace_readwrite_async_thread (GTask        *task,
5984                                 gpointer      object,
5985                                 gpointer      task_data,
5986                                 GCancellable *cancellable)
5987 {
5988   GFileIOStream *stream;
5989   GError *error = NULL;
5990   ReplaceRWAsyncData *data = task_data;
5991
5992   stream = g_file_replace_readwrite (G_FILE (object),
5993                                      data->etag,
5994                                      data->make_backup,
5995                                      data->flags,
5996                                      cancellable,
5997                                      &error);
5998
5999   if (stream == NULL)
6000     g_task_return_error (task, error);
6001   else
6002     g_task_return_pointer (task, stream, g_object_unref);
6003 }
6004
6005 static void
6006 g_file_real_replace_readwrite_async (GFile               *file,
6007                                      const char          *etag,
6008                                      gboolean             make_backup,
6009                                      GFileCreateFlags     flags,
6010                                      int                  io_priority,
6011                                      GCancellable        *cancellable,
6012                                      GAsyncReadyCallback  callback,
6013                                      gpointer             user_data)
6014 {
6015   GTask *task;
6016   ReplaceRWAsyncData *data;
6017
6018   data = g_new0 (ReplaceRWAsyncData, 1);
6019   data->etag = g_strdup (etag);
6020   data->make_backup = make_backup;
6021   data->flags = flags;
6022
6023   task = g_task_new (file, cancellable, callback, user_data);
6024   g_task_set_source_tag (task, g_file_real_replace_readwrite_async);
6025   g_task_set_task_data (task, data, (GDestroyNotify)replace_rw_async_data_free);
6026   g_task_set_priority (task, io_priority);
6027
6028   g_task_run_in_thread (task, replace_readwrite_async_thread);
6029   g_object_unref (task);
6030 }
6031
6032 static GFileIOStream *
6033 g_file_real_replace_readwrite_finish (GFile         *file,
6034                                       GAsyncResult  *res,
6035                                       GError       **error)
6036 {
6037   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6038
6039   return g_task_propagate_pointer (G_TASK (res), error);
6040 }
6041
6042 static void
6043 set_display_name_async_thread (GTask        *task,
6044                                gpointer      object,
6045                                gpointer      task_data,
6046                                GCancellable *cancellable)
6047 {
6048   GError *error = NULL;
6049   char *name = task_data;
6050   GFile *file;
6051
6052   file = g_file_set_display_name (G_FILE (object), name, cancellable, &error);
6053
6054   if (file == NULL)
6055     g_task_return_error (task, error);
6056   else
6057     g_task_return_pointer (task, file, g_object_unref);
6058 }
6059
6060 static void
6061 g_file_real_set_display_name_async (GFile               *file,
6062                                     const char          *display_name,
6063                                     int                  io_priority,
6064                                     GCancellable        *cancellable,
6065                                     GAsyncReadyCallback  callback,
6066                                     gpointer             user_data)
6067 {
6068   GTask *task;
6069
6070   task = g_task_new (file, cancellable, callback, user_data);
6071   g_task_set_source_tag (task, g_file_real_set_display_name_async);
6072   g_task_set_task_data (task, g_strdup (display_name), g_free);
6073   g_task_set_priority (task, io_priority);
6074
6075   g_task_run_in_thread (task, set_display_name_async_thread);
6076   g_object_unref (task);
6077 }
6078
6079 static GFile *
6080 g_file_real_set_display_name_finish (GFile         *file,
6081                                      GAsyncResult  *res,
6082                                      GError       **error)
6083 {
6084   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6085
6086   return g_task_propagate_pointer (G_TASK (res), error);
6087 }
6088
6089 typedef struct {
6090   GFileQueryInfoFlags flags;
6091   GFileInfo *info;
6092   gboolean res;
6093   GError *error;
6094 } SetInfoAsyncData;
6095
6096 static void
6097 set_info_data_free (SetInfoAsyncData *data)
6098 {
6099   if (data->info)
6100     g_object_unref (data->info);
6101   if (data->error)
6102     g_error_free (data->error);
6103   g_free (data);
6104 }
6105
6106 static void
6107 set_info_async_thread (GTask        *task,
6108                        gpointer      object,
6109                        gpointer      task_data,
6110                        GCancellable *cancellable)
6111 {
6112   SetInfoAsyncData *data = task_data;
6113
6114   data->error = NULL;
6115   data->res = g_file_set_attributes_from_info (G_FILE (object),
6116                                                data->info,
6117                                                data->flags,
6118                                                cancellable,
6119                                                &data->error);
6120 }
6121
6122 static void
6123 g_file_real_set_attributes_async (GFile               *file,
6124                                   GFileInfo           *info,
6125                                   GFileQueryInfoFlags  flags,
6126                                   int                  io_priority,
6127                                   GCancellable        *cancellable,
6128                                   GAsyncReadyCallback  callback,
6129                                   gpointer             user_data)
6130 {
6131   GTask *task;
6132   SetInfoAsyncData *data;
6133
6134   data = g_new0 (SetInfoAsyncData, 1);
6135   data->info = g_file_info_dup (info);
6136   data->flags = flags;
6137
6138   task = g_task_new (file, cancellable, callback, user_data);
6139   g_task_set_source_tag (task, g_file_real_set_attributes_async);
6140   g_task_set_task_data (task, data, (GDestroyNotify)set_info_data_free);
6141   g_task_set_priority (task, io_priority);
6142
6143   g_task_run_in_thread (task, set_info_async_thread);
6144   g_object_unref (task);
6145 }
6146
6147 static gboolean
6148 g_file_real_set_attributes_finish (GFile         *file,
6149                                    GAsyncResult  *res,
6150                                    GFileInfo    **info,
6151                                    GError       **error)
6152 {
6153   SetInfoAsyncData *data;
6154
6155   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6156
6157   data = g_task_get_task_data (G_TASK (res));
6158
6159   if (info)
6160     *info = g_object_ref (data->info);
6161
6162   if (error != NULL && data->error)
6163     *error = g_error_copy (data->error);
6164
6165   return data->res;
6166 }
6167
6168 static void
6169 find_enclosing_mount_async_thread (GTask        *task,
6170                                    gpointer      object,
6171                                    gpointer      task_data,
6172                                    GCancellable *cancellable)
6173 {
6174   GError *error = NULL;
6175   GMount *mount;
6176
6177   mount = g_file_find_enclosing_mount (G_FILE (object), cancellable, &error);
6178
6179   if (mount == NULL)
6180     g_task_return_error (task, error);
6181   else
6182     g_task_return_pointer (task, mount, g_object_unref);
6183 }
6184
6185 static void
6186 g_file_real_find_enclosing_mount_async (GFile               *file,
6187                                         int                  io_priority,
6188                                         GCancellable        *cancellable,
6189                                         GAsyncReadyCallback  callback,
6190                                         gpointer             user_data)
6191 {
6192   GTask *task;
6193
6194   task = g_task_new (file, cancellable, callback, user_data);
6195   g_task_set_source_tag (task, g_file_real_find_enclosing_mount_async);
6196   g_task_set_priority (task, io_priority);
6197
6198   g_task_run_in_thread (task, find_enclosing_mount_async_thread);
6199   g_object_unref (task);
6200 }
6201
6202 static GMount *
6203 g_file_real_find_enclosing_mount_finish (GFile         *file,
6204                                          GAsyncResult  *res,
6205                                          GError       **error)
6206 {
6207   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6208
6209   return g_task_propagate_pointer (G_TASK (res), error);
6210 }
6211
6212
6213 typedef struct {
6214   GFile *source;
6215   GFile *destination;
6216   GFileCopyFlags flags;
6217   GFileProgressCallback progress_cb;
6218   gpointer progress_cb_data;
6219 } CopyAsyncData;
6220
6221 static void
6222 copy_async_data_free (CopyAsyncData *data)
6223 {
6224   g_object_unref (data->source);
6225   g_object_unref (data->destination);
6226   g_slice_free (CopyAsyncData, data);
6227 }
6228
6229 typedef struct {
6230   CopyAsyncData *data;
6231   goffset current_num_bytes;
6232   goffset total_num_bytes;
6233 } ProgressData;
6234
6235 static gboolean
6236 copy_async_progress_in_main (gpointer user_data)
6237 {
6238   ProgressData *progress = user_data;
6239   CopyAsyncData *data = progress->data;
6240
6241   data->progress_cb (progress->current_num_bytes,
6242                      progress->total_num_bytes,
6243                      data->progress_cb_data);
6244
6245   return FALSE;
6246 }
6247
6248 static void
6249 copy_async_progress_callback (goffset  current_num_bytes,
6250                               goffset  total_num_bytes,
6251                               gpointer user_data)
6252 {
6253   GTask *task = user_data;
6254   CopyAsyncData *data = g_task_get_task_data (task);
6255   ProgressData *progress;
6256
6257   progress = g_new (ProgressData, 1);
6258   progress->data = data;
6259   progress->current_num_bytes = current_num_bytes;
6260   progress->total_num_bytes = total_num_bytes;
6261
6262   g_main_context_invoke_full (g_task_get_context (task),
6263                               g_task_get_priority (task),
6264                               copy_async_progress_in_main,
6265                               progress,
6266                               g_free);
6267 }
6268
6269 static void
6270 copy_async_thread (GTask        *task,
6271                    gpointer      source,
6272                    gpointer      task_data,
6273                    GCancellable *cancellable)
6274 {
6275   CopyAsyncData *data = task_data;
6276   gboolean result;
6277   GError *error = NULL;
6278
6279   result = g_file_copy (data->source,
6280                         data->destination,
6281                         data->flags,
6282                         cancellable,
6283                         (data->progress_cb != NULL) ? copy_async_progress_callback : NULL,
6284                         task,
6285                         &error);
6286   if (result)
6287     g_task_return_boolean (task, TRUE);
6288   else
6289     g_task_return_error (task, error);
6290 }
6291
6292 static void
6293 g_file_real_copy_async (GFile                  *source,
6294                         GFile                  *destination,
6295                         GFileCopyFlags          flags,
6296                         int                     io_priority,
6297                         GCancellable           *cancellable,
6298                         GFileProgressCallback   progress_callback,
6299                         gpointer                progress_callback_data,
6300                         GAsyncReadyCallback     callback,
6301                         gpointer                user_data)
6302 {
6303   GTask *task;
6304   CopyAsyncData *data;
6305
6306   data = g_slice_new (CopyAsyncData);
6307   data->source = g_object_ref (source);
6308   data->destination = g_object_ref (destination);
6309   data->flags = flags;
6310   data->progress_cb = progress_callback;
6311   data->progress_cb_data = progress_callback_data;
6312
6313   task = g_task_new (source, cancellable, callback, user_data);
6314   g_task_set_source_tag (task, g_file_real_copy_async);
6315   g_task_set_task_data (task, data, (GDestroyNotify)copy_async_data_free);
6316   g_task_set_priority (task, io_priority);
6317   g_task_run_in_thread (task, copy_async_thread);
6318   g_object_unref (task);
6319 }
6320
6321 static gboolean
6322 g_file_real_copy_finish (GFile        *file,
6323                          GAsyncResult *res,
6324                          GError      **error)
6325 {
6326   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6327
6328   return g_task_propagate_boolean (G_TASK (res), error);
6329 }
6330
6331
6332 /********************************************
6333  *   Default VFS operations                 *
6334  ********************************************/
6335
6336 /**
6337  * g_file_new_for_path:
6338  * @path: (type filename): a string containing a relative or absolute path.
6339  *     The string must be encoded in the glib filename encoding.
6340  *
6341  * Constructs a #GFile for a given path. This operation never
6342  * fails, but the returned object might not support any I/O
6343  * operation if @path is malformed.
6344  *
6345  * Returns: (transfer full): a new #GFile for the given @path.
6346  *   Free the returned object with g_object_unref().
6347  */
6348 GFile *
6349 g_file_new_for_path (const char *path)
6350 {
6351   g_return_val_if_fail (path != NULL, NULL);
6352
6353   return g_vfs_get_file_for_path (g_vfs_get_default (), path);
6354 }
6355
6356 /**
6357  * g_file_new_for_uri:
6358  * @uri: a UTF-8 string containing a URI
6359  *
6360  * Constructs a #GFile for a given URI. This operation never
6361  * fails, but the returned object might not support any I/O
6362  * operation if @uri is malformed or if the uri type is
6363  * not supported.
6364  *
6365  * Returns: (transfer full): a new #GFile for the given @uri.
6366  *     Free the returned object with g_object_unref().
6367  */
6368 GFile *
6369 g_file_new_for_uri (const char *uri)
6370 {
6371   g_return_val_if_fail (uri != NULL, NULL);
6372
6373   return g_vfs_get_file_for_uri (g_vfs_get_default (), uri);
6374 }
6375
6376 /**
6377  * g_file_new_tmp:
6378  * @tmpl: (type filename) (allow-none): Template for the file
6379  *   name, as in g_file_open_tmp(), or %NULL for a default template
6380  * @iostream: (out): on return, a #GFileIOStream for the created file
6381  * @error: a #GError, or %NULL
6382  *
6383  * Opens a file in the preferred directory for temporary files (as
6384  * returned by g_get_tmp_dir()) and returns a #GFile and
6385  * #GFileIOStream pointing to it.
6386  *
6387  * @tmpl should be a string in the GLib file name encoding
6388  * containing a sequence of six 'X' characters, and containing no
6389  * directory components. If it is %NULL, a default template is used.
6390  *
6391  * Unlike the other #GFile constructors, this will return %NULL if
6392  * a temporary file could not be created.
6393  *
6394  * Returns: (transfer full): a new #GFile.
6395  *     Free the returned object with g_object_unref().
6396  *
6397  * Since: 2.32
6398  */
6399 GFile *
6400 g_file_new_tmp (const char     *tmpl,
6401                 GFileIOStream **iostream,
6402                 GError        **error)
6403 {
6404   gint fd;
6405   gchar *path;
6406   GFile *file;
6407   GFileOutputStream *output;
6408
6409   g_return_val_if_fail (iostream != NULL, NULL);
6410
6411   fd = g_file_open_tmp (tmpl, &path, error);
6412   if (fd == -1)
6413     return NULL;
6414
6415   file = g_file_new_for_path (path);
6416
6417   output = _g_local_file_output_stream_new (fd);
6418   *iostream = _g_local_file_io_stream_new (G_LOCAL_FILE_OUTPUT_STREAM (output));
6419
6420   g_object_unref (output);
6421   g_free (path);
6422
6423   return file;
6424 }
6425
6426 /**
6427  * g_file_parse_name:
6428  * @parse_name: a file name or path to be parsed
6429  *
6430  * Constructs a #GFile with the given @parse_name (i.e. something
6431  * given by g_file_get_parse_name()). This operation never fails,
6432  * but the returned object might not support any I/O operation if
6433  * the @parse_name cannot be parsed.
6434  *
6435  * Returns: (transfer full): a new #GFile.
6436  */
6437 GFile *
6438 g_file_parse_name (const char *parse_name)
6439 {
6440   g_return_val_if_fail (parse_name != NULL, NULL);
6441
6442   return g_vfs_parse_name (g_vfs_get_default (), parse_name);
6443 }
6444
6445 static gboolean
6446 is_valid_scheme_character (char c)
6447 {
6448   return g_ascii_isalnum (c) || c == '+' || c == '-' || c == '.';
6449 }
6450
6451 /* Following RFC 2396, valid schemes are built like:
6452  *       scheme        = alpha *( alpha | digit | "+" | "-" | "." )
6453  */
6454 static gboolean
6455 has_valid_scheme (const char *uri)
6456 {
6457   const char *p;
6458
6459   p = uri;
6460
6461   if (!g_ascii_isalpha (*p))
6462     return FALSE;
6463
6464   do {
6465     p++;
6466   } while (is_valid_scheme_character (*p));
6467
6468   return *p == ':';
6469 }
6470
6471 static GFile *
6472 new_for_cmdline_arg (const gchar *arg,
6473                      const gchar *cwd)
6474 {
6475   GFile *file;
6476   char *filename;
6477
6478   if (g_path_is_absolute (arg))
6479     return g_file_new_for_path (arg);
6480
6481   if (has_valid_scheme (arg))
6482     return g_file_new_for_uri (arg);
6483
6484   if (cwd == NULL)
6485     {
6486       char *current_dir;
6487
6488       current_dir = g_get_current_dir ();
6489       filename = g_build_filename (current_dir, arg, NULL);
6490       g_free (current_dir);
6491     }
6492   else
6493     filename = g_build_filename (cwd, arg, NULL);
6494
6495   file = g_file_new_for_path (filename);
6496   g_free (filename);
6497
6498   return file;
6499 }
6500
6501 /**
6502  * g_file_new_for_commandline_arg:
6503  * @arg: a command line string
6504  *
6505  * Creates a #GFile with the given argument from the command line.
6506  * The value of @arg can be either a URI, an absolute path or a
6507  * relative path resolved relative to the current working directory.
6508  * This operation never fails, but the returned object might not
6509  * support any I/O operation if @arg points to a malformed path.
6510  *
6511  * Note that on Windows, this function expects its argument to be in
6512  * UTF-8 -- not the system code page.  This means that you
6513  * should not use this function with string from argv as it is passed
6514  * to main().  g_win32_get_command_line() will return a UTF-8 version of
6515  * the commandline.  #GApplication also uses UTF-8 but
6516  * g_application_command_line_create_file_for_arg() may be more useful
6517  * for you there.  It is also always possible to use this function with
6518  * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
6519  *
6520  * Returns: (transfer full): a new #GFile.
6521  *    Free the returned object with g_object_unref().
6522  */
6523 GFile *
6524 g_file_new_for_commandline_arg (const char *arg)
6525 {
6526   g_return_val_if_fail (arg != NULL, NULL);
6527
6528   return new_for_cmdline_arg (arg, NULL);
6529 }
6530
6531 /**
6532  * g_file_new_for_commandline_arg_and_cwd:
6533  * @arg: a command line string
6534  * @cwd: (type filename): the current working directory of the commandline
6535  *
6536  * Creates a #GFile with the given argument from the command line.
6537  *
6538  * This function is similar to g_file_new_for_commandline_arg() except
6539  * that it allows for passing the current working directory as an
6540  * argument instead of using the current working directory of the
6541  * process.
6542  *
6543  * This is useful if the commandline argument was given in a context
6544  * other than the invocation of the current process.
6545  *
6546  * See also g_application_command_line_create_file_for_arg().
6547  *
6548  * Returns: (transfer full): a new #GFile
6549  *
6550  * Since: 2.36
6551  **/
6552 GFile *
6553 g_file_new_for_commandline_arg_and_cwd (const gchar *arg,
6554                                         const gchar *cwd)
6555 {
6556   g_return_val_if_fail (arg != NULL, NULL);
6557   g_return_val_if_fail (cwd != NULL, NULL);
6558
6559   return new_for_cmdline_arg (arg, cwd);
6560 }
6561
6562 /**
6563  * g_file_mount_enclosing_volume:
6564  * @location: input #GFile
6565  * @flags: flags affecting the operation
6566  * @mount_operation: (allow-none): a #GMountOperation
6567  *     or %NULL to avoid user interaction
6568  * @cancellable: (allow-none): optional #GCancellable object,
6569  *     %NULL to ignore
6570  * @callback: (allow-none): a #GAsyncReadyCallback to call
6571  *     when the request is satisfied, or %NULL
6572  * @user_data: the data to pass to callback function
6573  *
6574  * Starts a @mount_operation, mounting the volume that contains
6575  * the file @location.
6576  *
6577  * When this operation has completed, @callback will be called with
6578  * @user_user data, and the operation can be finalized with
6579  * g_file_mount_enclosing_volume_finish().
6580  *
6581  * If @cancellable is not %NULL, then the operation can be cancelled by
6582  * triggering the cancellable object from another thread. If the operation
6583  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6584  */
6585 void
6586 g_file_mount_enclosing_volume (GFile               *location,
6587                                GMountMountFlags     flags,
6588                                GMountOperation     *mount_operation,
6589                                GCancellable        *cancellable,
6590                                GAsyncReadyCallback  callback,
6591                                gpointer             user_data)
6592 {
6593   GFileIface *iface;
6594
6595   g_return_if_fail (G_IS_FILE (location));
6596
6597   iface = G_FILE_GET_IFACE (location);
6598
6599   if (iface->mount_enclosing_volume == NULL)
6600     {
6601       g_task_report_new_error (location, callback, user_data,
6602                                g_file_mount_enclosing_volume,
6603                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
6604                                _("volume doesn't implement mount"));
6605       return;
6606     }
6607
6608   (* iface->mount_enclosing_volume) (location, flags, mount_operation, cancellable, callback, user_data);
6609
6610 }
6611
6612 /**
6613  * g_file_mount_enclosing_volume_finish:
6614  * @location: input #GFile
6615  * @result: a #GAsyncResult
6616  * @error: a #GError, or %NULL
6617  *
6618  * Finishes a mount operation started by g_file_mount_enclosing_volume().
6619  *
6620  * Returns: %TRUE if successful. If an error has occurred,
6621  *     this function will return %FALSE and set @error
6622  *     appropriately if present.
6623  */
6624 gboolean
6625 g_file_mount_enclosing_volume_finish (GFile         *location,
6626                                       GAsyncResult  *result,
6627                                       GError       **error)
6628 {
6629   GFileIface *iface;
6630
6631   g_return_val_if_fail (G_IS_FILE (location), FALSE);
6632   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
6633
6634   if (g_async_result_legacy_propagate_error (result, error))
6635     return FALSE;
6636   else if (g_async_result_is_tagged (result, g_file_mount_enclosing_volume))
6637     return g_task_propagate_boolean (G_TASK (result), error);
6638
6639   iface = G_FILE_GET_IFACE (location);
6640
6641   return (* iface->mount_enclosing_volume_finish) (location, result, error);
6642 }
6643
6644 /********************************************
6645  *   Utility functions                      *
6646  ********************************************/
6647
6648 /**
6649  * g_file_query_default_handler:
6650  * @file: a #GFile to open
6651  * @cancellable: optional #GCancellable object, %NULL to ignore
6652  * @error: a #GError, or %NULL
6653  *
6654  * Returns the #GAppInfo that is registered as the default
6655  * application to handle the file specified by @file.
6656  *
6657  * If @cancellable is not %NULL, then the operation can be cancelled by
6658  * triggering the cancellable object from another thread. If the operation
6659  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6660  *
6661  * Returns: (transfer full): a #GAppInfo if the handle was found,
6662  *     %NULL if there were errors.
6663  *     When you are done with it, release it with g_object_unref()
6664  */
6665 GAppInfo *
6666 g_file_query_default_handler (GFile         *file,
6667                               GCancellable  *cancellable,
6668                               GError       **error)
6669 {
6670   char *uri_scheme;
6671   const char *content_type;
6672   GAppInfo *appinfo;
6673   GFileInfo *info;
6674   char *path;
6675
6676   uri_scheme = g_file_get_uri_scheme (file);
6677   if (uri_scheme && uri_scheme[0] != '\0')
6678     {
6679       appinfo = g_app_info_get_default_for_uri_scheme (uri_scheme);
6680       g_free (uri_scheme);
6681
6682       if (appinfo != NULL)
6683         return appinfo;
6684     }
6685
6686   info = g_file_query_info (file,
6687                             G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE,
6688                             0,
6689                             cancellable,
6690                             error);
6691   if (info == NULL)
6692     return NULL;
6693
6694   appinfo = NULL;
6695
6696   content_type = g_file_info_get_content_type (info);
6697   if (content_type)
6698     {
6699       /* Don't use is_native(), as we want to support fuse paths if available */
6700       path = g_file_get_path (file);
6701       appinfo = g_app_info_get_default_for_type (content_type,
6702                                                  path == NULL);
6703       g_free (path);
6704     }
6705
6706   g_object_unref (info);
6707
6708   if (appinfo != NULL)
6709     return appinfo;
6710
6711   g_set_error_literal (error, G_IO_ERROR,
6712                        G_IO_ERROR_NOT_SUPPORTED,
6713                        _("No application is registered as handling this file"));
6714   return NULL;
6715 }
6716
6717 #define GET_CONTENT_BLOCK_SIZE 8192
6718
6719 /**
6720  * g_file_load_contents:
6721  * @file: input #GFile
6722  * @cancellable: optional #GCancellable object, %NULL to ignore
6723  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
6724  * @length: (out) (allow-none): a location to place the length of the contents of the file,
6725  *    or %NULL if the length is not needed
6726  * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
6727  *    or %NULL if the entity tag is not needed
6728  * @error: a #GError, or %NULL
6729  *
6730  * Loads the content of the file into memory. The data is always
6731  * zero-terminated, but this is not included in the resultant @length.
6732  * The returned @content should be freed with g_free() when no longer
6733  * needed.
6734  *
6735  * If @cancellable is not %NULL, then the operation can be cancelled by
6736  * triggering the cancellable object from another thread. If the operation
6737  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6738  *
6739  * Returns: %TRUE if the @file's contents were successfully loaded.
6740  *     %FALSE if there were errors.
6741  */
6742 gboolean
6743 g_file_load_contents (GFile         *file,
6744                       GCancellable  *cancellable,
6745                       char         **contents,
6746                       gsize         *length,
6747                       char         **etag_out,
6748                       GError       **error)
6749 {
6750   GFileInputStream *in;
6751   GByteArray *content;
6752   gsize pos;
6753   gssize res;
6754   GFileInfo *info;
6755
6756   g_return_val_if_fail (G_IS_FILE (file), FALSE);
6757   g_return_val_if_fail (contents != NULL, FALSE);
6758
6759   in = g_file_read (file, cancellable, error);
6760   if (in == NULL)
6761     return FALSE;
6762
6763   content = g_byte_array_new ();
6764   pos = 0;
6765
6766   g_byte_array_set_size (content, pos + GET_CONTENT_BLOCK_SIZE + 1);
6767   while ((res = g_input_stream_read (G_INPUT_STREAM (in),
6768                                      content->data + pos,
6769                                      GET_CONTENT_BLOCK_SIZE,
6770                                      cancellable, error)) > 0)
6771     {
6772       pos += res;
6773       g_byte_array_set_size (content, pos + GET_CONTENT_BLOCK_SIZE + 1);
6774     }
6775
6776   if (etag_out)
6777     {
6778       *etag_out = NULL;
6779
6780       info = g_file_input_stream_query_info (in,
6781                                              G_FILE_ATTRIBUTE_ETAG_VALUE,
6782                                              cancellable,
6783                                              NULL);
6784       if (info)
6785         {
6786           *etag_out = g_strdup (g_file_info_get_etag (info));
6787           g_object_unref (info);
6788         }
6789     }
6790
6791   /* Ignore errors on close */
6792   g_input_stream_close (G_INPUT_STREAM (in), cancellable, NULL);
6793   g_object_unref (in);
6794
6795   if (res < 0)
6796     {
6797       /* error is set already */
6798       g_byte_array_free (content, TRUE);
6799       return FALSE;
6800     }
6801
6802   if (length)
6803     *length = pos;
6804
6805   /* Zero terminate (we got an extra byte allocated for this */
6806   content->data[pos] = 0;
6807
6808   *contents = (char *)g_byte_array_free (content, FALSE);
6809
6810   return TRUE;
6811 }
6812
6813 typedef struct {
6814   GTask *task;
6815   GFileReadMoreCallback read_more_callback;
6816   GByteArray *content;
6817   gsize pos;
6818   char *etag;
6819 } LoadContentsData;
6820
6821
6822 static void
6823 load_contents_data_free (LoadContentsData *data)
6824 {
6825   if (data->content)
6826     g_byte_array_free (data->content, TRUE);
6827   g_free (data->etag);
6828   g_free (data);
6829 }
6830
6831 static void
6832 load_contents_close_callback (GObject      *obj,
6833                               GAsyncResult *close_res,
6834                               gpointer      user_data)
6835 {
6836   GInputStream *stream = G_INPUT_STREAM (obj);
6837   LoadContentsData *data = user_data;
6838
6839   /* Ignore errors here, we're only reading anyway */
6840   g_input_stream_close_finish (stream, close_res, NULL);
6841   g_object_unref (stream);
6842
6843   g_task_return_boolean (data->task, TRUE);
6844   g_object_unref (data->task);
6845 }
6846
6847 static void
6848 load_contents_fstat_callback (GObject      *obj,
6849                               GAsyncResult *stat_res,
6850                               gpointer      user_data)
6851 {
6852   GInputStream *stream = G_INPUT_STREAM (obj);
6853   LoadContentsData *data = user_data;
6854   GFileInfo *info;
6855
6856   info = g_file_input_stream_query_info_finish (G_FILE_INPUT_STREAM (stream),
6857                                                 stat_res, NULL);
6858   if (info)
6859     {
6860       data->etag = g_strdup (g_file_info_get_etag (info));
6861       g_object_unref (info);
6862     }
6863
6864   g_input_stream_close_async (stream, 0,
6865                               g_task_get_cancellable (data->task),
6866                               load_contents_close_callback, data);
6867 }
6868
6869 static void
6870 load_contents_read_callback (GObject      *obj,
6871                              GAsyncResult *read_res,
6872                              gpointer      user_data)
6873 {
6874   GInputStream *stream = G_INPUT_STREAM (obj);
6875   LoadContentsData *data = user_data;
6876   GError *error = NULL;
6877   gssize read_size;
6878
6879   read_size = g_input_stream_read_finish (stream, read_res, &error);
6880
6881   if (read_size < 0)
6882     {
6883       g_task_return_error (data->task, error);
6884       g_object_unref (data->task);
6885
6886       /* Close the file ignoring any error */
6887       g_input_stream_close_async (stream, 0, NULL, NULL, NULL);
6888       g_object_unref (stream);
6889     }
6890   else if (read_size == 0)
6891     {
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     }
6899   else if (read_size > 0)
6900     {
6901       data->pos += read_size;
6902
6903       g_byte_array_set_size (data->content,
6904                              data->pos + GET_CONTENT_BLOCK_SIZE);
6905
6906
6907       if (data->read_more_callback &&
6908           !data->read_more_callback ((char *)data->content->data, data->pos,
6909                                      g_async_result_get_user_data (G_ASYNC_RESULT (data->task))))
6910         g_file_input_stream_query_info_async (G_FILE_INPUT_STREAM (stream),
6911                                               G_FILE_ATTRIBUTE_ETAG_VALUE,
6912                                               0,
6913                                               g_task_get_cancellable (data->task),
6914                                               load_contents_fstat_callback,
6915                                               data);
6916       else
6917         g_input_stream_read_async (stream,
6918                                    data->content->data + data->pos,
6919                                    GET_CONTENT_BLOCK_SIZE,
6920                                    0,
6921                                    g_task_get_cancellable (data->task),
6922                                    load_contents_read_callback,
6923                                    data);
6924     }
6925 }
6926
6927 static void
6928 load_contents_open_callback (GObject      *obj,
6929                              GAsyncResult *open_res,
6930                              gpointer      user_data)
6931 {
6932   GFile *file = G_FILE (obj);
6933   GFileInputStream *stream;
6934   LoadContentsData *data = user_data;
6935   GError *error = NULL;
6936
6937   stream = g_file_read_finish (file, open_res, &error);
6938
6939   if (stream)
6940     {
6941       g_byte_array_set_size (data->content,
6942                              data->pos + GET_CONTENT_BLOCK_SIZE);
6943       g_input_stream_read_async (G_INPUT_STREAM (stream),
6944                                  data->content->data + data->pos,
6945                                  GET_CONTENT_BLOCK_SIZE,
6946                                  0,
6947                                  g_task_get_cancellable (data->task),
6948                                  load_contents_read_callback,
6949                                  data);
6950     }
6951   else
6952     {
6953       g_task_return_error (data->task, error);
6954       g_object_unref (data->task);
6955     }
6956 }
6957
6958 /**
6959  * g_file_load_partial_contents_async: (skip)
6960  * @file: input #GFile
6961  * @cancellable: optional #GCancellable object, %NULL to ignore
6962  * @read_more_callback: a #GFileReadMoreCallback to receive partial data
6963  *     and to specify whether further data should be read
6964  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
6965  * @user_data: the data to pass to the callback functions
6966  *
6967  * Reads the partial contents of a file. A #GFileReadMoreCallback should
6968  * be used to stop reading from the file when appropriate, else this
6969  * function will behave exactly as g_file_load_contents_async(). This
6970  * operation can be finished by g_file_load_partial_contents_finish().
6971  *
6972  * Users of this function should be aware that @user_data is passed to
6973  * both the @read_more_callback and the @callback.
6974  *
6975  * If @cancellable is not %NULL, then the operation can be cancelled by
6976  * triggering the cancellable object from another thread. If the operation
6977  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6978  */
6979 void
6980 g_file_load_partial_contents_async (GFile                 *file,
6981                                     GCancellable          *cancellable,
6982                                     GFileReadMoreCallback  read_more_callback,
6983                                     GAsyncReadyCallback    callback,
6984                                     gpointer               user_data)
6985 {
6986   LoadContentsData *data;
6987
6988   g_return_if_fail (G_IS_FILE (file));
6989
6990   data = g_new0 (LoadContentsData, 1);
6991   data->read_more_callback = read_more_callback;
6992   data->content = g_byte_array_new ();
6993
6994   data->task = g_task_new (file, cancellable, callback, user_data);
6995   g_task_set_source_tag (data->task, g_file_load_partial_contents_async);
6996   g_task_set_task_data (data->task, data, (GDestroyNotify)load_contents_data_free);
6997
6998   g_file_read_async (file,
6999                      0,
7000                      g_task_get_cancellable (data->task),
7001                      load_contents_open_callback,
7002                      data);
7003 }
7004
7005 /**
7006  * g_file_load_partial_contents_finish:
7007  * @file: input #GFile
7008  * @res: a #GAsyncResult
7009  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
7010  * @length: (out) (allow-none): a location to place the length of the contents of the file,
7011  *     or %NULL if the length is not needed
7012  * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
7013  *     or %NULL if the entity tag is not needed
7014  * @error: a #GError, or %NULL
7015  *
7016  * Finishes an asynchronous partial load operation that was started
7017  * with g_file_load_partial_contents_async(). The data is always
7018  * zero-terminated, but this is not included in the resultant @length.
7019  * The returned @content should be freed with g_free() when no longer
7020  * needed.
7021  *
7022  * Returns: %TRUE if the load was successful. If %FALSE and @error is
7023  *     present, it will be set appropriately.
7024  */
7025 gboolean
7026 g_file_load_partial_contents_finish (GFile         *file,
7027                                      GAsyncResult  *res,
7028                                      char         **contents,
7029                                      gsize         *length,
7030                                      char         **etag_out,
7031                                      GError       **error)
7032 {
7033   GTask *task;
7034   LoadContentsData *data;
7035
7036   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7037   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
7038   g_return_val_if_fail (contents != NULL, FALSE);
7039
7040   task = G_TASK (res);
7041
7042   if (!g_task_propagate_boolean (task, error))
7043     {
7044       if (length)
7045         *length = 0;
7046       return FALSE;
7047     }
7048
7049   data = g_task_get_task_data (task);
7050
7051   if (length)
7052     *length = data->pos;
7053
7054   if (etag_out)
7055     {
7056       *etag_out = data->etag;
7057       data->etag = NULL;
7058     }
7059
7060   /* Zero terminate */
7061   g_byte_array_set_size (data->content, data->pos + 1);
7062   data->content->data[data->pos] = 0;
7063
7064   *contents = (char *)g_byte_array_free (data->content, FALSE);
7065   data->content = NULL;
7066
7067   return TRUE;
7068 }
7069
7070 /**
7071  * g_file_load_contents_async:
7072  * @file: input #GFile
7073  * @cancellable: optional #GCancellable object, %NULL to ignore
7074  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7075  * @user_data: the data to pass to callback function
7076  *
7077  * Starts an asynchronous load of the @file's contents.
7078  *
7079  * For more details, see g_file_load_contents() which is
7080  * the synchronous version of this call.
7081  *
7082  * When the load operation has completed, @callback will be called
7083  * with @user data. To finish the operation, call
7084  * g_file_load_contents_finish() with the #GAsyncResult returned by
7085  * the @callback.
7086  *
7087  * If @cancellable is not %NULL, then the operation can be cancelled by
7088  * triggering the cancellable object from another thread. If the operation
7089  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7090  */
7091 void
7092 g_file_load_contents_async (GFile               *file,
7093                            GCancellable        *cancellable,
7094                            GAsyncReadyCallback  callback,
7095                            gpointer             user_data)
7096 {
7097   g_file_load_partial_contents_async (file,
7098                                       cancellable,
7099                                       NULL,
7100                                       callback, user_data);
7101 }
7102
7103 /**
7104  * g_file_load_contents_finish:
7105  * @file: input #GFile
7106  * @res: a #GAsyncResult
7107  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
7108  * @length: (out) (allow-none): a location to place the length of the contents of the file,
7109  *     or %NULL if the length is not needed
7110  * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
7111  *     or %NULL if the entity tag is not needed
7112  * @error: a #GError, or %NULL
7113  *
7114  * Finishes an asynchronous load of the @file's contents.
7115  * The contents are placed in @contents, and @length is set to the
7116  * size of the @contents string. The @content should be freed with
7117  * g_free() when no longer needed. If @etag_out is present, it will be
7118  * set to the new entity tag for the @file.
7119  *
7120  * Returns: %TRUE if the load was successful. If %FALSE and @error is
7121  *     present, it will be set appropriately.
7122  */
7123 gboolean
7124 g_file_load_contents_finish (GFile         *file,
7125                              GAsyncResult  *res,
7126                              char         **contents,
7127                              gsize         *length,
7128                              char         **etag_out,
7129                              GError       **error)
7130 {
7131   return g_file_load_partial_contents_finish (file,
7132                                               res,
7133                                               contents,
7134                                               length,
7135                                               etag_out,
7136                                               error);
7137 }
7138
7139 /**
7140  * g_file_replace_contents:
7141  * @file: input #GFile
7142  * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
7143  * @length: the length of @contents in bytes
7144  * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document,
7145  *     or %NULL
7146  * @make_backup: %TRUE if a backup should be created
7147  * @flags: a set of #GFileCreateFlags
7148  * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag]
7149  *      for the document. This should be freed with g_free() when no longer
7150  *      needed, or %NULL
7151  * @cancellable: optional #GCancellable object, %NULL to ignore
7152  * @error: a #GError, or %NULL
7153  *
7154  * Replaces the contents of @file with @contents of @length bytes.
7155  *
7156  * If @etag is specified (not %NULL), any existing file must have that etag,
7157  * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
7158  *
7159  * If @make_backup is %TRUE, this function will attempt to make a backup
7160  * of @file. Internally, it uses g_file_replace(), so will try to replace the
7161  * file contents in the safest way possible. For example, atomic renames are
7162  * used when replacing local files’ contents.
7163  *
7164  * If @cancellable is not %NULL, then the operation can be cancelled by
7165  * triggering the cancellable object from another thread. If the operation
7166  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7167  *
7168  * The returned @new_etag can be used to verify that the file hasn't
7169  * changed the next time it is saved over.
7170  *
7171  * Returns: %TRUE if successful. If an error has occurred, this function
7172  *     will return %FALSE and set @error appropriately if present.
7173  */
7174 gboolean
7175 g_file_replace_contents (GFile             *file,
7176                          const char        *contents,
7177                          gsize              length,
7178                          const char        *etag,
7179                          gboolean           make_backup,
7180                          GFileCreateFlags   flags,
7181                          char             **new_etag,
7182                          GCancellable      *cancellable,
7183                          GError           **error)
7184 {
7185   GFileOutputStream *out;
7186   gsize pos, remainder;
7187   gssize res;
7188   gboolean ret;
7189
7190   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7191   g_return_val_if_fail (contents != NULL, FALSE);
7192
7193   out = g_file_replace (file, etag, make_backup, flags, cancellable, error);
7194   if (out == NULL)
7195     return FALSE;
7196
7197   pos = 0;
7198   remainder = length;
7199   while (remainder > 0 &&
7200          (res = g_output_stream_write (G_OUTPUT_STREAM (out),
7201                                        contents + pos,
7202                                        MIN (remainder, GET_CONTENT_BLOCK_SIZE),
7203                                        cancellable,
7204                                        error)) > 0)
7205     {
7206       pos += res;
7207       remainder -= res;
7208     }
7209
7210   if (remainder > 0 && res < 0)
7211     {
7212       /* Ignore errors on close */
7213       g_output_stream_close (G_OUTPUT_STREAM (out), cancellable, NULL);
7214       g_object_unref (out);
7215
7216       /* error is set already */
7217       return FALSE;
7218     }
7219
7220   ret = g_output_stream_close (G_OUTPUT_STREAM (out), cancellable, error);
7221
7222   if (new_etag)
7223     *new_etag = g_file_output_stream_get_etag (out);
7224
7225   g_object_unref (out);
7226
7227   return ret;
7228 }
7229
7230 typedef struct {
7231   GTask *task;
7232   GBytes *content;
7233   gsize pos;
7234   char *etag;
7235   gboolean failed;
7236 } ReplaceContentsData;
7237
7238 static void
7239 replace_contents_data_free (ReplaceContentsData *data)
7240 {
7241   g_bytes_unref (data->content);
7242   g_free (data->etag);
7243   g_free (data);
7244 }
7245
7246 static void
7247 replace_contents_close_callback (GObject      *obj,
7248                                  GAsyncResult *close_res,
7249                                  gpointer      user_data)
7250 {
7251   GOutputStream *stream = G_OUTPUT_STREAM (obj);
7252   ReplaceContentsData *data = user_data;
7253
7254   /* Ignore errors here, we're only reading anyway */
7255   g_output_stream_close_finish (stream, close_res, NULL);
7256   g_object_unref (stream);
7257
7258   if (!data->failed)
7259     {
7260       data->etag = g_file_output_stream_get_etag (G_FILE_OUTPUT_STREAM (stream));
7261       g_task_return_boolean (data->task, TRUE);
7262     }
7263   g_object_unref (data->task);
7264 }
7265
7266 static void
7267 replace_contents_write_callback (GObject      *obj,
7268                                  GAsyncResult *read_res,
7269                                  gpointer      user_data)
7270 {
7271   GOutputStream *stream = G_OUTPUT_STREAM (obj);
7272   ReplaceContentsData *data = user_data;
7273   GError *error = NULL;
7274   gssize write_size;
7275
7276   write_size = g_output_stream_write_finish (stream, read_res, &error);
7277
7278   if (write_size <= 0)
7279     {
7280       /* Error or EOF, close the file */
7281       if (write_size < 0)
7282         {
7283           data->failed = TRUE;
7284           g_task_return_error (data->task, error);
7285         }
7286       g_output_stream_close_async (stream, 0,
7287                                    g_task_get_cancellable (data->task),
7288                                    replace_contents_close_callback, data);
7289     }
7290   else if (write_size > 0)
7291     {
7292       const gchar *content;
7293       gsize length;
7294
7295       content = g_bytes_get_data (data->content, &length);
7296       data->pos += write_size;
7297
7298       if (data->pos >= length)
7299         g_output_stream_close_async (stream, 0,
7300                                      g_task_get_cancellable (data->task),
7301                                      replace_contents_close_callback, data);
7302       else
7303         g_output_stream_write_async (stream,
7304                                      content + data->pos,
7305                                      length - data->pos,
7306                                      0,
7307                                      g_task_get_cancellable (data->task),
7308                                      replace_contents_write_callback,
7309                                      data);
7310     }
7311 }
7312
7313 static void
7314 replace_contents_open_callback (GObject      *obj,
7315                                 GAsyncResult *open_res,
7316                                 gpointer      user_data)
7317 {
7318   GFile *file = G_FILE (obj);
7319   GFileOutputStream *stream;
7320   ReplaceContentsData *data = user_data;
7321   GError *error = NULL;
7322
7323   stream = g_file_replace_finish (file, open_res, &error);
7324
7325   if (stream)
7326     {
7327       const gchar *content;
7328       gsize length;
7329
7330       content = g_bytes_get_data (data->content, &length);
7331       g_output_stream_write_async (G_OUTPUT_STREAM (stream),
7332                                    content + data->pos,
7333                                    length - data->pos,
7334                                    0,
7335                                    g_task_get_cancellable (data->task),
7336                                    replace_contents_write_callback,
7337                                    data);
7338     }
7339   else
7340     {
7341       g_task_return_error (data->task, error);
7342       g_object_unref (data->task);
7343     }
7344 }
7345
7346 /**
7347  * g_file_replace_contents_async:
7348  * @file: input #GFile
7349  * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
7350  * @length: the length of @contents in bytes
7351  * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
7352  * @make_backup: %TRUE if a backup should be created
7353  * @flags: a set of #GFileCreateFlags
7354  * @cancellable: optional #GCancellable object, %NULL to ignore
7355  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7356  * @user_data: the data to pass to callback function
7357  *
7358  * Starts an asynchronous replacement of @file with the given
7359  * @contents of @length bytes. @etag will replace the document's
7360  * current entity tag.
7361  *
7362  * When this operation has completed, @callback will be called with
7363  * @user_user data, and the operation can be finalized with
7364  * g_file_replace_contents_finish().
7365  *
7366  * If @cancellable is not %NULL, then the operation can be cancelled by
7367  * triggering the cancellable object from another thread. If the operation
7368  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7369  *
7370  * If @make_backup is %TRUE, this function will attempt to
7371  * make a backup of @file.
7372  *
7373  * Note that no copy of @content will be made, so it must stay valid
7374  * until @callback is called. See g_file_replace_contents_bytes_async()
7375  * for a #GBytes version that will automatically hold a reference to the
7376  * contents (without copying) for the duration of the call.
7377  */
7378 void
7379 g_file_replace_contents_async  (GFile               *file,
7380                                 const char          *contents,
7381                                 gsize                length,
7382                                 const char          *etag,
7383                                 gboolean             make_backup,
7384                                 GFileCreateFlags     flags,
7385                                 GCancellable        *cancellable,
7386                                 GAsyncReadyCallback  callback,
7387                                 gpointer             user_data)
7388 {
7389   GBytes *bytes;
7390
7391   bytes = g_bytes_new_static (contents, length);
7392   g_file_replace_contents_bytes_async (file, bytes, etag, make_backup, flags,
7393       cancellable, callback, user_data);
7394   g_bytes_unref (bytes);
7395 }
7396
7397 /**
7398  * g_file_replace_contents_bytes_async:
7399  * @file: input #GFile
7400  * @contents: a #GBytes
7401  * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
7402  * @make_backup: %TRUE if a backup should be created
7403  * @flags: a set of #GFileCreateFlags
7404  * @cancellable: optional #GCancellable object, %NULL to ignore
7405  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7406  * @user_data: the data to pass to callback function
7407  *
7408  * Same as g_file_replace_contents_async() but takes a #GBytes input instead.
7409  * This function will keep a ref on @contents until the operation is done.
7410  * Unlike g_file_replace_contents_async() this allows forgetting about the
7411  * content without waiting for the callback.
7412  *
7413  * When this operation has completed, @callback will be called with
7414  * @user_user data, and the operation can be finalized with
7415  * g_file_replace_contents_finish().
7416  *
7417  * Since: 2.40
7418  */
7419 void
7420 g_file_replace_contents_bytes_async  (GFile               *file,
7421                                       GBytes              *contents,
7422                                       const char          *etag,
7423                                       gboolean             make_backup,
7424                                       GFileCreateFlags     flags,
7425                                       GCancellable        *cancellable,
7426                                       GAsyncReadyCallback  callback,
7427                                       gpointer             user_data)
7428 {
7429   ReplaceContentsData *data;
7430
7431   g_return_if_fail (G_IS_FILE (file));
7432   g_return_if_fail (contents != NULL);
7433
7434   data = g_new0 (ReplaceContentsData, 1);
7435
7436   data->content = g_bytes_ref (contents);
7437
7438   data->task = g_task_new (file, cancellable, callback, user_data);
7439   g_task_set_source_tag (data->task, g_file_replace_contents_bytes_async);
7440   g_task_set_task_data (data->task, data, (GDestroyNotify)replace_contents_data_free);
7441
7442   g_file_replace_async (file,
7443                         etag,
7444                         make_backup,
7445                         flags,
7446                         0,
7447                         g_task_get_cancellable (data->task),
7448                         replace_contents_open_callback,
7449                         data);
7450 }
7451
7452 /**
7453  * g_file_replace_contents_finish:
7454  * @file: input #GFile
7455  * @res: a #GAsyncResult
7456  * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag]
7457  *     for the document. This should be freed with g_free() when it is no
7458  *     longer needed, or %NULL
7459  * @error: a #GError, or %NULL
7460  *
7461  * Finishes an asynchronous replace of the given @file. See
7462  * g_file_replace_contents_async(). Sets @new_etag to the new entity
7463  * tag for the document, if present.
7464  *
7465  * Returns: %TRUE on success, %FALSE on failure.
7466  */
7467 gboolean
7468 g_file_replace_contents_finish (GFile         *file,
7469                                 GAsyncResult  *res,
7470                                 char         **new_etag,
7471                                 GError       **error)
7472 {
7473   GTask *task;
7474   ReplaceContentsData *data;
7475
7476   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7477   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
7478
7479   task = G_TASK (res);
7480
7481   if (!g_task_propagate_boolean (task, error))
7482     return FALSE;
7483
7484   data = g_task_get_task_data (task);
7485
7486   if (new_etag)
7487     {
7488       *new_etag = data->etag;
7489       data->etag = NULL; /* Take ownership */
7490     }
7491
7492   return TRUE;
7493 }
7494
7495 gboolean
7496 g_file_real_measure_disk_usage (GFile                         *file,
7497                                 GFileMeasureFlags              flags,
7498                                 GCancellable                  *cancellable,
7499                                 GFileMeasureProgressCallback   progress_callback,
7500                                 gpointer                       progress_data,
7501                                 guint64                       *disk_usage,
7502                                 guint64                       *num_dirs,
7503                                 guint64                       *num_files,
7504                                 GError                       **error)
7505 {
7506   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7507                        "Operation not supported for the current backend.");
7508   return FALSE;
7509 }
7510
7511 typedef struct
7512 {
7513   GFileMeasureFlags             flags;
7514   GFileMeasureProgressCallback  progress_callback;
7515   gpointer                      progress_data;
7516 } MeasureTaskData;
7517
7518 typedef struct
7519 {
7520   guint64 disk_usage;
7521   guint64 num_dirs;
7522   guint64 num_files;
7523 } MeasureResult;
7524
7525 typedef struct
7526 {
7527   GFileMeasureProgressCallback callback;
7528   gpointer                     user_data;
7529   gboolean                     reporting;
7530   guint64                      current_size;
7531   guint64                      num_dirs;
7532   guint64                      num_files;
7533 } MeasureProgress;
7534
7535 static gboolean
7536 measure_disk_usage_invoke_progress (gpointer user_data)
7537 {
7538   MeasureProgress *progress = user_data;
7539
7540   (* progress->callback) (progress->reporting,
7541                           progress->current_size, progress->num_dirs, progress->num_files,
7542                           progress->user_data);
7543
7544   return FALSE;
7545 }
7546
7547 static void
7548 measure_disk_usage_progress (gboolean reporting,
7549                              guint64  current_size,
7550                              guint64  num_dirs,
7551                              guint64  num_files,
7552                              gpointer user_data)
7553 {
7554   MeasureProgress progress;
7555   GTask *task = user_data;
7556   MeasureTaskData *data;
7557
7558   data = g_task_get_task_data (task);
7559
7560   progress.callback = data->progress_callback;
7561   progress.user_data = data->progress_data;
7562   progress.reporting = reporting;
7563   progress.current_size = current_size;
7564   progress.num_dirs = num_dirs;
7565   progress.num_files = num_files;
7566
7567   g_main_context_invoke_full (g_task_get_context (task),
7568                               g_task_get_priority (task),
7569                               measure_disk_usage_invoke_progress,
7570                               g_memdup (&progress, sizeof progress),
7571                               g_free);
7572 }
7573
7574 static void
7575 measure_disk_usage_thread (GTask        *task,
7576                            gpointer      source_object,
7577                            gpointer      task_data,
7578                            GCancellable *cancellable)
7579 {
7580   MeasureTaskData *data = task_data;
7581   GError *error = NULL;
7582   MeasureResult result = { 0, };
7583
7584   if (g_file_measure_disk_usage (source_object, data->flags, cancellable,
7585                                  data->progress_callback ? measure_disk_usage_progress : NULL, task,
7586                                  &result.disk_usage, &result.num_dirs, &result.num_files,
7587                                  &error))
7588     g_task_return_pointer (task, g_memdup (&result, sizeof result), g_free);
7589   else
7590     g_task_return_error (task, error);
7591 }
7592
7593 static void
7594 g_file_real_measure_disk_usage_async (GFile                        *file,
7595                                       GFileMeasureFlags             flags,
7596                                       gint                          io_priority,
7597                                       GCancellable                 *cancellable,
7598                                       GFileMeasureProgressCallback  progress_callback,
7599                                       gpointer                      progress_data,
7600                                       GAsyncReadyCallback           callback,
7601                                       gpointer                      user_data)
7602 {
7603   MeasureTaskData data;
7604   GTask *task;
7605
7606   data.flags = flags;
7607   data.progress_callback = progress_callback;
7608   data.progress_data = progress_data;
7609
7610   task = g_task_new (file, cancellable, callback, user_data);
7611   g_task_set_source_tag (task, g_file_real_measure_disk_usage_async);
7612   g_task_set_task_data (task, g_memdup (&data, sizeof data), g_free);
7613   g_task_set_priority (task, io_priority);
7614
7615   g_task_run_in_thread (task, measure_disk_usage_thread);
7616   g_object_unref (task);
7617 }
7618
7619 static gboolean
7620 g_file_real_measure_disk_usage_finish (GFile         *file,
7621                                        GAsyncResult  *result,
7622                                        guint64       *disk_usage,
7623                                        guint64       *num_dirs,
7624                                        guint64       *num_files,
7625                                        GError       **error)
7626 {
7627   MeasureResult *measure_result;
7628
7629   g_return_val_if_fail (g_task_is_valid (result, file), FALSE);
7630
7631   measure_result = g_task_propagate_pointer (G_TASK (result), error);
7632
7633   if (measure_result == NULL)
7634     return FALSE;
7635
7636   if (disk_usage)
7637     *disk_usage = measure_result->disk_usage;
7638
7639   if (num_dirs)
7640     *num_dirs = measure_result->num_dirs;
7641
7642   if (num_files)
7643     *num_files = measure_result->num_files;
7644
7645   g_free (measure_result);
7646
7647   return TRUE;
7648 }
7649
7650 /**
7651  * g_file_measure_disk_usage:
7652  * @file: a #GFile
7653  * @flags: #GFileMeasureFlags
7654  * @cancellable: (allow-none): optional #GCancellable
7655  * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
7656  * @progress_data: user_data for @progress_callback
7657  * @disk_usage: (allow-none) (out): the number of bytes of disk space used
7658  * @num_dirs: (allow-none) (out): the number of directories encountered
7659  * @num_files: (allow-none) (out): the number of non-directories encountered
7660  * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
7661  *
7662  * Recursively measures the disk usage of @file.
7663  *
7664  * This is essentially an analog of the 'du' command, but it also
7665  * reports the number of directories and non-directory files encountered
7666  * (including things like symbolic links).
7667  *
7668  * By default, errors are only reported against the toplevel file
7669  * itself.  Errors found while recursing are silently ignored, unless
7670  * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
7671  *
7672  * The returned size, @disk_usage, is in bytes and should be formatted
7673  * with g_format_size() in order to get something reasonable for showing
7674  * in a user interface.
7675  *
7676  * @progress_callback and @progress_data can be given to request
7677  * periodic progress updates while scanning.  See the documentation for
7678  * #GFileMeasureProgressCallback for information about when and how the
7679  * callback will be invoked.
7680  *
7681  * Returns: %TRUE if successful, with the out parameters set.
7682  *          %FALSE otherwise, with @error set.
7683  *
7684  * Since: 2.38
7685  **/
7686 gboolean
7687 g_file_measure_disk_usage (GFile                         *file,
7688                            GFileMeasureFlags              flags,
7689                            GCancellable                  *cancellable,
7690                            GFileMeasureProgressCallback   progress_callback,
7691                            gpointer                       progress_data,
7692                            guint64                       *disk_usage,
7693                            guint64                       *num_dirs,
7694                            guint64                       *num_files,
7695                            GError                       **error)
7696 {
7697   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7698   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
7699   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
7700
7701   return G_FILE_GET_IFACE (file)->measure_disk_usage (file, flags, cancellable,
7702                                                       progress_callback, progress_data,
7703                                                       disk_usage, num_dirs, num_files,
7704                                                       error);
7705 }
7706
7707 /**
7708  * g_file_measure_disk_usage_async:
7709  * @file: a #GFile
7710  * @flags: #GFileMeasureFlags
7711  * @io_priority: the [I/O priority][io-priority] of the request
7712  * @cancellable: (allow-none): optional #GCancellable
7713  * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
7714  * @progress_data: user_data for @progress_callback
7715  * @callback: (allow-none): a #GAsyncReadyCallback to call when complete
7716  * @user_data: the data to pass to callback function
7717  *
7718  * Recursively measures the disk usage of @file.
7719  *
7720  * This is the asynchronous version of g_file_measure_disk_usage().  See
7721  * there for more information.
7722  *
7723  * Since: 2.38
7724  **/
7725 void
7726 g_file_measure_disk_usage_async (GFile                        *file,
7727                                  GFileMeasureFlags             flags,
7728                                  gint                          io_priority,
7729                                  GCancellable                 *cancellable,
7730                                  GFileMeasureProgressCallback  progress_callback,
7731                                  gpointer                      progress_data,
7732                                  GAsyncReadyCallback           callback,
7733                                  gpointer                      user_data)
7734 {
7735   g_return_if_fail (G_IS_FILE (file));
7736   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
7737
7738   G_FILE_GET_IFACE (file)->measure_disk_usage_async (file, flags, io_priority, cancellable,
7739                                                      progress_callback, progress_data,
7740                                                      callback, user_data);
7741 }
7742
7743 /**
7744  * g_file_measure_disk_usage_finish:
7745  * @file: a #GFile
7746  * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
7747  * @disk_usage: (allow-none) (out): the number of bytes of disk space used
7748  * @num_dirs: (allow-none) (out): the number of directories encountered
7749  * @num_files: (allow-none) (out): the number of non-directories encountered
7750  * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
7751  *
7752  * Collects the results from an earlier call to
7753  * g_file_measure_disk_usage_async().  See g_file_measure_disk_usage() for
7754  * more information.
7755  *
7756  * Returns: %TRUE if successful, with the out parameters set.
7757  *          %FALSE otherwise, with @error set.
7758  *
7759  * Since: 2.38
7760  **/
7761 gboolean
7762 g_file_measure_disk_usage_finish (GFile         *file,
7763                                   GAsyncResult  *result,
7764                                   guint64       *disk_usage,
7765                                   guint64       *num_dirs,
7766                                   guint64       *num_files,
7767                                   GError       **error)
7768 {
7769   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7770   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
7771
7772   return G_FILE_GET_IFACE (file)->measure_disk_usage_finish (file, result, disk_usage, num_dirs, num_files, error);
7773 }
7774
7775 /**
7776  * g_file_start_mountable:
7777  * @file: input #GFile
7778  * @flags: flags affecting the operation
7779  * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
7780  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
7781  * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
7782  * @user_data: the data to pass to callback function
7783  *
7784  * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
7785  * Using @start_operation, you can request callbacks when, for instance,
7786  * passwords are needed during authentication.
7787  *
7788  * If @cancellable is not %NULL, then the operation can be cancelled by
7789  * triggering the cancellable object from another thread. If the operation
7790  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7791  *
7792  * When the operation is finished, @callback will be called.
7793  * You can then call g_file_mount_mountable_finish() to get
7794  * the result of the operation.
7795  *
7796  * Since: 2.22
7797  */
7798 void
7799 g_file_start_mountable (GFile               *file,
7800                         GDriveStartFlags     flags,
7801                         GMountOperation     *start_operation,
7802                         GCancellable        *cancellable,
7803                         GAsyncReadyCallback  callback,
7804                         gpointer             user_data)
7805 {
7806   GFileIface *iface;
7807
7808   g_return_if_fail (G_IS_FILE (file));
7809
7810   iface = G_FILE_GET_IFACE (file);
7811
7812   if (iface->start_mountable == NULL)
7813     {
7814       g_task_report_new_error (file, callback, user_data,
7815                                g_file_start_mountable,
7816                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7817                                _("Operation not supported"));
7818       return;
7819     }
7820
7821   (* iface->start_mountable) (file,
7822                               flags,
7823                               start_operation,
7824                               cancellable,
7825                               callback,
7826                               user_data);
7827 }
7828
7829 /**
7830  * g_file_start_mountable_finish:
7831  * @file: input #GFile
7832  * @result: a #GAsyncResult
7833  * @error: a #GError, or %NULL
7834  *
7835  * Finishes a start operation. See g_file_start_mountable() for details.
7836  *
7837  * Finish an asynchronous start operation that was started
7838  * with g_file_start_mountable().
7839  *
7840  * Returns: %TRUE if the operation finished successfully. %FALSE
7841  * otherwise.
7842  *
7843  * Since: 2.22
7844  */
7845 gboolean
7846 g_file_start_mountable_finish (GFile         *file,
7847                                GAsyncResult  *result,
7848                                GError       **error)
7849 {
7850   GFileIface *iface;
7851
7852   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7853   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
7854
7855   if (g_async_result_legacy_propagate_error (result, error))
7856     return FALSE;
7857   else if (g_async_result_is_tagged (result, g_file_start_mountable))
7858     return g_task_propagate_boolean (G_TASK (result), error);
7859
7860   iface = G_FILE_GET_IFACE (file);
7861   return (* iface->start_mountable_finish) (file, result, error);
7862 }
7863
7864 /**
7865  * g_file_stop_mountable:
7866  * @file: input #GFile
7867  * @flags: flags affecting the operation
7868  * @mount_operation: (allow-none): a #GMountOperation,
7869  *     or %NULL to avoid user interaction.
7870  * @cancellable: (allow-none): optional #GCancellable object,
7871  *     %NULL to ignore
7872  * @callback: (allow-none): a #GAsyncReadyCallback to call
7873  *     when the request is satisfied, or %NULL
7874  * @user_data: the data to pass to callback function
7875  *
7876  * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
7877  *
7878  * If @cancellable is not %NULL, then the operation can be cancelled by
7879  * triggering the cancellable object from another thread. If the operation
7880  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7881  *
7882  * When the operation is finished, @callback will be called.
7883  * You can then call g_file_stop_mountable_finish() to get
7884  * the result of the operation.
7885  *
7886  * Since: 2.22
7887  */
7888 void
7889 g_file_stop_mountable (GFile               *file,
7890                        GMountUnmountFlags   flags,
7891                        GMountOperation     *mount_operation,
7892                        GCancellable        *cancellable,
7893                        GAsyncReadyCallback  callback,
7894                        gpointer             user_data)
7895 {
7896   GFileIface *iface;
7897
7898   g_return_if_fail (G_IS_FILE (file));
7899
7900   iface = G_FILE_GET_IFACE (file);
7901
7902   if (iface->stop_mountable == NULL)
7903     {
7904       g_task_report_new_error (file, callback, user_data,
7905                                g_file_stop_mountable,
7906                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7907                                _("Operation not supported"));
7908       return;
7909     }
7910
7911   (* iface->stop_mountable) (file,
7912                              flags,
7913                              mount_operation,
7914                              cancellable,
7915                              callback,
7916                              user_data);
7917 }
7918
7919 /**
7920  * g_file_stop_mountable_finish:
7921  * @file: input #GFile
7922  * @result: a #GAsyncResult
7923  * @error: a #GError, or %NULL
7924  *
7925  * Finishes an stop operation, see g_file_stop_mountable() for details.
7926  *
7927  * Finish an asynchronous stop operation that was started
7928  * with g_file_stop_mountable().
7929  *
7930  * Returns: %TRUE if the operation finished successfully.
7931  *     %FALSE otherwise.
7932  *
7933  * Since: 2.22
7934  */
7935 gboolean
7936 g_file_stop_mountable_finish (GFile         *file,
7937                               GAsyncResult  *result,
7938                               GError       **error)
7939 {
7940   GFileIface *iface;
7941
7942   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7943   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
7944
7945   if (g_async_result_legacy_propagate_error (result, error))
7946     return FALSE;
7947   else if (g_async_result_is_tagged (result, g_file_stop_mountable))
7948     return g_task_propagate_boolean (G_TASK (result), error);
7949
7950   iface = G_FILE_GET_IFACE (file);
7951   return (* iface->stop_mountable_finish) (file, result, error);
7952 }
7953
7954 /**
7955  * g_file_poll_mountable:
7956  * @file: input #GFile
7957  * @cancellable: optional #GCancellable object, %NULL to ignore
7958  * @callback: (allow-none): a #GAsyncReadyCallback to call
7959  *     when the request is satisfied, or %NULL
7960  * @user_data: the data to pass to callback function
7961  *
7962  * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
7963  *
7964  * If @cancellable is not %NULL, then the operation can be cancelled by
7965  * triggering the cancellable object from another thread. If the operation
7966  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7967  *
7968  * When the operation is finished, @callback will be called.
7969  * You can then call g_file_mount_mountable_finish() to get
7970  * the result of the operation.
7971  *
7972  * Since: 2.22
7973  */
7974 void
7975 g_file_poll_mountable (GFile               *file,
7976                        GCancellable        *cancellable,
7977                        GAsyncReadyCallback  callback,
7978                        gpointer             user_data)
7979 {
7980   GFileIface *iface;
7981
7982   g_return_if_fail (G_IS_FILE (file));
7983
7984   iface = G_FILE_GET_IFACE (file);
7985
7986   if (iface->poll_mountable == NULL)
7987     {
7988       g_task_report_new_error (file, callback, user_data,
7989                                g_file_poll_mountable,
7990                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7991                                _("Operation not supported"));
7992       return;
7993     }
7994
7995   (* iface->poll_mountable) (file,
7996                              cancellable,
7997                              callback,
7998                              user_data);
7999 }
8000
8001 /**
8002  * g_file_poll_mountable_finish:
8003  * @file: input #GFile
8004  * @result: a #GAsyncResult
8005  * @error: a #GError, or %NULL
8006  *
8007  * Finishes a poll operation. See g_file_poll_mountable() for details.
8008  *
8009  * Finish an asynchronous poll operation that was polled
8010  * with g_file_poll_mountable().
8011  *
8012  * Returns: %TRUE if the operation finished successfully. %FALSE
8013  * otherwise.
8014  *
8015  * Since: 2.22
8016  */
8017 gboolean
8018 g_file_poll_mountable_finish (GFile         *file,
8019                               GAsyncResult  *result,
8020                               GError       **error)
8021 {
8022   GFileIface *iface;
8023
8024   g_return_val_if_fail (G_IS_FILE (file), FALSE);
8025   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
8026
8027   if (g_async_result_legacy_propagate_error (result, error))
8028     return FALSE;
8029   else if (g_async_result_is_tagged (result, g_file_poll_mountable))
8030     return g_task_propagate_boolean (G_TASK (result), error);
8031
8032   iface = G_FILE_GET_IFACE (file);
8033   return (* iface->poll_mountable_finish) (file, result, error);
8034 }
8035
8036 /**
8037  * g_file_supports_thread_contexts:
8038  * @file: a #GFile
8039  *
8040  * Checks if @file supports
8041  * [thread-default contexts][g-main-context-push-thread-default-context].
8042  * If this returns %FALSE, you cannot perform asynchronous operations on
8043  * @file in a thread that has a thread-default context.
8044  *
8045  * Returns: Whether or not @file supports thread-default contexts.
8046  *
8047  * Since: 2.22
8048  */
8049 gboolean
8050 g_file_supports_thread_contexts (GFile *file)
8051 {
8052  GFileIface *iface;
8053
8054  g_return_val_if_fail (G_IS_FILE (file), FALSE);
8055
8056  iface = G_FILE_GET_IFACE (file);
8057  return iface->supports_thread_contexts;
8058 }