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