Unified network I/O

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.

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.

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

Generated by GTK-Doc V1.18