luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-26 07:26:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GFile SECTION

Browse Source 
Move it to the struct docs.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
This commit is contained in:
Philip Withnall 2023-11-14 14:04:28 +00:00
parent 70881dbabe
commit 172bb52e3f
4 changed files with 67 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
gio/gfile.c
View File

@ -86,94 +86,99 @@ typedef off_t loff_t;
/** /**
* SECTION:gfile * GFile:
* @short_description: File and Directory Handling
* @include: gio/gio.h
* @see_also: #GFileInfo, #GFileEnumerator
* *
* #GFile is a high level abstraction for manipulating files on a * `GFile` is a high level abstraction for manipulating files on a
* virtual file system. #GFiles are lightweight, immutable objects * virtual file system. `GFile`s are lightweight, immutable objects
* that do no I/O upon creation. It is necessary to understand that * 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 * 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: * 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.
* *
* 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 * 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. * 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 * 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 * `GFile` using [method@Gio.File.get_parent] to get an identifier for the
* directory, g_file_get_child() to get a child within a directory, * parent directory, [method@Gio.File.get_child] to get a child within a
* g_file_resolve_relative_path() to resolve a relative path between two * directory, and [method@Gio.File.resolve_relative_path] to resolve a relative
* #GFiles. There can be multiple hierarchies, so you may not end up at * path between two `GFile`s. There can be multiple hierarchies, so you may not
* the same root if you repeatedly call g_file_get_parent() on two different * end up at the same root if you repeatedly call [method@Gio.File.get_parent]
* files. * on two different files.
* *
* All #GFiles have a basename (get with g_file_get_basename()). These names * All `GFile`s have a basename (get with [method@Gio.File.get_basename]). These
* are byte strings that are used to identify the file on the filesystem * 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 * (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 * 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 * you want to use filenames in a user interface you should use the display
* name that you can get by requesting the * name that you can get by requesting the
* %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). * `G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME` attribute with
* This is guaranteed to be in UTF-8 and can be used in a user interface. * [method@Gio.File.query_info]. This is guaranteed to be in UTF-8 and can be
* But always store the real basename or the #GFile to use to actually * used in a user interface. But always store the real basename or the `GFile`
* access the file, because there is no way to go from a display name to * to use to actually access the file, because there is no way to go from a
* the actual name. * 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, * 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, * 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 * 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 * 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 * `G_FILE_ATTRIBUTE_ID_FILE` attribute. Note that `GFile` does some trivial
* canonicalization of pathnames passed in, so that trivial differences in * canonicalization of pathnames passed in, so that trivial differences in
* the path string used at creation (duplicated slashes, slash at end of * 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 * to suit your application. Asynchronous versions of synchronous functions
* simply have _async() appended to their function names. The asynchronous * simply have `_async()` appended to their function names. The asynchronous
* I/O functions call a #GAsyncReadyCallback which is then used to finalize * I/O functions call a [callback@Gio.AsyncReadyCallback] which is then used to
* the operation, producing a GAsyncResult which is then passed to the * finalize the operation, producing a [iface@Gio.AsyncResult] which is then
* function's matching _finish() operation. * passed to the function’s matching `_finish()` operation.
* *
* It is highly recommended to use asynchronous calls when running within a * 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 * 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. * 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 * Synchronous I/O operations should be performed from worker threads. See the
* [introduction to asynchronous programming section][async-programming] for * [introduction to asynchronous programming section](overview.html#asynchronous-programming)
* more. * 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: * 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 * short. Entity tags are somewhat like a more abstract version of the
* traditional mtime, and can be used to quickly determine if the file * traditional mtime, and can be used to quickly determine if the file
* has been modified from the version on the file system. See the * has been modified from the version on the file system. See the
* HTTP 1.1 * HTTP 1.1
* [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) * [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, static void g_file_real_query_info_async (GFile *file,
@ -1833,7 +1838,7 @@ g_file_create (GFile *file,
/** /**
* g_file_replace: * g_file_replace:
* @file: input #GFile * @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 * for the current #GFile, or #NULL to ignore
* @make_backup: %TRUE if a backup should be created * @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags * @flags: a set of #GFileCreateFlags
@ -2038,7 +2043,7 @@ g_file_create_readwrite (GFile *file,
/** /**
* g_file_replace_readwrite: * g_file_replace_readwrite:
* @file: a #GFile * @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 * for the current #GFile, or #NULL to ignore
* @make_backup: %TRUE if a backup should be created * @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags * @flags: a set of #GFileCreateFlags
@ -2302,7 +2307,7 @@ g_file_create_finish (GFile *file,
/** /**
* g_file_replace_async: * g_file_replace_async:
* @file: input #GFile * @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 * or %NULL to ignore
* @make_backup: %TRUE if a backup should be created * @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags * @flags: a set of #GFileCreateFlags
@ -2526,7 +2531,7 @@ g_file_create_readwrite_finish (GFile *file,
/** /**
* g_file_replace_readwrite_async: * g_file_replace_readwrite_async:
* @file: input #GFile * @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 * or %NULL to ignore
* @make_backup: %TRUE if a backup should be created * @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags * @flags: a set of #GFileCreateFlags
@ -8309,11 +8314,11 @@ g_file_load_contents_finish (GFile *file,
* @file: input #GFile * @file: input #GFile
* @contents: (element-type guint8) (array length=length): a string containing the new contents for @file * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
* @length: the length of @contents in bytes * @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 * or %NULL
* @make_backup: %TRUE if a backup should be created * @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags * @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 * for the document. This should be freed with g_free() when no longer
* needed, or %NULL * needed, or %NULL
* @cancellable: optional #GCancellable object, %NULL to ignore * @cancellable: optional #GCancellable object, %NULL to ignore
@ -8516,7 +8521,7 @@ replace_contents_open_callback (GObject *obj,
* @file: input #GFile * @file: input #GFile
* @contents: (element-type guint8) (array length=length): string of contents to replace the file with * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
* @length: the length of @contents in bytes * @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 * @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags * @flags: a set of #GFileCreateFlags
* @cancellable: optional #GCancellable object, %NULL to ignore * @cancellable: optional #GCancellable object, %NULL to ignore
@ -8566,7 +8571,7 @@ g_file_replace_contents_async (GFile *file,
* g_file_replace_contents_bytes_async: * g_file_replace_contents_bytes_async:
* @file: input #GFile * @file: input #GFile
* @contents: a #GBytes * @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 * @make_backup: %TRUE if a backup should be created
* @flags: a set of #GFileCreateFlags * @flags: a set of #GFileCreateFlags
* @cancellable: optional #GCancellable object, %NULL to ignore * @cancellable: optional #GCancellable object, %NULL to ignore
@ -8621,7 +8626,7 @@ g_file_replace_contents_bytes_async (GFile *file,
* g_file_replace_contents_finish: * g_file_replace_contents_finish:
* @file: input #GFile * @file: input #GFile
* @res: a #GAsyncResult * @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 * for the document. This should be freed with g_free() when it is no
* longer needed, or %NULL * longer needed, or %NULL
* @error: a #GError, or %NULL * @error: a #GError, or %NULL

10
gio/gfile.h
View File

@ -36,16 +36,6 @@ G_BEGIN_DECLS
#define G_IS_FILE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_FILE)) #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)) #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; typedef struct _GFileIface GFileIface;

2
gio/gfileinfo.c
View File

@ -2066,7 +2066,7 @@ g_file_info_get_symlink_target (GFileInfo *info)
* g_file_info_get_etag: * g_file_info_get_etag:
* @info: a #GFileInfo. * @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. * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
* *
* It is an error to call this if the #GFileInfo does not contain * It is an error to call this if the #GFileInfo does not contain

7
gio/giotypes.h
View File

@ -76,13 +76,6 @@ typedef struct _GFileMonitor GFileMonitor;
typedef struct _GFilterInputStream GFilterInputStream; typedef struct _GFilterInputStream GFilterInputStream;
typedef struct _GFilterOutputStream GFilterOutputStream; 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 _GFile GFile; /* Dummy typedef */
typedef struct _GFileInfo GFileInfo; typedef struct _GFileInfo GFileInfo;