Gnet Network Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GNet main module

## Name

GNet main module -- Main header and utility functions.

## Synopsis

    #define     GNET_CHECK_VERSION              (major,minor,micro)
    GIOError    gnet_io_channel_writen          (GIOChannel *channel,
                                                 gchar *buf,
                                                 guint len,
                                                 guint *bytes_written);
    GIOError    gnet_io_channel_readn           (GIOChannel *channel,
                                                 gchar *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);

## Description

gnet.h is the main header file for Gnet applications. It also includes some utility functions for working with glib IOChannels.

## Details

### GNET_CHECK_VERSION()

    #define     GNET_CHECK_VERSION(major,minor,micro)

`major` : |
`minor` : |
`micro` : |

### gnet_io_channel_writen ()

    GIOError    gnet_io_channel_writen          (GIOChannel *channel,
                                                 gchar *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_read(). 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).

`channel` : | the channel to write to
`buf` : | the buffer to read from
`len` : | length of the buffer
`bytes_written` : | pointer to integer for the function to store the number of bytes writen.
Returns : | `G_IO_ERROR_NONE` if everything is ok; something else otherwise. Also, returns the number of bytes writen by modifying the integer pointed to by `bytes_written`.

### gnet_io_channel_readn ()

    GIOError    gnet_io_channel_readn           (GIOChannel *channel,
                                                 gchar *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).

`channel` : | the channel to read from
`buf` : | the buffer to write to
`len` : | the length of the buffer
`bytes_read` : | pointer to integer for the function to store the number of of bytes read.
Returns : | `G_IO_ERROR_NONE` if everything is ok; something else otherwise. Also, returns the number of bytes read by modifying the integer pointed to by `bytes_read`. If `bytes_read` is 0, the end of the file has been reached (eg, the socket has been closed).

### 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.

`channel` : | the channel to read from
`buf` : | the buffer to write to
`len` : | length of the buffer
`bytes_read` : | pointer to integer for the function to store the number of of bytes read.
Returns : | `G_IO_ERROR_NONE` if everything is ok; something else otherwise. Also, returns the number of bytes read by modifying the integer pointed to by `bytes_read` (this number includes the newline). If an error is returned, the contents of `buf` and `bytes_read` are undefined.

### 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.

`channel` : | the channel to read from
`buf_ptr` : | pointer to gchar* for the functin to store the new buffer
`bytes_read` : | pointer to integer for the function to store the number of of bytes read.
Returns : | `G_IO_ERROR_NONE` if everything is ok; something else otherwise. Also, returns the number of bytes read by modifying the integer pointed to by `bytes_read` (this number includes the newline), and the data through the pointer pointed to by `buf_ptr`. This data should be freed with g_free(). If an error is returned, the contents of `buf_ptr` and `bytes_read` are undefined.

<<< Previous Page | Home | Up | Next Page >>>
Gnet Library Reference | Internet address module