![]() | ![]() | ![]() | GNet Network Library Reference Manual | ![]() |
---|
ConnConn — TCP connection object |
GConn; GConnEvent; enum GConnEventType; void (*GConnFunc) (GConn *conn, GConnEvent *event, gpointer user_data); GConn* gnet_conn_new (const gchar *hostname, gint port, GConnFunc func, gpointer user_data); GConn* gnet_conn_new_inetaddr (const GInetAddr *inetaddr, GConnFunc func, gpointer user_data); GConn* gnet_conn_new_socket (GTcpSocket *socket, GConnFunc func, gpointer user_data); void gnet_conn_delete (GConn *conn); void gnet_conn_ref (GConn *conn); void gnet_conn_unref (GConn *conn); void gnet_conn_set_callback (GConn *conn, GConnFunc func, gpointer user_data); void gnet_conn_connect (GConn *conn); void gnet_conn_disconnect (GConn *conn); gboolean gnet_conn_is_connected (const GConn *conn); void gnet_conn_read (GConn *conn); void gnet_conn_readn (GConn *conn, gint length); void gnet_conn_readline (GConn *conn); void gnet_conn_write (GConn *conn, gchar *buffer, gint length); void gnet_conn_set_watch_error (GConn *conn, gboolean enable); void gnet_conn_set_watch_readable (GConn *conn, gboolean enable); void gnet_conn_set_watch_writable (GConn *conn, gboolean enable); void gnet_conn_timeout (GConn *conn, guint timeout);
A GConn represents a TCP connection. A GConn is created directly by calling gnet_conn_new() or gnet_conn_new_inetaddr(). To connect to the host, call gnet_conn_connect() and to disconnect call gnet_conn_disconnect(). GConn's are also created by a GServer when a client connects. Call gnet_conn_set_callback() to set the GConn callback after it is created by the GServer. To disconnect and delete the GConn, call gnet_conn_delete().
The iochannel field and GIOChannel functions can be used to read from or write to the socket. GIOChannel functions block. To make an asynchronous read call gnet_conn_read() and to make an asynchronous write call gnet_conn_write(). The callback is called whenever a read or write completes.
Use gnet_conn_set_watch_error() to get an event if an error occurs. Use gnet_conn_set_watch_readable() and gnet_conn_set_watch_writable() to get events when the connection is readable or writable. These can be used to implement custom I/O handling. For example, consider writing from a mmap()'ed file. gnet_conn_write() will allocate memory for a buffer and copy part of the file into the buffer. To avoid the copy, use gnet_conn_set_watch_writable() to catch the writable event and then write directly from memory to the socket.
gnet_conn_timeout() sets a timeout on the GConn. The GNET_CONN_TIMEOUT event occurs when the timer expires. For example, the timer may be set before connecting to the host. If the connection is made, the GNET_CONN_CONNECT event occurs. The timer can then be reset by setting the timeout to 0. Otherwise, the GNET_CONN_TIMEOUT event will eventually occur.
typedef struct { /* Public */ gchar* hostname; gint port; GIOChannel* iochannel; GTcpSocket* socket; GInetAddr* inetaddr; /* Private */ guint ref_count; guint ref_count_internal; /* Connect */ GTcpSocketConnectAsyncID connect_id; GTcpSocketNewAsyncID new_id; /* Write */ GList* write_queue; guint bytes_written; /* Read */ gchar* buffer; guint length; guint bytes_read; gboolean read_eof; GList* read_queue; guint process_buffer_timeout; /* Readable/writable */ gboolean watch_readable; gboolean watch_writable; /* IO watch */ guint watch_flags; guint watch; /* Timer */ guint timer; /* User data */ GConnFunc func; gpointer user_data; } GConn;
TCP Connection. Some of the fields are public, but do not set these fields.
gchar *hostname; | host name |
gint port; | port |
GIOChannel *iochannel; | IO channel |
GTcpSocket *socket; | socket |
GInetAddr *inetaddr; | address |
guint ref_count; | [private] |
guint ref_count_internal; | [private] |
GTcpSocketConnectAsyncID connect_id; | [private] |
GTcpSocketNewAsyncID new_id; | [private] |
GList *write_queue; | [private] |
guint bytes_written; | [private] |
gchar *buffer; | [private] |
guint length; | [private] |
guint bytes_read; | [private] |
gboolean read_eof; | [private] |
GList *read_queue; | [private] |
guint process_buffer_timeout; | [private] |
gboolean watch_readable; | [private] |
gboolean watch_writable; | [private] |
guint watch_flags; | [private] |
guint watch; | [private] |
guint timer; | [private] |
GConnFunc func; | [private] |
gpointer user_data; | [private] |
typedef struct { GConnEventType type; gchar* buffer; gint length; } GConnEvent;
GConn Event. buffer and length are set only on GNET_CONN_READ events. The buffer is caller-owned.
GConnEventType type; | event type |
gchar *buffer; | buffer |
gint length; | buffer length |
typedef enum { GNET_CONN_ERROR, GNET_CONN_CONNECT, GNET_CONN_CLOSE, GNET_CONN_TIMEOUT, GNET_CONN_READ, GNET_CONN_WRITE, GNET_CONN_READABLE, GNET_CONN_WRITABLE } GConnEventType;
Event type. Used by GConnEvent.
GNET_CONN_ERROR | Connection error |
GNET_CONN_CONNECT | Connection complete |
GNET_CONN_CLOSE | Connection closed |
GNET_CONN_TIMEOUT | Timeout |
GNET_CONN_READ | Read complete |
GNET_CONN_WRITE | Write complete |
GNET_CONN_READABLE | Connection is readable |
GNET_CONN_WRITABLE | Connection is writable |
void (*GConnFunc) (GConn *conn, GConnEvent *event, gpointer user_data);
Callback for GConn.
Possible events:
GNET_CONN_ERROR: GConn error. The event occurs if the connection fails somehow. The connection is closed before this event occurs.
GNET_CONN_CONNECT: Completion of gnet_conn_connect().
GNET_CONN_CLOSE: Connection has been closed. The event does not occur as a result of calling gnet_conn_disconnect(), gnet_conn_unref(), or gnet_conn_delete().
GNET_CONN_TIMEOUT: Timer set by gnet_conn_timeout() expires.
GNET_CONN_READ: Data has been read. This event occurs as a result of calling gnet_conn_read(), gnet_conn_readn(), or gnet_conn_readline(). buffer and length are set in the event object. The buffer is caller owned.
GNET_CONN_WRITE: Data has been written. This event occurs as a result of calling gnet_conn_write().
GNET_CONN_READABLE: The connection is readable.
GNET_CONN_WRITABLE: The connection is writable.
conn : | GConn |
event : | event (caller owned) |
user_data : | user data specified in gnet_conn_new() |
GConn* gnet_conn_new (const gchar *hostname, gint port, GConnFunc func, gpointer user_data);
Creates a GConn. A connection is not made until gnet_conn_connect() is called. The callback func is called when events occur.
GConn* gnet_conn_new_inetaddr (const GInetAddr *inetaddr, GConnFunc func, gpointer user_data);
Creates a GConn. A connection is not made until gnet_conn_connect() is called. The callback func is called when events occur.
GConn* gnet_conn_new_socket (GTcpSocket *socket, GConnFunc func, gpointer user_data);
Creates a GConn. The GConn is created from the socket. The socket is callee owned - do not delete it. The callback is called when events occur.
void gnet_conn_unref (GConn *conn);
Removes a reference from a GConn. A GConn is deleted when the reference count reaches 0.
conn : | a GConn |
void gnet_conn_set_callback (GConn *conn, GConnFunc func, gpointer user_data);
Sets the GConnEvent callback for a GConn. The callback func is called when events occur.
void gnet_conn_connect (GConn *conn);
Establishes a 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.
conn : | a GConn |
void gnet_conn_disconnect (GConn *conn);
Closes the connection. The connection can later be reestablished by calling gnet_conn_connect() again. If the connection was not established, this function does nothing.
conn : | a GConn |
gboolean gnet_conn_is_connected (const GConn *conn);
Checks if the connection is established.
conn : | a GConn |
Returns : | TRUE if the connection is established, FALSE otherwise. |
void gnet_conn_read (GConn *conn);
Begins an asynchronous read. The connection callback is called when any data has been read. This function may be called again before the asynchronous read completes.
conn : | a GConn |
void gnet_conn_readn (GConn *conn, gint length);
Begins an asynchronous read of exactly length bytes. The connection callback is called when the data has been read. This function may be called again before the asynchronous read completes.
conn : | a GConn |
length : | Number of bytes to read |
void gnet_conn_readline (GConn *conn);
Begins an asynchronous line read. The connection callback is called when a line has been read. Lines are terminated with \n, \r, \r\n, or \0. The terminator is \0'ed out in the buffer. The terminating \0 is accounted for in the buffer length. This function may be called again before the asynchronous read completes.
conn : | a GConn |
void gnet_conn_write (GConn *conn, gchar *buffer, gint length);
Sets up an asynchronous write to conn from buffer. The buffer is copied, so it may be deleted by the caller. This function can be called again before the asynchronous write completes.
conn : | a GConn |
buffer : | buffer to write from |
length : | length of buffer |
void gnet_conn_set_watch_error (GConn *conn, gboolean enable);
Enables (or disables) the GNET_CONN_ERROR event for a GConn. If enabled, the GNET_CONN_ERROR event occurs when an error occurs. The conn is disconnected before the callback is made.
conn : | a GConn |
enable : | enable the GNET_CONN_READABLE event? |
void gnet_conn_set_watch_readable (GConn *conn, gboolean enable);
Enables (or disables) the GNET_CONN_READABLE event for a GConn. If enabled, the GNET_CONN_READABLE event occurs when data can be read from the socket. Read from the iochannel member of the conn. Do not enable this while using gnet_conn_read(), gnet_conn_readn(), or gnet_conn_readline().
conn : | a GConn |
enable : | enable the GNET_CONN_READABLE event? |
void gnet_conn_set_watch_writable (GConn *conn, gboolean enable);
Enables (or disables) the GNET_CONN_WRITABLE event for a GConn. If enabled, the GNET_CONN_WRITABLE event occurs when data can be written to the socket. Write to the iochannel member of the conn. Do not enable this while using gnet_conn_write().
conn : | a GConn |
enable : | enable the GNET_CONN_WRITABLE event? |
void gnet_conn_timeout (GConn *conn, guint timeout);
Sets a timeout on a GConn. When the timer expires, the GNET_CONN_STATUS_TIMEOUT event occurs. If there already is a timeout set on conn, the old timeout is canceled. Set timeout to 0 to cancel the current timeout.
conn : | a GConn |
timeout : | Timeout (in milliseconds) |
<< GConnHttp | Server >> |