* virtual file system. #GFile<!-- -->s are lightweight, immutable
* objects that do no I/O upon creation. It is necessary to understand that
* #GFile objects do not represent files, merely a handle to a file. All
- * file I/O is implemented as streaming operations (see #GInputStream and #GOutputStream).
+ * file I/O is implemented as streaming operations (see #GInputStream and
+ * #GOutputStream).
*
* To construct a #GFile, you can use:
* g_file_new_for_path() if you have a path.
* g_file_unmount_mountable() to unmount a mountable file.
* g_file_eject_mountable() to eject a mountable file.
*
- *
+ * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
+ * One notable feature of #GFile<!-- -->s are entity tags, or "etags" for
+ * short. Entity tags are somewhat like a more abstract version of the
+ * traditional mtime, and can be used to quickly determine if the file has
+ * been modified from the version on the file system. See the HTTP 1.1
+ * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19">specification</ulink>
+ * for HTTP Etag headers, which are a very similar concept.
+ * </para>
**/
static void g_file_base_init (gpointer g_class);
* @file: input #GFile.
* @attributes: a string containing a #GFileAttributeInfo query.
* @flags: a set of #GFileQueryInfoFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback to call when the request is satisfied
* @file: input #GFile.
* @attributes: a string containing a #GFileAttributeInfo query.
* @flags: a set of #GFileQueryInfoFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback to call when the request is satisfied
/**
* g_file_replace:
* @file: input #GFile.
- * @etag: an Entity Tag for the current #GFile.
- * @make_backup: %TRUE if a backup should be created.
+ * @etag: an <link linkend="gfile-etag">entity tag</link> for the
+ * current #GFile.
+ * @make_backup: %TRUE if a backup should be created`.
* @flags: a set of #GFileCreateFlags.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @error: a #GError, or %NULL
/**
* g_file_read_async:
* @file: input #GFile.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback.
* g_file_append_to_async:
* @file: input #GFile.
* @flags: a set of #GFileCreateFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback.
* g_file_create_async:
* @file: input #GFile.
* @flags: a set of #GFileCreateFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback.
/**
* g_file_replace_async:
* @file: input #GFile.
- * @etag: an Entity Tag for the current #GFile.
+ * @etag: an <link linkend="gfile-etag">entity tag</link> for the
+ * current #GFile.
* @make_backup: a #gboolean.
* @flags: a set of #GFileCreateFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback.
* g_file_set_display_name_async:
* @file: input #GFile.
* @display_name: a string.
- * @io_priority: the <link linkend="gioscheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback.
* @file: input #GFile.
* @info: a #GFileInfo.
* @flags: a #GFileQueryInfoFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback.
* @file: input #GFile.
* @contents: a string containing the new contents for @file.
* @length: the length of @contents in bytes.
- * @etag: the old entity tag for the document.
+ * @etag: the old <link linkend="gfile-etag">entity tag</link>
+ * for the document.
* @make_backup: a #gboolean.
* @flags: a set of #GFileCreateFlags.
- * @new_etag: a location to a new entity tag for the document.
+ * @new_etag: a location to a new <link linkend="gfile-etag">entity tag</link>
+ * for the document.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @error: a #GError, or %NULL
*
* @file: input #GFile.
* @contents: string of contents to replace the file with.
* @length: the length of @contents in bytes.
- * @etag: a new entity tag for the @file.
+ * @etag: a new <link linkend="gfile-etag">entity tag</link> for the @file.
* @make_backup: a #gboolean.
* @flags: a set of #GFileCreateFlags.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* g_file_replace_contents_finish:
* @file: input #GFile.
* @res: a #GAsyncResult.
- * @new_etag: a location of a new entity tag for the document.
+ * @new_etag: a location of a new <link linkend="gfile-etag">entity tag</link>
+ * for the document.
* @error: a #GError, or %NULL
*
* Finishes an asynchronous replace of the given @file. See
* </thead>
* <tbody>
* <row><entry>"std"</entry><entry>The "Standard" namespace. General file
- * information that any application may need should be put in this namespace. Examples
- * include the file's name, type, and size.</entry></row>
+ * information that any application may need should be put in this namespace.
+ * Examples include the file's name, type, and size.</entry></row>
* <row><entry>"etag"</entry><entry>The "Entity Tag" namespace.
* GIO use "entity tags" to quickly determine if a file has been modified
- * from the version on the file system. Entity tags are globally unique identifiers,
- * and should always be sent with the current revision of a file.
- * An example of a key in this namespace is "value", which contains the value of the
- * current entity tag.</entry></row>
+ * from the version on the file system. Entity tags are globally unique
+ * identifiers, and should always be sent with the current revision of a
+ * file. An example of a key in this namespace is "value", which contains
+ * the value of the current entity tag.</entry></row>
* <row><entry>"id"</entry><entry>The "Identification" namespace. This
* namespace is used by file managers and applications that list directories
* to check for loops and to uniquely identify files.</entry></row>
* @stream: A #GInputStream.
* @buffer: a buffer to read data into (which should be at least count bytes long).
* @count: the number of bytes that will be read from the stream
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: callback to call when the request is satisfied
* g_input_stream_skip_async:
* @stream: A #GInputStream.
* @count: the number of bytes that will be skipped from the stream
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: callback to call when the request is satisfied
/**
* g_input_stream_close_async:
* @stream: A #GInputStream.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
+ * @io_priority: the <link linkend="io-priority">I/O priority</link>
* of the request.
* @cancellable: optional cancellable object
* @callback: callback to call when the request is satisfied