luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-04 10:16:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add docs for etags

Browse Source 
svn path=/trunk/; revision=6001
This commit is contained in:
Matthias Clasen 2007-11-30 18:11:03 +00:00
parent 3d8579f93a
commit c524cabff2
9 changed files with 50 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
gio/ChangeLog
View File

@ -1,3 +1,7 @@
2007-11-30 Matthias Clasen <mclasen@redhat.com>
* *.c: Explain etags and link to the explanation
2007-11-29 Matthias Clasen <mclasen@redhat.com>
* *.c: Explain I/O priority.

2
gio/gbufferedinputstream.c
View File

@ -445,7 +445,7 @@ async_fill_callback_wrapper (GObject *source_object,
* g_buffered_input_stream_fill_async:
* @stream: #GBufferedInputStream.
* @count: a #gssize.
* @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
* @callback: a #GAsyncReadyCallback.

47
gio/gfile.c
View File

@ -46,7 +46,8 @@
* 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.
@ -72,7 +73,14 @@
* 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);
@ -669,7 +677,7 @@ g_file_enumerate_children (GFile *file,
* @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
@ -797,7 +805,7 @@ g_file_query_info (GFile *file,
* @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
@ -1095,8 +1103,9 @@ g_file_create (GFile *file,
/**
* 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
@ -1154,7 +1163,7 @@ g_file_replace (GFile *file,
/**
* 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.
@ -1227,7 +1236,7 @@ g_file_read_finish (GFile *file,
* 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.
@ -1304,7 +1313,7 @@ g_file_append_to_finish (GFile *file,
* 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.
@ -1380,10 +1389,11 @@ g_file_create_finish (GFile *file,
/**
* 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.
@ -2299,7 +2309,7 @@ g_file_set_display_name (GFile *file,
* 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.
@ -2611,7 +2621,7 @@ g_file_real_set_attributes_from_info (GFile *file,
* @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.
@ -4390,10 +4400,12 @@ g_file_load_contents_finish (GFile *file,
* @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
*
@ -4592,7 +4604,7 @@ replace_contents_open_callback (GObject *obj,
* @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.
@ -4655,7 +4667,8 @@ g_file_replace_contents_async (GFile *file,
* 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

12
gio/gfileattribute.c
View File

@ -67,14 +67,14 @@
* </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>

2
gio/gfileenumerator.c
View File

@ -363,7 +363,7 @@ close_async_callback_wrapper (GObject *source_object,
/**
* g_file_enumerator_close_async:
* @enumerator: a #GFileEnumerator.
* @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

4
gio/gfileinfo.c
View File

@ -1325,8 +1325,8 @@ g_file_info_get_symlink_target (GFileInfo *info)
* g_file_info_get_etag:
* @info: a #GFileInfo.
*
* Gets the entity tag for a given #GFileInfo.
* See %G_FILE_ATTRIBUTE_ETAG_VALUE.
* Gets the <link linkend="gfile-etag">entity tag</link> for a given
* #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
*
* Returns: a string containing the value of the "etag:value" attribute.
**/

2
gio/gfileinputstream.c
View File

@ -181,7 +181,7 @@ async_ready_callback_wrapper (GObject *source_object,
* g_file_input_stream_query_info_async:
* @stream: a #GFileInputStream.
* @attributes: a file attribute query string.
* @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

6
gio/ginputstream.c
View File

@ -520,7 +520,7 @@ async_ready_close_callback_wrapper (GObject *source_object,
* @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
@ -655,7 +655,7 @@ g_input_stream_read_finish (GInputStream *stream,
* 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
@ -787,7 +787,7 @@ g_input_stream_skip_finish (GInputStream *stream,
/**
* 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

2
gio/gioscheduler.c
View File

@ -33,12 +33,14 @@
* Schedules asynchronous I/O operations for integration into the main
* event loop (#GMainLoop).
*
* <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm>
* Each I/O operation has a priority, and the scheduler uses the priorities
* to determine the order in which operations are executed. They are
* <emphasis>not</emphasis> used to determine system-wide I/O scheduling.
* Priorities are integers, with lower numbers indicating higher priority.
* It is recommended to choose priorities between %G_PRIORITY_LOW and
* %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default.
* </para>
**/
struct _GIOJob {