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