@menu
* GObject::
+* GIO::
* Pixbuf Loader::
* Pango Layout::
* Gtk Object::
* 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{<gobject>} represents a reference to a toolkit
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
+ <gfile>
+ make-gfile
+ <gfile-info>
+ gfile-query-info
+ gfile-info-list-attributes
+ gfile-info-get-attribute-status
+ gfile-info-get-attribute-value
+ <gfile-enumerator>
+ gfile-enumerate-children
+ gfile-enumerator-next-files
+ gfile-enumerator-close
+ <g-stream>
+ <g-input-stream>
+ g-input-stream-read
+ g-input-stream-skip
+ g-input-stream-close
+ <gfile-input-stream>
+ gfile-read
+ <g-output-stream>
+ g-output-stream-write
+ g-output-stream-flush
+ g-output-stream-close
+ <gfile-output-stream>
+ gfile-append-to
+ gfile-create
+ gfile-replace
+@end pre
+
+@deffn Class <gfile>
+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 <gfile-info>
+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 <gfile-enumerator>
+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 <g-stream>
+Abstract superclass of GIO streams.
+@end deffn
+
+@deffn Class <g-input-stream>
+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 <gfile-input-stream>
+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 <g-output-stream>
+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 <gfile-output-stream>
+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
projects / mit-scheme.git / commitdiff