mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-25 06:56:14 +01:00
docs: Move the GFile SECTION
Move it to the struct docs. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3037
This commit is contained in:
Philip Withnall
parent
70881dbabe
commit
172bb52e3f
127
gio/gfile.c
127
gio/gfile.c
@ -86,94 +86,99 @@ typedef off_t loff_t;
|
||||
|
||||
|
||||
/**
|
||||
* SECTION:gfile
|
||||
* @short_description: File and Directory Handling
|
||||
* @include: gio/gio.h
|
||||
* @see_also: #GFileInfo, #GFileEnumerator
|
||||
* GFile:
|
||||
*
|
||||
* #GFile is a high level abstraction for manipulating files on a
|
||||
* virtual file system. #GFiles are lightweight, immutable objects
|
||||
* `GFile` is a high level abstraction for manipulating files on a
|
||||
* 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 an identifier for a
|
||||
* `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).
|
||||
* (see [class@Gio.InputStream] and [class@Gio.OutputStream]).
|
||||
*
|
||||
* To construct a #GFile, you can use:
|
||||
* - g_file_new_for_path() if you have a path.
|
||||
* - g_file_new_for_uri() if you have a URI.
|
||||
* - g_file_new_for_commandline_arg() for a command line argument.
|
||||
* - g_file_new_tmp() to create a temporary file from a template.
|
||||
* - g_file_new_tmp_async() to asynchronously create a temporary file.
|
||||
* - g_file_new_tmp_dir_async() to asynchronously create a temporary directory.
|
||||
* - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
|
||||
* - g_file_new_build_filename() or g_file_new_build_filenamev() to create a file from path elements.
|
||||
* To construct a `GFile`, you can use:
|
||||
*
|
||||
* One way to think of a #GFile is as an abstraction of a pathname. For
|
||||
* - [func@Gio.File.new_for_path] if you have a path.
|
||||
* - [func@Gio.File.new_for_uri] if you have a URI.
|
||||
* - [func@Gio.File.new_for_commandline_arg] or
|
||||
* [func@Gio.File.new_for_commandline_arg_and_cwd] for a command line
|
||||
* argument.
|
||||
* - [func@Gio.File.new_tmp] to create a temporary file from a template.
|
||||
* - [func@Gio.File.new_tmp_async] to asynchronously create a temporary file.
|
||||
* - [func@Gio.File.new_tmp_dir_async] to asynchronously create a temporary
|
||||
* directory.
|
||||
* - [func@Gio.File.parse_name] from a UTF-8 string gotten from
|
||||
* [method@Gio.File.get_parse_name].
|
||||
* - [func@Gio.File.new_build_filename] or [func@Gio.File.new_build_filenamev]
|
||||
* to create a file from path elements.
|
||||
*
|
||||
* 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
|
||||
* `GFile`s 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
|
||||
* `GFile`s 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
|
||||
* files.
|
||||
* `GFile` using [method@Gio.File.get_parent] to get an identifier for the
|
||||
* parent directory, [method@Gio.File.get_child] to get a child within a
|
||||
* directory, and [method@Gio.File.resolve_relative_path] to resolve a relative
|
||||
* path between two `GFile`s. There can be multiple hierarchies, so you may not
|
||||
* end up at the same root if you repeatedly call [method@Gio.File.get_parent]
|
||||
* on two different files.
|
||||
*
|
||||
* 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
|
||||
* All `GFile`s have a basename (get with [method@Gio.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
|
||||
* %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
|
||||
* 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.
|
||||
* `G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME` attribute with
|
||||
* [method@Gio.File.query_info]. 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
|
||||
* 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
|
||||
* hard or soft links may cause two different `GFile`s 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
|
||||
* %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
|
||||
* check if two `GFile`s point to the same file you can query for the
|
||||
* `G_FILE_ATTRIBUTE_ID_FILE` attribute. Note that `GFile` does some trivial
|
||||
* 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.
|
||||
* path, `.` or `..` path segments, etc) does not create different `GFile`s.
|
||||
*
|
||||
* Many #GFile operations have both synchronous and asynchronous versions
|
||||
* 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.
|
||||
* simply have `_async()` appended to their function names. The asynchronous
|
||||
* I/O functions call a [callback@Gio.AsyncReadyCallback] which is then used to
|
||||
* finalize the operation, producing a [iface@Gio.AsyncResult] which is then
|
||||
* passed to the function’s matching `_finish()` operation.
|
||||
*
|
||||
* It is highly recommended to use asynchronous calls when running within a
|
||||
* shared main loop, such as in the main thread of an application. This avoids
|
||||
* I/O operations blocking other sources on the main loop from being dispatched.
|
||||
* Synchronous I/O operations should be performed from worker threads. See the
|
||||
* [introduction to asynchronous programming section][async-programming] for
|
||||
* more.
|
||||
* [introduction to asynchronous programming section](overview.html#asynchronous-programming)
|
||||
* for more.
|
||||
*
|
||||
* Some #GFile operations almost always take a noticeable amount of time, and
|
||||
* Some `GFile` operations almost always take a noticeable amount of time, and
|
||||
* so do not have synchronous analogs. Notable cases include:
|
||||
* - g_file_mount_mountable() to mount a mountable file.
|
||||
* - g_file_unmount_mountable_with_operation() to unmount a mountable file.
|
||||
* - g_file_eject_mountable_with_operation() to eject a mountable file.
|
||||
*
|
||||
* ## Entity Tags # {#gfile-etag}
|
||||
* - [method@Gio.File.mount_mountable] to mount a mountable file.
|
||||
* - [method@Gio.File.unmount_mountable_with_operation] to unmount a mountable
|
||||
* file.
|
||||
* - [method@Gio.File.eject_mountable_with_operation] to eject a mountable file.
|
||||
*
|
||||
* One notable feature of #GFiles are entity tags, or "etags" for
|
||||
* ## Entity Tags
|
||||
*
|
||||
* 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
|
||||
* [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
|
||||
* for HTTP Etag headers, which are a very similar concept.
|
||||
* for HTTP `ETag` headers, which are a very similar concept.
|
||||
*/
|
||||
|
||||
static void g_file_real_query_info_async (GFile *file,
|
||||
@ -1833,7 +1838,7 @@ g_file_create (GFile *file,
|
||||
/**
|
||||
* g_file_replace:
|
||||
* @file: input #GFile
|
||||
* @etag: (nullable): an optional [entity tag][gfile-etag]
|
||||
* @etag: (nullable): an optional [entity tag](#entity-tags)
|
||||
* for the current #GFile, or #NULL to ignore
|
||||
* @make_backup: %TRUE if a backup should be created
|
||||
* @flags: a set of #GFileCreateFlags
|
||||
@ -2038,7 +2043,7 @@ g_file_create_readwrite (GFile *file,
|
||||
/**
|
||||
* g_file_replace_readwrite:
|
||||
* @file: a #GFile
|
||||
* @etag: (nullable): an optional [entity tag][gfile-etag]
|
||||
* @etag: (nullable): an optional [entity tag](#entity-tags)
|
||||
* for the current #GFile, or #NULL to ignore
|
||||
* @make_backup: %TRUE if a backup should be created
|
||||
* @flags: a set of #GFileCreateFlags
|
||||
@ -2302,7 +2307,7 @@ g_file_create_finish (GFile *file,
|
||||
/**
|
||||
* g_file_replace_async:
|
||||
* @file: input #GFile
|
||||
* @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile,
|
||||
* @etag: (nullable): an [entity tag](#entity-tags) for the current #GFile,
|
||||
* or %NULL to ignore
|
||||
* @make_backup: %TRUE if a backup should be created
|
||||
* @flags: a set of #GFileCreateFlags
|
||||
@ -2526,7 +2531,7 @@ g_file_create_readwrite_finish (GFile *file,
|
||||
/**
|
||||
* g_file_replace_readwrite_async:
|
||||
* @file: input #GFile
|
||||
* @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile,
|
||||
* @etag: (nullable): an [entity tag](#entity-tags) for the current #GFile,
|
||||
* or %NULL to ignore
|
||||
* @make_backup: %TRUE if a backup should be created
|
||||
* @flags: a set of #GFileCreateFlags
|
||||
@ -8309,11 +8314,11 @@ g_file_load_contents_finish (GFile *file,
|
||||
* @file: input #GFile
|
||||
* @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
|
||||
* @length: the length of @contents in bytes
|
||||
* @etag: (nullable): the old [entity-tag][gfile-etag] for the document,
|
||||
* @etag: (nullable): the old [entity-tag](#entity-tags) for the document,
|
||||
* or %NULL
|
||||
* @make_backup: %TRUE if a backup should be created
|
||||
* @flags: a set of #GFileCreateFlags
|
||||
* @new_etag: (out) (optional) (nullable): a location to a new [entity tag][gfile-etag]
|
||||
* @new_etag: (out) (optional) (nullable): a location to a new [entity tag](#entity-tags)
|
||||
* for the document. This should be freed with g_free() when no longer
|
||||
* needed, or %NULL
|
||||
* @cancellable: optional #GCancellable object, %NULL to ignore
|
||||
@ -8516,7 +8521,7 @@ replace_contents_open_callback (GObject *obj,
|
||||
* @file: input #GFile
|
||||
* @contents: (element-type guint8) (array length=length): string of contents to replace the file with
|
||||
* @length: the length of @contents in bytes
|
||||
* @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL
|
||||
* @etag: (nullable): a new [entity tag](#entity-tags) for the @file, or %NULL
|
||||
* @make_backup: %TRUE if a backup should be created
|
||||
* @flags: a set of #GFileCreateFlags
|
||||
* @cancellable: optional #GCancellable object, %NULL to ignore
|
||||
@ -8566,7 +8571,7 @@ g_file_replace_contents_async (GFile *file,
|
||||
* g_file_replace_contents_bytes_async:
|
||||
* @file: input #GFile
|
||||
* @contents: a #GBytes
|
||||
* @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL
|
||||
* @etag: (nullable): a new [entity tag](#entity-tags) for the @file, or %NULL
|
||||
* @make_backup: %TRUE if a backup should be created
|
||||
* @flags: a set of #GFileCreateFlags
|
||||
* @cancellable: optional #GCancellable object, %NULL to ignore
|
||||
@ -8621,7 +8626,7 @@ g_file_replace_contents_bytes_async (GFile *file,
|
||||
* g_file_replace_contents_finish:
|
||||
* @file: input #GFile
|
||||
* @res: a #GAsyncResult
|
||||
* @new_etag: (out) (optional) (nullable): a location of a new [entity tag][gfile-etag]
|
||||
* @new_etag: (out) (optional) (nullable): a location of a new [entity tag](#entity-tags)
|
||||
* for the document. This should be freed with g_free() when it is no
|
||||
* longer needed, or %NULL
|
||||
* @error: a #GError, or %NULL
|
||||
|
||||
10
gio/gfile.h
10
gio/gfile.h
@ -36,16 +36,6 @@ G_BEGIN_DECLS
|
||||
#define G_IS_FILE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_FILE))
|
||||
#define G_FILE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_FILE, GFileIface))
|
||||
|
||||
#if 0
|
||||
/**
|
||||
* GFile:
|
||||
*
|
||||
* A handle to an object implementing the #GFileIface interface.
|
||||
* Generally stores a location within the file system. Handles do not
|
||||
* necessarily represent files or directories that currently exist.
|
||||
**/
|
||||
typedef struct _GFile GFile; /* Dummy typedef */
|
||||
#endif
|
||||
typedef struct _GFileIface GFileIface;
|
||||
|
||||
|
||||
|
||||
@ -2066,7 +2066,7 @@ g_file_info_get_symlink_target (GFileInfo *info)
|
||||
* g_file_info_get_etag:
|
||||
* @info: a #GFileInfo.
|
||||
*
|
||||
* Gets the [entity tag][gfile-etag] for a given
|
||||
* Gets the [entity tag](iface.File.html#entity-tags) for a given
|
||||
* #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
|
||||
*
|
||||
* It is an error to call this if the #GFileInfo does not contain
|
||||
|
||||
@ -76,13 +76,6 @@ typedef struct _GFileMonitor GFileMonitor;
|
||||
typedef struct _GFilterInputStream GFilterInputStream;
|
||||
typedef struct _GFilterOutputStream GFilterOutputStream;
|
||||
|
||||
/**
|
||||
* GFile:
|
||||
*
|
||||
* A handle to an object implementing the #GFileIface interface.
|
||||
* Generally stores a location within the file system. Handles do not
|
||||
* necessarily represent files or directories that currently exist.
|
||||
**/
|
||||
typedef struct _GFile GFile; /* Dummy typedef */
|
||||
typedef struct _GFileInfo GFileInfo;
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user