GLib Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
#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; |
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.
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.
GIOChannel* g_io_channel_unix_new (int fd); |
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.
fd : | a file descriptor. |
Returns : | a new GIOChannel. |
gint g_io_channel_unix_get_fd (GIOChannel *channel); |
Returns the file descriptor of the Unix GIOChannel.
channel : | a GIOChannel, created with g_io_channel_unix_new(). |
Returns : | the file descriptor of the GIOChannel. |
void g_io_channel_init (GIOChannel *channel); |
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).
channel : | a GIOChannel. |
GIOError g_io_channel_read (GIOChannel *channel, gchar *buf, guint count, guint *bytes_read); |
Reads data from a GIOChannel.
channel : | a GIOChannel. |
buf : | a buffer to read the data into (which should be at least count bytes long). |
count : | the number of bytes to read from the GIOChannel. |
bytes_read : | returns the number of bytes actually read. |
Returns : | G_IO_ERROR_NONE if the operation was successful. |
typedef enum { G_IO_ERROR_NONE, G_IO_ERROR_AGAIN, G_IO_ERROR_INVAL, G_IO_ERROR_UNKNOWN } GIOError; |
GIOError g_io_channel_write (GIOChannel *channel, gchar *buf, guint count, guint *bytes_written); |
Writes data to a GIOChannel.
channel : | a GIOChannel. |
buf : | the buffer containing the data to write. |
count : | the number of bytes to write. |
bytes_written : | the number of bytes actually written. |
Returns : | G_IO_ERROR_NONE if the operation was successful. |
GIOError g_io_channel_seek (GIOChannel *channel, gint offset, GSeekType type); |
Sets the current position in the GIOChannel, similar to the standard system call fseek().
channel : | a GIOChannel. |
offset : | an offset, in bytes, which is added to the position specified by type. |
type : | the position in the file, which can be G_SEEK_CUR (the current position), G_SEEK_SET (the start of the file), or G_SEEK_END (the end of the file). |
Returns : | G_IO_ERROR_NONE if the operation was successful. |
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_SEEK_CUR | the current position in the file. |
G_SEEK_SET | the start of the file. |
G_SEEK_END | the end of the file. |
void g_io_channel_close (GIOChannel *channel); |
Closes a GIOChannel. The GIOChannel will be freed when its reference count drops to 0.
channel : | a GIOChannel. |
void g_io_channel_ref (GIOChannel *channel); |
Increments the reference count of a GIOChannel.
channel : | a GIOChannel. |
void g_io_channel_unref (GIOChannel *channel); |
Decrements the reference count of a GIOChannel.
channel : | a GIOChannel. |
guint g_io_add_watch (GIOChannel *channel, GIOCondition condition, GIOFunc func, gpointer user_data); |
Adds the GIOChannel into the main event loop with the default priority.
channel : | a GIOChannel. |
condition : | the condition to watch for. |
func : | the function to call when the condition is satisfied. |
user_data : | user data to pass to func. |
Returns : | the event source id. |
guint g_io_add_watch_full (GIOChannel *channel, gint priority, GIOCondition condition, GIOFunc func, gpointer user_data, GDestroyNotify notify); |
Adds the GIOChannel into the main event loop with the given priority.
channel : | a GIOChannel. |
priority : | the priority of the GIOChannel source. |
condition : | the condition to watch for. |
func : | the function to call when the condition is satisfied. |
user_data : | user data to pass to func. |
notify : | the function to call when the source is removed. |
Returns : | the event source id. |
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.
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. |
gboolean (*GIOFunc) (GIOChannel *source, GIOCondition condition, gpointer data); |
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.
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. |
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.
Convenience functions for creating GIOChannel instances and adding them to the main event loop.