Unified network I/O

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

## Synopsis

    typedef             MateVFSSocket;
                        MateVFSSocketImpl;
    MateVFSResult      (*MateVFSSocketReadFunc)           (gpointer connection,
                                                             gpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *bytes_read_out,
                                                             MateVFSCancellation *cancellation);
    MateVFSResult      (*MateVFSSocketWriteFunc)          (gpointer connection,
                                                             gconstpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *bytes_written_out,
                                                             MateVFSCancellation *cancellation);
    void                (*MateVFSSocketCloseFunc)          (gpointer connection,
                                                             MateVFSCancellation *cancellation);
    MateVFSResult      (*MateVFSSocketSetTimeoutFunc)     (gpointer connection,
                                                             GTimeVal *timeout,
                                                             MateVFSCancellation *cancellation);
    MateVFSSocket *    mate_vfs_socket_new                (MateVFSSocketImpl *impl,
                                                             void *connection);
    MateVFSResult      mate_vfs_socket_write              (MateVFSSocket *socket,
                                                             gconstpointer buffer,
                                                             int bytes,
                                                             MateVFSFileSize *bytes_written,
                                                             MateVFSCancellation *cancellation);
    MateVFSResult      mate_vfs_socket_close              (MateVFSSocket *socket,
                                                             MateVFSCancellation *cancellation);
    MateVFSResult      mate_vfs_socket_read               (MateVFSSocket *socket,
                                                             gpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *bytes_read,
                                                             MateVFSCancellation *cancellation);
    void                mate_vfs_socket_free               (MateVFSSocket *socket);
    MateVFSResult      mate_vfs_socket_set_timeout        (MateVFSSocket *socket,
                                                             GTimeVal *timeout,
                                                             MateVFSCancellation *cancellation);

## Description

The MateVFSSocket 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 MateVFS cancellation mechanism and you can specify a maximum amount of time an operation may take through mate_vfs_socket_set_timeout.

## Details

### MateVFSSocket

    typedef struct MateVFSSocket MateVFSSocket;

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

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

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

### MateVFSSocketImpl

    typedef struct {
      MateVFSSocketReadFunc read;
      MateVFSSocketWriteFunc write;
      MateVFSSocketCloseFunc close;
      MateVFSSocketSetTimeoutFunc set_timeout;
    } MateVFSSocketImpl;

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

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

MateVFSSocketReadFunc `read`; | A MateVFSSocketReadFunc function used for reading from a socket.
MateVFSSocketWriteFunc `write`; | A MateVFSSocketWriteFunc function used for writing to a socket.
MateVFSSocketCloseFunc `close`; | A MateVFSSocketCloseFunc function used for closing an open socket.
MateVFSSocketSetTimeoutFunc `set_timeout`; | A MateVFSSocketSetTimeoutFunc function used for setting a socket's timeout.

### MateVFSSocketReadFunc ()

    MateVFSResult      (*MateVFSSocketReadFunc)           (gpointer connection,
                                                             gpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *bytes_read_out,
                                                             MateVFSCancellation *cancellation);

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

This function is implemented by a MateVFSSocketImpl, and it defines how data should be written to a buffer using the `mate_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 MateVFSResult signalling the result of the read operation.

### MateVFSSocketWriteFunc ()

    MateVFSResult      (*MateVFSSocketWriteFunc)          (gpointer connection,
                                                             gconstpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *bytes_written_out,
                                                             MateVFSCancellation *cancellation);

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

This function is implemented by a MateVFSSocketImpl, and it defines how data should be written to a buffer using the `mate_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 MateVFSResult signalling the result of the write operation.

### MateVFSSocketCloseFunc ()

    void                (*MateVFSSocketCloseFunc)          (gpointer connection,
                                                             MateVFSCancellation *cancellation);

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

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

`connection` : |
`cancellation` : | A cancellation handle that allows clients to cancel the write operation.

### MateVFSSocketSetTimeoutFunc ()

    MateVFSResult      (*MateVFSSocketSetTimeoutFunc)     (gpointer connection,
                                                             GTimeVal *timeout,
                                                             MateVFSCancellation *cancellation);

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

This function is implemented by a MateVFSSocketImpl, and it defines how a socket timeout should be set using should be closed by the `mate_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 MateVFSResult signalling the result of the write operation.

### mate_vfs_socket_new ()

    MateVFSSocket *    mate_vfs_socket_new                (MateVFSSocketImpl *impl,
                                                             void *connection);

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

`impl` : | an implementation of socket, e.g. MateVFSSSL.
`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.

### mate_vfs_socket_write ()

    MateVFSResult      mate_vfs_socket_write              (MateVFSSocket *socket,
                                                             gconstpointer buffer,
                                                             int bytes,
                                                             MateVFSFileSize *bytes_written,
                                                             MateVFSCancellation *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 MateVFSFileSize, will contain the number of bytes actually written to the `socket` on return.
`cancellation` : | optional cancellation object.
Returns : | MateVFSResult indicating the success of the operation.

### mate_vfs_socket_close ()

    MateVFSResult      mate_vfs_socket_close              (MateVFSSocket *socket,
                                                             MateVFSCancellation *cancellation);

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

`socket` : | the socket to be closed.
`cancellation` : | optional cancellation object.
Returns : | MateVFSResult indicating the success of the operation.

### mate_vfs_socket_read ()

    MateVFSResult      mate_vfs_socket_read               (MateVFSSocket *socket,
                                                             gpointer buffer,
                                                             MateVFSFileSize bytes,
                                                             MateVFSFileSize *bytes_read,
                                                             MateVFSCancellation *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 MateVFSFileSize, will contain the number of bytes actually read from the socket on return.
`cancellation` : | optional cancellation object.
Returns : | MateVFSResult indicating the success of the operation.

### mate_vfs_socket_free ()

    void                mate_vfs_socket_free               (MateVFSSocket *socket);

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

`socket` : | The MateVFSSocket you want to free.

Since 2.8

### mate_vfs_socket_set_timeout ()

    MateVFSResult      mate_vfs_socket_set_timeout        (MateVFSSocket *socket,
                                                             GTimeVal *timeout,
                                                             MateVFSCancellation *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 : | MateVFSResult indicating the success of the operation.

Since 2.8