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