gio/gfile.c

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