IOChannel

Name

IOChannel -- IOChannel utility functions

Synopsis



GIOError    gnet_io_channel_writen          (GIOChannel *channel,
                                             gpointer buf,
                                             guint len,
                                             guint *bytes_written);
GIOError    gnet_io_channel_readn           (GIOChannel *channel,
                                             gpointer buf,
                                             guint len,
                                             guint *bytes_read);
GIOError    gnet_io_channel_readline        (GIOChannel *channel,
                                             gchar *buf,
                                             guint len,
                                             guint *bytes_read);
GIOError    gnet_io_channel_readline_strdup (GIOChannel *channel,
                                             gchar **buf_ptr,
                                             guint *bytes_read);
enum        GNetIOChannelWriteAsyncStatus;
typedef     GNetIOChannelWriteAsyncID;
GNetIOChannelWriteAsyncID gnet_io_channel_write_async
                                            (GIOChannel *iochannel,
                                             gchar *buffer,
                                             guint length,
                                             guint timeout,
                                             GNetIOChannelWriteAsyncFunc func,
                                             gpointer user_data);
void        gnet_io_channel_write_async_cancel
                                            (GNetIOChannelWriteAsyncID id,
                                             gboolean delete_buffer);
enum        GNetIOChannelReadAsyncStatus;
typedef     GNetIOChannelReadAsyncID;
GNetIOChannelReadAsyncID gnet_io_channel_read_async
                                            (GIOChannel *iochannel,
                                             gchar *buffer,
                                             guint length,
                                             guint timeout,
                                             gboolean read_one_byte_at_a_time,
                                             GNetIOChannelReadAsyncCheckFunc check_func,
                                             gpointer check_user_data,
                                             GNetIOChannelReadAsyncFunc func,
                                             gpointer user_data);
void        gnet_io_channel_read_async_cancel
                                            (GNetIOChannelReadAsyncID id);
gint        gnet_io_channel_readany_check_func
                                            (gchar *buffer,
                                             guint length,
                                             gpointer data);
gint        gnet_io_channel_readline_check_func
                                            (gchar *buffer,
                                             guint length,
                                             gpointer data);
#define     gnet_io_channel_readany_async   (IO, BUF, LEN, TO, FUNC, UD)
#define     gnet_io_channel_readline_async  (IO, BUF, LEN, TO, FUNC, UD)

Description

Helpful functions for use with IOChannels.

Details

gnet_io_channel_writen ()

GIOError    gnet_io_channel_writen          (GIOChannel *channel,
                                             gpointer buf,
                                             guint len,
                                             guint *bytes_written);

Write all len bytes in the buffer to the channel. This is basically a wrapper around g_io_channel_write(). The problem with g_io_channel_write() is that it may not write all the bytes in the buffer and return a short count even when there was not an error (this is rare, but it can happen and is often difficult to detect when it does).


gnet_io_channel_readn ()

GIOError    gnet_io_channel_readn           (GIOChannel *channel,
                                             gpointer buf,
                                             guint len,
                                             guint *bytes_read);

Read exactly len bytes from the channel the buffer to the channel. This is basically a wrapper around g_io_channel_read(). The problem with g_io_channel_read() is that it may not read all the bytes wanted and return a short count even when there was not an error (this is rare, but it can happen and is often difficult to detect when it does).


gnet_io_channel_readline ()

GIOError    gnet_io_channel_readline        (GIOChannel *channel,
                                             gchar *buf,
                                             guint len,
                                             guint *bytes_read);

Read a line from the channel. The line will be null-terminated and include the newline character. If there is not enough room for the line, the line is truncated to fit in the buffer.

Warnings: (in the gotcha sense, not the bug sense)

1. If the buffer is full and the last character is not a newline, the line was truncated. So, do not assume the buffer ends with a newline.

2. bytes_read is actually the number of bytes put in the buffer. That is, it includes the terminating null character.

3. Null characters can appear in the line before the terminating null (I could send the string "Hello world\0\n"). If this matters in your program, check the string length of the buffer against the bytes read.

I hope this isn't too confusing. Usually the function works as you expect it to if you have a big enough buffer. If you have the Stevens book, you should be familiar with the semantics.


gnet_io_channel_readline_strdup ()

GIOError    gnet_io_channel_readline_strdup (GIOChannel *channel,
                                             gchar **buf_ptr,
                                             guint *bytes_read);

Read a line from the channel. The line will be null-terminated and include the newline character. Similarly to g_strdup_printf, a buffer large enough to hold the string will be allocated.

Warnings: (in the gotcha sense, not the bug sense)

1. If the last character of the buffer is not a newline, the line was truncated by EOF. So, do not assume the buffer ends with a newline.

2. bytes_read is actually the number of bytes put in the buffer. That is, it includes the terminating null character.

3. Null characters can appear in the line before the terminating null (I could send the string "Hello world\0\n"). If this matters in your program, check the string length of the buffer against the bytes read.


enum GNetIOChannelWriteAsyncStatus

typedef enum {
  GNET_IOCHANNEL_WRITE_ASYNC_STATUS_OK,
  GNET_IOCHANNEL_WRITE_ASYNC_STATUS_TIMEOUT,
  GNET_IOCHANNEL_WRITE_ASYNC_STATUS_ERROR
} GNetIOChannelWriteAsyncStatus;


GNetIOChannelWriteAsyncID


gnet_io_channel_write_async ()

GNetIOChannelWriteAsyncID gnet_io_channel_write_async
                                            (GIOChannel *iochannel,
                                             gchar *buffer,
                                             guint length,
                                             guint timeout,
                                             GNetIOChannelWriteAsyncFunc func,
                                             gpointer user_data);


gnet_io_channel_write_async_cancel ()

void        gnet_io_channel_write_async_cancel
                                            (GNetIOChannelWriteAsyncID id,
                                             gboolean delete_buffer);


enum GNetIOChannelReadAsyncStatus

typedef enum {
  GNET_IOCHANNEL_READ_ASYNC_STATUS_OK,
  GNET_IOCHANNEL_READ_ASYNC_STATUS_TIMEOUT,
  GNET_IOCHANNEL_READ_ASYNC_STATUS_ERROR
} GNetIOChannelReadAsyncStatus;


GNetIOChannelReadAsyncID


gnet_io_channel_read_async ()

GNetIOChannelReadAsyncID gnet_io_channel_read_async
                                            (GIOChannel *iochannel,
                                             gchar *buffer,
                                             guint length,
                                             guint timeout,
                                             gboolean read_one_byte_at_a_time,
                                             GNetIOChannelReadAsyncCheckFunc check_func,
                                             gpointer check_user_data,
                                             GNetIOChannelReadAsyncFunc func,
                                             gpointer user_data);


gnet_io_channel_read_async_cancel ()

void        gnet_io_channel_read_async_cancel
                                            (GNetIOChannelReadAsyncID id);


gnet_io_channel_readany_check_func ()

gint        gnet_io_channel_readany_check_func
                                            (gchar *buffer,
                                             guint length,
                                             gpointer data);


gnet_io_channel_readline_check_func ()

gint        gnet_io_channel_readline_check_func
                                            (gchar *buffer,
                                             guint length,
                                             gpointer data);


gnet_io_channel_readany_async()

#define     gnet_io_channel_readany_async(IO, BUF, LEN, TO, FUNC, UD)


gnet_io_channel_readline_async()

#define     gnet_io_channel_readline_async(IO, BUF, LEN, TO, FUNC, UD)