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

# Unified network I/O

Posix style network input/output functions.

## Synopsis

    typedef             GnomeVFSSocket;
                        GnomeVFSSocketImpl;
    GnomeVFSResult      (*GnomeVFSSocketReadFunc)           (gpointer connection,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read_out,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      (*GnomeVFSSocketWriteFunc)          (gpointer connection,
                                                             gconstpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_written_out,
                                                             GnomeVFSCancellation *cancellation);
    void                (*GnomeVFSSocketCloseFunc)          (gpointer connection,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      (*GnomeVFSSocketSetTimeoutFunc)     (gpointer connection,
                                                             GTimeVal *timeout,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSSocket*     gnome_vfs_socket_new                (GnomeVFSSocketImpl *impl,
                                                             void *connection);
    GnomeVFSResult      gnome_vfs_socket_write              (GnomeVFSSocket *socket,
                                                             gconstpointer buffer,
                                                             int bytes,
                                                             GnomeVFSFileSize *bytes_written,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_socket_close              (GnomeVFSSocket *socket,
                                                             GnomeVFSCancellation *cancellation);
    GnomeVFSResult      gnome_vfs_socket_read               (GnomeVFSSocket *socket,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read,
                                                             GnomeVFSCancellation *cancellation);
    void                gnome_vfs_socket_free               (GnomeVFSSocket *socket);
    GnomeVFSResult      gnome_vfs_socket_set_timeout        (GnomeVFSSocket *socket,
                                                             GTimeVal *timeout,
                                                             GnomeVFSCancellation *cancellation);

## Description

The GnomeVFSSocket function family unifies network I/O through functions similar to the standard POSIX read/write functions. The main difference is that all operations are cancellable through the standard GnomeVFS cancellation mechanism and you can specify a maximum amount of time an operation may take through gnome_vfs_socket_set_timeout.

## Details

### GnomeVFSSocket

    typedef struct GnomeVFSSocket GnomeVFSSocket;

An handle to a generic unbuffered socket connection established with `gnome_vfs_socket_new()`.

The specifics of the underlying socket implementation are hidden inside the GnomeVFSSocketImpl passed on construction.

If you need buffered I/O, you will also have to create a GnomeVFSSocketBuffer.

### GnomeVFSSocketImpl

    typedef struct {
      GnomeVFSSocketReadFunc read;
      GnomeVFSSocketWriteFunc write;
      GnomeVFSSocketCloseFunc close;
      GnomeVFSSocketSetTimeoutFunc set_timeout;
    } GnomeVFSSocketImpl;

An implementation of a generic socket (i.e. of GnomeVFSSocket) encapsulating the details of how socket I/O works.

Please refer to GnomeVFSSSL for a sample implementation of this interface.

GnomeVFSSocketReadFunc read;

  A GnomeVFSSocketReadFunc function used for reading from a socket.

GnomeVFSSocketWriteFunc write;

  A GnomeVFSSocketWriteFunc function used for writing to a socket.

GnomeVFSSocketCloseFunc close;

  A GnomeVFSSocketCloseFunc function used for closing an open socket.

GnomeVFSSocketSetTimeoutFunc set_timeout;

  A GnomeVFSSocketSetTimeoutFunc function used for setting a socket's timeout.

### GnomeVFSSocketReadFunc ()

    GnomeVFSResult      (*GnomeVFSSocketReadFunc)           (gpointer connection,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read_out,
                                                             GnomeVFSCancellation *cancellation);

This is a generic prototype for a function that reads from a socket.

This function is implemented by a GnomeVFSSocketImpl, and it defines how data should be written to a buffer using the `gnome_vfs_socket_read()` function which hides the socket implementation details.

`connection` :

  The socket connection.

`buffer` :

  A connection buffer.

`bytes` :

  The bytes to read.

`bytes_read_out` :

  The bytes that were read (out).

`cancellation` :

  A cancellation handle that allows clients to cancel the read operation.

Returns :

  A GnomeVFSResult signalling the result of the read operation.

### GnomeVFSSocketWriteFunc ()

    GnomeVFSResult      (*GnomeVFSSocketWriteFunc)          (gpointer connection,
                                                             gconstpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_written_out,
                                                             GnomeVFSCancellation *cancellation);

This is a generic prototype for a function that writes to a socket.

This function is implemented by a GnomeVFSSocketImpl, and it defines how data should be written to a buffer using the `gnome_vfs_socket_write()` function which hides the socket implementation details.

`connection` :

  The socket connection.

`buffer` :

  A connection buffer.

`bytes` :

  The bytes to write.

`bytes_written_out` :

  The bytes that were written.

`cancellation` :

  A cancellation handle that allows clients to cancel the write operation.

Returns :

  A GnomeVFSResult signalling the result of the write operation.

### GnomeVFSSocketCloseFunc ()

    void                (*GnomeVFSSocketCloseFunc)          (gpointer connection,
                                                             GnomeVFSCancellation *cancellation);

This is a generic prototype for a function that closes a socket.

This function is implemented by a GnomeVFSSocketImpl, and it defines how an open socket that was previously opened by `gnome_vfs_socket_new()` should be closed using the `gnome_vfs_socket_set_timeout()` function which hides the socket implementation details.

`connection` :

`cancellation` :

  A cancellation handle that allows clients to cancel the write operation.

### GnomeVFSSocketSetTimeoutFunc ()

    GnomeVFSResult      (*GnomeVFSSocketSetTimeoutFunc)     (gpointer connection,
                                                             GTimeVal *timeout,
                                                             GnomeVFSCancellation *cancellation);

This is a generic prototype for a function that sets a socket timeout.

This function is implemented by a GnomeVFSSocketImpl, and it defines how a socket timeout should be set using should be closed by the `gnome_vfs_socket_close()` function which hides the socket implementation details.

`connection` :

`timeout` :

`cancellation` :

  A cancellation handle that allows clients to cancel the write operation.

Returns :

  A GnomeVFSResult signalling the result of the write operation.

### gnome_vfs_socket_new ()

    GnomeVFSSocket*     gnome_vfs_socket_new                (GnomeVFSSocketImpl *impl,
                                                             void *connection);

Creates a new GnomeVFSSocket using the specific implementation `impl`.

`impl` :

  an implementation of socket, e.g. GnomeVFSSSL.

`connection` :

  pointer to a connection object used by `impl` to track. state (the exact nature of `connection` varies from implementation to implementation).

Returns :

  a newly created socket.

### gnome_vfs_socket_write ()

    GnomeVFSResult      gnome_vfs_socket_write              (GnomeVFSSocket *socket,
                                                             gconstpointer buffer,
                                                             int bytes,
                                                             GnomeVFSFileSize *bytes_written,
                                                             GnomeVFSCancellation *cancellation);

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

`socket` :

  socket to write data to.

`buffer` :

  data to write to the socket.

`bytes` :

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

`bytes_written` :

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

`cancellation` :

  optional cancellation object.

Returns :

  GnomeVFSResult indicating the success of the operation.

### gnome_vfs_socket_close ()

    GnomeVFSResult      gnome_vfs_socket_close              (GnomeVFSSocket *socket,
                                                             GnomeVFSCancellation *cancellation);

Close `socket`, freeing any resources it may be using.

`socket` :

  the socket to be closed.

`cancellation` :

  optional cancellation object.

Returns :

  GnomeVFSResult indicating the success of the operation.

### gnome_vfs_socket_read ()

    GnomeVFSResult      gnome_vfs_socket_read               (GnomeVFSSocket *socket,
                                                             gpointer buffer,
                                                             GnomeVFSFileSize bytes,
                                                             GnomeVFSFileSize *bytes_read,
                                                             GnomeVFSCancellation *cancellation);

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

`socket` :

  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` into `buffer`.

`bytes_read` :

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

`cancellation` :

  optional cancellation object.

Returns :

  GnomeVFSResult indicating the success of the operation.

### gnome_vfs_socket_free ()

    void                gnome_vfs_socket_free               (GnomeVFSSocket *socket);

Frees the memory allocated for `socket`, but does not call any GnomeVFSSocketImpl function.

`socket` :

  The GnomeVFSSocket you want to free.

Since 2.8

### gnome_vfs_socket_set_timeout ()

    GnomeVFSResult      gnome_vfs_socket_set_timeout        (GnomeVFSSocket *socket,
                                                             GTimeVal *timeout,
                                                             GnomeVFSCancellation *cancellation);

Set a timeout of `timeout`. If `timeout` is `NULL`, following operations will block indefinitely).

Note if you set `timeout` to 0 (means tv_sec and tv_usec are both 0) every following operation will return immediately. (This can be used for polling.)

`socket` :

  socket to set the timeout of.

`timeout` :

  the timeout.

`cancellation` :

  optional cancellation object.

Returns :

  GnomeVFSResult indicating the success of the operation.

Since 2.8