gfile.c 268 KB
Newer Older
1 2
/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
/* GIO - GLib Input, Output and Streaming Library
 * 
 * Copyright (C) 2006-2007 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General
 * Public License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, MA 02111-1307, USA.
 *
 * Author: Alexander Larsson <alexl@redhat.com>
 */

25
#include "config.h"
26

27
#ifdef __linux__
28 29 30 31 32 33 34
#include <sys/ioctl.h>
#include <errno.h>
/* See linux.git/fs/btrfs/ioctl.h */
#define BTRFS_IOCTL_MAGIC 0x94
#define BTRFS_IOC_CLONE _IOW(BTRFS_IOCTL_MAGIC, 9, int)
#endif

35 36 37 38 39 40
#ifdef HAVE_SPLICE
#include <sys/stat.h>
#include <unistd.h>
#include <fcntl.h>
#include <errno.h>
#endif
41

42 43 44 45 46
#include <string.h>
#include <sys/types.h>
#ifdef HAVE_PWD_H
#include <pwd.h>
#endif
47

48
#include "gfile.h"
Colin Walters's avatar
Colin Walters committed
49
#include "glib/gstdio.h"
50 51 52
#ifdef G_OS_UNIX
#include "glib-unix.h"
#endif
53
#include "gvfs.h"
54
#include "gtask.h"
55
#include "gfileattribute-priv.h"
56
#include "gfiledescriptorbased.h"
57
#include "gpollfilemonitor.h"
58 59 60
#include "gappinfo.h"
#include "gfileinputstream.h"
#include "gfileoutputstream.h"
61 62
#include "glocalfileoutputstream.h"
#include "glocalfileiostream.h"
63
#include "glocalfile.h"
64 65 66
#include "gcancellable.h"
#include "gasyncresult.h"
#include "gioerror.h"
67 68
#include "glibintl.h"

69

70 71 72
/**
 * SECTION:gfile
 * @short_description: File and Directory Handling
Matthias Clasen's avatar
Matthias Clasen committed
73
 * @include: gio/gio.h
74
 * @see_also: #GFileInfo, #GFileEnumerator
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
 *
 * #GFile is a high level abstraction for manipulating files on a
 * virtual file system. #GFiles are lightweight, immutable objects
 * that do no I/O upon creation. It is necessary to understand that
 * #GFile objects do not represent files, merely an identifier for a
 * file. All file content I/O is implemented as streaming operations
 * (see #GInputStream and #GOutputStream).
 *
 * To construct a #GFile, you can use:
 * <simplelist>
 * <member>g_file_new_for_path() if you have a path.</member>
 * <member>g_file_new_for_uri() if you have a URI.</member>
 * <member>g_file_new_for_commandline_arg() for a command line argument.</member>
 * <member>g_file_new_tmp() to create a temporary file from a template.</member>
 * <member>g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().</member>
 * </simplelist>
 *
 * One way to think of a #GFile is as an abstraction of a pathname. For
 * normal files the system pathname is what is stored internally, but as
 * #GFiles are extensible it could also be something else that corresponds
 * to a pathname in a userspace implementation of a filesystem.
 *
 * #GFiles make up hierarchies of directories and files that correspond to
 * the files on a filesystem. You can move through the file system with
 * #GFile using g_file_get_parent() to get an identifier for the parent
 * directory, g_file_get_child() to get a child within a directory,
 * g_file_resolve_relative_path() to resolve a relative path between two
 * #GFiles. There can be multiple hierarchies, so you may not end up at
 * the same root if you repeatedly call g_file_get_parent() on two different
104 105
 * files.
 *
106 107 108 109 110 111
 * All #GFiles have a basename (get with g_file_get_basename()). These names
 * are byte strings that are used to identify the file on the filesystem
 * (relative to its parent directory) and there is no guarantees that they
 * have any particular charset encoding or even make any sense at all. If
 * you want to use filenames in a user interface you should use the display
 * name that you can get by requesting the
112
 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
113 114 115 116 117 118 119 120 121 122 123
 * This is guaranteed to be in UTF-8 and can be used in a user interface.
 * But always store the real basename or the #GFile to use to actually
 * access the file, because there is no way to go from a display name to
 * the actual name.
 *
 * Using #GFile as an identifier has the same weaknesses as using a path
 * in that there may be multiple aliases for the same file. For instance,
 * hard or soft links may cause two different #GFiles to refer to the same
 * file. Other possible causes for aliases are: case insensitive filesystems,
 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
 * check if two #GFiles point to the same file you can query for the
124
 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
125 126 127 128 129 130 131 132 133 134
 * canonicalization of pathnames passed in, so that trivial differences in
 * the path string used at creation (duplicated slashes, slash at end of
 * path, "." or ".." path segments, etc) does not create different #GFiles.
 *
 * Many #GFile operations have both synchronous and asynchronous versions
 * to suit your application. Asynchronous versions of synchronous functions
 * simply have _async() appended to their function names. The asynchronous
 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
 * the operation, producing a GAsyncResult which is then passed to the
 * function's matching _finish() operation.
135 136 137 138
 *
 * Some #GFile operations do not have synchronous analogs, as they may
 * take a very long time to finish, and blocking may leave an application
 * unusable. Notable cases include:
139 140 141 142 143 144
 * <simplelist>
 * <member>g_file_mount_mountable() to mount a mountable file.</member>
 * <member>g_file_unmount_mountable_with_operation() to unmount a mountable file.</member>
 * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member>
 * </simplelist>
 *
Matthias Clasen's avatar
Matthias Clasen committed
145
 * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
146 147
 * One notable feature of #GFiles are entity tags, or "etags" for
 * short. Entity tags are somewhat like a more abstract version of the
Matthias Clasen's avatar
Matthias Clasen committed
148
 * traditional mtime, and can be used to quickly determine if the file has
149
 * been modified from the version on the file system. See the HTTP 1.1
Matthias Clasen's avatar
Matthias Clasen committed
150
 * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink>
Matthias Clasen's avatar
Matthias Clasen committed
151 152
 * for HTTP Etag headers, which are a very similar concept.
 * </para>
153 154
 **/

155
static void               g_file_real_query_info_async            (GFile                  *file,
156 157 158 159 160 161
                                                                   const char             *attributes,
                                                                   GFileQueryInfoFlags     flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
162
static GFileInfo *        g_file_real_query_info_finish           (GFile                  *file,
163 164
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
165
static void               g_file_real_query_filesystem_info_async (GFile                  *file,
166 167 168 169 170
                                                                   const char             *attributes,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
171
static GFileInfo *        g_file_real_query_filesystem_info_finish (GFile                  *file,
172 173
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
174
static void               g_file_real_enumerate_children_async    (GFile                  *file,
175 176 177 178 179 180
                                                                   const char             *attributes,
                                                                   GFileQueryInfoFlags     flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
181
static GFileEnumerator *  g_file_real_enumerate_children_finish   (GFile                  *file,
182 183
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
184
static void               g_file_real_read_async                  (GFile                  *file,
185 186 187 188
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
189
static GFileInputStream * g_file_real_read_finish                 (GFile                  *file,
190 191
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
192
static void               g_file_real_append_to_async             (GFile                  *file,
193 194 195 196 197
                                                                   GFileCreateFlags        flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
198
static GFileOutputStream *g_file_real_append_to_finish            (GFile                  *file,
199 200
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
201
static void               g_file_real_create_async                (GFile                  *file,
202 203 204 205 206
                                                                   GFileCreateFlags        flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
207
static GFileOutputStream *g_file_real_create_finish               (GFile                  *file,
208 209
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
210
static void               g_file_real_replace_async               (GFile                  *file,
211 212 213 214 215 216 217
                                                                   const char             *etag,
                                                                   gboolean                make_backup,
                                                                   GFileCreateFlags        flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
218
static GFileOutputStream *g_file_real_replace_finish              (GFile                  *file,
219 220
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
221
static void               g_file_real_delete_async                (GFile                  *file,
222 223 224 225
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
226
static gboolean           g_file_real_delete_finish               (GFile                  *file,
227 228
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
229 230 231 232 233 234 235 236
static void               g_file_real_trash_async                 (GFile                  *file,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
static gboolean           g_file_real_trash_finish                (GFile                  *file,
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
237 238 239 240 241 242 243 244
static void               g_file_real_make_directory_async        (GFile                  *file,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
static gboolean           g_file_real_make_directory_finish       (GFile                  *file,
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
static void               g_file_real_open_readwrite_async        (GFile                  *file,
                                                                   int                  io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
static GFileIOStream *    g_file_real_open_readwrite_finish       (GFile                  *file,
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
static void               g_file_real_create_readwrite_async      (GFile                  *file,
                                                                   GFileCreateFlags        flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
static GFileIOStream *    g_file_real_create_readwrite_finish     (GFile                  *file,
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
static void               g_file_real_replace_readwrite_async     (GFile                  *file,
                                                                   const char             *etag,
                                                                   gboolean                make_backup,
                                                                   GFileCreateFlags        flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
static GFileIOStream *    g_file_real_replace_readwrite_finish    (GFile                  *file,
                                                                  GAsyncResult            *res,
                                                                  GError                 **error);
273
static gboolean           g_file_real_set_attributes_from_info    (GFile                  *file,
274 275 276 277
                                                                   GFileInfo              *info,
                                                                   GFileQueryInfoFlags     flags,
                                                                   GCancellable           *cancellable,
                                                                   GError                **error);
278
static void               g_file_real_set_display_name_async      (GFile                  *file,
279 280 281 282 283
                                                                   const char             *display_name,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
284
static GFile *            g_file_real_set_display_name_finish     (GFile                  *file,
285 286
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
287
static void               g_file_real_set_attributes_async        (GFile                  *file,
288 289 290 291 292 293
                                                                   GFileInfo              *info,
                                                                   GFileQueryInfoFlags     flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
294
static gboolean           g_file_real_set_attributes_finish       (GFile                  *file,
295 296 297
                                                                   GAsyncResult           *res,
                                                                   GFileInfo             **info,
                                                                   GError                **error);
298
static void               g_file_real_find_enclosing_mount_async  (GFile                  *file,
299 300 301 302
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
303
static GMount *           g_file_real_find_enclosing_mount_finish (GFile                  *file,
304 305
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
306
static void               g_file_real_copy_async                  (GFile                  *source,
307 308 309 310 311 312 313 314
                                                                   GFile                  *destination,
                                                                   GFileCopyFlags          flags,
                                                                   int                     io_priority,
                                                                   GCancellable           *cancellable,
                                                                   GFileProgressCallback   progress_callback,
                                                                   gpointer                progress_callback_data,
                                                                   GAsyncReadyCallback     callback,
                                                                   gpointer                user_data);
315
static gboolean           g_file_real_copy_finish                 (GFile                  *file,
316 317
                                                                   GAsyncResult           *res,
                                                                   GError                **error);
318

319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342
static gboolean           g_file_real_measure_disk_usage          (GFile                         *file,
                                                                   GFileMeasureFlags              flags,
                                                                   GCancellable                  *cancellable,
                                                                   GFileMeasureProgressCallback   progress_callback,
                                                                   gpointer                       progress_data,
                                                                   guint64                       *disk_usage,
                                                                   guint64                       *num_dirs,
                                                                   guint64                       *num_files,
                                                                   GError                       **error);
static void               g_file_real_measure_disk_usage_async    (GFile                         *file,
                                                                   GFileMeasureFlags              flags,
                                                                   gint                           io_priority,
                                                                   GCancellable                  *cancellable,
                                                                   GFileMeasureProgressCallback   progress_callback,
                                                                   gpointer                       progress_data,
                                                                   GAsyncReadyCallback            callback,
                                                                   gpointer                       user_data);
static gboolean           g_file_real_measure_disk_usage_finish   (GFile                         *file,
                                                                   GAsyncResult                  *result,
                                                                   guint64                       *disk_usage,
                                                                   guint64                       *num_dirs,
                                                                   guint64                       *num_files,
                                                                   GError                       **error);

343 344
typedef GFileIface GFileInterface;
G_DEFINE_INTERFACE (GFile, g_file, G_TYPE_OBJECT)
345 346

static void
347
g_file_default_init (GFileIface *iface)
348 349 350 351 352 353 354
{
  iface->enumerate_children_async = g_file_real_enumerate_children_async;
  iface->enumerate_children_finish = g_file_real_enumerate_children_finish;
  iface->set_display_name_async = g_file_real_set_display_name_async;
  iface->set_display_name_finish = g_file_real_set_display_name_finish;
  iface->query_info_async = g_file_real_query_info_async;
  iface->query_info_finish = g_file_real_query_info_finish;
355 356
  iface->query_filesystem_info_async = g_file_real_query_filesystem_info_async;
  iface->query_filesystem_info_finish = g_file_real_query_filesystem_info_finish;
357 358 359 360 361 362 363 364 365 366
  iface->set_attributes_async = g_file_real_set_attributes_async;
  iface->set_attributes_finish = g_file_real_set_attributes_finish;
  iface->read_async = g_file_real_read_async;
  iface->read_finish = g_file_real_read_finish;
  iface->append_to_async = g_file_real_append_to_async;
  iface->append_to_finish = g_file_real_append_to_finish;
  iface->create_async = g_file_real_create_async;
  iface->create_finish = g_file_real_create_finish;
  iface->replace_async = g_file_real_replace_async;
  iface->replace_finish = g_file_real_replace_finish;
367 368
  iface->delete_file_async = g_file_real_delete_async;
  iface->delete_file_finish = g_file_real_delete_finish;
369 370
  iface->trash_async = g_file_real_trash_async;
  iface->trash_finish = g_file_real_trash_finish;
371 372
  iface->make_directory_async = g_file_real_make_directory_async;
  iface->make_directory_finish = g_file_real_make_directory_finish;
373 374 375 376 377 378
  iface->open_readwrite_async = g_file_real_open_readwrite_async;
  iface->open_readwrite_finish = g_file_real_open_readwrite_finish;
  iface->create_readwrite_async = g_file_real_create_readwrite_async;
  iface->create_readwrite_finish = g_file_real_create_readwrite_finish;
  iface->replace_readwrite_async = g_file_real_replace_readwrite_async;
  iface->replace_readwrite_finish = g_file_real_replace_readwrite_finish;
379 380
  iface->find_enclosing_mount_async = g_file_real_find_enclosing_mount_async;
  iface->find_enclosing_mount_finish = g_file_real_find_enclosing_mount_finish;
381
  iface->set_attributes_from_info = g_file_real_set_attributes_from_info;
382 383
  iface->copy_async = g_file_real_copy_async;
  iface->copy_finish = g_file_real_copy_finish;
384 385 386
  iface->measure_disk_usage = g_file_real_measure_disk_usage;
  iface->measure_disk_usage_async = g_file_real_measure_disk_usage_async;
  iface->measure_disk_usage_finish = g_file_real_measure_disk_usage_finish;
387 388 389 390 391
}


/**
 * g_file_is_native:
392
 * @file: input #GFile
393
 *
394
 * Checks to see if a file is native to the platform.
395
 *
396 397 398 399
 * A native file s one expressed in the platform-native filename format,
 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
 * as it might be on a locally mounted remote filesystem.
 *
400 401 402
 * On some systems non-native files may be available using the native
 * filesystem via a userspace filesystem (FUSE), in these cases this call
 * will return %FALSE, but g_file_get_path() will still return a native path.
403
 *
404 405 406 407
 * This call does no blocking I/O.
 *
 * Returns: %TRUE if @file is native
 */
408 409 410 411 412 413 414 415 416 417 418 419 420 421
gboolean
g_file_is_native (GFile *file)
{
  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), FALSE);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->is_native) (file);
}


/**
422 423 424
 * g_file_has_uri_scheme:
 * @file: input #GFile
 * @uri_scheme: a string containing a URI scheme
425
 *
426 427
 * Checks to see if a #GFile has a given URI scheme.
 *
428 429
 * This call does no blocking I/O.
 *
430
 * Returns: %TRUE if #GFile's backend supports the
Matthias Clasen's avatar
Matthias Clasen committed
431 432
 *     given URI scheme, %FALSE if URI scheme is %NULL,
 *     not supported, or #GFile is invalid.
433
 */
434
gboolean
Matthias Clasen's avatar
Matthias Clasen committed
435
g_file_has_uri_scheme (GFile      *file,
436
                       const char *uri_scheme)
437 438
{
  GFileIface *iface;
439

440 441 442 443 444 445 446 447 448 449 450
  g_return_val_if_fail (G_IS_FILE (file), FALSE);
  g_return_val_if_fail (uri_scheme != NULL, FALSE);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->has_uri_scheme) (file, uri_scheme);
}


/**
 * g_file_get_uri_scheme:
451
 * @file: input #GFile
452
 *
453
 * Gets the URI scheme for a #GFile.
454
 * RFC 3986 decodes the scheme as:
455
 * <programlisting>
456
 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
457
 * </programlisting>
458
 * Common schemes include "file", "http", "ftp", etc.
459
 *
460 461 462 463
 * This call does no blocking I/O.
 *
 * Returns: a string containing the URI scheme for the given
 *     #GFile. The returned string should be freed with g_free()
464
 *     when no longer needed.
465
 */
466 467 468 469 470 471 472 473 474 475 476 477 478 479 480
char *
g_file_get_uri_scheme (GFile *file)
{
  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_uri_scheme) (file);
}


/**
 * g_file_get_basename:
481
 * @file: input #GFile
482
 *
483
 * Gets the base name (the last component of the path) for a given #GFile.
484
 *
485
 * If called for the top level of a system (such as the filesystem root
486
 * or a uri like sftp://host/) it will return a single directory separator
487
 * (and on Windows, possibly a drive letter).
488
 *
489
 * The base name is a byte string (not UTF-8). It has no defined encoding
490 491 492 493
 * or rules other than it may not contain zero bytes.  If you want to use
 * filenames in a user interface you should use the display name that you
 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
 * attribute with g_file_query_info().
494 495 496 497 498
 *
 * This call does no blocking I/O.
 *
 * Returns: string containing the #GFile's base name, or %NULL
 *     if given #GFile is invalid. The returned string should be
499
 *     freed with g_free() when no longer needed.
500
 */
501 502 503 504
char *
g_file_get_basename (GFile *file)
{
  GFileIface *iface;
505

506 507 508 509 510 511 512 513 514
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_basename) (file);
}

/**
 * g_file_get_path:
515
 * @file: input #GFile
516
 *
517
 * Gets the local pathname for #GFile, if one exists.
518
 *
519 520 521 522
 * This call does no blocking I/O.
 *
 * Returns: string containing the #GFile's path, or %NULL if
 *     no such path exists. The returned string should be
523
 *     freed with g_free() when no longer needed.
524
 */
525 526 527 528 529 530 531 532 533 534 535 536 537 538
char *
g_file_get_path (GFile *file)
{
  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_path) (file);
}

/**
 * g_file_get_uri:
539
 * @file: input #GFile
540
 *
541
 * Gets the URI for the @file.
542
 *
543 544
 * This call does no blocking I/O.
 *
545
 * Returns: a string containing the #GFile's URI.
546 547 548
 *     The returned string should be freed with g_free()
 *     when no longer needed.
 */
549 550 551 552
char *
g_file_get_uri (GFile *file)
{
  GFileIface *iface;
553

554 555 556 557 558 559 560 561
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_uri) (file);
}

/**
Matthias Clasen's avatar
Matthias Clasen committed
562
 * g_file_get_parse_name:
563
 * @file: input #GFile
564
 *
565 566 567 568 569 570
 * Gets the parse name of the @file.
 * A parse name is a UTF-8 string that describes the
 * file such that one can get the #GFile back using
 * g_file_parse_name().
 *
 * This is generally used to show the #GFile as a nice
571 572
 * full-pathname kind of string in a user interface,
 * like in a location entry.
573
 *
574
 * For local files with names that can safely be converted
575 576
 * to UTF-8 the pathname is used, otherwise the IRI is used
 * (a form of URI that allows UTF-8 characters unescaped).
577
 *
578 579 580 581 582 583
 * This call does no blocking I/O.
 *
 * Returns: a string containing the #GFile's parse name.
 *     The returned string should be freed with g_free()
 *     when no longer needed.
 */
584 585 586 587
char *
g_file_get_parse_name (GFile *file)
{
  GFileIface *iface;
588

589 590 591 592 593 594 595 596 597
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_parse_name) (file);
}

/**
 * g_file_dup:
598
 * @file: input #GFile
599
 *
600 601 602
 * Duplicates a #GFile handle. This operation does not duplicate
 * the actual file or directory represented by the #GFile; see
 * g_file_copy() if attempting to copy a file.
603
 *
604 605 606 607 608
 * This call does no blocking I/O.
 *
 * Returns: (transfer full): a new #GFile that is a duplicate
 *     of the given #GFile.
 */
609 610 611 612
GFile *
g_file_dup (GFile *file)
{
  GFileIface *iface;
613

614 615 616 617 618 619 620 621 622
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->dup) (file);
}

/**
 * g_file_hash:
623
 * @file: (type GFile): #gconstpointer to a #GFile
624
 *
625
 * Creates a hash value for a #GFile.
626
 *
627
 * This call does no blocking I/O.
628 629
 *
 * Virtual: hash
630 631 632
 * Returns: 0 if @file is not a valid #GFile, otherwise an
 *     integer that can be used as hash value for the #GFile.
 *     This function is intended for easily hashing a #GFile to
633
 *     add to a #GHashTable or similar data structure.
634
 */
635 636 637 638
guint
g_file_hash (gconstpointer file)
{
  GFileIface *iface;
639

640 641 642 643 644 645 646 647 648
  g_return_val_if_fail (G_IS_FILE (file), 0);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->hash) ((GFile *)file);
}

/**
 * g_file_equal:
649 650 651 652
 * @file1: the first #GFile
 * @file2: the second #GFile
 *
 * Checks equality of two given #GFiles.
653
 *
654
 * Note that two #GFiles that differ can still refer to the same
655 656
 * file on the filesystem due to various forms of filename
 * aliasing.
657
 *
658 659
 * This call does no blocking I/O.
 *
660
 * Returns: %TRUE if @file1 and @file2 are equal.
661
 *     %FALSE if either is not a #GFile.
662
 */
663 664
gboolean
g_file_equal (GFile *file1,
665
              GFile *file2)
666 667
{
  GFileIface *iface;
668

669 670
  g_return_val_if_fail (G_IS_FILE (file1), FALSE);
  g_return_val_if_fail (G_IS_FILE (file2), FALSE);
671

672 673 674 675
  if (G_TYPE_FROM_INSTANCE (file1) != G_TYPE_FROM_INSTANCE (file2))
    return FALSE;

  iface = G_FILE_GET_IFACE (file1);
676

677 678 679 680 681 682
  return (* iface->equal) (file1, file2);
}


/**
 * g_file_get_parent:
683
 * @file: input #GFile
684
 *
685 686
 * Gets the parent directory for the @file.
 * If the @file represents the root directory of the
687
 * file system, then %NULL will be returned.
688
 *
689 690 691 692 693 694
 * This call does no blocking I/O.
 *
 * Returns: (transfer full): a #GFile structure to the
 *     parent of the given #GFile or %NULL if there is
 *     no parent. Free the returned object with g_object_unref().
 */
695 696 697 698
GFile *
g_file_get_parent (GFile *file)
{
  GFileIface *iface;
699

700 701 702 703 704 705 706
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_parent) (file);
}

707 708 709
/**
 * g_file_has_parent:
 * @file: input #GFile
710
 * @parent: (allow-none): the parent to check for, or %NULL
711 712 713 714 715 716 717 718 719 720 721
 *
 * Checks if @file has a parent, and optionally, if it is @parent.
 *
 * If @parent is %NULL then this function returns %TRUE if @file has any
 * parent at all.  If @parent is non-%NULL then %TRUE is only returned
 * if @file is a child of @parent.
 *
 * Returns: %TRUE if @file is a child of @parent (or any parent in the
 *          case that @parent is %NULL).
 *
 * Since: 2.24
722
 */
723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749
gboolean
g_file_has_parent (GFile *file,
                   GFile *parent)
{
  GFile *actual_parent;
  gboolean result;

  g_return_val_if_fail (G_IS_FILE (file), FALSE);
  g_return_val_if_fail (parent == NULL || G_IS_FILE (parent), FALSE);

  actual_parent = g_file_get_parent (file);

  if (actual_parent != NULL)
    {
      if (parent != NULL)
        result = g_file_equal (parent, actual_parent);
      else
        result = TRUE;

      g_object_unref (actual_parent);
    }
  else
    result = FALSE;

  return result;
}

750 751
/**
 * g_file_get_child:
752 753
 * @file: input #GFile
 * @name: string containing the child's basename
754
 *
755
 * Gets a child of @file with basename equal to @name.
756 757 758 759
 *
 * Note that the file with that specific name might not exist, but
 * you can still have a #GFile that points to it. You can use this
 * for instance to create that file.
760
 *
761 762
 * This call does no blocking I/O.
 *
763
 * Returns: (transfer full): a #GFile to a child specified by @name.
Matthias Clasen's avatar
Matthias Clasen committed
764
 *     Free the returned object with g_object_unref().
765
 */
766
GFile *
Matthias Clasen's avatar
Matthias Clasen committed
767
g_file_get_child (GFile      *file,
768
                  const char *name)
769 770 771 772 773 774 775 776 777
{
  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (name != NULL, NULL);

  return g_file_resolve_relative_path (file, name);
}

/**
 * g_file_get_child_for_display_name:
778 779 780 781 782 783 784 785 786 787 788 789 790 791 792
 * @file: input #GFile
 * @display_name: string to a possible child
 * @error: return location for an error
 *
 * Gets the child of @file for a given @display_name (i.e. a UTF-8
 * version of the name). If this function fails, it returns %NULL
 * and @error will be set. This is very useful when constructing a
 * #GFile for a new file and the user entered the filename in the
 * user interface, for instance when you select a directory and
 * type a filename in the file selector.
 *
 * This call does no blocking I/O.
 *
 * Returns: (transfer full): a #GFile to the specified child, or
 *     %NULL if the display name couldn't be converted.
Matthias Clasen's avatar
Matthias Clasen committed
793
 *     Free the returned object with g_object_unref().
794
 */
795
GFile *
Matthias Clasen's avatar
Matthias Clasen committed
796
g_file_get_child_for_display_name (GFile      *file,
797 798
                                   const char *display_name,
                                   GError **error)
799 800
{
  GFileIface *iface;
801

802 803 804 805 806 807 808 809
  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (display_name != NULL, NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->get_child_for_display_name) (file, display_name, error);
}

810 811
/**
 * g_file_has_prefix:
812 813 814 815 816 817 818 819 820 821 822 823 824
 * @file: input #GFile
 * @prefix: input #GFile
 *
 * Checks whether @file has the prefix specified by @prefix.
 *
 * In other words, if the names of initial elements of @file's
 * pathname match @prefix. Only full pathname elements are matched,
 * so a path like /foo is not considered a prefix of /foobar, only
 * of /foo/bar.
 *
 * This call does no I/O, as it works purely on names. As such it can
 * sometimes return %FALSE even if @file is inside a @prefix (from a
 * filesystem point of view), because the prefix of @file is an alias
Matthias Clasen's avatar
Matthias Clasen committed
825
 * of @prefix.
826
 *
827
 * Virtual: prefix_matches
828
 * Returns:  %TRUE if the @files's parent, grandparent, etc is @prefix,
Matthias Clasen's avatar
Matthias Clasen committed
829
 *     %FALSE otherwise.
830
 */
831 832
gboolean
g_file_has_prefix (GFile *file,
833
                   GFile *prefix)
834 835
{
  GFileIface *iface;
836

837 838
  g_return_val_if_fail (G_IS_FILE (file), FALSE);
  g_return_val_if_fail (G_IS_FILE (prefix), FALSE);
839

840
  if (G_TYPE_FROM_INSTANCE (file) != G_TYPE_FROM_INSTANCE (prefix))
841
    return FALSE;
842

843
  iface = G_FILE_GET_IFACE (file);
844

845 846 847
  /* The vtable function differs in arg order since
   * we're using the old contains_file call
   */
848
  return (* iface->prefix_matches) (prefix, file);
849 850 851 852
}

/**
 * g_file_get_relative_path:
853 854
 * @parent: input #GFile
 * @descendant: input #GFile
855
 *
856
 * Gets the path for @descendant relative to @parent.
857
 *
858 859 860 861 862 863 864
 * This call does no blocking I/O.
 *
 * Returns: string with the relative path from @descendant
 *     to @parent, or %NULL if @descendant doesn't have @parent
 *     as prefix. The returned string should be freed with g_free()
 *     when no longer needed.
 */
865 866
char *
g_file_get_relative_path (GFile *parent,
867
                          GFile *descendant)
868 869
{
  GFileIface *iface;
870

871 872 873 874 875
  g_return_val_if_fail (G_IS_FILE (parent), NULL);
  g_return_val_if_fail (G_IS_FILE (descendant), NULL);

  if (G_TYPE_FROM_INSTANCE (parent) != G_TYPE_FROM_INSTANCE (descendant))
    return NULL;
876

877 878 879 880 881 882 883
  iface = G_FILE_GET_IFACE (parent);

  return (* iface->get_relative_path) (parent, descendant);
}

/**
 * g_file_resolve_relative_path:
884 885
 * @file: input #GFile
 * @relative_path: a given relative path string
886
 *
887 888
 * Resolves a relative path for @file to an absolute path.
 *
889 890 891 892
 * This call does no blocking I/O.
 *
 * Returns: (transfer full): #GFile to the resolved path.
 *     %NULL if @relative_path is %NULL or if @file is invalid.
Matthias Clasen's avatar
Matthias Clasen committed
893
 *     Free the returned object with g_object_unref().
894
 */
895
GFile *
Matthias Clasen's avatar
Matthias Clasen committed
896
g_file_resolve_relative_path (GFile      *file,
897
                              const char *relative_path)
898 899 900 901 902 903 904 905 906 907 908 909 910
{
  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (relative_path != NULL, NULL);

  iface = G_FILE_GET_IFACE (file);

  return (* iface->resolve_relative_path) (file, relative_path);
}

/**
 * g_file_enumerate_children:
911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @error: #GError for error reporting
 *
 * Gets the requested information about the files in a directory.
 * The result is a #GFileEnumerator object that will give out
 * #GFileInfo objects for all the files in the directory.
 *
 * The @attributes value is a string that specifies the file
 * attributes that should be gathered. It is not an error if
 * it's not possible to read a particular requested attribute
 * from a file - it just won't be set. @attributes should
 * be a comma-separated list of attributes or attribute wildcards.
 * The wildcard "*" means all attributes, and a wildcard like
 * "standard::*" means all attributes in the standard namespace.
 * An example attribute query be "standard::*,owner::user".
 * The standard attributes are available as defines, like
 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
 *
 * If @cancellable is not %NULL, then the operation can be cancelled
 * by triggering the cancellable object from another thread. If the
 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
 * returned.
 *
 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
939
 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
940 941 942 943 944
 * error will be returned. Other errors are possible too.
 *
 * Returns: (transfer full): A #GFileEnumerator if successful,
 *     %NULL on error. Free the returned object with g_object_unref().
 */
945
GFileEnumerator *
Matthias Clasen's avatar
Matthias Clasen committed
946
g_file_enumerate_children (GFile                *file,
947 948 949 950
                           const char           *attributes,
                           GFileQueryInfoFlags   flags,
                           GCancellable         *cancellable,
                           GError              **error)
951 952
{
  GFileIface *iface;
953

954 955 956 957
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  if (g_cancellable_set_error_if_cancelled (cancellable, error))
    return NULL;
958

959 960 961 962
  iface = G_FILE_GET_IFACE (file);

  if (iface->enumerate_children == NULL)
    {
963 964 965
      g_set_error_literal (error, G_IO_ERROR,
                           G_IO_ERROR_NOT_SUPPORTED,
                           _("Operation not supported"));
966 967 968 969
      return NULL;
    }

  return (* iface->enumerate_children) (file, attributes, flags,
970
                                        cancellable, error);
971 972 973 974
}

/**
 * g_file_enumerate_children_async:
975 976 977 978 979 980 981 982
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
 * @io_priority: the <link linkend="io-priority">I/O priority</link>
 *     of the request
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call when the
983 984
 *     request is satisfied
 * @user_data: (closure): the data to pass to callback function
985
 *
986 987 988
 * Asynchronously gets the requested information about the files
 * in a directory. The result is a #GFileEnumerator object that will
 * give out #GFileInfo objects for all the files in the directory.
989 990 991 992
 *
 * For more details, see g_file_enumerate_children() which is
 * the synchronous version of this call.
 *
993 994 995 996
 * When the operation is finished, @callback will be called. You can
 * then call g_file_enumerate_children_finish() to get the result of
 * the operation.
 */
997
void
Matthias Clasen's avatar
Matthias Clasen committed
998
g_file_enumerate_children_async (GFile               *file,
999 1000 1001 1002 1003 1004
                                 const char          *attributes,
                                 GFileQueryInfoFlags  flags,
                                 int                  io_priority,
                                 GCancellable        *cancellable,
                                 GAsyncReadyCallback  callback,
                                 gpointer             user_data)
1005 1006 1007 1008 1009 1010 1011
{
  GFileIface *iface;

  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->enumerate_children_async) (file,
1012 1013 1014 1015 1016 1017
                                       attributes,
                                       flags,
                                       io_priority,
                                       cancellable,
                                       callback,
                                       user_data);
1018 1019 1020 1021
}

/**
 * g_file_enumerate_children_finish:
1022 1023 1024 1025
 * @file: input #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
 *
Matthias Clasen's avatar
Matthias Clasen committed
1026
 * Finishes an async enumerate children operation.
1027
 * See g_file_enumerate_children_async().
Matthias Clasen's avatar
Matthias Clasen committed
1028
 *
1029 1030
 * Returns: (transfer full): a #GFileEnumerator or %NULL
 *     if an error occurred.
1031
 *     Free the returned object with g_object_unref().
1032
 */
1033
GFileEnumerator *
Matthias Clasen's avatar
Matthias Clasen committed
1034
g_file_enumerate_children_finish (GFile         *file,
1035 1036
                                  GAsyncResult  *res,
                                  GError       **error)
1037 1038
{
  GFileIface *iface;
1039

1040 1041 1042
  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);

1043 1044
  if (g_async_result_legacy_propagate_error (res, error))
    return NULL;
1045

1046 1047 1048 1049
  iface = G_FILE_GET_IFACE (file);
  return (* iface->enumerate_children_finish) (file, res, error);
}

1050 1051
/**
 * g_file_query_exists:
1052 1053 1054
 * @file: input #GFile
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
1055 1056 1057 1058
 *
 * Utility function to check if a particular file exists. This is
 * implemented using g_file_query_info() and as such does blocking I/O.
 *
1059
 * Note that in many cases it is racy to first check for file existence
1060
 * and then execute something based on the outcome of that, because the
1061
 * file might have been created or removed in between the operations. The
1062 1063 1064
 * general approach to handling that is to not check, but just do the
 * operation and handle the errors as they come.
 *
1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080
 * As an example of race-free checking, take the case of reading a file,
 * and if it doesn't exist, creating it. There are two racy versions: read
 * it, and on error create it; and: check if it exists, if not create it.
 * These can both result in two processes creating the file (with perhaps
 * a partially written file as the result). The correct approach is to
 * always try to create the file with g_file_create() which will either
 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
 *
 * However, in many cases an existence check is useful in a user interface,
 * for instance to make a menu item sensitive/insensitive, so that you don't
 * have to fool users that something is possible and then just show an error
 * dialog. If you do this, you should make sure to also handle the errors
 * that can happen due to races when you execute the operation.
 *
 * Returns: %TRUE if the file exists (and can be detected without error),
 *     %FALSE otherwise (or if cancelled).
1081 1082
 */
gboolean
1083 1084
g_file_query_exists (GFile        *file,
                     GCancellable *cancellable)
1085 1086
{
  GFileInfo *info;
1087

1088
  g_return_val_if_fail (G_IS_FILE(file), FALSE);
1089

1090
  info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE,
1091
                            G_FILE_QUERY_INFO_NONE, cancellable, NULL);
1092 1093 1094 1095 1096
  if (info != NULL)
    {
      g_object_unref (info);
      return TRUE;
    }
1097

1098 1099
  return FALSE;
}
1100

1101 1102
/**
 * g_file_query_file_type:
1103 1104 1105 1106
 * @file: input #GFile
 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
1107 1108 1109 1110
 *
 * Utility function to inspect the #GFileType of a file. This is
 * implemented using g_file_query_info() and as such does blocking I/O.
 *
1111 1112 1113 1114 1115
 * The primary use case of this method is to check if a file is
 * a regular file, directory, or symlink.
 *
 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
 *     if the file does not exist
1116 1117 1118 1119
 *
 * Since: 2.18
 */
GFileType
1120 1121 1122
g_file_query_file_type (GFile               *file,
                        GFileQueryInfoFlags  flags,
                        GCancellable        *cancellable)
1123 1124 1125
{
  GFileInfo *info;
  GFileType file_type;
1126

1127
  g_return_val_if_fail (G_IS_FILE(file), G_FILE_TYPE_UNKNOWN);
1128
  info = g_file_query_info (file, G_FILE_ATTRIBUTE_STANDARD_TYPE, flags,
1129
                            cancellable, NULL);
1130 1131 1132 1133 1134 1135 1136
  if (info != NULL)
    {
      file_type = g_file_info_get_file_type (info);
      g_object_unref (info);
    }
  else
    file_type = G_FILE_TYPE_UNKNOWN;
1137

1138 1139 1140
  return file_type;
}

1141 1142
/**
 * g_file_query_info:
1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @error: a #GError
 *
 * Gets the requested information about specified @file.
 * The result is a #GFileInfo object that contains key-value
 * attributes (such as the type or size of the file).
 *
 * The @attributes value is a string that specifies the file
 * attributes that should be gathered. It is not an error if
 * it's not possible to read a particular requested attribute
 * from a file - it just won't be set. @attributes should be a
 * comma-separated list of attributes or attribute wildcards.
 * The wildcard "*" means all attributes, and a wildcard like
 * "standard::*" means all attributes in the standard namespace.
 * An example attribute query be "standard::*,owner::user".
 * The standard attributes are available as defines, like
 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
 *
 * If @cancellable is not %NULL, then the operation can be cancelled
 * by triggering the cancellable object from another thread. If the
 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
 * returned.
1169 1170
 *
 * For symlinks, normally the information about the target of the
1171 1172 1173 1174 1175
 * symlink is returned, rather than information about the symlink
 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
 * in @flags the information about the symlink itself will be returned.
 * Also, for symlinks that point to non-existing files the information
 * about the symlink itself will be returned.
1176
 *
1177 1178 1179
 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
 * returned. Other errors are possible too, and depend on what kind of
 * filesystem the file is on.
1180
 *
1181 1182 1183
 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
 *     on error. Free the returned object with g_object_unref().
 */
1184
GFileInfo *
Matthias Clasen's avatar
Matthias Clasen committed
1185
g_file_query_info (GFile                *file,
1186 1187 1188 1189
                   const char           *attributes,
                   GFileQueryInfoFlags   flags,
                   GCancellable         *cancellable,
                   GError              **error)
1190 1191
{
  GFileIface *iface;
1192

1193 1194 1195 1196
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  if (g_cancellable_set_error_if_cancelled (cancellable, error))
    return NULL;
1197

1198 1199 1200 1201
  iface = G_FILE_GET_IFACE (file);

  if (iface->query_info == NULL)
    {
1202 1203 1204
      g_set_error_literal (error, G_IO_ERROR,
                           G_IO_ERROR_NOT_SUPPORTED,
                           _("Operation not supported"));
1205 1206
      return NULL;
    }
1207

1208 1209 1210 1211 1212
  return (* iface->query_info) (file, attributes, flags, cancellable, error);
}

/**
 * g_file_query_info_async:
1213 1214 1215 1216 1217 1218 1219 1220 1221
 * @file: input #GFile
 * @attributes: an attribute query string
 * @flags: a set of #GFileQueryInfoFlags
 * @io_priority: the <link linkend="io-priority">I/O priority</link>
 *     of the request
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call when the
 *     request is satisfied
1222
 * @user_data: (closure): the data to pass to callback function
1223
 *
1224 1225 1226 1227 1228 1229 1230 1231 1232 1233
 * Asynchronously gets the requested information about specified @file.
 * The result is a #GFileInfo object that contains key-value attributes
 * (such as type or size for the file).
 *
 * For more details, see g_file_query_info() which is the synchronous
 * version of this call.
 *
 * When the operation is finished, @callback will be called. You can
 * then call g_file_query_info_finish() to get the result of the operation.
 */
1234
void
Matthias Clasen's avatar
Matthias Clasen committed
1235
g_file_query_info_async (GFile               *file,
1236 1237 1238 1239 1240 1241
                         const char          *attributes,
                         GFileQueryInfoFlags  flags,
                         int                  io_priority,
                         GCancellable        *cancellable,
                         GAsyncReadyCallback  callback,
                         gpointer             user_data)
1242 1243
{
  GFileIface *iface;
1244

1245 1246 1247 1248
  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->query_info_async) (file,
1249 1250 1251 1252 1253 1254
                               attributes,
                               flags,
                               io_priority,
                               cancellable,
                               callback,
                               user_data);
1255 1256 1257 1258
}

/**
 * g_file_query_info_finish:
1259 1260 1261 1262 1263
 * @file: input #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
 *
 * Finishes an asynchronous file info query.
1264
 * See g_file_query_info_async().
1265 1266 1267 1268 1269
 *
 * Returns: (transfer full): #GFileInfo for given @file
 *     or %NULL on error. Free the returned object with
 *     g_object_unref().
 */
1270
GFileInfo *
Matthias Clasen's avatar
Matthias Clasen committed
1271
g_file_query_info_finish (GFile         *file,
1272 1273
                          GAsyncResult  *res,
                          GError       **error)
1274 1275 1276 1277 1278 1279
{
  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);

1280 1281
  if (g_async_result_legacy_propagate_error (res, error))
    return NULL;
1282

1283 1284 1285 1286 1287 1288
  iface = G_FILE_GET_IFACE (file);
  return (* iface->query_info_finish) (file, res, error);
}

/**
 * g_file_query_filesystem_info:
1289 1290 1291 1292 1293 1294
 * @file: input #GFile
 * @attributes:  an attribute query string
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @error: a #GError
 *
1295 1296
 * Similar to g_file_query_info(), but obtains information
 * about the filesystem the @file is on, rather than the file itself.
1297
 * For instance the amount of space available and the type of
1298 1299
 * the filesystem.
 *
1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319
 * The @attributes value is a string that specifies the attributes
 * that should be gathered. It is not an error if it's not possible
 * to read a particular requested attribute from a file - it just
 * won't be set. @attributes should be a comma-separated list of
 * attributes or attribute wildcards. The wildcard "*" means all
 * attributes, and a wildcard like "filesystem::*" means all attributes
 * in the filesystem namespace. The standard namespace for filesystem
 * attributes is "filesystem". Common attributes of interest are
 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
 *
 * If @cancellable is not %NULL, then the operation can be cancelled
 * by triggering the cancellable object from another thread. If the
 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
 * returned.
 *
 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
 * be returned. Other errors are possible too, and depend on what
 * kind of filesystem the file is on.
1320
 *
1321
 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
1322
 *     Free the returned object with g_object_unref().
1323
 */
1324
GFileInfo *
Matthias Clasen's avatar
Matthias Clasen committed
1325
g_file_query_filesystem_info (GFile         *file,
1326 1327 1328
                              const char    *attributes,
                              GCancellable  *cancellable,
                              GError       **error)
1329 1330
{
  GFileIface *iface;
1331

1332 1333 1334 1335
  g_return_val_if_fail (G_IS_FILE (file), NULL);

  if (g_cancellable_set_error_if_cancelled (cancellable, error))
    return NULL;
1336

1337 1338 1339 1340
  iface = G_FILE_GET_IFACE (file);

  if (iface->query_filesystem_info == NULL)
    {
1341 1342 1343
      g_set_error_literal (error, G_IO_ERROR,
                           G_IO_ERROR_NOT_SUPPORTED,
                           _("Operation not supported"));
1344 1345
      return NULL;
    }
1346

1347 1348 1349
  return (* iface->query_filesystem_info) (file, attributes, cancellable, error);
}

1350 1351
/**
 * g_file_query_filesystem_info_async:
1352 1353 1354 1355 1356 1357 1358 1359
 * @file: input #GFile
 * @attributes: an attribute query string
 * @io_priority: the <link linkend="io-priority">I/O priority</link>
 *     of the request
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call
 *     when the request is satisfied
1360
 * @user_data: (closure): the data to pass to callback function
1361
 *
1362 1363 1364 1365
 * Asynchronously gets the requested information about the filesystem
 * that the specified @file is on. The result is a #GFileInfo object
 * that contains key-value attributes (such as type or size for the
 * file).
1366
 *
1367 1368 1369 1370 1371 1372
 * For more details, see g_file_query_filesystem_info() which is the
 * synchronous version of this call.
 *
 * When the operation is finished, @callback will be called. You can
 * then call g_file_query_info_finish() to get the result of the
 * operation.
1373
 */
1374 1375 1376 1377 1378 1379 1380 1381 1382
void
g_file_query_filesystem_info_async (GFile               *file,
                                    const char          *attributes,
                                    int                  io_priority,
                                    GCancellable        *cancellable,
                                    GAsyncReadyCallback  callback,
                                    gpointer             user_data)
{
  GFileIface *iface;
1383

1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396
  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->query_filesystem_info_async) (file,
                                          attributes,
                                          io_priority,
                                          cancellable,
                                          callback,
                                          user_data);
}

/**
 * g_file_query_filesystem_info_finish:
1397 1398 1399 1400 1401 1402 1403 1404 1405
 * @file: input #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
 *
 * Finishes an asynchronous filesystem info query.
 * See g_file_query_filesystem_info_async().
 *
 * Returns: (transfer full): #GFileInfo for given @file
 *     or %NULL on error.
1406
 *     Free the returned object with g_object_unref().
1407
 */
1408 1409 1410 1411 1412 1413 1414 1415 1416 1417
GFileInfo *
g_file_query_filesystem_info_finish (GFile         *file,
                                     GAsyncResult  *res,
                                     GError       **error)
{
  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);
  g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);

1418 1419
  if (g_async_result_legacy_propagate_error (res, error))
    return NULL;
1420

1421 1422 1423 1424
  iface = G_FILE_GET_IFACE (file);
  return (* iface->query_filesystem_info_finish) (file, res, error);
}

1425
/**
1426
 * g_file_find_enclosing_mount:
1427 1428 1429 1430
 * @file: input #GFile
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @error: a #GError
1431
 *
1432 1433 1434 1435 1436
 * Gets a #GMount for the #GFile.
 *
 * If the #GFileIface for @file does not have a mount (e.g.
 * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
 * and %NULL will be returned.
1437
 *
1438 1439
 * If @cancellable is not %NULL, then the operation can be cancelled by
 * triggering the cancellable object from another thread. If the operation
1440 1441 1442 1443
 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
 *
 * Returns: (transfer full): a #GMount where the @file is located
 *     or %NULL on error.
1444
 *     Free the returned object with g_object_unref().
1445
 */
1446 1447
GMount *
g_file_find_enclosing_mount (GFile         *file,
1448 1449
                             GCancellable  *cancellable,
                             GError       **error)
1450 1451 1452 1453
{
  GFileIface *iface;

  g_return_val_if_fail (G_IS_FILE (file), NULL);
1454

1455 1456 1457 1458
  if (g_cancellable_set_error_if_cancelled (cancellable, error))
    return NULL;

  iface = G_FILE_GET_IFACE (file);
1459
  if (iface->find_enclosing_mount == NULL)
1460
    {
1461

1462
      g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND,
1463 1464 1465 1466 1467
                           /* Translators: This is an error message when
                            * trying to find the enclosing (user visible)
                            * mount of a file, but none exists.
                            */
                           _("Containing mount does not exist"));
1468 1469
      return NULL;
    }
1470

1471
  return (* iface->find_enclosing_mount) (file, cancellable, error);
1472
}
1473

Matthias Clasen's avatar
Matthias Clasen committed
1474 1475 1476
/**
 * g_file_find_enclosing_mount_async:
 * @file: a #GFile
1477 1478 1479 1480 1481 1482
 * @io_priority: the <link linkend="io-priority">I/O priority</link>
 *     of the request
 * @cancellable: (allow-none): optional #GCancellable object,
 *     %NULL to ignore
 * @callback: (scope async): a #GAsyncReadyCallback to call
 *     when the request is satisfied
1483
 * @user_data: (closure): the data to pass to callback function
Matthias Clasen's avatar
Matthias Clasen committed
1484 1485 1486 1487 1488 1489
 *
 * Asynchronously gets the mount for the file.
 *
 * For more details, see g_file_find_enclosing_mount() which is
 * the synchronous version of this call.
 *
1490 1491 1492
 * When the operation is finished, @callback will be called.
 * You can then call g_file_find_enclosing_mount_finish() to
 * get the result of the operation.
Matthias Clasen's avatar
Matthias Clasen committed
1493
 */
1494 1495
void
g_file_find_enclosing_mount_async (GFile              *file,
1496 1497 1498 1499
                                   int                   io_priority,
                                   GCancellable         *cancellable,
                                   GAsyncReadyCallback   callback,
                                   gpointer              user_data)
1500 1501 1502 1503 1504 1505 1506
{
  GFileIface *iface;

  g_return_if_fail (G_IS_FILE (file));

  iface = G_FILE_GET_IFACE (file);
  (* iface->find_enclosing_mount_async) (file,
1507 1508 1509 1510
                                         io_priority,
                                         cancellable,
                                         callback,
                                         user_data);
1511 1512
}

Matthias Clasen's avatar
Matthias Clasen committed
1513 1514 1515 1516 1517
/**
 * g_file_find_enclosing_mount_finish:
 * @file: a #GFile
 * @res: a #GAsyncResult
 * @error: a #GError
1518 1519
 *
 * Finishes an asynchronous find mount request.
Matthias Clasen's avatar
Matthias Clasen committed
1520
 * See g_file_find_enclosing_mount_async().
1521
 *
1522
 * Returns: (transfer full): #GMount for given @file or %NULL on error.
1523
 *     Free the returned object with g_object_unref().