From d770153b286fdad3ac678f689d217c2ff7b4e49c Mon Sep 17 00:00:00 2001 From: Matt Birkholz Date: Fri, 13 Jul 2012 16:01:33 -0700 Subject: [PATCH] gtk: Documented the GIO interface. Punted g_file_info_remove_attribute (for now). --- doc/gtk/gtk.texinfo | 275 ++++++++++++++++++++++++++- src/gtk/Includes/gio/gfileinfo.cdecl | 8 +- src/gtk/gio.scm | 6 +- src/gtk/gtk.pkg | 1 - 4 files changed, 278 insertions(+), 12 deletions(-) diff --git a/doc/gtk/gtk.texinfo b/doc/gtk/gtk.texinfo index 6fc83abdf..c8316b76c 100644 --- a/doc/gtk/gtk.texinfo +++ b/doc/gtk/gtk.texinfo @@ -199,6 +199,7 @@ the Gtk interface. @menu * GObject:: +* GIO:: * Pixbuf Loader:: * Pango Layout:: * Gtk Object:: @@ -218,7 +219,7 @@ the Gtk interface. * Debugging Facilities:: @end menu -@node GObject, Pixbuf Loader, API Reference, API Reference +@node GObject, GIO, API Reference, API Reference @section GObject An instance of @bref{} represents a reference to a toolkit @@ -312,7 +313,277 @@ has not been interned by @bref{gquark-from-string}, an error is signaled. @end deffn -@node Pixbuf Loader, Pango Layout, GObject, API Reference +@node GIO, Pixbuf Loader, GObject, API Reference +@section GIO + +The basic interface to the GIO library is three procedures taking a +URI argument and returning either a Scheme port or a list of strings. +The URI can specify file, http and sftp protocols (and perhaps more, +depending on support in the GIO library). If an SFTP URI requires a +password, Scheme's @code{call-with-pass-phrase} procedure is called. +If the ports are GCed or the stack unwound, pending operations are +cancelled. Re-winding the stack is an error. + +@deffn Procedure open-input-gfile uri +Returns an input port that reads from @var{uri}. +@end deffn + +@deffn Procedure open-output-gfile uri +Returns an output port that writes a new file replacing @var{uri}. +@end deffn + +@deffn Procedure gdirectory-read uri +Returns a list of strings --- the names of the ``children'' of +@var{uri}, a directory resource. +@end deffn + +A more direct interface to GIO's GFile operations is provided by the +following 8 classes and 18 operations. + +@pre + + make-gfile + + gfile-query-info + gfile-info-list-attributes + gfile-info-get-attribute-status + gfile-info-get-attribute-value + + gfile-enumerate-children + gfile-enumerator-next-files + gfile-enumerator-close + + + g-input-stream-read + g-input-stream-skip + g-input-stream-close + + gfile-read + + g-output-stream-write + g-output-stream-flush + g-output-stream-close + + gfile-append-to + gfile-create + gfile-replace +@end pre + +@deffn Class +Represents a @code{GFile} toolkit object. +@end deffn + +@deffn Procedure make-gfile uri +Constructs a gfile for the given @var{uri}. This operation never +fails, but the returned object might not support any I/O if @var{uri} +is malformed or if the uri type is not supported. +@end deffn + +@deffn Class +Represents a @code{GFileInfo} toolkit object containing key-value +attributes (such as the type or size of a gfile). +@end deffn + +@deffn Procedure gfile-query-info gfile attributes follow-symlinks? +Gets the requested information about @var{gfile}. The result is a +gfile-info instance. + +@var{Attributes} should be a string specifying the file attributes to +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. +@var{Attributes} should be a comma-separated list of attributes or +attribute wildcards. The wildcard @code{*} means all attributes, and +a wildcard like @code{standard::*} means all attributes in the +standard namespace. An example attribute query is +@code{standard::*,owner::user}. + +Normally information about the target of a symlink +is returned, rather than information about the symlink itself. However +if @var{follow-symlinks?} is @code{#f}, information about the +symlink itself will be returned. If the target does not exist, +information about the symlink itself will be returned. (Huh???) +@end deffn + +There are many gfile attributes. Most have boolean or integer values. +Some are enum constants. For example the @code{"standard::type"} +attribute's value is a GFileType member, e.g. @code{(C-enum +"G_FILE_TYPE_UNKNOWN")}. For a complete list of GFileType members and +other GIO constants, see your @file{gioenums.h} header file. + +Here are the 76 keys listed in the @file{gfileinfo.h} header: +standard::type, standard::is-hidden, standard::is-backup, +standard::is-symlink, standard::is-virtual, standard::name, +standard::display-name, standard::edit-name, standard::copy-name, +standard::description, standard::icon, standard::content-type, +standard::fast-content-type, standard::size, standard::allocated-size, +standard::symlink-target, standard::target-uri, standard::sort-order, +etag::value, id::file, id::filesystem, access::can-read, +access::can-write, access::can-execute, access::can-delete, +access::can-trash, access::can-rename, mountable::can-mount, +mountable::can-unmount, mountable::can-eject, mountable::unix-device, +mountable::unix-device-file, mountable::hal-udi, mountable::can-start, +mountable::can-start-degraded, mountable::can-stop, +mountable::start-stop-type, mountable::can-poll, +mountable::is-media-check-automatic, time::modified, +time::modified-usec, time::access, time::access-usec, time::changed, +time::changed-usec, time::created, time::created-usec, unix::device, +unix::inode, unix::mode, unix::nlink, unix::uid, unix::gid, +unix::rdev, unix::block-size, unix::blocks, unix::is-mountpoint, +dos::is-archive, dos::is-system, owner::user, owner::user-real, +owner::group, thumbnail::path, thumbnail::failed, preview::icon, +filesystem::size, filesystem::free, filesystem::used, +filesystem::type, filesystem::readonly, filesystem::use-preview, +gvfs::backend, selinux::context, trash::item-count, trash::orig-path, +trash::deletion-date. + +@deffn Procedure gfile-info-list-attributes ginfo namespace +Lists the gfile-info attribute keys. +@var{Namespace} should be e.g. @code{"standard"} or @code{"*"}. +@end deffn + +@deffn Procedure gfile-info-get-attribute-status ginfo key +Returns @code{set} if the @code{key} attribute in @code{ginfo} has +been set. Returns @code{unset} if not. Returns @code{error-setting} +if there was an error collecting the value. +@end deffn + +@deffn Procedure gfile-info-get-attribute-value ginfo key +Returns a boolean, integer, string or list of strings depending on the +value of @var{key} in @var{ginfo}. +@end deffn + +@deffn Class +Represents a @code{GFileEnumerator}. +@end deffn + +@deffn Procedure gfile-enumerate-children gfile attributes follow-symlinks? +Gets the requested information about the files in @var{gfile} --- a +directory. The result is a gfile-enumerator that produces a gfile-info +for each file in the directory. If @var{gfile} is not a directory, an +error is signaled. + +@var{Attributes} should be a string specifying the file attributes to +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. +@var{Attributes} should be a comma-separated list of attributes or +attribute wildcards. The wildcard @code{*} means all attributes, and +a wildcard like @code{standard::*} means all attributes in the +standard namespace. An example attribute query is +@code{standard::*,owner::user}. +@end deffn + +@deffn Procedure gfile-enumerator-next-files genum n +Gets up to @var{n} more gfile-infos from @var{genum}. +@end deffn + +@deffn Procedure gfile-enumerator-close genum +Closes @var{genum}. +@end deffn + +@deffn Class +Abstract superclass of GIO streams. +@end deffn + +@deffn Class +A subclass of g-stream. +@end deffn + +@deffn Procedure g-input-stream-read gstream buffer start end +Returns the number of bytes read from @var{gstream} and +written into @var{buffer}. +@end deffn + +@deffn Procedure g-input-stream-skip gstream count +Returns the number of bytes read from @var{gstream} and discarded. +@end deffn + +@deffn Procedure g-input-stream-close gstream +Closes @var{gstream}. +@end deffn + +@deffn Class +A subclass of g-input-stream representing input from a file. +@end deffn + +@deffn Procedure gfile-read gfile +Returns a gfile-input-stream opened for reading from @var{gfile}. +@end deffn + +@deffn Class +A subclass of g-stream. +@end deffn + +@deffn Procedure g-output-stream-write gstream buffer start end +Returns the number of bytes written to @var{gstream}. Will return 0 +only if @var{start} equals @var{end}. +@end deffn + +@deffn Procedure g-output-stream-flush gstream +Forces a write of all user-space buffered data for @var{gstream}. +@end deffn + +@deffn Procedure g-output-stream-close gstream +Closes @var{gstream}. +@end deffn + +@deffn Class +A subclass of g-output-stream representing output to a file. +@end deffn + +@deffn Procedure gfile-replace gfile etag backup? . flags +Returns a gfile-output-stream that overwrites @var{gfile}, possibly +creating a backup copy of the file first. If the file doesn't exist, +it will be created. + +This will try to replace the file in the safest way possible so that +any errors during the writing will not affect an already existing copy +of the file. For instance, for local files it may write to a temporary +file and then atomically rename over the destination when the stream +is closed. + +By default files are generally created readable by everyone, but if +you include the symbol @code{private} in @var{flags} the file will be +made readable only to the current user, to the level that is supported +on the target filesystem. + +@var{Etag} should be zero or false, or an alien. If @var{etag} is an +alien, it is compared to the current entity tag of the file, and if +they differ an error is signaled. This generally means that the file +has been changed since you last read it. You can get the etag for a +gfile from the @code{"etag::value"} attribute in +its gfile-info. You can get the gfile-info for a gfile-input-stream +with @code{gfile-input-stream-query-info}. The etag for a +gfile-output-stream is available from +@code{gfile-output-stream-get-etag}. + +@var{Backup?} should be @code{#f} unless you require a backup of +an existing file to be made. If a backup cannot be made, an error +will be signaled. If you want to replace the file anyway, call +again with @var{backup?} @code{#f}. +@end deffn + +@deffn Procedure gfile-append-to gfile . flags +Returns a gfile-output-stream that appends to @var{gfile}. If the file +doesn't already exist it is created. + +By default files are created readable by everyone, but if you include +the symbol @code{private} in @var{flags} the file will be made +readable only to the current user, to the level that is supported on +the target filesystem. +@end deffn + +@deffn Procedure gfile-create gfile . flags +Returns a gfile-output-stream that writes to @var{gfile}. If the file +already exists an error is signaled. + +By default files are created readable by everyone, but if you include +the symbol @code{private} in @var{flags} the file will be made +readable only to the current user, to the level that is supported on +the target filesystem. +@end deffn + + +@node Pixbuf Loader, Pango Layout, GIO, API Reference @section Pixbuf Loader A pixbuf loader encapsulates the loading of a pixbuf. The diff --git a/src/gtk/Includes/gio/gfileinfo.cdecl b/src/gtk/Includes/gio/gfileinfo.cdecl index e4a8a3abb..17474a4ab 100644 --- a/src/gtk/Includes/gio/gfileinfo.cdecl +++ b/src/gtk/Includes/gio/gfileinfo.cdecl @@ -12,10 +12,10 @@ glib-2.0/gio/gfileinfo.h |# (info (* GFileInfo)) (attribute (* (const char)))) -(extern void - g_file_info_remove_attribute - (info (* GFileInfo)) - (attribute (* (const char)))) +;(extern void +; g_file_info_remove_attribute +; (info (* GFileInfo)) +; (attribute (* (const char)))) (extern GFileAttributeStatus g_file_info_get_attribute_status diff --git a/src/gtk/gio.scm b/src/gtk/gio.scm index 9c813b3a7..e5c5cee61 100644 --- a/src/gtk/gio.scm +++ b/src/gtk/gio.scm @@ -760,10 +760,6 @@ USA. (free-cstringv alien) strings)))) -(define (gfile-info-remove-attribute ginfo name) - (guarantee-string name 'gfile-info-remove-attribute) - (C-call "g_file_info_remove_attribute" (gobject-alien ginfo) name)) - (define (gfile-info-get-attribute-status ginfo name) (let ((code (C-call "g_file_info_get_attribute_status" (gobject-alien ginfo) @@ -778,7 +774,7 @@ USA. (let* ((alien (gobject-alien ginfo)) (type (C-call "g_file_info_get_attribute_type" alien name))) (cond ((fix:= type (C-enum "G_FILE_ATTRIBUTE_TYPE_INVALID")) - #f) + (error "Invalid attribute:" name)) ((fix:= type (C-enum "G_FILE_ATTRIBUTE_TYPE_STRING")) (c-peek-cstring (C-call "g_file_info_get_attribute_string" diff --git a/src/gtk/gtk.pkg b/src/gtk/gtk.pkg index 2a58159ca..8b47e81d7 100644 --- a/src/gtk/gtk.pkg +++ b/src/gtk/gtk.pkg @@ -90,7 +90,6 @@ USA. gfile-query-info gfile-info-list-attributes - gfile-info-remove-attribute gfile-info-get-attribute-status gfile-info-get-attribute-value -- 2.25.1