Unified bufferd network I/O
3
GNOME-VFS-2.0 Library

# Unified bufferd network I/O

Posix style buffered network input/output.

## Synopsis

    typedef             GnomeVFSSocketBuffer;
    GnomeVFSSocketBuffer* gnome_vfs_socket_buffer_new       (GnomeVFSSocket *socket);
    GnomeVFSResult      gnome_vfs_socket_buffer_destroy     (GnomeVFSSocketBuffer *socket_buffer,
                                                             gboolean close_socket,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_socket_buffer_read        (GnomeVFSSocketBuffer *socket_buffer,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_socket_buffer_peekc       (GnomeVFSSocketBuffer *socket_buffer,
                                                             char *character,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_socket_buffer_write       (GnomeVFSSocketBuffer *socket_buffer,
                                                             gconstpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_written,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_socket_buffer_flush       (GnomeVFSSocketBuffer *socket_buffer,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_socket_buffer_read_until  (GnomeVFSSocketBuffer *socket_buffer,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             gconstpointer boundary,
                                                             GnomeVFSFileSize boundary_len,
                                                             GnomeVFSFileSize *bytes_read,
                                                             gboolean *got_boundary,
                                                             GnomeVFSCancellation *cancellation);

## Description

The GnomeVFSSocketBuffer functions are very similar to the GnomeVFSSocket ones. The only difference is that all input/output is done through an internally managed buffer. This might increase I/O performance as well as give you the possibility to use some convenient functions like gnome_vfs_socket_buffer_peekc and gnome_vfs_socket_buffer_read_until.

You can manually force all internally buffered data to get written with gnome_vfs_socket_buffer_flush.

## Details

### GnomeVFSSocketBuffer

    typedef struct GnomeVFSSocketBuffer GnomeVFSSocketBuffer;

A handle to a socket buffer. A socket buffer is a temporary in-memory storage for data that is read from or written to a GnomeVFSSocket.

### gnome_vfs_socket_buffer_new ()

    GnomeVFSSocketBuffer* gnome_vfs_socket_buffer_new       (GnomeVFSSocket *socket);

Create a socket buffer around `socket`. A buffered socket allows data to be poked at without reading it as it will be buffered. A future read will retrieve the data again.

`socket` :

  socket to be buffered.

Returns :

  a newly allocated GnomeVFSSocketBuffer.

### gnome_vfs_socket_buffer_destroy ()

    GnomeVFSResult      gnome_vfs_socket_buffer_destroy     (GnomeVFSSocketBuffer *socket_buffer,
                                                             gboolean close_socket,
                                                             GnomeVFSCancellation *cancellation);

Free the socket buffer.

`socket_buffer` :

  buffered socket to destroy.

`close_socket` :

  if `TRUE`, the socket being buffered will be closed.

`cancellation` :

  handle allowing cancellation of the operation.

Returns :

  GnomeVFSResult indicating the success of the operation.

### gnome_vfs_socket_buffer_read ()

    GnomeVFSResult      gnome_vfs_socket_buffer_read        (GnomeVFSSocketBuffer *socket_buffer,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read,
                                                             GnomeVFSCancellation *cancellation);

Read `bytes` bytes of data from the `socket` into `socket_buffer`.

`socket_buffer` :

  buffered socket to read data from.

`buffer` :

  allocated buffer of at least `bytes` bytes to be read into.

`bytes` :

  number of bytes to read from `socket_buffer` into `buffer`.

`bytes_read` :

  pointer to a GnomeVFSFileSize, will contain the number of bytes actually read from the `socket_buffer` on return.

`cancellation` :

  handle allowing cancellation of the operation.

Returns :

  GnomeVFSResult indicating the success of the operation.

### gnome_vfs_socket_buffer_peekc ()

    GnomeVFSResult      gnome_vfs_socket_buffer_peekc       (GnomeVFSSocketBuffer *socket_buffer,
                                                             char *character,
                                                             GnomeVFSCancellation *cancellation);

Peek at the next character in `socket_buffer` without actually reading the character in. The next read will retrieve `c` (as well as any following data if requested).

`socket_buffer` :

  the socket buffer to read from.

`character` :

  pointer to a char, will contain a character on return from a successful "peek".

`cancellation` :

  handle allowing cancellation of the operation.

Returns :

  GnomeVFSResult indicating the success of the operation.

### gnome_vfs_socket_buffer_write ()

    GnomeVFSResult      gnome_vfs_socket_buffer_write       (GnomeVFSSocketBuffer *socket_buffer,
                                                             gconstpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_written,
                                                             GnomeVFSCancellation *cancellation);

Write `bytes` bytes of data from `buffer` to `socket_buffer`.

`socket_buffer` :

  buffered socket to write data to.

`buffer` :

  data to write to the `socket_buffer`.

`bytes` :

  number of bytes to write from `buffer` to `socket_buffer`.

`bytes_written` :

  pointer to a GnomeVFSFileSize, will contain the number of bytes actually written to the `socket_buffer` on return.

`cancellation` :

  handle allowing cancellation of the operation.

Returns :

  GnomeVFSResult indicating the success of the operation.

### gnome_vfs_socket_buffer_flush ()

    GnomeVFSResult      gnome_vfs_socket_buffer_flush       (GnomeVFSSocketBuffer *socket_buffer,
                                                             GnomeVFSCancellation *cancellation);

Write all outstanding data to `socket_buffer`.

`socket_buffer` :

  buffer to flush.

`cancellation` :

  handle allowing cancellation of the operation.

Returns :

  GnomeVFSResult indicating the success of the operation.

### gnome_vfs_socket_buffer_read_until ()

    GnomeVFSResult      gnome_vfs_socket_buffer_read_until  (GnomeVFSSocketBuffer *socket_buffer,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             gconstpointer boundary,
                                                             GnomeVFSFileSize boundary_len,
                                                             GnomeVFSFileSize *bytes_read,
                                                             gboolean *got_boundary,
                                                             GnomeVFSCancellation *cancellation);

Read up to `bytes` bytes of data from the `socket_buffer` into `buffer` until boundary is reached. `got_boundary` will be set accordingly.

Note that if `bytes` is smaller than `boundary_len` there is no way to detected the boundary! So if you want to make sure that every boundary is found (in a loop maybe) assure that `bytes` is at least as big as `boundary_len`.

`socket_buffer` :

  buffered socket to read data from.

`buffer` :

  allocated buffer of at least `bytes` bytes to be read into.

`bytes` :

  maximum number of bytes to read from `socket_buffer` into `buffer`.

`boundary` :

  the boundary until which is read.

`boundary_len` :

  the length of the `boundary`.

`bytes_read` :

  pointer to a GnomeVFSFileSize, will contain the number of bytes actually read from the `socket_buffer` on return.

`got_boundary` :

  pointer to a gboolean which will be `TRUE` if the boundary was found or `FALSE` otherwise.

`cancellation` :

  handle allowing cancellation of the operation.

Returns :

  GnomeVFSResult indicating the success of the operation.

Since 2.8