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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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: (nullable): 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 /* 256k minus malloc overhead */
2769 #define STREAM_BUFFER_SIZE (1024*256 - 2 *sizeof(gpointer))
2770
2771 static gboolean
2772 copy_stream_with_progress (GInputStream           *in,
2773                            GOutputStream          *out,
2774                            GFile                  *source,
2775                            GCancellable           *cancellable,
2776                            GFileProgressCallback   progress_callback,
2777                            gpointer                progress_callback_data,
2778                            GError                **error)
2779 {
2780   gssize n_read, n_written;
2781   goffset current_size;
2782   char *buffer, *p;
2783   gboolean res;
2784   goffset total_size;
2785   GFileInfo *info;
2786
2787   total_size = -1;
2788   /* avoid performance impact of querying total size when it's not needed */
2789   if (progress_callback)
2790     {
2791       info = g_file_input_stream_query_info (G_FILE_INPUT_STREAM (in),
2792                                              G_FILE_ATTRIBUTE_STANDARD_SIZE,
2793                                              cancellable, NULL);
2794       if (info)
2795         {
2796           if (g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_STANDARD_SIZE))
2797             total_size = g_file_info_get_size (info);
2798           g_object_unref (info);
2799         }
2800
2801       if (total_size == -1)
2802         {
2803           info = g_file_query_info (source,
2804                                     G_FILE_ATTRIBUTE_STANDARD_SIZE,
2805                                     G_FILE_QUERY_INFO_NONE,
2806                                     cancellable, NULL);
2807           if (info)
2808             {
2809               if (g_file_info_has_attribute (info, G_FILE_ATTRIBUTE_STANDARD_SIZE))
2810                 total_size = g_file_info_get_size (info);
2811               g_object_unref (info);
2812             }
2813         }
2814     }
2815
2816   if (total_size == -1)
2817     total_size = 0;
2818
2819   buffer = g_malloc0 (STREAM_BUFFER_SIZE);
2820   current_size = 0;
2821   res = TRUE;
2822   while (TRUE)
2823     {
2824       n_read = g_input_stream_read (in, buffer, STREAM_BUFFER_SIZE, cancellable, error);
2825       if (n_read == -1)
2826         {
2827           res = FALSE;
2828           break;
2829         }
2830
2831       if (n_read == 0)
2832         break;
2833
2834       current_size += n_read;
2835
2836       p = buffer;
2837       while (n_read > 0)
2838         {
2839           n_written = g_output_stream_write (out, p, n_read, cancellable, error);
2840           if (n_written == -1)
2841             {
2842               res = FALSE;
2843               break;
2844             }
2845
2846           p += n_written;
2847           n_read -= n_written;
2848         }
2849
2850       if (!res)
2851         break;
2852
2853       if (progress_callback)
2854         progress_callback (current_size, total_size, progress_callback_data);
2855     }
2856   g_free (buffer);
2857
2858   /* Make sure we send full copied size */
2859   if (progress_callback)
2860     progress_callback (current_size, total_size, progress_callback_data);
2861
2862   return res;
2863 }
2864
2865 #ifdef HAVE_SPLICE
2866
2867 static gboolean
2868 do_splice (int     fd_in,
2869            loff_t *off_in,
2870            int     fd_out,
2871            loff_t *off_out,
2872            size_t  len,
2873            long   *bytes_transferd,
2874            GError **error)
2875 {
2876   long result;
2877
2878 retry:
2879   result = splice (fd_in, off_in, fd_out, off_out, len, SPLICE_F_MORE);
2880
2881   if (result == -1)
2882     {
2883       int errsv = errno;
2884
2885       if (errsv == EINTR)
2886         goto retry;
2887       else if (errsv == ENOSYS || errsv == EINVAL)
2888         g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
2889                              _("Splice not supported"));
2890       else
2891         g_set_error (error, G_IO_ERROR,
2892                      g_io_error_from_errno (errsv),
2893                      _("Error splicing file: %s"),
2894                      g_strerror (errsv));
2895
2896       return FALSE;
2897     }
2898
2899   *bytes_transferd = result;
2900   return TRUE;
2901 }
2902
2903 static gboolean
2904 splice_stream_with_progress (GInputStream           *in,
2905                              GOutputStream          *out,
2906                              GCancellable           *cancellable,
2907                              GFileProgressCallback   progress_callback,
2908                              gpointer                progress_callback_data,
2909                              GError                **error)
2910 {
2911   int buffer[2] = { -1, -1 };
2912   gboolean res;
2913   goffset total_size;
2914   loff_t offset_in;
2915   loff_t offset_out;
2916   int fd_in, fd_out;
2917
2918   fd_in = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (in));
2919   fd_out = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (out));
2920
2921   if (!g_unix_open_pipe (buffer, FD_CLOEXEC, error))
2922     return FALSE;
2923
2924   total_size = -1;
2925   /* avoid performance impact of querying total size when it's not needed */
2926   if (progress_callback)
2927     {
2928       struct stat sbuf;
2929
2930       if (fstat (fd_in, &sbuf) == 0)
2931         total_size = sbuf.st_size;
2932     }
2933
2934   if (total_size == -1)
2935     total_size = 0;
2936
2937   offset_in = offset_out = 0;
2938   res = FALSE;
2939   while (TRUE)
2940     {
2941       long n_read;
2942       long n_written;
2943
2944       if (g_cancellable_set_error_if_cancelled (cancellable, error))
2945         break;
2946
2947       if (!do_splice (fd_in, &offset_in, buffer[1], NULL, 1024*64, &n_read, error))
2948         break;
2949
2950       if (n_read == 0)
2951         {
2952           res = TRUE;
2953           break;
2954         }
2955
2956       while (n_read > 0)
2957         {
2958           if (g_cancellable_set_error_if_cancelled (cancellable, error))
2959             goto out;
2960
2961           if (!do_splice (buffer[0], NULL, fd_out, &offset_out, n_read, &n_written, error))
2962             goto out;
2963
2964           n_read -= n_written;
2965         }
2966
2967       if (progress_callback)
2968         progress_callback (offset_in, total_size, progress_callback_data);
2969     }
2970
2971   /* Make sure we send full copied size */
2972   if (progress_callback)
2973     progress_callback (offset_in, total_size, progress_callback_data);
2974
2975   if (!g_close (buffer[0], error))
2976     goto out;
2977   buffer[0] = -1;
2978   if (!g_close (buffer[1], error))
2979     goto out;
2980   buffer[1] = -1;
2981  out:
2982   if (buffer[0] != -1)
2983     (void) g_close (buffer[0], NULL);
2984   if (buffer[1] != -1)
2985     (void) g_close (buffer[1], NULL);
2986
2987   return res;
2988 }
2989 #endif
2990
2991 #ifdef __linux__
2992 static gboolean
2993 btrfs_reflink_with_progress (GInputStream           *in,
2994                              GOutputStream          *out,
2995                              GFileInfo              *info,
2996                              GCancellable           *cancellable,
2997                              GFileProgressCallback   progress_callback,
2998                              gpointer                progress_callback_data,
2999                              GError                **error)
3000 {
3001   goffset source_size;
3002   int fd_in, fd_out;
3003   int ret;
3004
3005   fd_in = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (in));
3006   fd_out = g_file_descriptor_based_get_fd (G_FILE_DESCRIPTOR_BASED (out));
3007
3008   if (progress_callback)
3009     source_size = g_file_info_get_size (info);
3010
3011   /* Btrfs clone ioctl properties:
3012    *  - Works at the inode level
3013    *  - Doesn't work with directories
3014    *  - Always follows symlinks (source and destination)
3015    *
3016    * By the time we get here, *in and *out are both regular files */
3017   ret = ioctl (fd_out, BTRFS_IOC_CLONE, fd_in);
3018
3019   if (ret < 0)
3020     {
3021       if (errno == EXDEV)
3022         g_set_error_literal (error, G_IO_ERROR,
3023                              G_IO_ERROR_NOT_SUPPORTED,
3024                              _("Copy (reflink/clone) between mounts is not supported"));
3025       else if (errno == EINVAL)
3026         g_set_error_literal (error, G_IO_ERROR,
3027                              G_IO_ERROR_NOT_SUPPORTED,
3028                              _("Copy (reflink/clone) is not supported or invalid"));
3029       else
3030         /* Most probably something odd happened; retry with fallback */
3031         g_set_error_literal (error, G_IO_ERROR,
3032                              G_IO_ERROR_NOT_SUPPORTED,
3033                              _("Copy (reflink/clone) is not supported or didn’t work"));
3034       /* We retry with fallback for all error cases because Btrfs is currently
3035        * unstable, and so we can't trust it to do clone properly.
3036        * In addition, any hard errors here would cause the same failure in the
3037        * fallback manual copy as well. */
3038       return FALSE;
3039     }
3040
3041   /* Make sure we send full copied size */
3042   if (progress_callback)
3043     progress_callback (source_size, source_size, progress_callback_data);
3044
3045   return TRUE;
3046 }
3047 #endif
3048
3049 static gboolean
3050 file_copy_fallback (GFile                  *source,
3051                     GFile                  *destination,
3052                     GFileCopyFlags          flags,
3053                     GCancellable           *cancellable,
3054                     GFileProgressCallback   progress_callback,
3055                     gpointer                progress_callback_data,
3056                     GError                **error)
3057 {
3058   gboolean ret = FALSE;
3059   GFileInputStream *file_in = NULL;
3060   GInputStream *in = NULL;
3061   GOutputStream *out = NULL;
3062   GFileInfo *info = NULL;
3063   const char *target;
3064   char *attrs_to_read;
3065   gboolean do_set_attributes = FALSE;
3066
3067   /* need to know the file type */
3068   info = g_file_query_info (source,
3069                             G_FILE_ATTRIBUTE_STANDARD_TYPE "," G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET,
3070                             G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3071                             cancellable,
3072                             error);
3073   if (!info)
3074     goto out;
3075
3076   /* Maybe copy the symlink? */
3077   if ((flags & G_FILE_COPY_NOFOLLOW_SYMLINKS) &&
3078       g_file_info_get_file_type (info) == G_FILE_TYPE_SYMBOLIC_LINK)
3079     {
3080       target = g_file_info_get_symlink_target (info);
3081       if (target)
3082         {
3083           if (!copy_symlink (destination, flags, cancellable, target, error))
3084             goto out;
3085
3086           ret = TRUE;
3087           goto out;
3088         }
3089         /* ... else fall back on a regular file copy */
3090     }
3091   /* Handle "special" files (pipes, device nodes, ...)? */
3092   else if (g_file_info_get_file_type (info) == G_FILE_TYPE_SPECIAL)
3093     {
3094       /* FIXME: could try to recreate device nodes and others? */
3095       g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
3096                            _("Can’t copy special file"));
3097       goto out;
3098     }
3099
3100   /* Everything else should just fall back on a regular copy. */
3101
3102   file_in = open_source_for_copy (source, destination, flags, cancellable, error);
3103   if (!file_in)
3104     goto out;
3105   in = G_INPUT_STREAM (file_in);
3106
3107   if (!build_attribute_list_for_copy (destination, flags, &attrs_to_read,
3108                                       cancellable, error))
3109     goto out;
3110
3111   if (attrs_to_read != NULL)
3112     {
3113       GError *tmp_error = NULL;
3114
3115       /* Ok, ditch the previous lightweight info (on Unix we just
3116        * called lstat()); at this point we gather all the information
3117        * we need about the source from the opened file descriptor.
3118        */
3119       g_object_unref (info);
3120
3121       info = g_file_input_stream_query_info (file_in, attrs_to_read,
3122                                              cancellable, &tmp_error);
3123       if (!info)
3124         {
3125           /* Not all gvfs backends implement query_info_on_read(), we
3126            * can just fall back to the pathname again.
3127            * https://bugzilla.gnome.org/706254
3128            */
3129           if (g_error_matches (tmp_error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3130             {
3131               g_clear_error (&tmp_error);
3132               info = g_file_query_info (source, attrs_to_read, G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3133                                         cancellable, error);
3134             }
3135           else
3136             {
3137               g_free (attrs_to_read);
3138               g_propagate_error (error, tmp_error);
3139               goto out;
3140             }
3141         }
3142       g_free (attrs_to_read);
3143       if (!info)
3144         goto out;
3145
3146       do_set_attributes = TRUE;
3147     }
3148
3149   /* In the local file path, we pass down the source info which
3150    * includes things like unix::mode, to ensure that the target file
3151    * is not created with different permissions from the source file.
3152    *
3153    * If a future API like g_file_replace_with_info() is added, switch
3154    * this code to use that.
3155    */
3156   if (G_IS_LOCAL_FILE (destination))
3157     {
3158       if (flags & G_FILE_COPY_OVERWRITE)
3159         out = (GOutputStream*)_g_local_file_output_stream_replace (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3160                                                                    FALSE, NULL,
3161                                                                    flags & G_FILE_COPY_BACKUP,
3162                                                                    G_FILE_CREATE_REPLACE_DESTINATION,
3163                                                                    info,
3164                                                                    cancellable, error);
3165       else
3166         out = (GOutputStream*)_g_local_file_output_stream_create (_g_local_file_get_filename (G_LOCAL_FILE (destination)),
3167                                                                   FALSE, 0, info,
3168                                                                   cancellable, error);
3169     }
3170   else if (flags & G_FILE_COPY_OVERWRITE)
3171     {
3172       out = (GOutputStream *)g_file_replace (destination,
3173                                              NULL,
3174                                              flags & G_FILE_COPY_BACKUP,
3175                                              G_FILE_CREATE_REPLACE_DESTINATION,
3176                                              cancellable, error);
3177     }
3178   else
3179     {
3180       out = (GOutputStream *)g_file_create (destination, 0, cancellable, error);
3181     }
3182
3183   if (!out)
3184     goto out;
3185
3186 #ifdef __linux__
3187   if (G_IS_FILE_DESCRIPTOR_BASED (in) && G_IS_FILE_DESCRIPTOR_BASED (out))
3188     {
3189       GError *reflink_err = NULL;
3190
3191       if (!btrfs_reflink_with_progress (in, out, info, cancellable,
3192                                         progress_callback, progress_callback_data,
3193                                         &reflink_err))
3194         {
3195           if (g_error_matches (reflink_err, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3196             {
3197               g_clear_error (&reflink_err);
3198             }
3199           else
3200             {
3201               g_propagate_error (error, reflink_err);
3202               goto out;
3203             }
3204         }
3205       else
3206         {
3207           ret = TRUE;
3208           goto out;
3209         }
3210     }
3211 #endif
3212
3213 #ifdef HAVE_SPLICE
3214   if (G_IS_FILE_DESCRIPTOR_BASED (in) && G_IS_FILE_DESCRIPTOR_BASED (out))
3215     {
3216       GError *splice_err = NULL;
3217
3218       if (!splice_stream_with_progress (in, out, cancellable,
3219                                         progress_callback, progress_callback_data,
3220                                         &splice_err))
3221         {
3222           if (g_error_matches (splice_err, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED))
3223             {
3224               g_clear_error (&splice_err);
3225             }
3226           else
3227             {
3228               g_propagate_error (error, splice_err);
3229               goto out;
3230             }
3231         }
3232       else
3233         {
3234           ret = TRUE;
3235           goto out;
3236         }
3237     }
3238
3239 #endif
3240
3241   /* A plain read/write loop */
3242   if (!copy_stream_with_progress (in, out, source, cancellable,
3243                                   progress_callback, progress_callback_data,
3244                                   error))
3245     goto out;
3246
3247   ret = TRUE;
3248  out:
3249   if (in)
3250     {
3251       /* Don't care about errors in source here */
3252       (void) g_input_stream_close (in, cancellable, NULL);
3253       g_object_unref (in);
3254     }
3255
3256   if (out)
3257     {
3258       /* But write errors on close are bad! */
3259       if (!g_output_stream_close (out, cancellable, ret ? error : NULL))
3260         ret = FALSE;
3261       g_object_unref (out);
3262     }
3263
3264   /* Ignore errors here. Failure to copy metadata is not a hard error */
3265   /* TODO: set these attributes /before/ we do the rename() on Unix */
3266   if (ret && do_set_attributes)
3267     {
3268       g_file_set_attributes_from_info (destination,
3269                                        info,
3270                                        G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS,
3271                                        cancellable,
3272                                        NULL);
3273     }
3274
3275   g_clear_object (&info);
3276
3277   return ret;
3278 }
3279
3280 /**
3281  * g_file_copy:
3282  * @source: input #GFile
3283  * @destination: destination #GFile
3284  * @flags: set of #GFileCopyFlags
3285  * @cancellable: (nullable): optional #GCancellable object,
3286  *     %NULL to ignore
3287  * @progress_callback: (nullable) (scope call): function to callback with
3288  *     progress information, or %NULL if progress information is not needed
3289  * @progress_callback_data: (closure): user data to pass to @progress_callback
3290  * @error: #GError to set on error, or %NULL
3291  *
3292  * Copies the file @source to the location specified by @destination.
3293  * Can not handle recursive copies of directories.
3294  *
3295  * If the flag #G_FILE_COPY_OVERWRITE is specified an already
3296  * existing @destination file is overwritten.
3297  *
3298  * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
3299  * will be copied as symlinks, otherwise the target of the
3300  * @source symlink will be copied.
3301  *
3302  * If @cancellable is not %NULL, then the operation can be cancelled by
3303  * triggering the cancellable object from another thread. If the operation
3304  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3305  *
3306  * If @progress_callback is not %NULL, then the operation can be monitored
3307  * by setting this to a #GFileProgressCallback function.
3308  * @progress_callback_data will be passed to this function. It is guaranteed
3309  * that this callback will be called after all data has been transferred with
3310  * the total number of bytes copied during the operation.
3311  *
3312  * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
3313  * is returned, independent on the status of the @destination.
3314  *
3315  * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
3316  * the error %G_IO_ERROR_EXISTS is returned.
3317  *
3318  * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3319  * error is returned. If trying to overwrite a directory with a directory the
3320  * %G_IO_ERROR_WOULD_MERGE error is returned.
3321  *
3322  * If the source is a directory and the target does not exist, or
3323  * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
3324  * %G_IO_ERROR_WOULD_RECURSE error is returned.
3325  *
3326  * If you are interested in copying the #GFile object itself (not the on-disk
3327  * file), see g_file_dup().
3328  *
3329  * Returns: %TRUE on success, %FALSE otherwise.
3330  */
3331 gboolean
3332 g_file_copy (GFile                  *source,
3333              GFile                  *destination,
3334              GFileCopyFlags          flags,
3335              GCancellable           *cancellable,
3336              GFileProgressCallback   progress_callback,
3337              gpointer                progress_callback_data,
3338              GError                **error)
3339 {
3340   GFileIface *iface;
3341   GError *my_error;
3342   gboolean res;
3343
3344   g_return_val_if_fail (G_IS_FILE (source), FALSE);
3345   g_return_val_if_fail (G_IS_FILE (destination), FALSE);
3346
3347   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3348     return FALSE;
3349
3350   iface = G_FILE_GET_IFACE (destination);
3351   if (iface->copy)
3352     {
3353       my_error = NULL;
3354       res = (* iface->copy) (source, destination,
3355                              flags, cancellable,
3356                              progress_callback, progress_callback_data,
3357                              &my_error);
3358
3359       if (res)
3360         return TRUE;
3361
3362       if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3363         {
3364           g_propagate_error (error, my_error);
3365               return FALSE;
3366         }
3367       else
3368         g_clear_error (&my_error);
3369     }
3370
3371   /* If the types are different, and the destination method failed
3372    * also try the source method
3373    */
3374   if (G_OBJECT_TYPE (source) != G_OBJECT_TYPE (destination))
3375     {
3376       iface = G_FILE_GET_IFACE (source);
3377
3378       if (iface->copy)
3379         {
3380           my_error = NULL;
3381           res = (* iface->copy) (source, destination,
3382                                  flags, cancellable,
3383                                  progress_callback, progress_callback_data,
3384                                  &my_error);
3385
3386           if (res)
3387             return TRUE;
3388
3389           if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3390             {
3391               g_propagate_error (error, my_error);
3392               return FALSE;
3393             }
3394           else
3395             g_clear_error (&my_error);
3396         }
3397     }
3398
3399   return file_copy_fallback (source, destination, flags, cancellable,
3400                              progress_callback, progress_callback_data,
3401                              error);
3402 }
3403
3404 /**
3405  * g_file_copy_async: (skip)
3406  * @source: input #GFile
3407  * @destination: destination #GFile
3408  * @flags: set of #GFileCopyFlags
3409  * @io_priority: the [I/O priority][io-priority] of the request
3410  * @cancellable: (nullable): optional #GCancellable object,
3411  *     %NULL to ignore
3412  * @progress_callback: (nullable): function to callback with progress
3413  *     information, or %NULL if progress information is not needed
3414  * @progress_callback_data: (closure): user data to pass to @progress_callback
3415  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
3416  * @user_data: the data to pass to callback function
3417  *
3418  * Copies the file @source to the location specified by @destination
3419  * asynchronously. For details of the behaviour, see g_file_copy().
3420  *
3421  * If @progress_callback is not %NULL, then that function that will be called
3422  * just like in g_file_copy(). The callback will run in the default main context
3423  * of the thread calling g_file_copy_async() — the same context as @callback is
3424  * run in.
3425  *
3426  * When the operation is finished, @callback will be called. You can then call
3427  * g_file_copy_finish() to get the result of the operation.
3428  */
3429 void
3430 g_file_copy_async (GFile                  *source,
3431                    GFile                  *destination,
3432                    GFileCopyFlags          flags,
3433                    int                     io_priority,
3434                    GCancellable           *cancellable,
3435                    GFileProgressCallback   progress_callback,
3436                    gpointer                progress_callback_data,
3437                    GAsyncReadyCallback     callback,
3438                    gpointer                user_data)
3439 {
3440   GFileIface *iface;
3441
3442   g_return_if_fail (G_IS_FILE (source));
3443   g_return_if_fail (G_IS_FILE (destination));
3444
3445   iface = G_FILE_GET_IFACE (source);
3446   (* iface->copy_async) (source,
3447                          destination,
3448                          flags,
3449                          io_priority,
3450                          cancellable,
3451                          progress_callback,
3452                          progress_callback_data,
3453                          callback,
3454                          user_data);
3455 }
3456
3457 /**
3458  * g_file_copy_finish:
3459  * @file: input #GFile
3460  * @res: a #GAsyncResult
3461  * @error: a #GError, or %NULL
3462  *
3463  * Finishes copying the file started with g_file_copy_async().
3464  *
3465  * Returns: a %TRUE on success, %FALSE on error.
3466  */
3467 gboolean
3468 g_file_copy_finish (GFile         *file,
3469                     GAsyncResult  *res,
3470                     GError       **error)
3471 {
3472   GFileIface *iface;
3473
3474   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3475   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), FALSE);
3476
3477   if (g_async_result_legacy_propagate_error (res, error))
3478     return FALSE;
3479
3480   iface = G_FILE_GET_IFACE (file);
3481   return (* iface->copy_finish) (file, res, error);
3482 }
3483
3484 /**
3485  * g_file_move:
3486  * @source: #GFile pointing to the source location
3487  * @destination: #GFile pointing to the destination location
3488  * @flags: set of #GFileCopyFlags
3489  * @cancellable: (nullable): optional #GCancellable object,
3490  *     %NULL to ignore
3491  * @progress_callback: (nullable) (scope call): #GFileProgressCallback
3492  *     function for updates
3493  * @progress_callback_data: (closure): gpointer to user data for
3494  *     the callback function
3495  * @error: #GError for returning error conditions, or %NULL
3496  *
3497  * Tries to move the file or directory @source to the location specified
3498  * by @destination. If native move operations are supported then this is
3499  * used, otherwise a copy + delete fallback is used. The native
3500  * implementation may support moving directories (for instance on moves
3501  * inside the same filesystem), but the fallback code does not.
3502  *
3503  * If the flag #G_FILE_COPY_OVERWRITE is specified an already
3504  * existing @destination file is overwritten.
3505  *
3506  * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
3507  * will be copied as symlinks, otherwise the target of the
3508  * @source symlink will be copied.
3509  *
3510  * If @cancellable is not %NULL, then the operation can be cancelled by
3511  * triggering the cancellable object from another thread. If the operation
3512  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3513  *
3514  * If @progress_callback is not %NULL, then the operation can be monitored
3515  * by setting this to a #GFileProgressCallback function.
3516  * @progress_callback_data will be passed to this function. It is
3517  * guaranteed that this callback will be called after all data has been
3518  * transferred with the total number of bytes copied during the operation.
3519  *
3520  * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
3521  * error is returned, independent on the status of the @destination.
3522  *
3523  * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
3524  * then the error %G_IO_ERROR_EXISTS is returned.
3525  *
3526  * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
3527  * error is returned. If trying to overwrite a directory with a directory the
3528  * %G_IO_ERROR_WOULD_MERGE error is returned.
3529  *
3530  * If the source is a directory and the target does not exist, or
3531  * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
3532  * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
3533  * move operation isn't available).
3534  *
3535  * Returns: %TRUE on successful move, %FALSE otherwise.
3536  */
3537 gboolean
3538 g_file_move (GFile                  *source,
3539              GFile                  *destination,
3540              GFileCopyFlags          flags,
3541              GCancellable           *cancellable,
3542              GFileProgressCallback   progress_callback,
3543              gpointer                progress_callback_data,
3544              GError                **error)
3545 {
3546   GFileIface *iface;
3547   GError *my_error;
3548   gboolean res;
3549
3550   g_return_val_if_fail (G_IS_FILE (source), FALSE);
3551   g_return_val_if_fail (G_IS_FILE (destination), FALSE);
3552
3553   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3554     return FALSE;
3555
3556   iface = G_FILE_GET_IFACE (destination);
3557   if (iface->move)
3558     {
3559       my_error = NULL;
3560       res = (* iface->move) (source, destination,
3561                              flags, cancellable,
3562                              progress_callback, progress_callback_data,
3563                              &my_error);
3564
3565       if (res)
3566         return TRUE;
3567
3568       if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3569         {
3570           g_propagate_error (error, my_error);
3571           return FALSE;
3572         }
3573       else
3574         g_clear_error (&my_error);
3575     }
3576
3577   /* If the types are different, and the destination method failed
3578    * also try the source method
3579    */
3580   if (G_OBJECT_TYPE (source) != G_OBJECT_TYPE (destination))
3581     {
3582       iface = G_FILE_GET_IFACE (source);
3583
3584       if (iface->move)
3585         {
3586           my_error = NULL;
3587           res = (* iface->move) (source, destination,
3588                                  flags, cancellable,
3589                                  progress_callback, progress_callback_data,
3590                                  &my_error);
3591
3592           if (res)
3593             return TRUE;
3594
3595           if (my_error->domain != G_IO_ERROR || my_error->code != G_IO_ERROR_NOT_SUPPORTED)
3596             {
3597               g_propagate_error (error, my_error);
3598               return FALSE;
3599             }
3600           else
3601             g_clear_error (&my_error);
3602         }
3603     }
3604
3605   if (flags & G_FILE_COPY_NO_FALLBACK_FOR_MOVE)
3606     {
3607       g_set_error_literal (error, G_IO_ERROR,
3608                            G_IO_ERROR_NOT_SUPPORTED,
3609                            _("Operation not supported"));
3610       return FALSE;
3611     }
3612
3613   flags |= G_FILE_COPY_ALL_METADATA;
3614   if (!g_file_copy (source, destination, flags, cancellable,
3615                     progress_callback, progress_callback_data,
3616                     error))
3617     return FALSE;
3618
3619   return g_file_delete (source, cancellable, error);
3620 }
3621
3622 /**
3623  * g_file_make_directory:
3624  * @file: input #GFile
3625  * @cancellable: (nullable): optional #GCancellable object,
3626  *     %NULL to ignore
3627  * @error: a #GError, or %NULL
3628  *
3629  * Creates a directory. Note that this will only create a child directory
3630  * of the immediate parent directory of the path or URI given by the #GFile.
3631  * To recursively create directories, see g_file_make_directory_with_parents().
3632  * This function will fail if the parent directory does not exist, setting
3633  * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
3634  * creating directories, this function will fail, setting @error to
3635  * %G_IO_ERROR_NOT_SUPPORTED.
3636  *
3637  * For a local #GFile the newly created directory will have the default
3638  * (current) ownership and permissions of the current process.
3639  *
3640  * If @cancellable is not %NULL, then the operation can be cancelled by
3641  * triggering the cancellable object from another thread. If the operation
3642  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3643  *
3644  * Returns: %TRUE on successful creation, %FALSE otherwise.
3645  */
3646 gboolean
3647 g_file_make_directory (GFile         *file,
3648                        GCancellable  *cancellable,
3649                        GError       **error)
3650 {
3651   GFileIface *iface;
3652
3653   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3654
3655   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3656     return FALSE;
3657
3658   iface = G_FILE_GET_IFACE (file);
3659
3660   if (iface->make_directory == NULL)
3661     {
3662       g_set_error_literal (error, G_IO_ERROR,
3663                            G_IO_ERROR_NOT_SUPPORTED,
3664                            _("Operation not supported"));
3665       return FALSE;
3666     }
3667
3668   return (* iface->make_directory) (file, cancellable, error);
3669 }
3670
3671 /**
3672  * g_file_make_directory_async:
3673  * @file: input #GFile
3674  * @io_priority: the [I/O priority][io-priority] of the request
3675  * @cancellable: (nullable): optional #GCancellable object,
3676  *     %NULL to ignore
3677  * @callback: a #GAsyncReadyCallback to call
3678  *     when the request is satisfied
3679  * @user_data: the data to pass to callback function
3680  *
3681  * Asynchronously creates a directory.
3682  *
3683  * Virtual: make_directory_async
3684  * Since: 2.38
3685  */
3686 void
3687 g_file_make_directory_async (GFile               *file,
3688                              int                  io_priority,
3689                              GCancellable        *cancellable,
3690                              GAsyncReadyCallback  callback,
3691                              gpointer             user_data)
3692 {
3693   GFileIface *iface;
3694
3695   g_return_if_fail (G_IS_FILE (file));
3696
3697   iface = G_FILE_GET_IFACE (file);
3698   (* iface->make_directory_async) (file,
3699                                    io_priority,
3700                                    cancellable,
3701                                    callback,
3702                                    user_data);
3703 }
3704
3705 /**
3706  * g_file_make_directory_finish:
3707  * @file: input #GFile
3708  * @result: a #GAsyncResult
3709  * @error: a #GError, or %NULL
3710  *
3711  * Finishes an asynchronous directory creation, started with
3712  * g_file_make_directory_async().
3713  *
3714  * Virtual: make_directory_finish
3715  * Returns: %TRUE on successful directory creation, %FALSE otherwise.
3716  * Since: 2.38
3717  */
3718 gboolean
3719 g_file_make_directory_finish (GFile         *file,
3720                               GAsyncResult  *result,
3721                               GError       **error)
3722 {
3723   GFileIface *iface;
3724
3725   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3726   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
3727
3728   iface = G_FILE_GET_IFACE (file);
3729   return (* iface->make_directory_finish) (file, result, error);
3730 }
3731
3732 /**
3733  * g_file_make_directory_with_parents:
3734  * @file: input #GFile
3735  * @cancellable: (nullable): optional #GCancellable object,
3736  *     %NULL to ignore
3737  * @error: a #GError, or %NULL
3738  *
3739  * Creates a directory and any parent directories that may not
3740  * exist similar to 'mkdir -p'. If the file system does not support
3741  * creating directories, this function will fail, setting @error to
3742  * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
3743  * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
3744  * the similar g_mkdir_with_parents().
3745  *
3746  * For a local #GFile the newly created directories will have the default
3747  * (current) ownership and permissions of the current process.
3748  *
3749  * If @cancellable is not %NULL, then the operation can be cancelled by
3750  * triggering the cancellable object from another thread. If the operation
3751  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3752  *
3753  * Returns: %TRUE if all directories have been successfully created, %FALSE
3754  * otherwise.
3755  *
3756  * Since: 2.18
3757  */
3758 gboolean
3759 g_file_make_directory_with_parents (GFile         *file,
3760                                     GCancellable  *cancellable,
3761                                     GError       **error)
3762 {
3763   GFile *work_file = NULL;
3764   GList *list = NULL, *l;
3765   GError *my_error = NULL;
3766
3767   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3768
3769   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3770     return FALSE;
3771
3772   /* Try for the simple case of not having to create any parent
3773    * directories.  If any parent directory needs to be created, this
3774    * call will fail with NOT_FOUND. If that happens, then that value of
3775    * my_error persists into the while loop below.
3776    */
3777   g_file_make_directory (file, cancellable, &my_error);
3778   if (!g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
3779     {
3780       if (my_error)
3781         g_propagate_error (error, my_error);
3782       return my_error == NULL;
3783     }
3784
3785   work_file = g_object_ref (file);
3786
3787   /* Creates the parent directories as needed. In case any particular
3788    * creation operation fails for lack of other parent directories
3789    * (NOT_FOUND), the directory is added to a list of directories to
3790    * create later, and the value of my_error is retained until the next
3791    * iteration of the loop.  After the loop my_error should either be
3792    * empty or contain a real failure condition.
3793    */
3794   while (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
3795     {
3796       GFile *parent_file;
3797
3798       parent_file = g_file_get_parent (work_file);
3799       if (parent_file == NULL)
3800         break;
3801
3802       g_clear_error (&my_error);
3803       g_file_make_directory (parent_file, cancellable, &my_error);
3804       /* Another process may have created the directory in between the
3805        * G_IO_ERROR_NOT_FOUND and now
3806        */
3807       if (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_EXISTS))
3808         g_clear_error (&my_error);
3809
3810       g_object_unref (work_file);
3811       work_file = g_object_ref (parent_file);
3812
3813       if (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
3814         list = g_list_prepend (list, parent_file);  /* Transfer ownership of ref */
3815       else
3816         g_object_unref (parent_file);
3817     }
3818
3819   /* All directories should be able to be created now, so an error at
3820    * this point means the whole operation must fail -- except an EXISTS
3821    * error, which means that another process already created the
3822    * directory in between the previous failure and now.
3823    */
3824   for (l = list; my_error == NULL && l; l = l->next)
3825     {
3826       g_file_make_directory ((GFile *) l->data, cancellable, &my_error);
3827       if (g_error_matches (my_error, G_IO_ERROR, G_IO_ERROR_EXISTS))
3828         g_clear_error (&my_error);
3829     }
3830
3831   if (work_file)
3832     g_object_unref (work_file);
3833
3834   /* Clean up */
3835   while (list != NULL)
3836     {
3837       g_object_unref ((GFile *) list->data);
3838       list = g_list_remove (list, list->data);
3839     }
3840
3841   /* At this point an error in my_error means a that something
3842    * unexpected failed in either of the loops above, so the whole
3843    * operation must fail.
3844    */
3845   if (my_error != NULL)
3846     {
3847       g_propagate_error (error, my_error);
3848       return FALSE;
3849     }
3850
3851   return g_file_make_directory (file, cancellable, error);
3852 }
3853
3854 /**
3855  * g_file_make_symbolic_link:
3856  * @file: a #GFile with the name of the symlink to create
3857  * @symlink_value: (type filename): a string with the path for the target
3858  *     of the new symlink
3859  * @cancellable: (nullable): optional #GCancellable object,
3860  *     %NULL to ignore
3861  * @error: a #GError
3862  *
3863  * Creates a symbolic link named @file which contains the string
3864  * @symlink_value.
3865  *
3866  * If @cancellable is not %NULL, then the operation can be cancelled by
3867  * triggering the cancellable object from another thread. If the operation
3868  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3869  *
3870  * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
3871  */
3872 gboolean
3873 g_file_make_symbolic_link (GFile         *file,
3874                            const char    *symlink_value,
3875                            GCancellable  *cancellable,
3876                            GError       **error)
3877 {
3878   GFileIface *iface;
3879
3880   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3881   g_return_val_if_fail (symlink_value != NULL, FALSE);
3882
3883   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3884     return FALSE;
3885
3886   if (*symlink_value == '\0')
3887     {
3888       g_set_error_literal (error, G_IO_ERROR,
3889                            G_IO_ERROR_INVALID_ARGUMENT,
3890                            _("Invalid symlink value given"));
3891       return FALSE;
3892     }
3893
3894   iface = G_FILE_GET_IFACE (file);
3895
3896   if (iface->make_symbolic_link == NULL)
3897     {
3898       g_set_error_literal (error, G_IO_ERROR,
3899                            G_IO_ERROR_NOT_SUPPORTED,
3900                            _("Operation not supported"));
3901       return FALSE;
3902     }
3903
3904   return (* iface->make_symbolic_link) (file, symlink_value, cancellable, error);
3905 }
3906
3907 /**
3908  * g_file_delete:
3909  * @file: input #GFile
3910  * @cancellable: (nullable): optional #GCancellable object,
3911  *     %NULL to ignore
3912  * @error: a #GError, or %NULL
3913  *
3914  * Deletes a file. If the @file is a directory, it will only be
3915  * deleted if it is empty. This has the same semantics as g_unlink().
3916  *
3917  * If @cancellable is not %NULL, then the operation can be cancelled by
3918  * triggering the cancellable object from another thread. If the operation
3919  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
3920  *
3921  * Virtual: delete_file
3922  * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3923  */
3924 gboolean
3925 g_file_delete (GFile         *file,
3926                GCancellable  *cancellable,
3927                GError       **error)
3928 {
3929   GFileIface *iface;
3930
3931   g_return_val_if_fail (G_IS_FILE (file), FALSE);
3932
3933   if (g_cancellable_set_error_if_cancelled (cancellable, error))
3934     return FALSE;
3935
3936   iface = G_FILE_GET_IFACE (file);
3937
3938   if (iface->delete_file == NULL)
3939     {
3940       g_set_error_literal (error, G_IO_ERROR,
3941                            G_IO_ERROR_NOT_SUPPORTED,
3942                            _("Operation not supported"));
3943       return FALSE;
3944     }
3945
3946   return (* iface->delete_file) (file, cancellable, error);
3947 }
3948
3949 /**
3950  * g_file_delete_async:
3951  * @file: input #GFile
3952  * @io_priority: the [I/O priority][io-priority] of the request
3953  * @cancellable: (nullable): optional #GCancellable object,
3954  *     %NULL to ignore
3955  * @callback: a #GAsyncReadyCallback to call
3956  *     when the request is satisfied
3957  * @user_data: the data to pass to callback function
3958  *
3959  * Asynchronously delete a file. If the @file is a directory, it will
3960  * only be deleted if it is empty.  This has the same semantics as
3961  * g_unlink().
3962  *
3963  * Virtual: delete_file_async
3964  * Since: 2.34
3965  */
3966 void
3967 g_file_delete_async (GFile               *file,
3968                      int                  io_priority,
3969                      GCancellable        *cancellable,
3970                      GAsyncReadyCallback  callback,
3971                      gpointer             user_data)
3972 {
3973   GFileIface *iface;
3974
3975   g_return_if_fail (G_IS_FILE (file));
3976
3977   iface = G_FILE_GET_IFACE (file);
3978   (* iface->delete_file_async) (file,
3979                                 io_priority,
3980                                 cancellable,
3981                                 callback,
3982                                 user_data);
3983 }
3984
3985 /**
3986  * g_file_delete_finish:
3987  * @file: input #GFile
3988  * @result: a #GAsyncResult
3989  * @error: a #GError, or %NULL
3990  *
3991  * Finishes deleting a file started with g_file_delete_async().
3992  *
3993  * Virtual: delete_file_finish
3994  * Returns: %TRUE if the file was deleted. %FALSE otherwise.
3995  * Since: 2.34
3996  **/
3997 gboolean
3998 g_file_delete_finish (GFile         *file,
3999                       GAsyncResult  *result,
4000                       GError       **error)
4001 {
4002   GFileIface *iface;
4003
4004   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4005   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4006
4007   if (g_async_result_legacy_propagate_error (result, error))
4008     return FALSE;
4009
4010   iface = G_FILE_GET_IFACE (file);
4011   return (* iface->delete_file_finish) (file, result, error);
4012 }
4013
4014 /**
4015  * g_file_trash:
4016  * @file: #GFile to send to trash
4017  * @cancellable: (nullable): optional #GCancellable object,
4018  *     %NULL to ignore
4019  * @error: a #GError, or %NULL
4020  *
4021  * Sends @file to the "Trashcan", if possible. This is similar to
4022  * deleting it, but the user can recover it before emptying the trashcan.
4023  * Not all file systems support trashing, so this call can return the
4024  * %G_IO_ERROR_NOT_SUPPORTED error.
4025  *
4026  * If @cancellable is not %NULL, then the operation can be cancelled by
4027  * triggering the cancellable object from another thread. If the operation
4028  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4029  *
4030  * Virtual: trash
4031  * Returns: %TRUE on successful trash, %FALSE otherwise.
4032  */
4033 gboolean
4034 g_file_trash (GFile         *file,
4035               GCancellable  *cancellable,
4036               GError       **error)
4037 {
4038   GFileIface *iface;
4039
4040   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4041
4042   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4043     return FALSE;
4044
4045   iface = G_FILE_GET_IFACE (file);
4046
4047   if (iface->trash == NULL)
4048     {
4049       g_set_error_literal (error,
4050                            G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4051                            _("Trash not supported"));
4052       return FALSE;
4053     }
4054
4055   return (* iface->trash) (file, cancellable, error);
4056 }
4057
4058 /**
4059  * g_file_trash_async:
4060  * @file: input #GFile
4061  * @io_priority: the [I/O priority][io-priority] of the request
4062  * @cancellable: (nullable): optional #GCancellable object,
4063  *     %NULL to ignore
4064  * @callback: a #GAsyncReadyCallback to call
4065  *     when the request is satisfied
4066  * @user_data: the data to pass to callback function
4067  *
4068  * Asynchronously sends @file to the Trash location, if possible.
4069  *
4070  * Virtual: trash_async
4071  * Since: 2.38
4072  */
4073 void
4074 g_file_trash_async (GFile               *file,
4075                     int                  io_priority,
4076                     GCancellable        *cancellable,
4077                     GAsyncReadyCallback  callback,
4078                     gpointer             user_data)
4079 {
4080   GFileIface *iface;
4081
4082   g_return_if_fail (G_IS_FILE (file));
4083
4084   iface = G_FILE_GET_IFACE (file);
4085   (* iface->trash_async) (file,
4086                           io_priority,
4087                           cancellable,
4088                           callback,
4089                           user_data);
4090 }
4091
4092 /**
4093  * g_file_trash_finish:
4094  * @file: input #GFile
4095  * @result: a #GAsyncResult
4096  * @error: a #GError, or %NULL
4097  *
4098  * Finishes an asynchronous file trashing operation, started with
4099  * g_file_trash_async().
4100  *
4101  * Virtual: trash_finish
4102  * Returns: %TRUE on successful trash, %FALSE otherwise.
4103  * Since: 2.38
4104  */
4105 gboolean
4106 g_file_trash_finish (GFile         *file,
4107                      GAsyncResult  *result,
4108                      GError       **error)
4109 {
4110   GFileIface *iface;
4111
4112   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4113   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4114
4115   iface = G_FILE_GET_IFACE (file);
4116   return (* iface->trash_finish) (file, result, error);
4117 }
4118
4119 /**
4120  * g_file_set_display_name:
4121  * @file: input #GFile
4122  * @display_name: a string
4123  * @cancellable: (nullable): optional #GCancellable object,
4124  *     %NULL to ignore
4125  * @error: a #GError, or %NULL
4126  *
4127  * Renames @file to the specified display name.
4128  *
4129  * The display name is converted from UTF-8 to the correct encoding
4130  * for the target filesystem if possible and the @file is renamed to this.
4131  *
4132  * If you want to implement a rename operation in the user interface the
4133  * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
4134  * initial value in the rename widget, and then the result after editing
4135  * should be passed to g_file_set_display_name().
4136  *
4137  * On success the resulting converted filename is returned.
4138  *
4139  * If @cancellable is not %NULL, then the operation can be cancelled by
4140  * triggering the cancellable object from another thread. If the operation
4141  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4142  *
4143  * Returns: (transfer full): a #GFile specifying what @file was renamed to,
4144  *     or %NULL if there was an error.
4145  *     Free the returned object with g_object_unref().
4146  */
4147 GFile *
4148 g_file_set_display_name (GFile         *file,
4149                          const gchar   *display_name,
4150                          GCancellable  *cancellable,
4151                          GError       **error)
4152 {
4153   GFileIface *iface;
4154
4155   g_return_val_if_fail (G_IS_FILE (file), NULL);
4156   g_return_val_if_fail (display_name != NULL, NULL);
4157
4158   if (strchr (display_name, G_DIR_SEPARATOR) != NULL)
4159     {
4160       g_set_error (error,
4161                    G_IO_ERROR,
4162                    G_IO_ERROR_INVALID_ARGUMENT,
4163                    _("File names cannot contain “%c”"), G_DIR_SEPARATOR);
4164       return NULL;
4165     }
4166
4167   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4168     return NULL;
4169
4170   iface = G_FILE_GET_IFACE (file);
4171
4172   return (* iface->set_display_name) (file, display_name, cancellable, error);
4173 }
4174
4175 /**
4176  * g_file_set_display_name_async:
4177  * @file: input #GFile
4178  * @display_name: a string
4179  * @io_priority: the [I/O priority][io-priority] of the request
4180  * @cancellable: (nullable): optional #GCancellable object,
4181  *     %NULL to ignore
4182  * @callback: (scope async): a #GAsyncReadyCallback to call
4183  *     when the request is satisfied
4184  * @user_data: (closure): the data to pass to callback function
4185  *
4186  * Asynchronously sets the display name for a given #GFile.
4187  *
4188  * For more details, see g_file_set_display_name() which is
4189  * the synchronous version of this call.
4190  *
4191  * When the operation is finished, @callback will be called.
4192  * You can then call g_file_set_display_name_finish() to get
4193  * the result of the operation.
4194  */
4195 void
4196 g_file_set_display_name_async (GFile               *file,
4197                                const gchar         *display_name,
4198                                gint                 io_priority,
4199                                GCancellable        *cancellable,
4200                                GAsyncReadyCallback  callback,
4201                                gpointer             user_data)
4202 {
4203   GFileIface *iface;
4204
4205   g_return_if_fail (G_IS_FILE (file));
4206   g_return_if_fail (display_name != NULL);
4207
4208   iface = G_FILE_GET_IFACE (file);
4209   (* iface->set_display_name_async) (file,
4210                                      display_name,
4211                                      io_priority,
4212                                      cancellable,
4213                                      callback,
4214                                      user_data);
4215 }
4216
4217 /**
4218  * g_file_set_display_name_finish:
4219  * @file: input #GFile
4220  * @res: a #GAsyncResult
4221  * @error: a #GError, or %NULL
4222  *
4223  * Finishes setting a display name started with
4224  * g_file_set_display_name_async().
4225  *
4226  * Returns: (transfer full): a #GFile or %NULL on error.
4227  *     Free the returned object with g_object_unref().
4228  */
4229 GFile *
4230 g_file_set_display_name_finish (GFile         *file,
4231                                 GAsyncResult  *res,
4232                                 GError       **error)
4233 {
4234   GFileIface *iface;
4235
4236   g_return_val_if_fail (G_IS_FILE (file), NULL);
4237   g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
4238
4239   if (g_async_result_legacy_propagate_error (res, error))
4240     return NULL;
4241
4242   iface = G_FILE_GET_IFACE (file);
4243   return (* iface->set_display_name_finish) (file, res, error);
4244 }
4245
4246 /**
4247  * g_file_query_settable_attributes:
4248  * @file: input #GFile
4249  * @cancellable: (nullable): optional #GCancellable object,
4250  *     %NULL to ignore
4251  * @error: a #GError, or %NULL
4252  *
4253  * Obtain the list of settable attributes for the file.
4254  *
4255  * Returns the type and full attribute name of all the attributes
4256  * that can be set on this file. This doesn't mean setting it will
4257  * always succeed though, you might get an access failure, or some
4258  * specific file may not support a specific attribute.
4259  *
4260  * If @cancellable is not %NULL, then the operation can be cancelled by
4261  * triggering the cancellable object from another thread. If the operation
4262  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4263  *
4264  * Returns: a #GFileAttributeInfoList describing the settable attributes.
4265  *     When you are done with it, release it with
4266  *     g_file_attribute_info_list_unref()
4267  */
4268 GFileAttributeInfoList *
4269 g_file_query_settable_attributes (GFile         *file,
4270                                   GCancellable  *cancellable,
4271                                   GError       **error)
4272 {
4273   GFileIface *iface;
4274   GError *my_error;
4275   GFileAttributeInfoList *list;
4276
4277   g_return_val_if_fail (G_IS_FILE (file), NULL);
4278
4279   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4280     return NULL;
4281
4282   iface = G_FILE_GET_IFACE (file);
4283
4284   if (iface->query_settable_attributes == NULL)
4285     return g_file_attribute_info_list_new ();
4286
4287   my_error = NULL;
4288   list = (* iface->query_settable_attributes) (file, cancellable, &my_error);
4289
4290   if (list == NULL)
4291     {
4292       if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_NOT_SUPPORTED)
4293         {
4294           list = g_file_attribute_info_list_new ();
4295           g_error_free (my_error);
4296         }
4297       else
4298         g_propagate_error (error, my_error);
4299     }
4300
4301   return list;
4302 }
4303
4304 /**
4305  * g_file_query_writable_namespaces:
4306  * @file: input #GFile
4307  * @cancellable: (nullable): optional #GCancellable object,
4308  *     %NULL to ignore
4309  * @error: a #GError, or %NULL
4310  *
4311  * Obtain the list of attribute namespaces where new attributes
4312  * can be created by a user. An example of this is extended
4313  * attributes (in the "xattr" namespace).
4314  *
4315  * If @cancellable is not %NULL, then the operation can be cancelled by
4316  * triggering the cancellable object from another thread. If the operation
4317  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4318  *
4319  * Returns: a #GFileAttributeInfoList describing the writable namespaces.
4320  *     When you are done with it, release it with
4321  *     g_file_attribute_info_list_unref()
4322  */
4323 GFileAttributeInfoList *
4324 g_file_query_writable_namespaces (GFile         *file,
4325                                   GCancellable  *cancellable,
4326                                   GError       **error)
4327 {
4328   GFileIface *iface;
4329   GError *my_error;
4330   GFileAttributeInfoList *list;
4331
4332   g_return_val_if_fail (G_IS_FILE (file), NULL);
4333
4334   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4335     return NULL;
4336
4337   iface = G_FILE_GET_IFACE (file);
4338
4339   if (iface->query_writable_namespaces == NULL)
4340     return g_file_attribute_info_list_new ();
4341
4342   my_error = NULL;
4343   list = (* iface->query_writable_namespaces) (file, cancellable, &my_error);
4344
4345   if (list == NULL)
4346     {
4347       g_warn_if_reached();
4348       list = g_file_attribute_info_list_new ();
4349     }
4350
4351   if (my_error != NULL)
4352     {
4353       if (my_error->domain == G_IO_ERROR && my_error->code == G_IO_ERROR_NOT_SUPPORTED)
4354         {
4355           g_error_free (my_error);
4356         }
4357       else
4358         g_propagate_error (error, my_error);
4359     }
4360
4361   return list;
4362 }
4363
4364 /**
4365  * g_file_set_attribute:
4366  * @file: input #GFile
4367  * @attribute: a string containing the attribute's name
4368  * @type: The type of the attribute
4369  * @value_p: (nullable): a pointer to the value (or the pointer
4370  *     itself if the type is a pointer type)
4371  * @flags: a set of #GFileQueryInfoFlags
4372  * @cancellable: (nullable): optional #GCancellable object,
4373  *     %NULL to ignore
4374  * @error: a #GError, or %NULL
4375  *
4376  * Sets an attribute in the file with attribute name @attribute to @value.
4377  *
4378  * Some attributes can be unset by setting @attribute to
4379  * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
4380  *
4381  * If @cancellable is not %NULL, then the operation can be cancelled by
4382  * triggering the cancellable object from another thread. If the operation
4383  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4384  *
4385  * Returns: %TRUE if the attribute was set, %FALSE otherwise.
4386  */
4387 gboolean
4388 g_file_set_attribute (GFile                *file,
4389                       const gchar          *attribute,
4390                       GFileAttributeType    type,
4391                       gpointer              value_p,
4392                       GFileQueryInfoFlags   flags,
4393                       GCancellable         *cancellable,
4394                       GError              **error)
4395 {
4396   GFileIface *iface;
4397
4398   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4399   g_return_val_if_fail (attribute != NULL && *attribute != '\0', FALSE);
4400
4401   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4402     return FALSE;
4403
4404   iface = G_FILE_GET_IFACE (file);
4405
4406   if (iface->set_attribute == NULL)
4407     {
4408       g_set_error_literal (error, G_IO_ERROR,
4409                            G_IO_ERROR_NOT_SUPPORTED,
4410                            _("Operation not supported"));
4411       return FALSE;
4412     }
4413
4414   return (* iface->set_attribute) (file, attribute, type, value_p, flags, cancellable, error);
4415 }
4416
4417 /**
4418  * g_file_set_attributes_from_info:
4419  * @file: input #GFile
4420  * @info: a #GFileInfo
4421  * @flags: #GFileQueryInfoFlags
4422  * @cancellable: (nullable): optional #GCancellable object,
4423  *     %NULL to ignore
4424  * @error: a #GError, or %NULL
4425  *
4426  * Tries to set all attributes in the #GFileInfo on the target
4427  * values, not stopping on the first error.
4428  *
4429  * If there is any error during this operation then @error will
4430  * be set to the first error. Error on particular fields are flagged
4431  * by setting the "status" field in the attribute value to
4432  * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
4433  * also detect further errors.
4434  *
4435  * If @cancellable is not %NULL, then the operation can be cancelled by
4436  * triggering the cancellable object from another thread. If the operation
4437  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4438  *
4439  * Returns: %FALSE if there was any error, %TRUE otherwise.
4440  */
4441 gboolean
4442 g_file_set_attributes_from_info (GFile                *file,
4443                                  GFileInfo            *info,
4444                                  GFileQueryInfoFlags   flags,
4445                                  GCancellable         *cancellable,
4446                                  GError              **error)
4447 {
4448   GFileIface *iface;
4449
4450   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4451   g_return_val_if_fail (G_IS_FILE_INFO (info), FALSE);
4452
4453   if (g_cancellable_set_error_if_cancelled (cancellable, error))
4454     return FALSE;
4455
4456   g_file_info_clear_status (info);
4457
4458   iface = G_FILE_GET_IFACE (file);
4459
4460   return (* iface->set_attributes_from_info) (file,
4461                                               info,
4462                                               flags,
4463                                               cancellable,
4464                                               error);
4465 }
4466
4467 static gboolean
4468 g_file_real_set_attributes_from_info (GFile                *file,
4469                                       GFileInfo            *info,
4470                                       GFileQueryInfoFlags   flags,
4471                                       GCancellable         *cancellable,
4472                                       GError              **error)
4473 {
4474   char **attributes;
4475   int i;
4476   gboolean res;
4477   GFileAttributeValue *value;
4478
4479   res = TRUE;
4480
4481   attributes = g_file_info_list_attributes (info, NULL);
4482
4483   for (i = 0; attributes[i] != NULL; i++)
4484     {
4485       value = _g_file_info_get_attribute_value (info, attributes[i]);
4486
4487       if (value->status != G_FILE_ATTRIBUTE_STATUS_UNSET)
4488         continue;
4489
4490       if (!g_file_set_attribute (file, attributes[i],
4491                                  value->type, _g_file_attribute_value_peek_as_pointer (value),
4492                                  flags, cancellable, error))
4493         {
4494           value->status = G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING;
4495           res = FALSE;
4496           /* Don't set error multiple times */
4497           error = NULL;
4498         }
4499       else
4500         value->status = G_FILE_ATTRIBUTE_STATUS_SET;
4501     }
4502
4503   g_strfreev (attributes);
4504
4505   return res;
4506 }
4507
4508 /**
4509  * g_file_set_attributes_async:
4510  * @file: input #GFile
4511  * @info: a #GFileInfo
4512  * @flags: a #GFileQueryInfoFlags
4513  * @io_priority: the [I/O priority][io-priority] of the request
4514  * @cancellable: (nullable): optional #GCancellable object,
4515  *     %NULL to ignore
4516  * @callback: (scope async): a #GAsyncReadyCallback
4517  * @user_data: (closure): a #gpointer
4518  *
4519  * Asynchronously sets the attributes of @file with @info.
4520  *
4521  * For more details, see g_file_set_attributes_from_info(),
4522  * which is the synchronous version of this call.
4523  *
4524  * When the operation is finished, @callback will be called.
4525  * You can then call g_file_set_attributes_finish() to get
4526  * the result of the operation.
4527  */
4528 void
4529 g_file_set_attributes_async (GFile               *file,
4530                              GFileInfo           *info,
4531                              GFileQueryInfoFlags  flags,
4532                              int                  io_priority,
4533                              GCancellable        *cancellable,
4534                              GAsyncReadyCallback  callback,
4535                              gpointer             user_data)
4536 {
4537   GFileIface *iface;
4538
4539   g_return_if_fail (G_IS_FILE (file));
4540   g_return_if_fail (G_IS_FILE_INFO (info));
4541
4542   iface = G_FILE_GET_IFACE (file);
4543   (* iface->set_attributes_async) (file,
4544                                    info,
4545                                    flags,
4546                                    io_priority,
4547                                    cancellable,
4548                                    callback,
4549                                    user_data);
4550 }
4551
4552 /**
4553  * g_file_set_attributes_finish:
4554  * @file: input #GFile
4555  * @result: a #GAsyncResult
4556  * @info: (out) (transfer full): a #GFileInfo
4557  * @error: a #GError, or %NULL
4558  *
4559  * Finishes setting an attribute started in g_file_set_attributes_async().
4560  *
4561  * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
4562  */
4563 gboolean
4564 g_file_set_attributes_finish (GFile         *file,
4565                               GAsyncResult  *result,
4566                               GFileInfo    **info,
4567                               GError       **error)
4568 {
4569   GFileIface *iface;
4570
4571   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4572   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4573
4574   /* No standard handling of errors here, as we must set info even
4575    * on errors
4576    */
4577   iface = G_FILE_GET_IFACE (file);
4578   return (* iface->set_attributes_finish) (file, result, info, error);
4579 }
4580
4581 /**
4582  * g_file_set_attribute_string:
4583  * @file: input #GFile
4584  * @attribute: a string containing the attribute's name
4585  * @value: a string containing the attribute's value
4586  * @flags: #GFileQueryInfoFlags
4587  * @cancellable: (nullable): optional #GCancellable object,
4588  *     %NULL to ignore
4589  * @error: a #GError, or %NULL
4590  *
4591  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
4592  * If @attribute is of a different type, this operation will fail.
4593  *
4594  * If @cancellable is not %NULL, then the operation can be cancelled by
4595  * triggering the cancellable object from another thread. If the operation
4596  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4597  *
4598  * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4599  */
4600 gboolean
4601 g_file_set_attribute_string (GFile                *file,
4602                              const char           *attribute,
4603                              const char           *value,
4604                              GFileQueryInfoFlags   flags,
4605                              GCancellable         *cancellable,
4606                              GError              **error)
4607 {
4608   return g_file_set_attribute (file, attribute,
4609                                G_FILE_ATTRIBUTE_TYPE_STRING, (gpointer)value,
4610                                flags, cancellable, error);
4611 }
4612
4613 /**
4614  * g_file_set_attribute_byte_string:
4615  * @file: input #GFile
4616  * @attribute: a string containing the attribute's name
4617  * @value: a string containing the attribute's new value
4618  * @flags: a #GFileQueryInfoFlags
4619  * @cancellable: (nullable): optional #GCancellable object,
4620  *     %NULL to ignore
4621  * @error: a #GError, or %NULL
4622  *
4623  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
4624  * If @attribute is of a different type, this operation will fail,
4625  * returning %FALSE.
4626  *
4627  * If @cancellable is not %NULL, then the operation can be cancelled by
4628  * triggering the cancellable object from another thread. If the operation
4629  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4630  *
4631  * Returns: %TRUE if the @attribute was successfully set to @value
4632  *     in the @file, %FALSE otherwise.
4633  */
4634 gboolean
4635 g_file_set_attribute_byte_string  (GFile                *file,
4636                                    const gchar          *attribute,
4637                                    const gchar          *value,
4638                                    GFileQueryInfoFlags   flags,
4639                                    GCancellable         *cancellable,
4640                                    GError              **error)
4641 {
4642   return g_file_set_attribute (file, attribute,
4643                                G_FILE_ATTRIBUTE_TYPE_BYTE_STRING, (gpointer)value,
4644                                flags, cancellable, error);
4645 }
4646
4647 /**
4648  * g_file_set_attribute_uint32:
4649  * @file: input #GFile
4650  * @attribute: a string containing the attribute's name
4651  * @value: a #guint32 containing the attribute's new value
4652  * @flags: a #GFileQueryInfoFlags
4653  * @cancellable: (nullable): optional #GCancellable object,
4654  *     %NULL to ignore
4655  * @error: a #GError, or %NULL
4656  *
4657  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
4658  * If @attribute is of a different type, this operation will fail.
4659  *
4660  * If @cancellable is not %NULL, then the operation can be cancelled by
4661  * triggering the cancellable object from another thread. If the operation
4662  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4663  *
4664  * Returns: %TRUE if the @attribute was successfully set to @value
4665  *     in the @file, %FALSE otherwise.
4666  */
4667 gboolean
4668 g_file_set_attribute_uint32 (GFile                *file,
4669                              const gchar          *attribute,
4670                              guint32               value,
4671                              GFileQueryInfoFlags   flags,
4672                              GCancellable         *cancellable,
4673                              GError              **error)
4674 {
4675   return g_file_set_attribute (file, attribute,
4676                                G_FILE_ATTRIBUTE_TYPE_UINT32, &value,
4677                                flags, cancellable, error);
4678 }
4679
4680 /**
4681  * g_file_set_attribute_int32:
4682  * @file: input #GFile
4683  * @attribute: a string containing the attribute's name
4684  * @value: a #gint32 containing the attribute's new value
4685  * @flags: a #GFileQueryInfoFlags
4686  * @cancellable: (nullable): optional #GCancellable object,
4687  *     %NULL to ignore
4688  * @error: a #GError, or %NULL
4689  *
4690  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
4691  * If @attribute is of a different type, this operation will fail.
4692  *
4693  * If @cancellable is not %NULL, then the operation can be cancelled by
4694  * triggering the cancellable object from another thread. If the operation
4695  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4696  *
4697  * Returns: %TRUE if the @attribute was successfully set to @value
4698  *     in the @file, %FALSE otherwise.
4699  */
4700 gboolean
4701 g_file_set_attribute_int32 (GFile                *file,
4702                             const gchar          *attribute,
4703                             gint32                value,
4704                             GFileQueryInfoFlags   flags,
4705                             GCancellable         *cancellable,
4706                             GError              **error)
4707 {
4708   return g_file_set_attribute (file, attribute,
4709                                G_FILE_ATTRIBUTE_TYPE_INT32, &value,
4710                                flags, cancellable, error);
4711 }
4712
4713 /**
4714  * g_file_set_attribute_uint64:
4715  * @file: input #GFile
4716  * @attribute: a string containing the attribute's name
4717  * @value: a #guint64 containing the attribute's new value
4718  * @flags: a #GFileQueryInfoFlags
4719  * @cancellable: (nullable): optional #GCancellable object,
4720  *     %NULL to ignore
4721  * @error: a #GError, or %NULL
4722  *
4723  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
4724  * If @attribute is of a different type, this operation will fail.
4725  *
4726  * If @cancellable is not %NULL, then the operation can be cancelled by
4727  * triggering the cancellable object from another thread. If the operation
4728  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4729  *
4730  * Returns: %TRUE if the @attribute was successfully set to @value
4731  *     in the @file, %FALSE otherwise.
4732  */
4733 gboolean
4734 g_file_set_attribute_uint64 (GFile                *file,
4735                              const gchar          *attribute,
4736                              guint64               value,
4737                              GFileQueryInfoFlags   flags,
4738                              GCancellable         *cancellable,
4739                              GError              **error)
4740  {
4741   return g_file_set_attribute (file, attribute,
4742                                G_FILE_ATTRIBUTE_TYPE_UINT64, &value,
4743                                flags, cancellable, error);
4744 }
4745
4746 /**
4747  * g_file_set_attribute_int64:
4748  * @file: input #GFile
4749  * @attribute: a string containing the attribute's name
4750  * @value: a #guint64 containing the attribute's new value
4751  * @flags: a #GFileQueryInfoFlags
4752  * @cancellable: (nullable): optional #GCancellable object,
4753  *     %NULL to ignore
4754  * @error: a #GError, or %NULL
4755  *
4756  * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
4757  * If @attribute is of a different type, this operation will fail.
4758  *
4759  * If @cancellable is not %NULL, then the operation can be cancelled by
4760  * triggering the cancellable object from another thread. If the operation
4761  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4762  *
4763  * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
4764  */
4765 gboolean
4766 g_file_set_attribute_int64 (GFile                *file,
4767                             const gchar          *attribute,
4768                             gint64                value,
4769                             GFileQueryInfoFlags   flags,
4770                             GCancellable         *cancellable,
4771                             GError              **error)
4772 {
4773   return g_file_set_attribute (file, attribute,
4774                                G_FILE_ATTRIBUTE_TYPE_INT64, &value,
4775                                flags, cancellable, error);
4776 }
4777
4778 /**
4779  * g_file_mount_mountable:
4780  * @file: input #GFile
4781  * @flags: flags affecting the operation
4782  * @mount_operation: (nullable): a #GMountOperation,
4783  *     or %NULL to avoid user interaction
4784  * @cancellable: (nullable): optional #GCancellable object,
4785  *     %NULL to ignore
4786  * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
4787  *     when the request is satisfied, or %NULL
4788  * @user_data: (closure): the data to pass to callback function
4789  *
4790  * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
4791  * Using @mount_operation, you can request callbacks when, for instance,
4792  * passwords are needed during authentication.
4793  *
4794  * If @cancellable is not %NULL, then the operation can be cancelled by
4795  * triggering the cancellable object from another thread. If the operation
4796  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4797  *
4798  * When the operation is finished, @callback will be called.
4799  * You can then call g_file_mount_mountable_finish() to get
4800  * the result of the operation.
4801  */
4802 void
4803 g_file_mount_mountable (GFile               *file,
4804                         GMountMountFlags     flags,
4805                         GMountOperation     *mount_operation,
4806                         GCancellable        *cancellable,
4807                         GAsyncReadyCallback  callback,
4808                         gpointer             user_data)
4809 {
4810   GFileIface *iface;
4811
4812   g_return_if_fail (G_IS_FILE (file));
4813
4814   iface = G_FILE_GET_IFACE (file);
4815
4816   if (iface->mount_mountable == NULL)
4817     {
4818       g_task_report_new_error (file, callback, user_data,
4819                                g_file_mount_mountable,
4820                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4821                                _("Operation not supported"));
4822       return;
4823     }
4824
4825   (* iface->mount_mountable) (file,
4826                               flags,
4827                               mount_operation,
4828                               cancellable,
4829                               callback,
4830                               user_data);
4831 }
4832
4833 /**
4834  * g_file_mount_mountable_finish:
4835  * @file: input #GFile
4836  * @result: a #GAsyncResult
4837  * @error: a #GError, or %NULL
4838  *
4839  * Finishes a mount operation. See g_file_mount_mountable() for details.
4840  *
4841  * Finish an asynchronous mount operation that was started
4842  * with g_file_mount_mountable().
4843  *
4844  * Returns: (transfer full): a #GFile or %NULL on error.
4845  *     Free the returned object with g_object_unref().
4846  */
4847 GFile *
4848 g_file_mount_mountable_finish (GFile         *file,
4849                                GAsyncResult  *result,
4850                                GError       **error)
4851 {
4852   GFileIface *iface;
4853
4854   g_return_val_if_fail (G_IS_FILE (file), NULL);
4855   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
4856
4857   if (g_async_result_legacy_propagate_error (result, error))
4858     return NULL;
4859   else if (g_async_result_is_tagged (result, g_file_mount_mountable))
4860     return g_task_propagate_pointer (G_TASK (result), error);
4861
4862   iface = G_FILE_GET_IFACE (file);
4863   return (* iface->mount_mountable_finish) (file, result, error);
4864 }
4865
4866 /**
4867  * g_file_unmount_mountable:
4868  * @file: input #GFile
4869  * @flags: flags affecting the operation
4870  * @cancellable: (nullable): optional #GCancellable object,
4871  *     %NULL to ignore
4872  * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
4873  *     when the request is satisfied, or %NULL
4874  * @user_data: (closure): the data to pass to callback function
4875  *
4876  * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
4877  *
4878  * If @cancellable is not %NULL, then the operation can be cancelled by
4879  * triggering the cancellable object from another thread. If the operation
4880  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4881  *
4882  * When the operation is finished, @callback will be called.
4883  * You can then call g_file_unmount_mountable_finish() to get
4884  * the result of the operation.
4885  *
4886  * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
4887  */
4888 void
4889 g_file_unmount_mountable (GFile               *file,
4890                           GMountUnmountFlags   flags,
4891                           GCancellable        *cancellable,
4892                           GAsyncReadyCallback  callback,
4893                           gpointer             user_data)
4894 {
4895   GFileIface *iface;
4896
4897   g_return_if_fail (G_IS_FILE (file));
4898
4899   iface = G_FILE_GET_IFACE (file);
4900
4901   if (iface->unmount_mountable == NULL)
4902     {
4903       g_task_report_new_error (file, callback, user_data,
4904                                g_file_unmount_mountable_with_operation,
4905                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4906                                _("Operation not supported"));
4907       return;
4908     }
4909
4910   (* iface->unmount_mountable) (file,
4911                                 flags,
4912                                 cancellable,
4913                                 callback,
4914                                 user_data);
4915 }
4916
4917 /**
4918  * g_file_unmount_mountable_finish:
4919  * @file: input #GFile
4920  * @result: a #GAsyncResult
4921  * @error: a #GError, or %NULL
4922  *
4923  * Finishes an unmount operation, see g_file_unmount_mountable() for details.
4924  *
4925  * Finish an asynchronous unmount operation that was started
4926  * with g_file_unmount_mountable().
4927  *
4928  * Returns: %TRUE if the operation finished successfully.
4929  *     %FALSE otherwise.
4930  *
4931  * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
4932  *     instead.
4933  */
4934 gboolean
4935 g_file_unmount_mountable_finish (GFile         *file,
4936                                  GAsyncResult  *result,
4937                                  GError       **error)
4938 {
4939   GFileIface *iface;
4940
4941   g_return_val_if_fail (G_IS_FILE (file), FALSE);
4942   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
4943
4944   if (g_async_result_legacy_propagate_error (result, error))
4945     return FALSE;
4946   else if (g_async_result_is_tagged (result, g_file_unmount_mountable_with_operation))
4947     return g_task_propagate_boolean (G_TASK (result), error);
4948
4949   iface = G_FILE_GET_IFACE (file);
4950   return (* iface->unmount_mountable_finish) (file, result, error);
4951 }
4952
4953 /**
4954  * g_file_unmount_mountable_with_operation:
4955  * @file: input #GFile
4956  * @flags: flags affecting the operation
4957  * @mount_operation: (nullable): a #GMountOperation,
4958  *     or %NULL to avoid user interaction
4959  * @cancellable: (nullable): optional #GCancellable object,
4960  *     %NULL to ignore
4961  * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
4962  *     when the request is satisfied, or %NULL
4963  * @user_data: (closure): the data to pass to callback function
4964  *
4965  * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
4966  *
4967  * If @cancellable is not %NULL, then the operation can be cancelled by
4968  * triggering the cancellable object from another thread. If the operation
4969  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
4970  *
4971  * When the operation is finished, @callback will be called.
4972  * You can then call g_file_unmount_mountable_finish() to get
4973  * the result of the operation.
4974  *
4975  * Since: 2.22
4976  */
4977 void
4978 g_file_unmount_mountable_with_operation (GFile               *file,
4979                                          GMountUnmountFlags   flags,
4980                                          GMountOperation     *mount_operation,
4981                                          GCancellable        *cancellable,
4982                                          GAsyncReadyCallback  callback,
4983                                          gpointer             user_data)
4984 {
4985   GFileIface *iface;
4986
4987   g_return_if_fail (G_IS_FILE (file));
4988
4989   iface = G_FILE_GET_IFACE (file);
4990
4991   if (iface->unmount_mountable == NULL && iface->unmount_mountable_with_operation == NULL)
4992     {
4993       g_task_report_new_error (file, callback, user_data,
4994                                g_file_unmount_mountable_with_operation,
4995                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
4996                                _("Operation not supported"));
4997       return;
4998     }
4999
5000   if (iface->unmount_mountable_with_operation != NULL)
5001     (* iface->unmount_mountable_with_operation) (file,
5002                                                  flags,
5003                                                  mount_operation,
5004                                                  cancellable,
5005                                                  callback,
5006                                                  user_data);
5007   else
5008     (* iface->unmount_mountable) (file,
5009                                   flags,
5010                                   cancellable,
5011                                   callback,
5012                                   user_data);
5013 }
5014
5015 /**
5016  * g_file_unmount_mountable_with_operation_finish:
5017  * @file: input #GFile
5018  * @result: a #GAsyncResult
5019  * @error: a #GError, or %NULL
5020  *
5021  * Finishes an unmount operation,
5022  * see g_file_unmount_mountable_with_operation() for details.
5023  *
5024  * Finish an asynchronous unmount operation that was started
5025  * with g_file_unmount_mountable_with_operation().
5026  *
5027  * Returns: %TRUE if the operation finished successfully.
5028  *     %FALSE otherwise.
5029  *
5030  * Since: 2.22
5031  */
5032 gboolean
5033 g_file_unmount_mountable_with_operation_finish (GFile         *file,
5034                                                 GAsyncResult  *result,
5035                                                 GError       **error)
5036 {
5037   GFileIface *iface;
5038
5039   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5040   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5041
5042   if (g_async_result_legacy_propagate_error (result, error))
5043     return FALSE;
5044   else if (g_async_result_is_tagged (result, g_file_unmount_mountable_with_operation))
5045     return g_task_propagate_boolean (G_TASK (result), error);
5046
5047   iface = G_FILE_GET_IFACE (file);
5048   if (iface->unmount_mountable_with_operation_finish != NULL)
5049     return (* iface->unmount_mountable_with_operation_finish) (file, result, error);
5050   else
5051     return (* iface->unmount_mountable_finish) (file, result, error);
5052 }
5053
5054 /**
5055  * g_file_eject_mountable:
5056  * @file: input #GFile
5057  * @flags: flags affecting the operation
5058  * @cancellable: (nullable): optional #GCancellable object,
5059  *     %NULL to ignore
5060  * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
5061  *     when the request is satisfied, or %NULL
5062  * @user_data: (closure): the data to pass to callback function
5063  *
5064  * Starts an asynchronous eject on a mountable.
5065  * When this operation has completed, @callback will be called with
5066  * @user_user data, and the operation can be finalized with
5067  * g_file_eject_mountable_finish().
5068  *
5069  * If @cancellable is not %NULL, then the operation can be cancelled by
5070  * triggering the cancellable object from another thread. If the operation
5071  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5072  *
5073  * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
5074  */
5075 void
5076 g_file_eject_mountable (GFile               *file,
5077                         GMountUnmountFlags   flags,
5078                         GCancellable        *cancellable,
5079                         GAsyncReadyCallback  callback,
5080                         gpointer             user_data)
5081 {
5082   GFileIface *iface;
5083
5084   g_return_if_fail (G_IS_FILE (file));
5085
5086   iface = G_FILE_GET_IFACE (file);
5087
5088   if (iface->eject_mountable == NULL)
5089     {
5090       g_task_report_new_error (file, callback, user_data,
5091                                g_file_eject_mountable_with_operation,
5092                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5093                                _("Operation not supported"));
5094       return;
5095     }
5096
5097   (* iface->eject_mountable) (file,
5098                               flags,
5099                               cancellable,
5100                               callback,
5101                               user_data);
5102 }
5103
5104 /**
5105  * g_file_eject_mountable_finish:
5106  * @file: input #GFile
5107  * @result: a #GAsyncResult
5108  * @error: a #GError, or %NULL
5109  *
5110  * Finishes an asynchronous eject operation started by
5111  * g_file_eject_mountable().
5112  *
5113  * Returns: %TRUE if the @file was ejected successfully.
5114  *     %FALSE otherwise.
5115  *
5116  * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
5117  *     instead.
5118  */
5119 gboolean
5120 g_file_eject_mountable_finish (GFile         *file,
5121                                GAsyncResult  *result,
5122                                GError       **error)
5123 {
5124   GFileIface *iface;
5125
5126   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5127   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5128
5129   if (g_async_result_legacy_propagate_error (result, error))
5130     return FALSE;
5131   else if (g_async_result_is_tagged (result, g_file_eject_mountable_with_operation))
5132     return g_task_propagate_boolean (G_TASK (result), error);
5133
5134   iface = G_FILE_GET_IFACE (file);
5135   return (* iface->eject_mountable_finish) (file, result, error);
5136 }
5137
5138 /**
5139  * g_file_eject_mountable_with_operation:
5140  * @file: input #GFile
5141  * @flags: flags affecting the operation
5142  * @mount_operation: (nullable): a #GMountOperation,
5143  *     or %NULL to avoid user interaction
5144  * @cancellable: (nullable): optional #GCancellable object,
5145  *     %NULL to ignore
5146  * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
5147  *     when the request is satisfied, or %NULL
5148  * @user_data: (closure): the data to pass to callback function
5149  *
5150  * Starts an asynchronous eject on a mountable.
5151  * When this operation has completed, @callback will be called with
5152  * @user_user data, and the operation can be finalized with
5153  * g_file_eject_mountable_with_operation_finish().
5154  *
5155  * If @cancellable is not %NULL, then the operation can be cancelled by
5156  * triggering the cancellable object from another thread. If the operation
5157  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5158  *
5159  * Since: 2.22
5160  */
5161 void
5162 g_file_eject_mountable_with_operation (GFile               *file,
5163                                        GMountUnmountFlags   flags,
5164                                        GMountOperation     *mount_operation,
5165                                        GCancellable        *cancellable,
5166                                        GAsyncReadyCallback  callback,
5167                                        gpointer             user_data)
5168 {
5169   GFileIface *iface;
5170
5171   g_return_if_fail (G_IS_FILE (file));
5172
5173   iface = G_FILE_GET_IFACE (file);
5174
5175   if (iface->eject_mountable == NULL && iface->eject_mountable_with_operation == NULL)
5176     {
5177       g_task_report_new_error (file, callback, user_data,
5178                                g_file_eject_mountable_with_operation,
5179                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
5180                                _("Operation not supported"));
5181       return;
5182     }
5183
5184   if (iface->eject_mountable_with_operation != NULL)
5185     (* iface->eject_mountable_with_operation) (file,
5186                                                flags,
5187                                                mount_operation,
5188                                                cancellable,
5189                                                callback,
5190                                                user_data);
5191   else
5192     (* iface->eject_mountable) (file,
5193                                 flags,
5194                                 cancellable,
5195                                 callback,
5196                                 user_data);
5197 }
5198
5199 /**
5200  * g_file_eject_mountable_with_operation_finish:
5201  * @file: input #GFile
5202  * @result: a #GAsyncResult
5203  * @error: a #GError, or %NULL
5204  *
5205  * Finishes an asynchronous eject operation started by
5206  * g_file_eject_mountable_with_operation().
5207  *
5208  * Returns: %TRUE if the @file was ejected successfully.
5209  *     %FALSE otherwise.
5210  *
5211  * Since: 2.22
5212  */
5213 gboolean
5214 g_file_eject_mountable_with_operation_finish (GFile         *file,
5215                                               GAsyncResult  *result,
5216                                               GError       **error)
5217 {
5218   GFileIface *iface;
5219
5220   g_return_val_if_fail (G_IS_FILE (file), FALSE);
5221   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
5222
5223   if (g_async_result_legacy_propagate_error (result, error))
5224     return FALSE;
5225   else if (g_async_result_is_tagged (result, g_file_eject_mountable_with_operation))
5226     return g_task_propagate_boolean (G_TASK (result), error);
5227
5228   iface = G_FILE_GET_IFACE (file);
5229   if (iface->eject_mountable_with_operation_finish != NULL)
5230     return (* iface->eject_mountable_with_operation_finish) (file, result, error);
5231   else
5232     return (* iface->eject_mountable_finish) (file, result, error);
5233 }
5234
5235 /**
5236  * g_file_monitor_directory:
5237  * @file: input #GFile
5238  * @flags: a set of #GFileMonitorFlags
5239  * @cancellable: (nullable): optional #GCancellable object,
5240  *     %NULL to ignore
5241  * @error: a #GError, or %NULL
5242  *
5243  * Obtains a directory monitor for the given file.
5244  * This may fail if directory monitoring is not supported.
5245  *
5246  * If @cancellable is not %NULL, then the operation can be cancelled by
5247  * triggering the cancellable object from another thread. If the operation
5248  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5249  *
5250  * It does not make sense for @flags to contain
5251  * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
5252  * directories.  It is not possible to monitor all the files in a
5253  * directory for changes made via hard links; if you want to do this then
5254  * you must register individual watches with g_file_monitor().
5255  *
5256  * Virtual: monitor_dir
5257  * Returns: (transfer full): a #GFileMonitor for the given @file,
5258  *     or %NULL on error.
5259  *     Free the returned object with g_object_unref().
5260  */
5261 GFileMonitor *
5262 g_file_monitor_directory (GFile              *file,
5263                           GFileMonitorFlags   flags,
5264                           GCancellable       *cancellable,
5265                           GError            **error)
5266 {
5267   GFileIface *iface;
5268
5269   g_return_val_if_fail (G_IS_FILE (file), NULL);
5270   g_return_val_if_fail (~flags & G_FILE_MONITOR_WATCH_HARD_LINKS, NULL);
5271
5272   if (g_cancellable_set_error_if_cancelled (cancellable, error))
5273     return NULL;
5274
5275   iface = G_FILE_GET_IFACE (file);
5276
5277   if (iface->monitor_dir == NULL)
5278     {
5279       g_set_error_literal (error, G_IO_ERROR,
5280                            G_IO_ERROR_NOT_SUPPORTED,
5281                            _("Operation not supported"));
5282       return NULL;
5283     }
5284
5285   return (* iface->monitor_dir) (file, flags, cancellable, error);
5286 }
5287
5288 /**
5289  * g_file_monitor_file:
5290  * @file: input #GFile
5291  * @flags: a set of #GFileMonitorFlags
5292  * @cancellable: (nullable): optional #GCancellable object,
5293  *     %NULL to ignore
5294  * @error: a #GError, or %NULL
5295  *
5296  * Obtains a file monitor for the given file. If no file notification
5297  * mechanism exists, then regular polling of the file is used.
5298  *
5299  * If @cancellable is not %NULL, then the operation can be cancelled by
5300  * triggering the cancellable object from another thread. If the operation
5301  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5302  *
5303  * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
5304  * will also attempt to report changes made to the file via another
5305  * filename (ie, a hard link). Without this flag, you can only rely on
5306  * changes made through the filename contained in @file to be
5307  * reported. Using this flag may result in an increase in resource
5308  * usage, and may not have any effect depending on the #GFileMonitor
5309  * backend and/or filesystem type.
5310  *
5311  * Returns: (transfer full): a #GFileMonitor for the given @file,
5312  *     or %NULL on error.
5313  *     Free the returned object with g_object_unref().
5314  */
5315 GFileMonitor *
5316 g_file_monitor_file (GFile              *file,
5317                      GFileMonitorFlags   flags,
5318                      GCancellable       *cancellable,
5319                      GError            **error)
5320 {
5321   GFileIface *iface;
5322   GFileMonitor *monitor;
5323
5324   g_return_val_if_fail (G_IS_FILE (file), NULL);
5325
5326   if (g_cancellable_set_error_if_cancelled (cancellable, error))
5327     return NULL;
5328
5329   iface = G_FILE_GET_IFACE (file);
5330
5331   monitor = NULL;
5332
5333   if (iface->monitor_file)
5334     monitor = (* iface->monitor_file) (file, flags, cancellable, NULL);
5335
5336   /* Fallback to polling */
5337   if (monitor == NULL)
5338     monitor = _g_poll_file_monitor_new (file);
5339
5340   return monitor;
5341 }
5342
5343 /**
5344  * g_file_monitor:
5345  * @file: input #GFile
5346  * @flags: a set of #GFileMonitorFlags
5347  * @cancellable: (nullable): optional #GCancellable object,
5348  *     %NULL to ignore
5349  * @error: a #GError, or %NULL
5350  *
5351  * Obtains a file or directory monitor for the given file,
5352  * depending on the type of the file.
5353  *
5354  * If @cancellable is not %NULL, then the operation can be cancelled by
5355  * triggering the cancellable object from another thread. If the operation
5356  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
5357  *
5358  * Returns: (transfer full): a #GFileMonitor for the given @file,
5359  *     or %NULL on error.
5360  *     Free the returned object with g_object_unref().
5361  *
5362  * Since: 2.18
5363  */
5364 GFileMonitor *
5365 g_file_monitor (GFile              *file,
5366                 GFileMonitorFlags   flags,
5367                 GCancellable       *cancellable,
5368                 GError            **error)
5369 {
5370   if (g_file_query_file_type (file, 0, cancellable) == G_FILE_TYPE_DIRECTORY)
5371     return g_file_monitor_directory (file,
5372                                      flags & ~G_FILE_MONITOR_WATCH_HARD_LINKS,
5373                                      cancellable, error);
5374   else
5375     return g_file_monitor_file (file, flags, cancellable, error);
5376 }
5377
5378 /********************************************
5379  *   Default implementation of async ops    *
5380  ********************************************/
5381
5382 typedef struct {
5383   char *attributes;
5384   GFileQueryInfoFlags flags;
5385 } QueryInfoAsyncData;
5386
5387 static void
5388 query_info_data_free (QueryInfoAsyncData *data)
5389 {
5390   g_free (data->attributes);
5391   g_free (data);
5392 }
5393
5394 static void
5395 query_info_async_thread (GTask         *task,
5396                          gpointer       object,
5397                          gpointer       task_data,
5398                          GCancellable  *cancellable)
5399 {
5400   QueryInfoAsyncData *data = task_data;
5401   GFileInfo *info;
5402   GError *error = NULL;
5403
5404   info = g_file_query_info (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5405   if (info)
5406     g_task_return_pointer (task, info, g_object_unref);
5407   else
5408     g_task_return_error (task, error);
5409 }
5410
5411 static void
5412 g_file_real_query_info_async (GFile               *file,
5413                               const char          *attributes,
5414                               GFileQueryInfoFlags  flags,
5415                               int                  io_priority,
5416                               GCancellable        *cancellable,
5417                               GAsyncReadyCallback  callback,
5418                               gpointer             user_data)
5419 {
5420   GTask *task;
5421   QueryInfoAsyncData *data;
5422
5423   data = g_new0 (QueryInfoAsyncData, 1);
5424   data->attributes = g_strdup (attributes);
5425   data->flags = flags;
5426
5427   task = g_task_new (file, cancellable, callback, user_data);
5428   g_task_set_source_tag (task, g_file_real_query_info_async);
5429   g_task_set_task_data (task, data, (GDestroyNotify)query_info_data_free);
5430   g_task_set_priority (task, io_priority);
5431   g_task_run_in_thread (task, query_info_async_thread);
5432   g_object_unref (task);
5433 }
5434
5435 static GFileInfo *
5436 g_file_real_query_info_finish (GFile         *file,
5437                                GAsyncResult  *res,
5438                                GError       **error)
5439 {
5440   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5441
5442   return g_task_propagate_pointer (G_TASK (res), error);
5443 }
5444
5445 static void
5446 query_filesystem_info_async_thread (GTask         *task,
5447                                     gpointer       object,
5448                                     gpointer       task_data,
5449                                     GCancellable  *cancellable)
5450 {
5451   const char *attributes = task_data;
5452   GFileInfo *info;
5453   GError *error = NULL;
5454
5455   info = g_file_query_filesystem_info (G_FILE (object), attributes, cancellable, &error);
5456   if (info)
5457     g_task_return_pointer (task, info, g_object_unref);
5458   else
5459     g_task_return_error (task, error);
5460 }
5461
5462 static void
5463 g_file_real_query_filesystem_info_async (GFile               *file,
5464                                          const char          *attributes,
5465                                          int                  io_priority,
5466                                          GCancellable        *cancellable,
5467                                          GAsyncReadyCallback  callback,
5468                                          gpointer             user_data)
5469 {
5470   GTask *task;
5471
5472   task = g_task_new (file, cancellable, callback, user_data);
5473   g_task_set_source_tag (task, g_file_real_query_filesystem_info_async);
5474   g_task_set_task_data (task, g_strdup (attributes), g_free);
5475   g_task_set_priority (task, io_priority);
5476   g_task_run_in_thread (task, query_filesystem_info_async_thread);
5477   g_object_unref (task);
5478 }
5479
5480 static GFileInfo *
5481 g_file_real_query_filesystem_info_finish (GFile         *file,
5482                                           GAsyncResult  *res,
5483                                           GError       **error)
5484 {
5485   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5486
5487   return g_task_propagate_pointer (G_TASK (res), error);
5488 }
5489
5490 static void
5491 enumerate_children_async_thread (GTask         *task,
5492                                  gpointer       object,
5493                                  gpointer       task_data,
5494                                  GCancellable  *cancellable)
5495 {
5496   QueryInfoAsyncData *data = task_data;
5497   GFileEnumerator *enumerator;
5498   GError *error = NULL;
5499
5500   enumerator = g_file_enumerate_children (G_FILE (object), data->attributes, data->flags, cancellable, &error);
5501   if (error)
5502     g_task_return_error (task, error);
5503   else
5504     g_task_return_pointer (task, enumerator, g_object_unref);
5505 }
5506
5507 static void
5508 g_file_real_enumerate_children_async (GFile               *file,
5509                                       const char          *attributes,
5510                                       GFileQueryInfoFlags  flags,
5511                                       int                  io_priority,
5512                                       GCancellable        *cancellable,
5513                                       GAsyncReadyCallback  callback,
5514                                       gpointer             user_data)
5515 {
5516   GTask *task;
5517   QueryInfoAsyncData *data;
5518
5519   data = g_new0 (QueryInfoAsyncData, 1);
5520   data->attributes = g_strdup (attributes);
5521   data->flags = flags;
5522
5523   task = g_task_new (file, cancellable, callback, user_data);
5524   g_task_set_source_tag (task, g_file_real_enumerate_children_async);
5525   g_task_set_task_data (task, data, (GDestroyNotify)query_info_data_free);
5526   g_task_set_priority (task, io_priority);
5527   g_task_run_in_thread (task, enumerate_children_async_thread);
5528   g_object_unref (task);
5529 }
5530
5531 static GFileEnumerator *
5532 g_file_real_enumerate_children_finish (GFile         *file,
5533                                        GAsyncResult  *res,
5534                                        GError       **error)
5535 {
5536   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5537
5538   return g_task_propagate_pointer (G_TASK (res), error);
5539 }
5540
5541 static void
5542 open_read_async_thread (GTask         *task,
5543                         gpointer       object,
5544                         gpointer       task_data,
5545                         GCancellable  *cancellable)
5546 {
5547   GFileInputStream *stream;
5548   GError *error = NULL;
5549
5550   stream = g_file_read (G_FILE (object), cancellable, &error);
5551   if (stream)
5552     g_task_return_pointer (task, stream, g_object_unref);
5553   else
5554     g_task_return_error (task, error);
5555 }
5556
5557 static void
5558 g_file_real_read_async (GFile               *file,
5559                         int                  io_priority,
5560                         GCancellable        *cancellable,
5561                         GAsyncReadyCallback  callback,
5562                         gpointer             user_data)
5563 {
5564   GTask *task;
5565
5566   task = g_task_new (file, cancellable, callback, user_data);
5567   g_task_set_source_tag (task, g_file_real_read_async);
5568   g_task_set_priority (task, io_priority);
5569   g_task_run_in_thread (task, open_read_async_thread);
5570   g_object_unref (task);
5571 }
5572
5573 static GFileInputStream *
5574 g_file_real_read_finish (GFile         *file,
5575                          GAsyncResult  *res,
5576                          GError       **error)
5577 {
5578   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5579
5580   return g_task_propagate_pointer (G_TASK (res), error);
5581 }
5582
5583 static void
5584 append_to_async_thread (GTask         *task,
5585                         gpointer       source_object,
5586                         gpointer       task_data,
5587                         GCancellable  *cancellable)
5588 {
5589   GFileCreateFlags *data = task_data;
5590   GFileOutputStream *stream;
5591   GError *error = NULL;
5592
5593   stream = g_file_append_to (G_FILE (source_object), *data, cancellable, &error);
5594   if (stream)
5595     g_task_return_pointer (task, stream, g_object_unref);
5596   else
5597     g_task_return_error (task, error);
5598 }
5599
5600 static void
5601 g_file_real_append_to_async (GFile               *file,
5602                              GFileCreateFlags     flags,
5603                              int                  io_priority,
5604                              GCancellable        *cancellable,
5605                              GAsyncReadyCallback  callback,
5606                              gpointer             user_data)
5607 {
5608   GFileCreateFlags *data;
5609   GTask *task;
5610
5611   data = g_new0 (GFileCreateFlags, 1);
5612   *data = flags;
5613
5614   task = g_task_new (file, cancellable, callback, user_data);
5615   g_task_set_source_tag (task, g_file_real_append_to_async);
5616   g_task_set_task_data (task, data, g_free);
5617   g_task_set_priority (task, io_priority);
5618
5619   g_task_run_in_thread (task, append_to_async_thread);
5620   g_object_unref (task);
5621 }
5622
5623 static GFileOutputStream *
5624 g_file_real_append_to_finish (GFile         *file,
5625                               GAsyncResult  *res,
5626                               GError       **error)
5627 {
5628   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5629
5630   return g_task_propagate_pointer (G_TASK (res), error);
5631 }
5632
5633 static void
5634 create_async_thread (GTask         *task,
5635                      gpointer       source_object,
5636                      gpointer       task_data,
5637                      GCancellable  *cancellable)
5638 {
5639   GFileCreateFlags *data = task_data;
5640   GFileOutputStream *stream;
5641   GError *error = NULL;
5642
5643   stream = g_file_create (G_FILE (source_object), *data, cancellable, &error);
5644   if (stream)
5645     g_task_return_pointer (task, stream, g_object_unref);
5646   else
5647     g_task_return_error (task, error);
5648 }
5649
5650 static void
5651 g_file_real_create_async (GFile               *file,
5652                           GFileCreateFlags     flags,
5653                           int                  io_priority,
5654                           GCancellable        *cancellable,
5655                           GAsyncReadyCallback  callback,
5656                           gpointer             user_data)
5657 {
5658   GFileCreateFlags *data;
5659   GTask *task;
5660
5661   data = g_new0 (GFileCreateFlags, 1);
5662   *data = flags;
5663
5664   task = g_task_new (file, cancellable, callback, user_data);
5665   g_task_set_source_tag (task, g_file_real_create_async);
5666   g_task_set_task_data (task, data, g_free);
5667   g_task_set_priority (task, io_priority);
5668
5669   g_task_run_in_thread (task, create_async_thread);
5670   g_object_unref (task);
5671 }
5672
5673 static GFileOutputStream *
5674 g_file_real_create_finish (GFile         *file,
5675                            GAsyncResult  *res,
5676                            GError       **error)
5677 {
5678   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5679
5680   return g_task_propagate_pointer (G_TASK (res), error);
5681 }
5682
5683 typedef struct {
5684   GFileOutputStream *stream;
5685   char *etag;
5686   gboolean make_backup;
5687   GFileCreateFlags flags;
5688 } ReplaceAsyncData;
5689
5690 static void
5691 replace_async_data_free (ReplaceAsyncData *data)
5692 {
5693   if (data->stream)
5694     g_object_unref (data->stream);
5695   g_free (data->etag);
5696   g_free (data);
5697 }
5698
5699 static void
5700 replace_async_thread (GTask         *task,
5701                       gpointer       source_object,
5702                       gpointer       task_data,
5703                       GCancellable  *cancellable)
5704 {
5705   GFileOutputStream *stream;
5706   ReplaceAsyncData *data = task_data;
5707   GError *error = NULL;
5708
5709   stream = g_file_replace (G_FILE (source_object),
5710                            data->etag,
5711                            data->make_backup,
5712                            data->flags,
5713                            cancellable,
5714                            &error);
5715
5716   if (stream)
5717     g_task_return_pointer (task, stream, g_object_unref);
5718   else
5719     g_task_return_error (task, error);
5720 }
5721
5722 static void
5723 g_file_real_replace_async (GFile               *file,
5724                            const char          *etag,
5725                            gboolean             make_backup,
5726                            GFileCreateFlags     flags,
5727                            int                  io_priority,
5728                            GCancellable        *cancellable,
5729                            GAsyncReadyCallback  callback,
5730                            gpointer             user_data)
5731 {
5732   GTask *task;
5733   ReplaceAsyncData *data;
5734
5735   data = g_new0 (ReplaceAsyncData, 1);
5736   data->etag = g_strdup (etag);
5737   data->make_backup = make_backup;
5738   data->flags = flags;
5739
5740   task = g_task_new (file, cancellable, callback, user_data);
5741   g_task_set_source_tag (task, g_file_real_replace_async);
5742   g_task_set_task_data (task, data, (GDestroyNotify)replace_async_data_free);
5743   g_task_set_priority (task, io_priority);
5744
5745   g_task_run_in_thread (task, replace_async_thread);
5746   g_object_unref (task);
5747 }
5748
5749 static GFileOutputStream *
5750 g_file_real_replace_finish (GFile         *file,
5751                             GAsyncResult  *res,
5752                             GError       **error)
5753 {
5754   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5755
5756   return g_task_propagate_pointer (G_TASK (res), error);
5757 }
5758
5759 static void
5760 delete_async_thread (GTask        *task,
5761                      gpointer      object,
5762                      gpointer      task_data,
5763                      GCancellable *cancellable)
5764 {
5765   GError *error = NULL;
5766
5767   if (g_file_delete (G_FILE (object), cancellable, &error))
5768     g_task_return_boolean (task, TRUE);
5769   else
5770     g_task_return_error (task, error);
5771 }
5772
5773 static void
5774 g_file_real_delete_async (GFile               *file,
5775                           int                  io_priority,
5776                           GCancellable        *cancellable,
5777                           GAsyncReadyCallback  callback,
5778                           gpointer             user_data)
5779 {
5780   GTask *task;
5781
5782   task = g_task_new (file, cancellable, callback, user_data);
5783   g_task_set_source_tag (task, g_file_real_delete_async);
5784   g_task_set_priority (task, io_priority);
5785   g_task_run_in_thread (task, delete_async_thread);
5786   g_object_unref (task);
5787 }
5788
5789 static gboolean
5790 g_file_real_delete_finish (GFile         *file,
5791                            GAsyncResult  *res,
5792                            GError       **error)
5793 {
5794   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
5795
5796   return g_task_propagate_boolean (G_TASK (res), error);
5797 }
5798
5799 static void
5800 trash_async_thread (GTask        *task,
5801                     gpointer      object,
5802                     gpointer      task_data,
5803                     GCancellable *cancellable)
5804 {
5805   GError *error = NULL;
5806
5807   if (g_file_trash (G_FILE (object), cancellable, &error))
5808     g_task_return_boolean (task, TRUE);
5809   else
5810     g_task_return_error (task, error);
5811 }
5812
5813 static void
5814 g_file_real_trash_async (GFile               *file,
5815                          int                  io_priority,
5816                          GCancellable        *cancellable,
5817                          GAsyncReadyCallback  callback,
5818                          gpointer             user_data)
5819 {
5820   GTask *task;
5821
5822   task = g_task_new (file, cancellable, callback, user_data);
5823   g_task_set_source_tag (task, g_file_real_trash_async);
5824   g_task_set_priority (task, io_priority);
5825   g_task_run_in_thread (task, trash_async_thread);
5826   g_object_unref (task);
5827 }
5828
5829 static gboolean
5830 g_file_real_trash_finish (GFile         *file,
5831                           GAsyncResult  *res,
5832                           GError       **error)
5833 {
5834   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
5835
5836   return g_task_propagate_boolean (G_TASK (res), error);
5837 }
5838
5839 static void
5840 make_directory_async_thread (GTask        *task,
5841                              gpointer      object,
5842                              gpointer      task_data,
5843                              GCancellable *cancellable)
5844 {
5845   GError *error = NULL;
5846
5847   if (g_file_make_directory (G_FILE (object), cancellable, &error))
5848     g_task_return_boolean (task, TRUE);
5849   else
5850     g_task_return_error (task, error);
5851 }
5852
5853 static void
5854 g_file_real_make_directory_async (GFile               *file,
5855                                   int                  io_priority,
5856                                   GCancellable        *cancellable,
5857                                   GAsyncReadyCallback  callback,
5858                                   gpointer             user_data)
5859 {
5860   GTask *task;
5861
5862   task = g_task_new (file, cancellable, callback, user_data);
5863   g_task_set_source_tag (task, g_file_real_make_directory_async);
5864   g_task_set_priority (task, io_priority);
5865   g_task_run_in_thread (task, make_directory_async_thread);
5866   g_object_unref (task);
5867 }
5868
5869 static gboolean
5870 g_file_real_make_directory_finish (GFile         *file,
5871                                    GAsyncResult  *res,
5872                                    GError       **error)
5873 {
5874   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
5875
5876   return g_task_propagate_boolean (G_TASK (res), error);
5877 }
5878
5879 static void
5880 open_readwrite_async_thread (GTask        *task,
5881                              gpointer      object,
5882                              gpointer      task_data,
5883                              GCancellable *cancellable)
5884 {
5885   GFileIOStream *stream;
5886   GError *error = NULL;
5887
5888   stream = g_file_open_readwrite (G_FILE (object), cancellable, &error);
5889
5890   if (stream == NULL)
5891     g_task_return_error (task, error);
5892   else
5893     g_task_return_pointer (task, stream, g_object_unref);
5894 }
5895
5896 static void
5897 g_file_real_open_readwrite_async (GFile               *file,
5898                                   int                  io_priority,
5899                                   GCancellable        *cancellable,
5900                                   GAsyncReadyCallback  callback,
5901                                   gpointer             user_data)
5902 {
5903   GTask *task;
5904
5905   task = g_task_new (file, cancellable, callback, user_data);
5906   g_task_set_source_tag (task, g_file_real_open_readwrite_async);
5907   g_task_set_priority (task, io_priority);
5908
5909   g_task_run_in_thread (task, open_readwrite_async_thread);
5910   g_object_unref (task);
5911 }
5912
5913 static GFileIOStream *
5914 g_file_real_open_readwrite_finish (GFile         *file,
5915                                    GAsyncResult  *res,
5916                                    GError       **error)
5917 {
5918   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5919
5920   return g_task_propagate_pointer (G_TASK (res), error);
5921 }
5922
5923 static void
5924 create_readwrite_async_thread (GTask        *task,
5925                                gpointer      object,
5926                                gpointer      task_data,
5927                                GCancellable *cancellable)
5928 {
5929   GFileCreateFlags *data = task_data;
5930   GFileIOStream *stream;
5931   GError *error = NULL;
5932
5933   stream = g_file_create_readwrite (G_FILE (object), *data, cancellable, &error);
5934
5935   if (stream == NULL)
5936     g_task_return_error (task, error);
5937   else
5938     g_task_return_pointer (task, stream, g_object_unref);
5939 }
5940
5941 static void
5942 g_file_real_create_readwrite_async (GFile               *file,
5943                                     GFileCreateFlags     flags,
5944                                     int                  io_priority,
5945                                     GCancellable        *cancellable,
5946                                     GAsyncReadyCallback  callback,
5947                                     gpointer             user_data)
5948 {
5949   GFileCreateFlags *data;
5950   GTask *task;
5951
5952   data = g_new0 (GFileCreateFlags, 1);
5953   *data = flags;
5954
5955   task = g_task_new (file, cancellable, callback, user_data);
5956   g_task_set_source_tag (task, g_file_real_create_readwrite_async);
5957   g_task_set_task_data (task, data, g_free);
5958   g_task_set_priority (task, io_priority);
5959
5960   g_task_run_in_thread (task, create_readwrite_async_thread);
5961   g_object_unref (task);
5962 }
5963
5964 static GFileIOStream *
5965 g_file_real_create_readwrite_finish (GFile         *file,
5966                                      GAsyncResult  *res,
5967                                      GError       **error)
5968 {
5969   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
5970
5971   return g_task_propagate_pointer (G_TASK (res), error);
5972 }
5973
5974 typedef struct {
5975   char *etag;
5976   gboolean make_backup;
5977   GFileCreateFlags flags;
5978 } ReplaceRWAsyncData;
5979
5980 static void
5981 replace_rw_async_data_free (ReplaceRWAsyncData *data)
5982 {
5983   g_free (data->etag);
5984   g_free (data);
5985 }
5986
5987 static void
5988 replace_readwrite_async_thread (GTask        *task,
5989                                 gpointer      object,
5990                                 gpointer      task_data,
5991                                 GCancellable *cancellable)
5992 {
5993   GFileIOStream *stream;
5994   GError *error = NULL;
5995   ReplaceRWAsyncData *data = task_data;
5996
5997   stream = g_file_replace_readwrite (G_FILE (object),
5998                                      data->etag,
5999                                      data->make_backup,
6000                                      data->flags,
6001                                      cancellable,
6002                                      &error);
6003
6004   if (stream == NULL)
6005     g_task_return_error (task, error);
6006   else
6007     g_task_return_pointer (task, stream, g_object_unref);
6008 }
6009
6010 static void
6011 g_file_real_replace_readwrite_async (GFile               *file,
6012                                      const char          *etag,
6013                                      gboolean             make_backup,
6014                                      GFileCreateFlags     flags,
6015                                      int                  io_priority,
6016                                      GCancellable        *cancellable,
6017                                      GAsyncReadyCallback  callback,
6018                                      gpointer             user_data)
6019 {
6020   GTask *task;
6021   ReplaceRWAsyncData *data;
6022
6023   data = g_new0 (ReplaceRWAsyncData, 1);
6024   data->etag = g_strdup (etag);
6025   data->make_backup = make_backup;
6026   data->flags = flags;
6027
6028   task = g_task_new (file, cancellable, callback, user_data);
6029   g_task_set_source_tag (task, g_file_real_replace_readwrite_async);
6030   g_task_set_task_data (task, data, (GDestroyNotify)replace_rw_async_data_free);
6031   g_task_set_priority (task, io_priority);
6032
6033   g_task_run_in_thread (task, replace_readwrite_async_thread);
6034   g_object_unref (task);
6035 }
6036
6037 static GFileIOStream *
6038 g_file_real_replace_readwrite_finish (GFile         *file,
6039                                       GAsyncResult  *res,
6040                                       GError       **error)
6041 {
6042   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6043
6044   return g_task_propagate_pointer (G_TASK (res), error);
6045 }
6046
6047 static void
6048 set_display_name_async_thread (GTask        *task,
6049                                gpointer      object,
6050                                gpointer      task_data,
6051                                GCancellable *cancellable)
6052 {
6053   GError *error = NULL;
6054   char *name = task_data;
6055   GFile *file;
6056
6057   file = g_file_set_display_name (G_FILE (object), name, cancellable, &error);
6058
6059   if (file == NULL)
6060     g_task_return_error (task, error);
6061   else
6062     g_task_return_pointer (task, file, g_object_unref);
6063 }
6064
6065 static void
6066 g_file_real_set_display_name_async (GFile               *file,
6067                                     const char          *display_name,
6068                                     int                  io_priority,
6069                                     GCancellable        *cancellable,
6070                                     GAsyncReadyCallback  callback,
6071                                     gpointer             user_data)
6072 {
6073   GTask *task;
6074
6075   task = g_task_new (file, cancellable, callback, user_data);
6076   g_task_set_source_tag (task, g_file_real_set_display_name_async);
6077   g_task_set_task_data (task, g_strdup (display_name), g_free);
6078   g_task_set_priority (task, io_priority);
6079
6080   g_task_run_in_thread (task, set_display_name_async_thread);
6081   g_object_unref (task);
6082 }
6083
6084 static GFile *
6085 g_file_real_set_display_name_finish (GFile         *file,
6086                                      GAsyncResult  *res,
6087                                      GError       **error)
6088 {
6089   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6090
6091   return g_task_propagate_pointer (G_TASK (res), error);
6092 }
6093
6094 typedef struct {
6095   GFileQueryInfoFlags flags;
6096   GFileInfo *info;
6097   gboolean res;
6098   GError *error;
6099 } SetInfoAsyncData;
6100
6101 static void
6102 set_info_data_free (SetInfoAsyncData *data)
6103 {
6104   if (data->info)
6105     g_object_unref (data->info);
6106   if (data->error)
6107     g_error_free (data->error);
6108   g_free (data);
6109 }
6110
6111 static void
6112 set_info_async_thread (GTask        *task,
6113                        gpointer      object,
6114                        gpointer      task_data,
6115                        GCancellable *cancellable)
6116 {
6117   SetInfoAsyncData *data = task_data;
6118
6119   data->error = NULL;
6120   data->res = g_file_set_attributes_from_info (G_FILE (object),
6121                                                data->info,
6122                                                data->flags,
6123                                                cancellable,
6124                                                &data->error);
6125 }
6126
6127 static void
6128 g_file_real_set_attributes_async (GFile               *file,
6129                                   GFileInfo           *info,
6130                                   GFileQueryInfoFlags  flags,
6131                                   int                  io_priority,
6132                                   GCancellable        *cancellable,
6133                                   GAsyncReadyCallback  callback,
6134                                   gpointer             user_data)
6135 {
6136   GTask *task;
6137   SetInfoAsyncData *data;
6138
6139   data = g_new0 (SetInfoAsyncData, 1);
6140   data->info = g_file_info_dup (info);
6141   data->flags = flags;
6142
6143   task = g_task_new (file, cancellable, callback, user_data);
6144   g_task_set_source_tag (task, g_file_real_set_attributes_async);
6145   g_task_set_task_data (task, data, (GDestroyNotify)set_info_data_free);
6146   g_task_set_priority (task, io_priority);
6147
6148   g_task_run_in_thread (task, set_info_async_thread);
6149   g_object_unref (task);
6150 }
6151
6152 static gboolean
6153 g_file_real_set_attributes_finish (GFile         *file,
6154                                    GAsyncResult  *res,
6155                                    GFileInfo    **info,
6156                                    GError       **error)
6157 {
6158   SetInfoAsyncData *data;
6159
6160   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6161
6162   data = g_task_get_task_data (G_TASK (res));
6163
6164   if (info)
6165     *info = g_object_ref (data->info);
6166
6167   if (error != NULL && data->error)
6168     *error = g_error_copy (data->error);
6169
6170   return data->res;
6171 }
6172
6173 static void
6174 find_enclosing_mount_async_thread (GTask        *task,
6175                                    gpointer      object,
6176                                    gpointer      task_data,
6177                                    GCancellable *cancellable)
6178 {
6179   GError *error = NULL;
6180   GMount *mount;
6181
6182   mount = g_file_find_enclosing_mount (G_FILE (object), cancellable, &error);
6183
6184   if (mount == NULL)
6185     g_task_return_error (task, error);
6186   else
6187     g_task_return_pointer (task, mount, g_object_unref);
6188 }
6189
6190 static void
6191 g_file_real_find_enclosing_mount_async (GFile               *file,
6192                                         int                  io_priority,
6193                                         GCancellable        *cancellable,
6194                                         GAsyncReadyCallback  callback,
6195                                         gpointer             user_data)
6196 {
6197   GTask *task;
6198
6199   task = g_task_new (file, cancellable, callback, user_data);
6200   g_task_set_source_tag (task, g_file_real_find_enclosing_mount_async);
6201   g_task_set_priority (task, io_priority);
6202
6203   g_task_run_in_thread (task, find_enclosing_mount_async_thread);
6204   g_object_unref (task);
6205 }
6206
6207 static GMount *
6208 g_file_real_find_enclosing_mount_finish (GFile         *file,
6209                                          GAsyncResult  *res,
6210                                          GError       **error)
6211 {
6212   g_return_val_if_fail (g_task_is_valid (res, file), NULL);
6213
6214   return g_task_propagate_pointer (G_TASK (res), error);
6215 }
6216
6217
6218 typedef struct {
6219   GFile *source;
6220   GFile *destination;
6221   GFileCopyFlags flags;
6222   GFileProgressCallback progress_cb;
6223   gpointer progress_cb_data;
6224 } CopyAsyncData;
6225
6226 static void
6227 copy_async_data_free (CopyAsyncData *data)
6228 {
6229   g_object_unref (data->source);
6230   g_object_unref (data->destination);
6231   g_slice_free (CopyAsyncData, data);
6232 }
6233
6234 typedef struct {
6235   CopyAsyncData *data;
6236   goffset current_num_bytes;
6237   goffset total_num_bytes;
6238 } ProgressData;
6239
6240 static gboolean
6241 copy_async_progress_in_main (gpointer user_data)
6242 {
6243   ProgressData *progress = user_data;
6244   CopyAsyncData *data = progress->data;
6245
6246   data->progress_cb (progress->current_num_bytes,
6247                      progress->total_num_bytes,
6248                      data->progress_cb_data);
6249
6250   return FALSE;
6251 }
6252
6253 static void
6254 copy_async_progress_callback (goffset  current_num_bytes,
6255                               goffset  total_num_bytes,
6256                               gpointer user_data)
6257 {
6258   GTask *task = user_data;
6259   CopyAsyncData *data = g_task_get_task_data (task);
6260   ProgressData *progress;
6261
6262   progress = g_new (ProgressData, 1);
6263   progress->data = data;
6264   progress->current_num_bytes = current_num_bytes;
6265   progress->total_num_bytes = total_num_bytes;
6266
6267   g_main_context_invoke_full (g_task_get_context (task),
6268                               g_task_get_priority (task),
6269                               copy_async_progress_in_main,
6270                               progress,
6271                               g_free);
6272 }
6273
6274 static void
6275 copy_async_thread (GTask        *task,
6276                    gpointer      source,
6277                    gpointer      task_data,
6278                    GCancellable *cancellable)
6279 {
6280   CopyAsyncData *data = task_data;
6281   gboolean result;
6282   GError *error = NULL;
6283
6284   result = g_file_copy (data->source,
6285                         data->destination,
6286                         data->flags,
6287                         cancellable,
6288                         (data->progress_cb != NULL) ? copy_async_progress_callback : NULL,
6289                         task,
6290                         &error);
6291   if (result)
6292     g_task_return_boolean (task, TRUE);
6293   else
6294     g_task_return_error (task, error);
6295 }
6296
6297 static void
6298 g_file_real_copy_async (GFile                  *source,
6299                         GFile                  *destination,
6300                         GFileCopyFlags          flags,
6301                         int                     io_priority,
6302                         GCancellable           *cancellable,
6303                         GFileProgressCallback   progress_callback,
6304                         gpointer                progress_callback_data,
6305                         GAsyncReadyCallback     callback,
6306                         gpointer                user_data)
6307 {
6308   GTask *task;
6309   CopyAsyncData *data;
6310
6311   data = g_slice_new (CopyAsyncData);
6312   data->source = g_object_ref (source);
6313   data->destination = g_object_ref (destination);
6314   data->flags = flags;
6315   data->progress_cb = progress_callback;
6316   data->progress_cb_data = progress_callback_data;
6317
6318   task = g_task_new (source, cancellable, callback, user_data);
6319   g_task_set_source_tag (task, g_file_real_copy_async);
6320   g_task_set_task_data (task, data, (GDestroyNotify)copy_async_data_free);
6321   g_task_set_priority (task, io_priority);
6322   g_task_run_in_thread (task, copy_async_thread);
6323   g_object_unref (task);
6324 }
6325
6326 static gboolean
6327 g_file_real_copy_finish (GFile        *file,
6328                          GAsyncResult *res,
6329                          GError      **error)
6330 {
6331   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
6332
6333   return g_task_propagate_boolean (G_TASK (res), error);
6334 }
6335
6336
6337 /********************************************
6338  *   Default VFS operations                 *
6339  ********************************************/
6340
6341 /**
6342  * g_file_new_for_path:
6343  * @path: (type filename): a string containing a relative or absolute path.
6344  *     The string must be encoded in the glib filename encoding.
6345  *
6346  * Constructs a #GFile for a given path. This operation never
6347  * fails, but the returned object might not support any I/O
6348  * operation if @path is malformed.
6349  *
6350  * Returns: (transfer full): a new #GFile for the given @path.
6351  *   Free the returned object with g_object_unref().
6352  */
6353 GFile *
6354 g_file_new_for_path (const char *path)
6355 {
6356   g_return_val_if_fail (path != NULL, NULL);
6357
6358   return g_vfs_get_file_for_path (g_vfs_get_default (), path);
6359 }
6360
6361 /**
6362  * g_file_new_for_uri:
6363  * @uri: a UTF-8 string containing a URI
6364  *
6365  * Constructs a #GFile for a given URI. This operation never
6366  * fails, but the returned object might not support any I/O
6367  * operation if @uri is malformed or if the uri type is
6368  * not supported.
6369  *
6370  * Returns: (transfer full): a new #GFile for the given @uri.
6371  *     Free the returned object with g_object_unref().
6372  */
6373 GFile *
6374 g_file_new_for_uri (const char *uri)
6375 {
6376   g_return_val_if_fail (uri != NULL, NULL);
6377
6378   return g_vfs_get_file_for_uri (g_vfs_get_default (), uri);
6379 }
6380
6381 /**
6382  * g_file_new_tmp:
6383  * @tmpl: (type filename) (nullable): Template for the file
6384  *   name, as in g_file_open_tmp(), or %NULL for a default template
6385  * @iostream: (out): on return, a #GFileIOStream for the created file
6386  * @error: a #GError, or %NULL
6387  *
6388  * Opens a file in the preferred directory for temporary files (as
6389  * returned by g_get_tmp_dir()) and returns a #GFile and
6390  * #GFileIOStream pointing to it.
6391  *
6392  * @tmpl should be a string in the GLib file name encoding
6393  * containing a sequence of six 'X' characters, and containing no
6394  * directory components. If it is %NULL, a default template is used.
6395  *
6396  * Unlike the other #GFile constructors, this will return %NULL if
6397  * a temporary file could not be created.
6398  *
6399  * Returns: (transfer full): a new #GFile.
6400  *     Free the returned object with g_object_unref().
6401  *
6402  * Since: 2.32
6403  */
6404 GFile *
6405 g_file_new_tmp (const char     *tmpl,
6406                 GFileIOStream **iostream,
6407                 GError        **error)
6408 {
6409   gint fd;
6410   gchar *path;
6411   GFile *file;
6412   GFileOutputStream *output;
6413
6414   g_return_val_if_fail (iostream != NULL, NULL);
6415
6416   fd = g_file_open_tmp (tmpl, &path, error);
6417   if (fd == -1)
6418     return NULL;
6419
6420   file = g_file_new_for_path (path);
6421
6422   output = _g_local_file_output_stream_new (fd);
6423   *iostream = _g_local_file_io_stream_new (G_LOCAL_FILE_OUTPUT_STREAM (output));
6424
6425   g_object_unref (output);
6426   g_free (path);
6427
6428   return file;
6429 }
6430
6431 /**
6432  * g_file_parse_name:
6433  * @parse_name: a file name or path to be parsed
6434  *
6435  * Constructs a #GFile with the given @parse_name (i.e. something
6436  * given by g_file_get_parse_name()). This operation never fails,
6437  * but the returned object might not support any I/O operation if
6438  * the @parse_name cannot be parsed.
6439  *
6440  * Returns: (transfer full): a new #GFile.
6441  */
6442 GFile *
6443 g_file_parse_name (const char *parse_name)
6444 {
6445   g_return_val_if_fail (parse_name != NULL, NULL);
6446
6447   return g_vfs_parse_name (g_vfs_get_default (), parse_name);
6448 }
6449
6450 static gboolean
6451 is_valid_scheme_character (char c)
6452 {
6453   return g_ascii_isalnum (c) || c == '+' || c == '-' || c == '.';
6454 }
6455
6456 /* Following RFC 2396, valid schemes are built like:
6457  *       scheme        = alpha *( alpha | digit | "+" | "-" | "." )
6458  */
6459 static gboolean
6460 has_valid_scheme (const char *uri)
6461 {
6462   const char *p;
6463
6464   p = uri;
6465
6466   if (!g_ascii_isalpha (*p))
6467     return FALSE;
6468
6469   do {
6470     p++;
6471   } while (is_valid_scheme_character (*p));
6472
6473   return *p == ':';
6474 }
6475
6476 static GFile *
6477 new_for_cmdline_arg (const gchar *arg,
6478                      const gchar *cwd)
6479 {
6480   GFile *file;
6481   char *filename;
6482
6483   if (g_path_is_absolute (arg))
6484     return g_file_new_for_path (arg);
6485
6486   if (has_valid_scheme (arg))
6487     return g_file_new_for_uri (arg);
6488
6489   if (cwd == NULL)
6490     {
6491       char *current_dir;
6492
6493       current_dir = g_get_current_dir ();
6494       filename = g_build_filename (current_dir, arg, NULL);
6495       g_free (current_dir);
6496     }
6497   else
6498     filename = g_build_filename (cwd, arg, NULL);
6499
6500   file = g_file_new_for_path (filename);
6501   g_free (filename);
6502
6503   return file;
6504 }
6505
6506 /**
6507  * g_file_new_for_commandline_arg:
6508  * @arg: a command line string
6509  *
6510  * Creates a #GFile with the given argument from the command line.
6511  * The value of @arg can be either a URI, an absolute path or a
6512  * relative path resolved relative to the current working directory.
6513  * This operation never fails, but the returned object might not
6514  * support any I/O operation if @arg points to a malformed path.
6515  *
6516  * Note that on Windows, this function expects its argument to be in
6517  * UTF-8 -- not the system code page.  This means that you
6518  * should not use this function with string from argv as it is passed
6519  * to main().  g_win32_get_command_line() will return a UTF-8 version of
6520  * the commandline.  #GApplication also uses UTF-8 but
6521  * g_application_command_line_create_file_for_arg() may be more useful
6522  * for you there.  It is also always possible to use this function with
6523  * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
6524  *
6525  * Returns: (transfer full): a new #GFile.
6526  *    Free the returned object with g_object_unref().
6527  */
6528 GFile *
6529 g_file_new_for_commandline_arg (const char *arg)
6530 {
6531   g_return_val_if_fail (arg != NULL, NULL);
6532
6533   return new_for_cmdline_arg (arg, NULL);
6534 }
6535
6536 /**
6537  * g_file_new_for_commandline_arg_and_cwd:
6538  * @arg: a command line string
6539  * @cwd: (type filename): the current working directory of the commandline
6540  *
6541  * Creates a #GFile with the given argument from the command line.
6542  *
6543  * This function is similar to g_file_new_for_commandline_arg() except
6544  * that it allows for passing the current working directory as an
6545  * argument instead of using the current working directory of the
6546  * process.
6547  *
6548  * This is useful if the commandline argument was given in a context
6549  * other than the invocation of the current process.
6550  *
6551  * See also g_application_command_line_create_file_for_arg().
6552  *
6553  * Returns: (transfer full): a new #GFile
6554  *
6555  * Since: 2.36
6556  **/
6557 GFile *
6558 g_file_new_for_commandline_arg_and_cwd (const gchar *arg,
6559                                         const gchar *cwd)
6560 {
6561   g_return_val_if_fail (arg != NULL, NULL);
6562   g_return_val_if_fail (cwd != NULL, NULL);
6563
6564   return new_for_cmdline_arg (arg, cwd);
6565 }
6566
6567 /**
6568  * g_file_mount_enclosing_volume:
6569  * @location: input #GFile
6570  * @flags: flags affecting the operation
6571  * @mount_operation: (nullable): a #GMountOperation
6572  *     or %NULL to avoid user interaction
6573  * @cancellable: (nullable): optional #GCancellable object,
6574  *     %NULL to ignore
6575  * @callback: (nullable): a #GAsyncReadyCallback to call
6576  *     when the request is satisfied, or %NULL
6577  * @user_data: the data to pass to callback function
6578  *
6579  * Starts a @mount_operation, mounting the volume that contains
6580  * the file @location.
6581  *
6582  * When this operation has completed, @callback will be called with
6583  * @user_user data, and the operation can be finalized with
6584  * g_file_mount_enclosing_volume_finish().
6585  *
6586  * If @cancellable is not %NULL, then the operation can be cancelled by
6587  * triggering the cancellable object from another thread. If the operation
6588  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6589  */
6590 void
6591 g_file_mount_enclosing_volume (GFile               *location,
6592                                GMountMountFlags     flags,
6593                                GMountOperation     *mount_operation,
6594                                GCancellable        *cancellable,
6595                                GAsyncReadyCallback  callback,
6596                                gpointer             user_data)
6597 {
6598   GFileIface *iface;
6599
6600   g_return_if_fail (G_IS_FILE (location));
6601
6602   iface = G_FILE_GET_IFACE (location);
6603
6604   if (iface->mount_enclosing_volume == NULL)
6605     {
6606       g_task_report_new_error (location, callback, user_data,
6607                                g_file_mount_enclosing_volume,
6608                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
6609                                _("volume doesn’t implement mount"));
6610       return;
6611     }
6612
6613   (* iface->mount_enclosing_volume) (location, flags, mount_operation, cancellable, callback, user_data);
6614
6615 }
6616
6617 /**
6618  * g_file_mount_enclosing_volume_finish:
6619  * @location: input #GFile
6620  * @result: a #GAsyncResult
6621  * @error: a #GError, or %NULL
6622  *
6623  * Finishes a mount operation started by g_file_mount_enclosing_volume().
6624  *
6625  * Returns: %TRUE if successful. If an error has occurred,
6626  *     this function will return %FALSE and set @error
6627  *     appropriately if present.
6628  */
6629 gboolean
6630 g_file_mount_enclosing_volume_finish (GFile         *location,
6631                                       GAsyncResult  *result,
6632                                       GError       **error)
6633 {
6634   GFileIface *iface;
6635
6636   g_return_val_if_fail (G_IS_FILE (location), FALSE);
6637   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
6638
6639   if (g_async_result_legacy_propagate_error (result, error))
6640     return FALSE;
6641   else if (g_async_result_is_tagged (result, g_file_mount_enclosing_volume))
6642     return g_task_propagate_boolean (G_TASK (result), error);
6643
6644   iface = G_FILE_GET_IFACE (location);
6645
6646   return (* iface->mount_enclosing_volume_finish) (location, result, error);
6647 }
6648
6649 /********************************************
6650  *   Utility functions                      *
6651  ********************************************/
6652
6653 /**
6654  * g_file_query_default_handler:
6655  * @file: a #GFile to open
6656  * @cancellable: optional #GCancellable object, %NULL to ignore
6657  * @error: a #GError, or %NULL
6658  *
6659  * Returns the #GAppInfo that is registered as the default
6660  * application to handle the file specified by @file.
6661  *
6662  * If @cancellable is not %NULL, then the operation can be cancelled by
6663  * triggering the cancellable object from another thread. If the operation
6664  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6665  *
6666  * Returns: (transfer full): a #GAppInfo if the handle was found,
6667  *     %NULL if there were errors.
6668  *     When you are done with it, release it with g_object_unref()
6669  */
6670 GAppInfo *
6671 g_file_query_default_handler (GFile         *file,
6672                               GCancellable  *cancellable,
6673                               GError       **error)
6674 {
6675   char *uri_scheme;
6676   const char *content_type;
6677   GAppInfo *appinfo;
6678   GFileInfo *info;
6679   char *path;
6680
6681   uri_scheme = g_file_get_uri_scheme (file);
6682   if (uri_scheme && uri_scheme[0] != '\0')
6683     {
6684       appinfo = g_app_info_get_default_for_uri_scheme (uri_scheme);
6685       g_free (uri_scheme);
6686
6687       if (appinfo != NULL)
6688         return appinfo;
6689     }
6690
6691   info = g_file_query_info (file,
6692                             G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE,
6693                             0,
6694                             cancellable,
6695                             error);
6696   if (info == NULL)
6697     return NULL;
6698
6699   appinfo = NULL;
6700
6701   content_type = g_file_info_get_content_type (info);
6702   if (content_type)
6703     {
6704       /* Don't use is_native(), as we want to support fuse paths if available */
6705       path = g_file_get_path (file);
6706       appinfo = g_app_info_get_default_for_type (content_type,
6707                                                  path == NULL);
6708       g_free (path);
6709     }
6710
6711   g_object_unref (info);
6712
6713   if (appinfo != NULL)
6714     return appinfo;
6715
6716   g_set_error_literal (error, G_IO_ERROR,
6717                        G_IO_ERROR_NOT_SUPPORTED,
6718                        _("No application is registered as handling this file"));
6719   return NULL;
6720 }
6721
6722 #define GET_CONTENT_BLOCK_SIZE 8192
6723
6724 /**
6725  * g_file_load_contents:
6726  * @file: input #GFile
6727  * @cancellable: optional #GCancellable object, %NULL to ignore
6728  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
6729  * @length: (out) (optional): a location to place the length of the contents of the file,
6730  *    or %NULL if the length is not needed
6731  * @etag_out: (out) (optional): a location to place the current entity tag for the file,
6732  *    or %NULL if the entity tag is not needed
6733  * @error: a #GError, or %NULL
6734  *
6735  * Loads the content of the file into memory. The data is always
6736  * zero-terminated, but this is not included in the resultant @length.
6737  * The returned @content should be freed with g_free() when no longer
6738  * needed.
6739  *
6740  * If @cancellable is not %NULL, then the operation can be cancelled by
6741  * triggering the cancellable object from another thread. If the operation
6742  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6743  *
6744  * Returns: %TRUE if the @file's contents were successfully loaded.
6745  *     %FALSE if there were errors.
6746  */
6747 gboolean
6748 g_file_load_contents (GFile         *file,
6749                       GCancellable  *cancellable,
6750                       char         **contents,
6751                       gsize         *length,
6752                       char         **etag_out,
6753                       GError       **error)
6754 {
6755   GFileInputStream *in;
6756   GByteArray *content;
6757   gsize pos;
6758   gssize res;
6759   GFileInfo *info;
6760
6761   g_return_val_if_fail (G_IS_FILE (file), FALSE);
6762   g_return_val_if_fail (contents != NULL, FALSE);
6763
6764   in = g_file_read (file, cancellable, error);
6765   if (in == NULL)
6766     return FALSE;
6767
6768   content = g_byte_array_new ();
6769   pos = 0;
6770
6771   g_byte_array_set_size (content, pos + GET_CONTENT_BLOCK_SIZE + 1);
6772   while ((res = g_input_stream_read (G_INPUT_STREAM (in),
6773                                      content->data + pos,
6774                                      GET_CONTENT_BLOCK_SIZE,
6775                                      cancellable, error)) > 0)
6776     {
6777       pos += res;
6778       g_byte_array_set_size (content, pos + GET_CONTENT_BLOCK_SIZE + 1);
6779     }
6780
6781   if (etag_out)
6782     {
6783       *etag_out = NULL;
6784
6785       info = g_file_input_stream_query_info (in,
6786                                              G_FILE_ATTRIBUTE_ETAG_VALUE,
6787                                              cancellable,
6788                                              NULL);
6789       if (info)
6790         {
6791           *etag_out = g_strdup (g_file_info_get_etag (info));
6792           g_object_unref (info);
6793         }
6794     }
6795
6796   /* Ignore errors on close */
6797   g_input_stream_close (G_INPUT_STREAM (in), cancellable, NULL);
6798   g_object_unref (in);
6799
6800   if (res < 0)
6801     {
6802       /* error is set already */
6803       g_byte_array_free (content, TRUE);
6804       return FALSE;
6805     }
6806
6807   if (length)
6808     *length = pos;
6809
6810   /* Zero terminate (we got an extra byte allocated for this */
6811   content->data[pos] = 0;
6812
6813   *contents = (char *)g_byte_array_free (content, FALSE);
6814
6815   return TRUE;
6816 }
6817
6818 typedef struct {
6819   GTask *task;
6820   GFileReadMoreCallback read_more_callback;
6821   GByteArray *content;
6822   gsize pos;
6823   char *etag;
6824 } LoadContentsData;
6825
6826
6827 static void
6828 load_contents_data_free (LoadContentsData *data)
6829 {
6830   if (data->content)
6831     g_byte_array_free (data->content, TRUE);
6832   g_free (data->etag);
6833   g_free (data);
6834 }
6835
6836 static void
6837 load_contents_close_callback (GObject      *obj,
6838                               GAsyncResult *close_res,
6839                               gpointer      user_data)
6840 {
6841   GInputStream *stream = G_INPUT_STREAM (obj);
6842   LoadContentsData *data = user_data;
6843
6844   /* Ignore errors here, we're only reading anyway */
6845   g_input_stream_close_finish (stream, close_res, NULL);
6846   g_object_unref (stream);
6847
6848   g_task_return_boolean (data->task, TRUE);
6849   g_object_unref (data->task);
6850 }
6851
6852 static void
6853 load_contents_fstat_callback (GObject      *obj,
6854                               GAsyncResult *stat_res,
6855                               gpointer      user_data)
6856 {
6857   GInputStream *stream = G_INPUT_STREAM (obj);
6858   LoadContentsData *data = user_data;
6859   GFileInfo *info;
6860
6861   info = g_file_input_stream_query_info_finish (G_FILE_INPUT_STREAM (stream),
6862                                                 stat_res, NULL);
6863   if (info)
6864     {
6865       data->etag = g_strdup (g_file_info_get_etag (info));
6866       g_object_unref (info);
6867     }
6868
6869   g_input_stream_close_async (stream, 0,
6870                               g_task_get_cancellable (data->task),
6871                               load_contents_close_callback, data);
6872 }
6873
6874 static void
6875 load_contents_read_callback (GObject      *obj,
6876                              GAsyncResult *read_res,
6877                              gpointer      user_data)
6878 {
6879   GInputStream *stream = G_INPUT_STREAM (obj);
6880   LoadContentsData *data = user_data;
6881   GError *error = NULL;
6882   gssize read_size;
6883
6884   read_size = g_input_stream_read_finish (stream, read_res, &error);
6885
6886   if (read_size < 0)
6887     {
6888       g_task_return_error (data->task, error);
6889       g_object_unref (data->task);
6890
6891       /* Close the file ignoring any error */
6892       g_input_stream_close_async (stream, 0, NULL, NULL, NULL);
6893       g_object_unref (stream);
6894     }
6895   else if (read_size == 0)
6896     {
6897       g_file_input_stream_query_info_async (G_FILE_INPUT_STREAM (stream),
6898                                             G_FILE_ATTRIBUTE_ETAG_VALUE,
6899                                             0,
6900                                             g_task_get_cancellable (data->task),
6901                                             load_contents_fstat_callback,
6902                                             data);
6903     }
6904   else if (read_size > 0)
6905     {
6906       data->pos += read_size;
6907
6908       g_byte_array_set_size (data->content,
6909                              data->pos + GET_CONTENT_BLOCK_SIZE);
6910
6911
6912       if (data->read_more_callback &&
6913           !data->read_more_callback ((char *)data->content->data, data->pos,
6914                                      g_async_result_get_user_data (G_ASYNC_RESULT (data->task))))
6915         g_file_input_stream_query_info_async (G_FILE_INPUT_STREAM (stream),
6916                                               G_FILE_ATTRIBUTE_ETAG_VALUE,
6917                                               0,
6918                                               g_task_get_cancellable (data->task),
6919                                               load_contents_fstat_callback,
6920                                               data);
6921       else
6922         g_input_stream_read_async (stream,
6923                                    data->content->data + data->pos,
6924                                    GET_CONTENT_BLOCK_SIZE,
6925                                    0,
6926                                    g_task_get_cancellable (data->task),
6927                                    load_contents_read_callback,
6928                                    data);
6929     }
6930 }
6931
6932 static void
6933 load_contents_open_callback (GObject      *obj,
6934                              GAsyncResult *open_res,
6935                              gpointer      user_data)
6936 {
6937   GFile *file = G_FILE (obj);
6938   GFileInputStream *stream;
6939   LoadContentsData *data = user_data;
6940   GError *error = NULL;
6941
6942   stream = g_file_read_finish (file, open_res, &error);
6943
6944   if (stream)
6945     {
6946       g_byte_array_set_size (data->content,
6947                              data->pos + GET_CONTENT_BLOCK_SIZE);
6948       g_input_stream_read_async (G_INPUT_STREAM (stream),
6949                                  data->content->data + data->pos,
6950                                  GET_CONTENT_BLOCK_SIZE,
6951                                  0,
6952                                  g_task_get_cancellable (data->task),
6953                                  load_contents_read_callback,
6954                                  data);
6955     }
6956   else
6957     {
6958       g_task_return_error (data->task, error);
6959       g_object_unref (data->task);
6960     }
6961 }
6962
6963 /**
6964  * g_file_load_partial_contents_async: (skip)
6965  * @file: input #GFile
6966  * @cancellable: optional #GCancellable object, %NULL to ignore
6967  * @read_more_callback: a #GFileReadMoreCallback to receive partial data
6968  *     and to specify whether further data should be read
6969  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
6970  * @user_data: the data to pass to the callback functions
6971  *
6972  * Reads the partial contents of a file. A #GFileReadMoreCallback should
6973  * be used to stop reading from the file when appropriate, else this
6974  * function will behave exactly as g_file_load_contents_async(). This
6975  * operation can be finished by g_file_load_partial_contents_finish().
6976  *
6977  * Users of this function should be aware that @user_data is passed to
6978  * both the @read_more_callback and the @callback.
6979  *
6980  * If @cancellable is not %NULL, then the operation can be cancelled by
6981  * triggering the cancellable object from another thread. If the operation
6982  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
6983  */
6984 void
6985 g_file_load_partial_contents_async (GFile                 *file,
6986                                     GCancellable          *cancellable,
6987                                     GFileReadMoreCallback  read_more_callback,
6988                                     GAsyncReadyCallback    callback,
6989                                     gpointer               user_data)
6990 {
6991   LoadContentsData *data;
6992
6993   g_return_if_fail (G_IS_FILE (file));
6994
6995   data = g_new0 (LoadContentsData, 1);
6996   data->read_more_callback = read_more_callback;
6997   data->content = g_byte_array_new ();
6998
6999   data->task = g_task_new (file, cancellable, callback, user_data);
7000   g_task_set_source_tag (data->task, g_file_load_partial_contents_async);
7001   g_task_set_task_data (data->task, data, (GDestroyNotify)load_contents_data_free);
7002
7003   g_file_read_async (file,
7004                      0,
7005                      g_task_get_cancellable (data->task),
7006                      load_contents_open_callback,
7007                      data);
7008 }
7009
7010 /**
7011  * g_file_load_partial_contents_finish:
7012  * @file: input #GFile
7013  * @res: a #GAsyncResult
7014  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
7015  * @length: (out) (optional): a location to place the length of the contents of the file,
7016  *     or %NULL if the length is not needed
7017  * @etag_out: (out) (optional): a location to place the current entity tag for the file,
7018  *     or %NULL if the entity tag is not needed
7019  * @error: a #GError, or %NULL
7020  *
7021  * Finishes an asynchronous partial load operation that was started
7022  * with g_file_load_partial_contents_async(). The data is always
7023  * zero-terminated, but this is not included in the resultant @length.
7024  * The returned @content should be freed with g_free() when no longer
7025  * needed.
7026  *
7027  * Returns: %TRUE if the load was successful. If %FALSE and @error is
7028  *     present, it will be set appropriately.
7029  */
7030 gboolean
7031 g_file_load_partial_contents_finish (GFile         *file,
7032                                      GAsyncResult  *res,
7033                                      char         **contents,
7034                                      gsize         *length,
7035                                      char         **etag_out,
7036                                      GError       **error)
7037 {
7038   GTask *task;
7039   LoadContentsData *data;
7040
7041   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7042   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
7043   g_return_val_if_fail (contents != NULL, FALSE);
7044
7045   task = G_TASK (res);
7046
7047   if (!g_task_propagate_boolean (task, error))
7048     {
7049       if (length)
7050         *length = 0;
7051       return FALSE;
7052     }
7053
7054   data = g_task_get_task_data (task);
7055
7056   if (length)
7057     *length = data->pos;
7058
7059   if (etag_out)
7060     {
7061       *etag_out = data->etag;
7062       data->etag = NULL;
7063     }
7064
7065   /* Zero terminate */
7066   g_byte_array_set_size (data->content, data->pos + 1);
7067   data->content->data[data->pos] = 0;
7068
7069   *contents = (char *)g_byte_array_free (data->content, FALSE);
7070   data->content = NULL;
7071
7072   return TRUE;
7073 }
7074
7075 /**
7076  * g_file_load_contents_async:
7077  * @file: input #GFile
7078  * @cancellable: optional #GCancellable object, %NULL to ignore
7079  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7080  * @user_data: the data to pass to callback function
7081  *
7082  * Starts an asynchronous load of the @file's contents.
7083  *
7084  * For more details, see g_file_load_contents() which is
7085  * the synchronous version of this call.
7086  *
7087  * When the load operation has completed, @callback will be called
7088  * with @user data. To finish the operation, call
7089  * g_file_load_contents_finish() with the #GAsyncResult returned by
7090  * the @callback.
7091  *
7092  * If @cancellable is not %NULL, then the operation can be cancelled by
7093  * triggering the cancellable object from another thread. If the operation
7094  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7095  */
7096 void
7097 g_file_load_contents_async (GFile               *file,
7098                            GCancellable        *cancellable,
7099                            GAsyncReadyCallback  callback,
7100                            gpointer             user_data)
7101 {
7102   g_file_load_partial_contents_async (file,
7103                                       cancellable,
7104                                       NULL,
7105                                       callback, user_data);
7106 }
7107
7108 /**
7109  * g_file_load_contents_finish:
7110  * @file: input #GFile
7111  * @res: a #GAsyncResult
7112  * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
7113  * @length: (out) (optional): a location to place the length of the contents of the file,
7114  *     or %NULL if the length is not needed
7115  * @etag_out: (out) (optional): a location to place the current entity tag for the file,
7116  *     or %NULL if the entity tag is not needed
7117  * @error: a #GError, or %NULL
7118  *
7119  * Finishes an asynchronous load of the @file's contents.
7120  * The contents are placed in @contents, and @length is set to the
7121  * size of the @contents string. The @content should be freed with
7122  * g_free() when no longer needed. If @etag_out is present, it will be
7123  * set to the new entity tag for the @file.
7124  *
7125  * Returns: %TRUE if the load was successful. If %FALSE and @error is
7126  *     present, it will be set appropriately.
7127  */
7128 gboolean
7129 g_file_load_contents_finish (GFile         *file,
7130                              GAsyncResult  *res,
7131                              char         **contents,
7132                              gsize         *length,
7133                              char         **etag_out,
7134                              GError       **error)
7135 {
7136   return g_file_load_partial_contents_finish (file,
7137                                               res,
7138                                               contents,
7139                                               length,
7140                                               etag_out,
7141                                               error);
7142 }
7143
7144 /**
7145  * g_file_replace_contents:
7146  * @file: input #GFile
7147  * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
7148  * @length: the length of @contents in bytes
7149  * @etag: (nullable): the old [entity-tag][gfile-etag] for the document,
7150  *     or %NULL
7151  * @make_backup: %TRUE if a backup should be created
7152  * @flags: a set of #GFileCreateFlags
7153  * @new_etag: (out) (optional): a location to a new [entity tag][gfile-etag]
7154  *      for the document. This should be freed with g_free() when no longer
7155  *      needed, or %NULL
7156  * @cancellable: optional #GCancellable object, %NULL to ignore
7157  * @error: a #GError, or %NULL
7158  *
7159  * Replaces the contents of @file with @contents of @length bytes.
7160  *
7161  * If @etag is specified (not %NULL), any existing file must have that etag,
7162  * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
7163  *
7164  * If @make_backup is %TRUE, this function will attempt to make a backup
7165  * of @file. Internally, it uses g_file_replace(), so will try to replace the
7166  * file contents in the safest way possible. For example, atomic renames are
7167  * used when replacing local files’ contents.
7168  *
7169  * If @cancellable is not %NULL, then the operation can be cancelled by
7170  * triggering the cancellable object from another thread. If the operation
7171  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7172  *
7173  * The returned @new_etag can be used to verify that the file hasn't
7174  * changed the next time it is saved over.
7175  *
7176  * Returns: %TRUE if successful. If an error has occurred, this function
7177  *     will return %FALSE and set @error appropriately if present.
7178  */
7179 gboolean
7180 g_file_replace_contents (GFile             *file,
7181                          const char        *contents,
7182                          gsize              length,
7183                          const char        *etag,
7184                          gboolean           make_backup,
7185                          GFileCreateFlags   flags,
7186                          char             **new_etag,
7187                          GCancellable      *cancellable,
7188                          GError           **error)
7189 {
7190   GFileOutputStream *out;
7191   gsize pos, remainder;
7192   gssize res;
7193   gboolean ret;
7194
7195   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7196   g_return_val_if_fail (contents != NULL, FALSE);
7197
7198   out = g_file_replace (file, etag, make_backup, flags, cancellable, error);
7199   if (out == NULL)
7200     return FALSE;
7201
7202   pos = 0;
7203   remainder = length;
7204   while (remainder > 0 &&
7205          (res = g_output_stream_write (G_OUTPUT_STREAM (out),
7206                                        contents + pos,
7207                                        MIN (remainder, GET_CONTENT_BLOCK_SIZE),
7208                                        cancellable,
7209                                        error)) > 0)
7210     {
7211       pos += res;
7212       remainder -= res;
7213     }
7214
7215   if (remainder > 0 && res < 0)
7216     {
7217       /* Ignore errors on close */
7218       g_output_stream_close (G_OUTPUT_STREAM (out), cancellable, NULL);
7219       g_object_unref (out);
7220
7221       /* error is set already */
7222       return FALSE;
7223     }
7224
7225   ret = g_output_stream_close (G_OUTPUT_STREAM (out), cancellable, error);
7226
7227   if (new_etag)
7228     *new_etag = g_file_output_stream_get_etag (out);
7229
7230   g_object_unref (out);
7231
7232   return ret;
7233 }
7234
7235 typedef struct {
7236   GTask *task;
7237   GBytes *content;
7238   gsize pos;
7239   char *etag;
7240   gboolean failed;
7241 } ReplaceContentsData;
7242
7243 static void
7244 replace_contents_data_free (ReplaceContentsData *data)
7245 {
7246   g_bytes_unref (data->content);
7247   g_free (data->etag);
7248   g_free (data);
7249 }
7250
7251 static void
7252 replace_contents_close_callback (GObject      *obj,
7253                                  GAsyncResult *close_res,
7254                                  gpointer      user_data)
7255 {
7256   GOutputStream *stream = G_OUTPUT_STREAM (obj);
7257   ReplaceContentsData *data = user_data;
7258
7259   /* Ignore errors here, we're only reading anyway */
7260   g_output_stream_close_finish (stream, close_res, NULL);
7261   g_object_unref (stream);
7262
7263   if (!data->failed)
7264     {
7265       data->etag = g_file_output_stream_get_etag (G_FILE_OUTPUT_STREAM (stream));
7266       g_task_return_boolean (data->task, TRUE);
7267     }
7268   g_object_unref (data->task);
7269 }
7270
7271 static void
7272 replace_contents_write_callback (GObject      *obj,
7273                                  GAsyncResult *read_res,
7274                                  gpointer      user_data)
7275 {
7276   GOutputStream *stream = G_OUTPUT_STREAM (obj);
7277   ReplaceContentsData *data = user_data;
7278   GError *error = NULL;
7279   gssize write_size;
7280
7281   write_size = g_output_stream_write_finish (stream, read_res, &error);
7282
7283   if (write_size <= 0)
7284     {
7285       /* Error or EOF, close the file */
7286       if (write_size < 0)
7287         {
7288           data->failed = TRUE;
7289           g_task_return_error (data->task, error);
7290         }
7291       g_output_stream_close_async (stream, 0,
7292                                    g_task_get_cancellable (data->task),
7293                                    replace_contents_close_callback, data);
7294     }
7295   else if (write_size > 0)
7296     {
7297       const gchar *content;
7298       gsize length;
7299
7300       content = g_bytes_get_data (data->content, &length);
7301       data->pos += write_size;
7302
7303       if (data->pos >= length)
7304         g_output_stream_close_async (stream, 0,
7305                                      g_task_get_cancellable (data->task),
7306                                      replace_contents_close_callback, data);
7307       else
7308         g_output_stream_write_async (stream,
7309                                      content + data->pos,
7310                                      length - data->pos,
7311                                      0,
7312                                      g_task_get_cancellable (data->task),
7313                                      replace_contents_write_callback,
7314                                      data);
7315     }
7316 }
7317
7318 static void
7319 replace_contents_open_callback (GObject      *obj,
7320                                 GAsyncResult *open_res,
7321                                 gpointer      user_data)
7322 {
7323   GFile *file = G_FILE (obj);
7324   GFileOutputStream *stream;
7325   ReplaceContentsData *data = user_data;
7326   GError *error = NULL;
7327
7328   stream = g_file_replace_finish (file, open_res, &error);
7329
7330   if (stream)
7331     {
7332       const gchar *content;
7333       gsize length;
7334
7335       content = g_bytes_get_data (data->content, &length);
7336       g_output_stream_write_async (G_OUTPUT_STREAM (stream),
7337                                    content + data->pos,
7338                                    length - data->pos,
7339                                    0,
7340                                    g_task_get_cancellable (data->task),
7341                                    replace_contents_write_callback,
7342                                    data);
7343     }
7344   else
7345     {
7346       g_task_return_error (data->task, error);
7347       g_object_unref (data->task);
7348     }
7349 }
7350
7351 /**
7352  * g_file_replace_contents_async:
7353  * @file: input #GFile
7354  * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
7355  * @length: the length of @contents in bytes
7356  * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL
7357  * @make_backup: %TRUE if a backup should be created
7358  * @flags: a set of #GFileCreateFlags
7359  * @cancellable: optional #GCancellable object, %NULL to ignore
7360  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7361  * @user_data: the data to pass to callback function
7362  *
7363  * Starts an asynchronous replacement of @file with the given
7364  * @contents of @length bytes. @etag will replace the document's
7365  * current entity tag.
7366  *
7367  * When this operation has completed, @callback will be called with
7368  * @user_user data, and the operation can be finalized with
7369  * g_file_replace_contents_finish().
7370  *
7371  * If @cancellable is not %NULL, then the operation can be cancelled by
7372  * triggering the cancellable object from another thread. If the operation
7373  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7374  *
7375  * If @make_backup is %TRUE, this function will attempt to
7376  * make a backup of @file.
7377  *
7378  * Note that no copy of @content will be made, so it must stay valid
7379  * until @callback is called. See g_file_replace_contents_bytes_async()
7380  * for a #GBytes version that will automatically hold a reference to the
7381  * contents (without copying) for the duration of the call.
7382  */
7383 void
7384 g_file_replace_contents_async  (GFile               *file,
7385                                 const char          *contents,
7386                                 gsize                length,
7387                                 const char          *etag,
7388                                 gboolean             make_backup,
7389                                 GFileCreateFlags     flags,
7390                                 GCancellable        *cancellable,
7391                                 GAsyncReadyCallback  callback,
7392                                 gpointer             user_data)
7393 {
7394   GBytes *bytes;
7395
7396   bytes = g_bytes_new_static (contents, length);
7397   g_file_replace_contents_bytes_async (file, bytes, etag, make_backup, flags,
7398       cancellable, callback, user_data);
7399   g_bytes_unref (bytes);
7400 }
7401
7402 /**
7403  * g_file_replace_contents_bytes_async:
7404  * @file: input #GFile
7405  * @contents: a #GBytes
7406  * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL
7407  * @make_backup: %TRUE if a backup should be created
7408  * @flags: a set of #GFileCreateFlags
7409  * @cancellable: optional #GCancellable object, %NULL to ignore
7410  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
7411  * @user_data: the data to pass to callback function
7412  *
7413  * Same as g_file_replace_contents_async() but takes a #GBytes input instead.
7414  * This function will keep a ref on @contents until the operation is done.
7415  * Unlike g_file_replace_contents_async() this allows forgetting about the
7416  * content without waiting for the callback.
7417  *
7418  * When this operation has completed, @callback will be called with
7419  * @user_user data, and the operation can be finalized with
7420  * g_file_replace_contents_finish().
7421  *
7422  * Since: 2.40
7423  */
7424 void
7425 g_file_replace_contents_bytes_async  (GFile               *file,
7426                                       GBytes              *contents,
7427                                       const char          *etag,
7428                                       gboolean             make_backup,
7429                                       GFileCreateFlags     flags,
7430                                       GCancellable        *cancellable,
7431                                       GAsyncReadyCallback  callback,
7432                                       gpointer             user_data)
7433 {
7434   ReplaceContentsData *data;
7435
7436   g_return_if_fail (G_IS_FILE (file));
7437   g_return_if_fail (contents != NULL);
7438
7439   data = g_new0 (ReplaceContentsData, 1);
7440
7441   data->content = g_bytes_ref (contents);
7442
7443   data->task = g_task_new (file, cancellable, callback, user_data);
7444   g_task_set_source_tag (data->task, g_file_replace_contents_bytes_async);
7445   g_task_set_task_data (data->task, data, (GDestroyNotify)replace_contents_data_free);
7446
7447   g_file_replace_async (file,
7448                         etag,
7449                         make_backup,
7450                         flags,
7451                         0,
7452                         g_task_get_cancellable (data->task),
7453                         replace_contents_open_callback,
7454                         data);
7455 }
7456
7457 /**
7458  * g_file_replace_contents_finish:
7459  * @file: input #GFile
7460  * @res: a #GAsyncResult
7461  * @new_etag: (out) (optional): a location of a new [entity tag][gfile-etag]
7462  *     for the document. This should be freed with g_free() when it is no
7463  *     longer needed, or %NULL
7464  * @error: a #GError, or %NULL
7465  *
7466  * Finishes an asynchronous replace of the given @file. See
7467  * g_file_replace_contents_async(). Sets @new_etag to the new entity
7468  * tag for the document, if present.
7469  *
7470  * Returns: %TRUE on success, %FALSE on failure.
7471  */
7472 gboolean
7473 g_file_replace_contents_finish (GFile         *file,
7474                                 GAsyncResult  *res,
7475                                 char         **new_etag,
7476                                 GError       **error)
7477 {
7478   GTask *task;
7479   ReplaceContentsData *data;
7480
7481   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7482   g_return_val_if_fail (g_task_is_valid (res, file), FALSE);
7483
7484   task = G_TASK (res);
7485
7486   if (!g_task_propagate_boolean (task, error))
7487     return FALSE;
7488
7489   data = g_task_get_task_data (task);
7490
7491   if (new_etag)
7492     {
7493       *new_etag = data->etag;
7494       data->etag = NULL; /* Take ownership */
7495     }
7496
7497   return TRUE;
7498 }
7499
7500 gboolean
7501 g_file_real_measure_disk_usage (GFile                         *file,
7502                                 GFileMeasureFlags              flags,
7503                                 GCancellable                  *cancellable,
7504                                 GFileMeasureProgressCallback   progress_callback,
7505                                 gpointer                       progress_data,
7506                                 guint64                       *disk_usage,
7507                                 guint64                       *num_dirs,
7508                                 guint64                       *num_files,
7509                                 GError                       **error)
7510 {
7511   g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7512                        "Operation not supported for the current backend.");
7513   return FALSE;
7514 }
7515
7516 typedef struct
7517 {
7518   GFileMeasureFlags             flags;
7519   GFileMeasureProgressCallback  progress_callback;
7520   gpointer                      progress_data;
7521 } MeasureTaskData;
7522
7523 typedef struct
7524 {
7525   guint64 disk_usage;
7526   guint64 num_dirs;
7527   guint64 num_files;
7528 } MeasureResult;
7529
7530 typedef struct
7531 {
7532   GFileMeasureProgressCallback callback;
7533   gpointer                     user_data;
7534   gboolean                     reporting;
7535   guint64                      current_size;
7536   guint64                      num_dirs;
7537   guint64                      num_files;
7538 } MeasureProgress;
7539
7540 static gboolean
7541 measure_disk_usage_invoke_progress (gpointer user_data)
7542 {
7543   MeasureProgress *progress = user_data;
7544
7545   (* progress->callback) (progress->reporting,
7546                           progress->current_size, progress->num_dirs, progress->num_files,
7547                           progress->user_data);
7548
7549   return FALSE;
7550 }
7551
7552 static void
7553 measure_disk_usage_progress (gboolean reporting,
7554                              guint64  current_size,
7555                              guint64  num_dirs,
7556                              guint64  num_files,
7557                              gpointer user_data)
7558 {
7559   MeasureProgress progress;
7560   GTask *task = user_data;
7561   MeasureTaskData *data;
7562
7563   data = g_task_get_task_data (task);
7564
7565   progress.callback = data->progress_callback;
7566   progress.user_data = data->progress_data;
7567   progress.reporting = reporting;
7568   progress.current_size = current_size;
7569   progress.num_dirs = num_dirs;
7570   progress.num_files = num_files;
7571
7572   g_main_context_invoke_full (g_task_get_context (task),
7573                               g_task_get_priority (task),
7574                               measure_disk_usage_invoke_progress,
7575                               g_memdup (&progress, sizeof progress),
7576                               g_free);
7577 }
7578
7579 static void
7580 measure_disk_usage_thread (GTask        *task,
7581                            gpointer      source_object,
7582                            gpointer      task_data,
7583                            GCancellable *cancellable)
7584 {
7585   MeasureTaskData *data = task_data;
7586   GError *error = NULL;
7587   MeasureResult result = { 0, };
7588
7589   if (g_file_measure_disk_usage (source_object, data->flags, cancellable,
7590                                  data->progress_callback ? measure_disk_usage_progress : NULL, task,
7591                                  &result.disk_usage, &result.num_dirs, &result.num_files,
7592                                  &error))
7593     g_task_return_pointer (task, g_memdup (&result, sizeof result), g_free);
7594   else
7595     g_task_return_error (task, error);
7596 }
7597
7598 static void
7599 g_file_real_measure_disk_usage_async (GFile                        *file,
7600                                       GFileMeasureFlags             flags,
7601                                       gint                          io_priority,
7602                                       GCancellable                 *cancellable,
7603                                       GFileMeasureProgressCallback  progress_callback,
7604                                       gpointer                      progress_data,
7605                                       GAsyncReadyCallback           callback,
7606                                       gpointer                      user_data)
7607 {
7608   MeasureTaskData data;
7609   GTask *task;
7610
7611   data.flags = flags;
7612   data.progress_callback = progress_callback;
7613   data.progress_data = progress_data;
7614
7615   task = g_task_new (file, cancellable, callback, user_data);
7616   g_task_set_source_tag (task, g_file_real_measure_disk_usage_async);
7617   g_task_set_task_data (task, g_memdup (&data, sizeof data), g_free);
7618   g_task_set_priority (task, io_priority);
7619
7620   g_task_run_in_thread (task, measure_disk_usage_thread);
7621   g_object_unref (task);
7622 }
7623
7624 static gboolean
7625 g_file_real_measure_disk_usage_finish (GFile         *file,
7626                                        GAsyncResult  *result,
7627                                        guint64       *disk_usage,
7628                                        guint64       *num_dirs,
7629                                        guint64       *num_files,
7630                                        GError       **error)
7631 {
7632   MeasureResult *measure_result;
7633
7634   g_return_val_if_fail (g_task_is_valid (result, file), FALSE);
7635
7636   measure_result = g_task_propagate_pointer (G_TASK (result), error);
7637
7638   if (measure_result == NULL)
7639     return FALSE;
7640
7641   if (disk_usage)
7642     *disk_usage = measure_result->disk_usage;
7643
7644   if (num_dirs)
7645     *num_dirs = measure_result->num_dirs;
7646
7647   if (num_files)
7648     *num_files = measure_result->num_files;
7649
7650   g_free (measure_result);
7651
7652   return TRUE;
7653 }
7654
7655 /**
7656  * g_file_measure_disk_usage:
7657  * @file: a #GFile
7658  * @flags: #GFileMeasureFlags
7659  * @cancellable: (nullable): optional #GCancellable
7660  * @progress_callback: (nullable): a #GFileMeasureProgressCallback
7661  * @progress_data: user_data for @progress_callback
7662  * @disk_usage: (out) (optional): the number of bytes of disk space used
7663  * @num_dirs: (out) (optional): the number of directories encountered
7664  * @num_files: (out) (optional): the number of non-directories encountered
7665  * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer
7666  *
7667  * Recursively measures the disk usage of @file.
7668  *
7669  * This is essentially an analog of the 'du' command, but it also
7670  * reports the number of directories and non-directory files encountered
7671  * (including things like symbolic links).
7672  *
7673  * By default, errors are only reported against the toplevel file
7674  * itself.  Errors found while recursing are silently ignored, unless
7675  * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
7676  *
7677  * The returned size, @disk_usage, is in bytes and should be formatted
7678  * with g_format_size() in order to get something reasonable for showing
7679  * in a user interface.
7680  *
7681  * @progress_callback and @progress_data can be given to request
7682  * periodic progress updates while scanning.  See the documentation for
7683  * #GFileMeasureProgressCallback for information about when and how the
7684  * callback will be invoked.
7685  *
7686  * Returns: %TRUE if successful, with the out parameters set.
7687  *          %FALSE otherwise, with @error set.
7688  *
7689  * Since: 2.38
7690  **/
7691 gboolean
7692 g_file_measure_disk_usage (GFile                         *file,
7693                            GFileMeasureFlags              flags,
7694                            GCancellable                  *cancellable,
7695                            GFileMeasureProgressCallback   progress_callback,
7696                            gpointer                       progress_data,
7697                            guint64                       *disk_usage,
7698                            guint64                       *num_dirs,
7699                            guint64                       *num_files,
7700                            GError                       **error)
7701 {
7702   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7703   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
7704   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
7705
7706   return G_FILE_GET_IFACE (file)->measure_disk_usage (file, flags, cancellable,
7707                                                       progress_callback, progress_data,
7708                                                       disk_usage, num_dirs, num_files,
7709                                                       error);
7710 }
7711
7712 /**
7713  * g_file_measure_disk_usage_async:
7714  * @file: a #GFile
7715  * @flags: #GFileMeasureFlags
7716  * @io_priority: the [I/O priority][io-priority] of the request
7717  * @cancellable: (nullable): optional #GCancellable
7718  * @progress_callback: (nullable): a #GFileMeasureProgressCallback
7719  * @progress_data: user_data for @progress_callback
7720  * @callback: (nullable): a #GAsyncReadyCallback to call when complete
7721  * @user_data: the data to pass to callback function
7722  *
7723  * Recursively measures the disk usage of @file.
7724  *
7725  * This is the asynchronous version of g_file_measure_disk_usage().  See
7726  * there for more information.
7727  *
7728  * Since: 2.38
7729  **/
7730 void
7731 g_file_measure_disk_usage_async (GFile                        *file,
7732                                  GFileMeasureFlags             flags,
7733                                  gint                          io_priority,
7734                                  GCancellable                 *cancellable,
7735                                  GFileMeasureProgressCallback  progress_callback,
7736                                  gpointer                      progress_data,
7737                                  GAsyncReadyCallback           callback,
7738                                  gpointer                      user_data)
7739 {
7740   g_return_if_fail (G_IS_FILE (file));
7741   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
7742
7743   G_FILE_GET_IFACE (file)->measure_disk_usage_async (file, flags, io_priority, cancellable,
7744                                                      progress_callback, progress_data,
7745                                                      callback, user_data);
7746 }
7747
7748 /**
7749  * g_file_measure_disk_usage_finish:
7750  * @file: a #GFile
7751  * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
7752  * @disk_usage: (out) (optional): the number of bytes of disk space used
7753  * @num_dirs: (out) (optional): the number of directories encountered
7754  * @num_files: (out) (optional): the number of non-directories encountered
7755  * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer
7756  *
7757  * Collects the results from an earlier call to
7758  * g_file_measure_disk_usage_async().  See g_file_measure_disk_usage() for
7759  * more information.
7760  *
7761  * Returns: %TRUE if successful, with the out parameters set.
7762  *          %FALSE otherwise, with @error set.
7763  *
7764  * Since: 2.38
7765  **/
7766 gboolean
7767 g_file_measure_disk_usage_finish (GFile         *file,
7768                                   GAsyncResult  *result,
7769                                   guint64       *disk_usage,
7770                                   guint64       *num_dirs,
7771                                   guint64       *num_files,
7772                                   GError       **error)
7773 {
7774   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7775   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
7776
7777   return G_FILE_GET_IFACE (file)->measure_disk_usage_finish (file, result, disk_usage, num_dirs, num_files, error);
7778 }
7779
7780 /**
7781  * g_file_start_mountable:
7782  * @file: input #GFile
7783  * @flags: flags affecting the operation
7784  * @start_operation: (nullable): a #GMountOperation, or %NULL to avoid user interaction
7785  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
7786  * @callback: (nullable): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
7787  * @user_data: the data to pass to callback function
7788  *
7789  * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
7790  * Using @start_operation, you can request callbacks when, for instance,
7791  * passwords are needed during authentication.
7792  *
7793  * If @cancellable is not %NULL, then the operation can be cancelled by
7794  * triggering the cancellable object from another thread. If the operation
7795  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7796  *
7797  * When the operation is finished, @callback will be called.
7798  * You can then call g_file_mount_mountable_finish() to get
7799  * the result of the operation.
7800  *
7801  * Since: 2.22
7802  */
7803 void
7804 g_file_start_mountable (GFile               *file,
7805                         GDriveStartFlags     flags,
7806                         GMountOperation     *start_operation,
7807                         GCancellable        *cancellable,
7808                         GAsyncReadyCallback  callback,
7809                         gpointer             user_data)
7810 {
7811   GFileIface *iface;
7812
7813   g_return_if_fail (G_IS_FILE (file));
7814
7815   iface = G_FILE_GET_IFACE (file);
7816
7817   if (iface->start_mountable == NULL)
7818     {
7819       g_task_report_new_error (file, callback, user_data,
7820                                g_file_start_mountable,
7821                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7822                                _("Operation not supported"));
7823       return;
7824     }
7825
7826   (* iface->start_mountable) (file,
7827                               flags,
7828                               start_operation,
7829                               cancellable,
7830                               callback,
7831                               user_data);
7832 }
7833
7834 /**
7835  * g_file_start_mountable_finish:
7836  * @file: input #GFile
7837  * @result: a #GAsyncResult
7838  * @error: a #GError, or %NULL
7839  *
7840  * Finishes a start operation. See g_file_start_mountable() for details.
7841  *
7842  * Finish an asynchronous start operation that was started
7843  * with g_file_start_mountable().
7844  *
7845  * Returns: %TRUE if the operation finished successfully. %FALSE
7846  * otherwise.
7847  *
7848  * Since: 2.22
7849  */
7850 gboolean
7851 g_file_start_mountable_finish (GFile         *file,
7852                                GAsyncResult  *result,
7853                                GError       **error)
7854 {
7855   GFileIface *iface;
7856
7857   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7858   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
7859
7860   if (g_async_result_legacy_propagate_error (result, error))
7861     return FALSE;
7862   else if (g_async_result_is_tagged (result, g_file_start_mountable))
7863     return g_task_propagate_boolean (G_TASK (result), error);
7864
7865   iface = G_FILE_GET_IFACE (file);
7866   return (* iface->start_mountable_finish) (file, result, error);
7867 }
7868
7869 /**
7870  * g_file_stop_mountable:
7871  * @file: input #GFile
7872  * @flags: flags affecting the operation
7873  * @mount_operation: (nullable): a #GMountOperation,
7874  *     or %NULL to avoid user interaction.
7875  * @cancellable: (nullable): optional #GCancellable object,
7876  *     %NULL to ignore
7877  * @callback: (nullable): a #GAsyncReadyCallback to call
7878  *     when the request is satisfied, or %NULL
7879  * @user_data: the data to pass to callback function
7880  *
7881  * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
7882  *
7883  * If @cancellable is not %NULL, then the operation can be cancelled by
7884  * triggering the cancellable object from another thread. If the operation
7885  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7886  *
7887  * When the operation is finished, @callback will be called.
7888  * You can then call g_file_stop_mountable_finish() to get
7889  * the result of the operation.
7890  *
7891  * Since: 2.22
7892  */
7893 void
7894 g_file_stop_mountable (GFile               *file,
7895                        GMountUnmountFlags   flags,
7896                        GMountOperation     *mount_operation,
7897                        GCancellable        *cancellable,
7898                        GAsyncReadyCallback  callback,
7899                        gpointer             user_data)
7900 {
7901   GFileIface *iface;
7902
7903   g_return_if_fail (G_IS_FILE (file));
7904
7905   iface = G_FILE_GET_IFACE (file);
7906
7907   if (iface->stop_mountable == NULL)
7908     {
7909       g_task_report_new_error (file, callback, user_data,
7910                                g_file_stop_mountable,
7911                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7912                                _("Operation not supported"));
7913       return;
7914     }
7915
7916   (* iface->stop_mountable) (file,
7917                              flags,
7918                              mount_operation,
7919                              cancellable,
7920                              callback,
7921                              user_data);
7922 }
7923
7924 /**
7925  * g_file_stop_mountable_finish:
7926  * @file: input #GFile
7927  * @result: a #GAsyncResult
7928  * @error: a #GError, or %NULL
7929  *
7930  * Finishes an stop operation, see g_file_stop_mountable() for details.
7931  *
7932  * Finish an asynchronous stop operation that was started
7933  * with g_file_stop_mountable().
7934  *
7935  * Returns: %TRUE if the operation finished successfully.
7936  *     %FALSE otherwise.
7937  *
7938  * Since: 2.22
7939  */
7940 gboolean
7941 g_file_stop_mountable_finish (GFile         *file,
7942                               GAsyncResult  *result,
7943                               GError       **error)
7944 {
7945   GFileIface *iface;
7946
7947   g_return_val_if_fail (G_IS_FILE (file), FALSE);
7948   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
7949
7950   if (g_async_result_legacy_propagate_error (result, error))
7951     return FALSE;
7952   else if (g_async_result_is_tagged (result, g_file_stop_mountable))
7953     return g_task_propagate_boolean (G_TASK (result), error);
7954
7955   iface = G_FILE_GET_IFACE (file);
7956   return (* iface->stop_mountable_finish) (file, result, error);
7957 }
7958
7959 /**
7960  * g_file_poll_mountable:
7961  * @file: input #GFile
7962  * @cancellable: optional #GCancellable object, %NULL to ignore
7963  * @callback: (nullable): a #GAsyncReadyCallback to call
7964  *     when the request is satisfied, or %NULL
7965  * @user_data: the data to pass to callback function
7966  *
7967  * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
7968  *
7969  * If @cancellable is not %NULL, then the operation can be cancelled by
7970  * triggering the cancellable object from another thread. If the operation
7971  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
7972  *
7973  * When the operation is finished, @callback will be called.
7974  * You can then call g_file_mount_mountable_finish() to get
7975  * the result of the operation.
7976  *
7977  * Since: 2.22
7978  */
7979 void
7980 g_file_poll_mountable (GFile               *file,
7981                        GCancellable        *cancellable,
7982                        GAsyncReadyCallback  callback,
7983                        gpointer             user_data)
7984 {
7985   GFileIface *iface;
7986
7987   g_return_if_fail (G_IS_FILE (file));
7988
7989   iface = G_FILE_GET_IFACE (file);
7990
7991   if (iface->poll_mountable == NULL)
7992     {
7993       g_task_report_new_error (file, callback, user_data,
7994                                g_file_poll_mountable,
7995                                G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
7996                                _("Operation not supported"));
7997       return;
7998     }
7999
8000   (* iface->poll_mountable) (file,
8001                              cancellable,
8002                              callback,
8003                              user_data);
8004 }
8005
8006 /**
8007  * g_file_poll_mountable_finish:
8008  * @file: input #GFile
8009  * @result: a #GAsyncResult
8010  * @error: a #GError, or %NULL
8011  *
8012  * Finishes a poll operation. See g_file_poll_mountable() for details.
8013  *
8014  * Finish an asynchronous poll operation that was polled
8015  * with g_file_poll_mountable().
8016  *
8017  * Returns: %TRUE if the operation finished successfully. %FALSE
8018  * otherwise.
8019  *
8020  * Since: 2.22
8021  */
8022 gboolean
8023 g_file_poll_mountable_finish (GFile         *file,
8024                               GAsyncResult  *result,
8025                               GError       **error)
8026 {
8027   GFileIface *iface;
8028
8029   g_return_val_if_fail (G_IS_FILE (file), FALSE);
8030   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
8031
8032   if (g_async_result_legacy_propagate_error (result, error))
8033     return FALSE;
8034   else if (g_async_result_is_tagged (result, g_file_poll_mountable))
8035     return g_task_propagate_boolean (G_TASK (result), error);
8036
8037   iface = G_FILE_GET_IFACE (file);
8038   return (* iface->poll_mountable_finish) (file, result, error);
8039 }
8040
8041 /**
8042  * g_file_supports_thread_contexts:
8043  * @file: a #GFile
8044  *
8045  * Checks if @file supports
8046  * [thread-default contexts][g-main-context-push-thread-default-context].
8047  * If this returns %FALSE, you cannot perform asynchronous operations on
8048  * @file in a thread that has a thread-default context.
8049  *
8050  * Returns: Whether or not @file supports thread-default contexts.
8051  *
8052  * Since: 2.22
8053  */
8054 gboolean
8055 g_file_supports_thread_contexts (GFile *file)
8056 {
8057  GFileIface *iface;
8058
8059  g_return_val_if_fail (G_IS_FILE (file), FALSE);
8060
8061  iface = G_FILE_GET_IFACE (file);
8062  return iface->supports_thread_contexts;
8063 }