Connection

GNet Network Library Reference Manual
<<< Previous Page	Home	Up	Next Page >>>

Details

struct GConn

struct GConn
{
  gchar*			hostname;
  gint				port;

  guint				ref_count;

  GTcpSocketConnectAsyncID 	connect_id;
  GTcpSocketNewAsyncID 		new_id;

  GTcpSocket* 			socket;
  GInetAddr*			inetaddr;
  GIOChannel* 			iochannel;

  guint				read_watch;	/* DEPRICATED */
  guint				write_watch;	/* DEPRICATED */
  guint				err_watch;	/* DEPRICATED */

  GNetIOChannelWriteAsyncID 	write_id;
  GList*			queued_writes;

  GNetIOChannelReadAsyncID  	read_id;

  guint				timer;

  GConnFunc			func;
  gpointer			user_data;

};

enum GConnStatus

typedef enum {
  GNET_CONN_STATUS_CONNECT,
  GNET_CONN_STATUS_CLOSE,
  GNET_CONN_STATUS_READ,
  GNET_CONN_STATUS_WRITE,
  GNET_CONN_STATUS_TIMEOUT,
  GNET_CONN_STATUS_ERROR
} GConnStatus;

Status of GConn, passed by GConnFunc.

GConnFunc ()

gboolean    (*GConnFunc)                    (GConn *conn,
                                             GConnStatus status,
                                             gchar *buffer,
                                             gint length,
                                             gpointer user_data);

Callback for gnet_conn_new(). When g_conn_connect() completes, the callback is called with status CONNECT. If the connection closes during a read, the callback is called with status CLOSE (and a NULL buffer). If gnet_conn_read() or another read function has data available, the callback is called with status READ and the buffer is set. If gnet_conn_read() was called with a NULL buffer, that buffer was allocated by GNet but is callee owned. If gnet_conn_read() was called with a non-NULL buffer, the buffer was allocated by the gnet_conn_read() caller (so is GConnFunc callee owned). The callee should return TRUE if they want to continue reading data. If gnet_conn_write() completes, the callback is called with status WRITE and the buffer is set the the buffer passed to gnet_conn_write(). If the gnet_conn_timeout() timer expires, the callback is called with status TIMEOUT. If an error ever occurs, the callback is called with status ERROR.

`conn` :	Connection
`status` :	Connection status
`buffer` :	Buffer (if a read or write)
`length` :	Length of the buffer
`user_data` :	User data specified in gnet_conn_new()
Returns :	Callee should return TRUE if the status is READ and they want to continue reading data. FALSE otherwise.

gnet_conn_new ()

GConn*      gnet_conn_new                   (const gchar *hostname,
                                             gint port,
                                             GConnFunc func,
                                             gpointer user_data);

Create a connection object representing a connection to a host. The actual connection is not made until gnet_conn_connect() is called. The callback is called when events occur. The events are connect, read, write, error, and timeout. These only occur if the appropriate function is called first. For example, use gnet_conn_read() to have the callback called when data is read.

`hostname` :	Hostname of host
`port` :	Port of host
`func` :	Function to call on connection, I/O, or error
`user_data` :	Data to pass to func
Returns :	A GConn.

gnet_conn_new_inetaddr ()

GConn*      gnet_conn_new_inetaddr          (const GInetAddr *inetaddr,
                                             GConnFunc func,
                                             gpointer user_data);

Create a connection object representing a connection to a host. This function is similar to gnet_conn_new() but has different arguments.

`inetaddr` :	address of host
`func` :	Function to call on connection, I/O, or error
`user_data` :	Data to pass to func
Returns :	A GConn.

gnet_conn_delete ()

void        gnet_conn_delete                (GConn *conn,
                                             gboolean delete_buffers);

Delete the connection. If delete_buffers is set, any write buffers are deleted.

`conn` :	Connection to delete
`delete_buffers` :	True if write buffers should be deleted.

gnet_conn_ref ()

void        gnet_conn_ref                   (GConn *conn);

Increment the reference counter of the GConn.

conn : GConn to reference

gnet_conn_unref ()

void        gnet_conn_unref                 (GConn *conn,
                                             gboolean delete_buffers);

Remove a reference from the GConn. When reference count reaches 0, the connection is deleted.

`conn` :	GConn to unreference
`delete_buffers` :

gnet_conn_connect ()

void        gnet_conn_connect               (GConn *conn,
                                             guint timeout);

Establish the connection. If the connection is pending or already established, this function does nothing. The callback is called when the connection is established or an error occurs. THE TIMEOUT IS NOT CURRENTLY USED (FIX).

`conn` :	Conn to connect to
`timeout` :	Timeout for connection.

gnet_conn_disconnect ()

void        gnet_conn_disconnect            (GConn *conn,
                                             gboolean delete_buffers);

End the connection. The connection can later be reestablished by calling gnet_conn_connect() again. If there the connection was not establish, this function does nothing. If delete_buffers is set, any write buffers are deleted.

`conn` :	Conn to disconnect
`delete_buffers` :	True if write buffers should be deleted.

gnet_conn_is_connected ()

gboolean    gnet_conn_is_connected          (const GConn *conn);

Check if the connection is established.

`conn` :	Connection to check
Returns :	TRUE if the connection is established, FALSE otherwise.

gnet_conn_read ()

void        gnet_conn_read                  (GConn *conn,
                                             gchar *buffer,
                                             guint length,
                                             guint timeout,
                                             gboolean read_one_byte_at_a_time,
                                             GNetIOChannelReadAsyncCheckFunc check_func,
                                             gpointer check_user_data);

Set up an asynchronous read from the connection to the buffer. This is a wrapper around gnet_io_channel_read_async(), which reads data until the check function stops it. The callback for this GConn is called when the read is complete or there is an error.

`conn` :	Connection to read from
`buffer` :	Buffer to read to (NULL if to be allocated)
`length` :	Length of the buffer (maximum size if buffer is to be allocated)
`timeout` :	Timeout for read (0 if no timeout)
`read_one_byte_at_a_time` :	TRUE if bytes should be read one-at-a-time
`check_func` :	Function to check if read is complete
`check_user_data` :	User data for check_func

gnet_conn_readany ()

void        gnet_conn_readany               (GConn *conn,
                                             gchar *buffer,
                                             guint length,
                                             guint timeout);

Set up an asynchronous read from the connection to the buffer. This is a wrapper around gnet_io_channel_readany(), which will read any amount of data.

`conn` :	Connection to read from
`buffer` :	Buffer to read to (NULL if to be allocated)
`length` :	Length of the buffer (maximum size if buffer is to be allocated)
`timeout` :	Timeout for read (0 if not timeout)

gnet_conn_readline ()

void        gnet_conn_readline              (GConn *conn,
                                             gchar *buffer,
                                             guint length,
                                             guint timeout);

Set up an asynchronous read from the connection to the buffer. This is a wrapper around gnet_io_channel_readline(), which will read data until a newline.

`conn` :	Connection to read from
`buffer` :	Buffer to read to (NULL if to be allocated)
`length` :	Length of the buffer (maximum size if buffer is to be allocated)
`timeout` :	Timeout for read (0 if not timeout)

gnet_conn_write ()

void        gnet_conn_write                 (GConn *conn,
                                             gchar *buffer,
                                             gint length,
                                             guint timeout);

Set up an asynchronous write to the connection from the buffer. This is a wrapper around gnet_io_channel_write_async(). This function may be called again before another asynchronous write completes.

`conn` :	Connection to write to
`buffer` :	Buffer to write
`length` :	Length of buffer
`timeout` :	Timeout for write (0 if no timeout)

gnet_conn_timeout ()

void        gnet_conn_timeout               (GConn *conn,
                                             guint timeout);

Set a timeout on the connection. When the time expires, the GConn's callback is called. If there already is a timeout, the old timeout is canceled.

`conn` :	Connection to set timeout on
`timeout` :	Timeout (in milliseconds)