Unified network I/O

## Unified network I/O Unified network I/O — Posix style network input/output functions. |

## Synopsis

    GnomeVFSResult (*GnomeVFSSocketReadFunc)    (gpointer connection,
                                                 gpointer buffer,
                                                 GnomeVFSFileSize bytes,
                                                 GnomeVFSFileSize *bytes_read,
                                                 GnomeVFSCancellation *cancellation);
    GnomeVFSResult (*GnomeVFSSocketWriteFunc)   (gpointer connection,
                                                 gconstpointer buffer,
                                                 GnomeVFSFileSize bytes,
                                                 GnomeVFSFileSize *bytes_written,
                                                 GnomeVFSCancellation *cancellation);
    void        (*GnomeVFSSocketCloseFunc)      (gpointer connection,
                                                 GnomeVFSCancellation *cancellation);
                GnomeVFSSocketImpl;
    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

### GnomeVFSSocketReadFunc ()

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

`connection` : |
`buffer` : |
`bytes` : |
`bytes_read` : |
`cancellation` : |
Returns : |

### GnomeVFSSocketWriteFunc ()

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

`connection` : |
`buffer` : |
`bytes` : |
`bytes_written` : |
`cancellation` : |
Returns : |

### GnomeVFSSocketCloseFunc ()

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

`connection` : |
`cancellation` : |

### GnomeVFSSocketImpl

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

### gnome_vfs_socket_new ()

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

Creates a new GnomeVFS Socket using the specific implementation `impl`.

`impl` : | an implementation of a 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