Name
IO Channels -- portable support for using files, pipes and sockets.
Synopsis
#include <glib.h>
struct GIOChannel;
GIOChannel* g_io_channel_unix_new (int fd);
gint g_io_channel_unix_get_fd (GIOChannel *channel);
void g_io_channel_init (GIOChannel *channel);
GIOError g_io_channel_read (GIOChannel *channel,
gchar *buf,
guint count,
guint *bytes_read);
enum GIOError;
GIOError g_io_channel_write (GIOChannel *channel,
gchar *buf,
guint count,
guint *bytes_written);
GIOError g_io_channel_seek (GIOChannel *channel,
gint offset,
GSeekType type);
enum GSeekType;
void g_io_channel_close (GIOChannel *channel);
void g_io_channel_ref (GIOChannel *channel);
void g_io_channel_unref (GIOChannel *channel);
guint g_io_add_watch (GIOChannel *channel,
GIOCondition condition,
GIOFunc func,
gpointer user_data);
guint g_io_add_watch_full (GIOChannel *channel,
gint priority,
GIOCondition condition,
GIOFunc func,
gpointer user_data,
GDestroyNotify notify);
enum GIOCondition;
gboolean (*GIOFunc) (GIOChannel *source,
GIOCondition condition,
gpointer data);
struct GIOFuncs;
|
Description
The GIOChannel data type aims to provide a portable method for using file
descriptors, pipes, and sockets, and integrating them into the
main event loop.
Currently full support is available on Unix platforms, though 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.
Once a GIOChannel has been created, it can be used in a generic manner
with the functions g_io_channel_read(), g_io_channel_write(),
g_io_channel_seek(), and g_io_channel_close().
To add a GIOChannel to the
main event loop
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.)
Using g_io_add_watch() or g_io_add_watch_full() increments a channel's
reference count.
GTK+ contains the convenience function gtk_input_add_full()
which creates a GIOChannel from a file descriptor and adds it to the
main event loop.
The event source can later be removed with gtk_input_remove().
Similar functions can also be found in GDK.
Details
struct GIOChannel
struct GIOChannel
{
guint channel_flags;
guint ref_count;
GIOFuncs *funcs;
}; |
A data structure representing an IO Channel. The fields should be considered
private and should only be accessed with the following functions.
g_io_channel_unix_new ()
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.
g_io_channel_unix_get_fd ()
Returns the file descriptor of the Unix GIOChannel.
g_io_channel_init ()
Initializes a GIOChannel struct. This is called by each of the above functions
when creating a GIOChannel, and so is not often needed by the application
programmer (unless you are creating a new type of GIOChannel).
enum GIOError
typedef enum
{
G_IO_ERROR_NONE,
G_IO_ERROR_AGAIN,
G_IO_ERROR_INVAL,
G_IO_ERROR_UNKNOWN
} GIOError; |
g_io_channel_seek ()
Sets the current position in the GIOChannel, similar to the standard system
call fseek().
enum GSeekType
typedef enum
{
G_SEEK_CUR,
G_SEEK_SET,
G_SEEK_END
} GSeekType; |
An enumeration specifying the base position for a g_io_channel_seek()
operation.
g_io_channel_close ()
Closes a GIOChannel.
The GIOChannel will be freed when its reference count drops to 0.
g_io_channel_ref ()
Increments the reference count of a GIOChannel.
g_io_channel_unref ()
Decrements the reference count of a GIOChannel.
enum GIOCondition
typedef enum
{
G_IO_IN GLIB_SYSDEF_POLLIN,
G_IO_OUT GLIB_SYSDEF_POLLOUT,
G_IO_PRI GLIB_SYSDEF_POLLPRI,
G_IO_ERR GLIB_SYSDEF_POLLERR,
G_IO_HUP GLIB_SYSDEF_POLLHUP,
G_IO_NVAL GLIB_SYSDEF_POLLNVAL
} GIOCondition; |
A bitwise combination representing a condition to watch for on an event
source.
struct GIOFuncs
struct GIOFuncs
{
GIOError (*io_read) (GIOChannel *channel,
gchar *buf,
guint count,
guint *bytes_read);
GIOError (*io_write) (GIOChannel *channel,
gchar *buf,
guint count,
guint *bytes_written);
GIOError (*io_seek) (GIOChannel *channel,
gint offset,
GSeekType type);
void (*io_close) (GIOChannel *channel);
guint (*io_add_watch) (GIOChannel *channel,
gint priority,
GIOCondition condition,
GIOFunc func,
gpointer user_data,
GDestroyNotify notify);
void (*io_free) (GIOChannel *channel);
}; |
A table of functions used to handle different types of GIOChannel in a
generic way.