GNOME.org
 

[glib] GIOChannel: move docs from tmpl to .c

commit 4bdf7d12a8ef7e027dced8d0da46986c2009180e
Author: Ryan Lortie <desrt desrt ca>
Date:   Sun Jan 31 00:39:40 2010 -0500

    GIOChannel: move docs from tmpl to .c

 docs/reference/glib/tmpl/.gitignore      |    1 +
 docs/reference/glib/tmpl/iochannels.sgml |  666 ------------------------------
 glib/giochannel.c                        |  196 +++++++++
 glib/giounix.c                           |   36 ++
 glib/giowin32.c                          |   52 +++
 5 files changed, 285 insertions(+), 666 deletions(-)
---
diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index b942d63..1045797 100644
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -9,6 +9,7 @@ ghostutils.sgml
 gurifuncs.sgml
 gvarianttype.sgml
 hash_tables.sgml
+iochannels.sgml
 memory_chunks.sgml
 option.sgml
 patterns.sgml 
diff --git a/glib/giochannel.c b/glib/giochannel.c
index 537fdb6..358bac6 100644
--- a/glib/giochannel.c
+++ b/glib/giochannel.c
@@ -50,6 +50,122 @@
 
 #include "galias.h"
 
+/**
+ * SECTION: iochannels
+ * @title: IO Channels
+ * @short_description: portable support for using files, pipes and
+ *                     sockets
+ * @see_also: <para> <variablelist> <varlistentry>
+ *            <term>gtk_input_add_full(), gtk_input_remove(),
+ *            gdk_input_add(), gdk_input_add_full(),
+ *            gdk_input_remove()</term> <listitem><para> Convenience
+ *            functions for creating #GIOChannel instances and adding
+ *            them to the <link linkend="glib-The-Main-Event-Loop">main
+ *            event loop</link>. </para></listitem> </varlistentry>
+ *            </variablelist> </para>
+ *
+ * The #GIOChannel data type aims to provide a portable method for
+ * using file descriptors, pipes, and sockets, and integrating them
+ * into the <link linkend="glib-The-Main-Event-Loop">main event
+ * loop</link>. Currently full support is available on UNIX platforms,
+ * support for Windows is only partially complete.
+ *
+ * To create a new #GIOChannel on UNIX systems use
+ * g_io_channel_unix_new(). This works for plain file descriptors,
+ * pipes and sockets. Alternatively, a channel can be created for a
+ * file in a system independent manner using g_io_channel_new_file().
+ *
+ * Once a #GIOChannel has been created, it can be used in a generic
+ * manner with the functions g_io_channel_read_chars(),
+ * g_io_channel_write_chars(), g_io_channel_seek_position(), and
+ * g_io_channel_shutdown().
+ *
+ * To add a #GIOChannel to the <link
+ * linkend="glib-The-Main-Event-Loop">main event loop</link> use
+ * g_io_add_watch() or g_io_add_watch_full(). Here you specify which
+ * events you are interested in on the #GIOChannel, and provide a
+ * function to be called whenever these events occur.
+ *
+ * #GIOChannel instances are created with an initial reference count of
+ * 1. g_io_channel_ref() and g_io_channel_unref() can be used to
+ * increment or decrement the reference count respectively. When the
+ * reference count falls to 0, the #GIOChannel is freed. (Though it
+ * isn't closed automatically, unless it was created using
+ * g_io_channel_new_from_file().) Using g_io_add_watch() or
+ * g_io_add_watch_full() increments a channel's reference count.
+ *
+ * The new functions g_io_channel_read_chars(),
+ * g_io_channel_read_line(), g_io_channel_read_line_string(),
+ * g_io_channel_read_to_end(), g_io_channel_write_chars(),
+ * g_io_channel_seek_position(), and g_io_channel_flush() should not be
+ * mixed with the deprecated functions g_io_channel_read(),
+ * g_io_channel_write(), and g_io_channel_seek() on the same channel.
+ **/
+
+/**
+ * GIOChannel:
+ *
+ * A data structure representing an IO Channel. The fields should be
+ * considered private and should only be accessed with the following
+ * functions.
+ **/
+
+/**
+ * GIOFuncs:
+ * @io_read: reads raw bytes from the channel.  This is called from
+ *           various functions such as g_io_channel_read_chars() to
+ *           read raw bytes from the channel.  Encoding and buffering
+ *           issues are dealt with at a higher level.
+ * @io_write: writes raw bytes to the channel.  This is called from
+ *            various functions such as g_io_channel_write_chars() to
+ *            write raw bytes to the channel.  Encoding and buffering
+ *            issues are dealt with at a higher level.
+ * @io_seek: (optional) seeks the channel.  This is called from
+ *           g_io_channel_seek() on channels that support it.
+ * @io_close: closes the channel.  This is called from
+ *            g_io_channel_close() after flushing the buffers.
+ * @io_create_watch: creates a watch on the channel.  This call
+ *                   corresponds directly to g_io_create_watch().
+ * @io_free: called from g_io_channel_unref() when the channel needs to
+ *           be freed.  This function must free the memory associated
+ *           with the channel, including freeing the #GIOChannel
+ *           structure itself.  The channel buffers have been flushed
+ *           and possibly @io_close has been called by the time this
+ *           function is called.
+ * @io_set_flags: sets the #GIOFlags on the channel.  This is called
+ *                from g_io_channel_set_flags() with all flags except
+ *                for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked
+ *                out.
+ * @io_get_flags: gets the #GIOFlags for the channel.  This function
+ *                need only return the %G_IO_FLAG_APPEND and
+ *                %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags()
+ *                automatically adds the others as appropriate.
+ *
+ * A table of functions used to handle different types of #GIOChannel
+ * in a generic way.
+ **/
+
+/**
+ * GIOStatus:
+ * @G_IO_STATUS_ERROR: An error occurred.
+ * @G_IO_STATUS_NORMAL: Success.
+ * @G_IO_STATUS_EOF: End of file.
+ * @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
+ *
+ * Stati returned by most of the #GIOFuncs functions.
+ **/
+
+/**
+ * GIOError:
+ * @G_IO_ERROR_NONE: no error
+ * @G_IO_ERROR_AGAIN: an EAGAIN error occurred
+ * @G_IO_ERROR_INVAL: an EINVAL error occurred
+ * @G_IO_ERROR_UNKNOWN: another error occurred
+ *
+ * #GIOError is only used by the deprecated functions
+ * g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().
+ **/
+
 #define G_IO_NICE_BUF_SIZE	1024
 
 /* This needs to be as wide as the largest character in any possible encoding */
@@ -571,6 +687,31 @@ g_io_add_watch_full (GIOChannel    *channel,
  *
  * Returns: the event source id
  */
+/**
+ * GIOFunc:
+ * @source: the #GIOChannel event source
+ * @condition: the condition which has been satisfied
+ * @data: user data set in g_io_add_watch() or g_io_add_watch_full()
+ * @Returns: the function should return %FALSE if the event source
+ *           should be removed
+ *
+ * Specifies the type of function passed to g_io_add_watch() or
+ * g_io_add_watch_full(), which is called when the requested condition
+ * on a #GIOChannel is satisfied.
+ **/
+/**
+ * GIOCondition:
+ * @G_IO_IN: There is data to read.
+ * @G_IO_OUT: Data can be written (without blocking).
+ * @G_IO_PRI: There is urgent data to read.
+ * @G_IO_ERR: Error condition.
+ * @G_IO_HUP: Hung up (the connection has been broken, usually for
+ *            pipes and sockets).
+ * @G_IO_NVAL: Invalid request. The file descriptor is not open.
+ *
+ * A bitwise combination representing a condition to watch for on an
+ * event source.
+ **/
 guint 
 g_io_add_watch (GIOChannel   *channel,
 		GIOCondition  condition,
@@ -803,6 +944,31 @@ g_io_channel_get_line_term (GIOChannel *channel,
  *
  * Return value: the status of the operation. 
  **/
+/**
+ * GIOFlags:
+ * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
+ *                    (see the documentation of the UNIX open()
+ *                    syscall).
+ * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
+ *                      %O_NONBLOCK/%O_NDELAY (see the documentation of
+ *                      the UNIX open() syscall).
+ * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
+ *                         This flag can not be changed.
+ * @G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable.
+ *                          This flag can not be changed.
+ * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
+ *                         i.e. that g_io_channel_seek_position() can
+ *                         be used on it.  This flag can not be changed.
+ * @G_IO_FLAG_MASK: the mask that specifies all the valid flags.
+ * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from
+ *                      g_io_channel_get_flags().
+ * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify
+ *                      with g_io_channel_set_flags().
+ *
+ * Specifies properties of a #GIOChannel. Some of the flags can only be
+ * read with g_io_channel_get_flags(), but not changed with
+ * g_io_channel_set_flags().
+ **/
 GIOStatus
 g_io_channel_set_flags (GIOChannel  *channel,
                         GIOFlags     flags,
@@ -908,6 +1074,15 @@ g_io_channel_get_close_on_unref	(GIOChannel *channel)
  *
  * Return value: the status of the operation.
  **/
+/**
+ * GSeekType:
+ * @G_SEEK_CUR: the current position in the file.
+ * @G_SEEK_SET: the start of the file.
+ * @G_SEEK_END: the end of the file.
+ *
+ * An enumeration specifying the base position for a
+ * g_io_channel_seek_position() operation.
+ **/
 GIOStatus
 g_io_channel_seek_position (GIOChannel  *channel,
                             gint64       offset,
@@ -2379,6 +2554,27 @@ g_io_channel_write_unichar (GIOChannel  *channel,
  *
  * Return value: the quark used as %G_IO_CHANNEL_ERROR
  **/
+/**
+ * G_IO_CHANNEL_ERROR:
+ *
+ * Error domain for #GIOChannel operations. Errors in this domain will
+ * be from the #GIOChannelError enumeration. See #GError for
+ * information on error domains.
+ **/
+/**
+ * GIOChannelError:
+ * @G_IO_CHANNEL_ERROR_FBIG: File too large.
+ * @G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
+ * @G_IO_CHANNEL_ERROR_IO: IO error.
+ * @G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
+ * @G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
+ * @G_IO_CHANNEL_ERROR_NXIO: No such device or address.
+ * @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
+ * @G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
+ * @G_IO_CHANNEL_ERROR_FAILED: Some other error.
+ *
+ * Error codes returned by #GIOChannel operations.
+ **/
 GQuark
 g_io_channel_error_quark (void)
 {
diff --git a/glib/giounix.c b/glib/giounix.c
index eaff939..0e89d5c 100644
--- a/glib/giounix.c
+++ b/glib/giounix.c
@@ -569,6 +569,32 @@ g_io_channel_new_file (const gchar *filename,
   return channel;
 }
 
+/**
+ * g_io_channel_unix_new:
+ * @fd: a file descriptor.
+ * @Returns: a new #GIOChannel.
+ *
+ * Creates a new #GIOChannel given a file descriptor. On UNIX systems
+ * this works for plain files, pipes, and sockets.
+ *
+ * The returned #GIOChannel has a reference count of 1.
+ *
+ * The default encoding for #GIOChannel is UTF-8. If your application
+ * is reading output from a command using via pipe, you may need to set
+ * the encoding to the encoding of the current locale (see
+ * g_get_charset()) with the g_io_channel_set_encoding() function.
+ *
+ * If you want to read raw binary data without interpretation, then
+ * call the g_io_channel_set_encoding() function with %NULL for the
+ * encoding argument.
+ *
+ * This function is available in GLib on Windows, too, but you should
+ * avoid using it on Windows. The domain of file descriptors and
+ * sockets overlap. There is no way for GLib to know which one you mean
+ * in case the argument you pass to this function happens to be both a
+ * valid file descriptor and socket. If that happens a warning is
+ * issued, and GLib assumes that it is the file descriptor you mean.
+ **/
 GIOChannel *
 g_io_channel_unix_new (gint fd)
 {
@@ -598,6 +624,16 @@ g_io_channel_unix_new (gint fd)
   return channel;
 }
 
+/**
+ * g_io_channel_unix_get_fd:
+ * @channel: a #GIOChannel, created with g_io_channel_unix_new().
+ * @Returns: the file descriptor of the #GIOChannel.
+ *
+ * Returns the file descriptor of the #GIOChannel.
+ *
+ * On Windows this function returns the file descriptor or socket of
+ * the #GIOChannel.
+ **/
 gint
 g_io_channel_unix_get_fd (GIOChannel *channel)
 {
diff --git a/glib/giowin32.c b/glib/giowin32.c
index d661865..07c9c5f 100644
--- a/glib/giowin32.c
+++ b/glib/giowin32.c
@@ -1973,6 +1973,16 @@ static GIOFuncs win32_channel_sock_funcs = {
   g_io_win32_sock_get_flags,
 };
 
+/**
+ * g_io_channel_win32_new_messages:
+ * @hwnd: a window handle.
+ * @Returns: a new #GIOChannel.
+ *
+ * Creates a new #GIOChannel given a window handle on Windows.
+ *
+ * This function creates a #GIOChannel that can be used to poll for
+ * Windows messages for the window in question.
+ **/
 GIOChannel *
 #if GLIB_SIZEOF_VOID_P == 8
 g_io_channel_win32_new_messages (gsize hwnd)
@@ -2036,6 +2046,34 @@ g_io_channel_win32_new_fd_internal (gint         fd,
   return channel;
 }
 
+/**
+ * g_io_channel_win32_new_fd:
+ * @fd: a C library file descriptor.
+ * @Returns: a new #GIOChannel.
+ *
+ * Creates a new #GIOChannel given a file descriptor on Windows. This
+ * works for file descriptors from the C runtime.
+ *
+ * This function works for file descriptors as returned by the open(),
+ * creat(), pipe() and fileno() calls in the Microsoft C runtime. In
+ * order to meaningfully use this function your code should use the
+ * same C runtime as GLib uses, which is msvcrt.dll. Note that in
+ * current Microsoft compilers it is near impossible to convince it to
+ * build code that would use msvcrt.dll. The last Microsoft compiler
+ * version that supported using msvcrt.dll as the C runtime was version
+ * 6. The GNU compiler and toolchain for Windows, also known as Mingw,
+ * fully supports msvcrt.dll.
+ *
+ * If you have created a #GIOChannel for a file descriptor and started
+ * watching (polling) it, you shouldn't call read() on the file
+ * descriptor. This is because adding polling for a file descriptor is
+ * implemented in GLib on Windows by starting a thread that sits
+ * blocked in a read() from the file descriptor most of the time. All
+ * reads from the file descriptor should be done by this internal GLib
+ * thread. Your code should call only g_io_channel_read().
+ *
+ * This function is available only in GLib on Windows.
+ **/
 GIOChannel *
 g_io_channel_win32_new_fd (gint fd)
 {
@@ -2058,6 +2096,20 @@ g_io_channel_win32_get_fd (GIOChannel *channel)
   return win32_channel->fd;
 }
 
+/**
+ * g_io_channel_win32_new_socket:
+ * @socket: a Winsock socket
+ * @Returns: a new #GIOChannel
+ *
+ * Creates a new #GIOChannel given a socket on Windows.
+ *
+ * This function works for sockets created by Winsock. It's available
+ * only in GLib on Windows.
+ *
+ * Polling a #GSource created to watch a channel for a socket puts the
+ * socket in non-blocking mode. This is a side-effect of the
+ * implementation and unavoidable.
+ **/
 GIOChannel *
 g_io_channel_win32_new_socket (int socket)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]