|  |  |  | GNet Network Library Reference Manual |  | 
|---|---|---|---|---|
#include <gnet.h>
                    GTcpSocket;
typedef             GTcpSocketConnectAsyncID;
enum                GTcpSocketConnectAsyncStatus;
void                (*GTcpSocketConnectAsyncFunc)       (GTcpSocket *socket,
                                                         GTcpSocketConnectAsyncStatus status,
                                                         gpointer data);
typedef             GTcpSocketNewAsyncID;
void                (*GTcpSocketNewAsyncFunc)           (GTcpSocket *socket,
                                                         gpointer data);
GTcpSocket*         gnet_tcp_socket_connect             (const gchar *hostname,
                                                         gint port);
GTcpSocketConnectAsyncID gnet_tcp_socket_connect_async  (const gchar *hostname,
                                                         gint port,
                                                         GTcpSocketConnectAsyncFunc func,
                                                         gpointer data);
GTcpSocketConnectAsyncID gnet_tcp_socket_connect_async_full
                                                        (const gchar *hostname,
                                                         gint port,
                                                         GTcpSocketConnectAsyncFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify,
                                                         GMainContext *context,
                                                         gint priority);
void                gnet_tcp_socket_connect_async_cancel
                                                        (GTcpSocketConnectAsyncID id);
GTcpSocket*         gnet_tcp_socket_new                 (const GInetAddr *addr);
GTcpSocketNewAsyncID gnet_tcp_socket_new_async          (const GInetAddr *addr,
                                                         GTcpSocketNewAsyncFunc func,
                                                         gpointer data);
GTcpSocketNewAsyncID gnet_tcp_socket_new_async_full     (const GInetAddr *addr,
                                                         GTcpSocketNewAsyncFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify,
                                                         GMainContext *context,
                                                         gint priority);
void                gnet_tcp_socket_new_async_cancel    (GTcpSocketNewAsyncID id);
void                gnet_tcp_socket_delete              (GTcpSocket *socket);
void                gnet_tcp_socket_ref                 (GTcpSocket *socket);
void                gnet_tcp_socket_unref               (GTcpSocket *socket);
GIOChannel*         gnet_tcp_socket_get_io_channel      (GTcpSocket *socket);
GInetAddr*          gnet_tcp_socket_get_remote_inetaddr (const GTcpSocket *socket);
GInetAddr*          gnet_tcp_socket_get_local_inetaddr  (const GTcpSocket *socket);
gint                gnet_tcp_socket_get_port            (const GTcpSocket *socket);
enum                GNetTOS;
void                gnet_tcp_socket_set_tos             (GTcpSocket *socket,
                                                         GNetTOS tos);
GTcpSocket*         gnet_tcp_socket_server_new          (void);
GTcpSocket*         gnet_tcp_socket_server_new_with_port
                                                        (gint port);
GTcpSocket*         gnet_tcp_socket_server_new_full     (const GInetAddr *iface,
                                                         gint port);
GTcpSocket*         gnet_tcp_socket_server_accept       (GTcpSocket *socket);
GTcpSocket*         gnet_tcp_socket_server_accept_nonblock
                                                        (GTcpSocket *socket);
void                (*GTcpSocketAcceptFunc)             (GTcpSocket *server,
                                                         GTcpSocket *client,
                                                         gpointer data);
void                gnet_tcp_socket_server_accept_async (GTcpSocket *socket,
                                                         GTcpSocketAcceptFunc accept_func,
                                                         gpointer user_data);
void                gnet_tcp_socket_server_accept_async_cancel
                                                        (GTcpSocket *socket);
GTcpSocket*         gnet_tcp_socket_new_direct          (const GInetAddr *addr);
GTcpSocketNewAsyncID gnet_tcp_socket_new_async_direct   (const GInetAddr *addr,
                                                         GTcpSocketNewAsyncFunc func,
                                                         gpointer data);
GTcpSocketNewAsyncID gnet_tcp_socket_new_async_direct_full
                                                        (const GInetAddr *addr,
                                                         GTcpSocketNewAsyncFunc func,
                                                         gpointer data,
                                                         GDestroyNotify notify,
                                                         GMainContext *context,
                                                         gint priority);
TCP is an internet protocol that transfers data reliably and in-order. This module provides support for TCP sockets.
To create a GTcpSocket and connect to a host, call
gnet_tcp_socket_new().  This function will block.  The asynchronous
version is gnet_tcp_socket_new_async().
Each TCP socket has a GIOChannel which can be used to read and write
from the socket.  A watch can be set on the GIOChannel by calling
g_io_add_watch() (a GLib function).
To create a TCP server, call gnet_tcp_socket_server_new().  The socket
will be bound to all interfaces.  To bind to a specific interface,
call gnet_tcp_socket_server_new_interface().  To accept a new
connection, call gnet_tcp_socket_server_accept().  This function
returns a GTcpSocket representing the client connection.  This
function can block.  To prevent blocking, call either
gnet_tcp_socket_server_accept_nonblock() or
gnet_tcp_socket_server_accept_async().  The former returns NULL
immediately if there is no new connection.  The latter calls a
callback whenever there is a new connection.  We recommend this
function.
This module will use SOCKS if enabled.
typedef struct _GTcpSocket GTcpSocket;
A GTcpSocket structure represents a TCP socket. The implementation is hidden.
typedef struct _GTcpSocketConnectState * GTcpSocketConnectAsyncID;
ID of an asynchronous connection started with
 gnet_tcp_socket_connect_async().  The connection can be canceled
 by calling gnet_tcp_socket_connect_async_cancel() with the ID.
typedef enum {
  GTCP_SOCKET_CONNECT_ASYNC_STATUS_OK,
  GTCP_SOCKET_CONNECT_ASYNC_STATUS_INETADDR_ERROR,
  GTCP_SOCKET_CONNECT_ASYNC_STATUS_TCP_ERROR
} GTcpSocketConnectAsyncStatus;
Status for connecting via gnet_tcp_socket_connect_async(), passed
 by GTcpSocketConnectAsyncFunc.  More errors may be added in the
 future, so it's best to compare against
 GTCP_SOCKET_CONNECT_ASYNC_STATUS_OK.
void (*GTcpSocketConnectAsyncFunc) (GTcpSocket *socket, GTcpSocketConnectAsyncStatus status, gpointer data);
Callback for gnet_tcp_socket_connect_async().
| socket: | TcpSocket that was connecting (callee owned) | 
| status: | Status of the connection | 
| data: | User data | 
typedef struct _GTcpSocketAsyncState * GTcpSocketNewAsyncID;
ID of an asynchronous tcp socket creation started with
 gnet_tcp_socket_new_async().  The creation can be canceled by
 calling gnet_tcp_socket_new_async_cancel() with the ID.
void (*GTcpSocketNewAsyncFunc) (GTcpSocket *socket, gpointer data);
Callback for gnet_tcp_socket_new_async().  The socket will be
 NULL if the connection failed.
| socket: | Socket that was connecting | 
| data: | User data | 
GTcpSocket* gnet_tcp_socket_connect (const gchar *hostname, gint port);
Creates a GTcpSocket and connects to hostname:port.  This
 function blocks (while gnet_tcp_socket_connect_async() does not).
 To get the GInetAddr of the GTcpSocket, call
 gnet_tcp_socket_get_remote_inetaddr().
| hostname: | host name | 
| port: | port | 
| Returns : | a new GTcpSocket; NULL on error. | 
GTcpSocketConnectAsyncID gnet_tcp_socket_connect_async (const gchar *hostname, gint port, GTcpSocketConnectAsyncFunc func, gpointer data);
Asynchronously creates a GTcpSocket and connects to
 hostname:port.  The callback is called when the connection is
 made or an error occurs.  The callback will not be called during
 the call to this function.
| hostname: | host name | 
| port: | port | 
| func: | callback function | 
| data: | data to pass to funcon callback | 
| Returns : | the ID of the connection; NULL on failure.  The ID can be
 used with gnet_tcp_socket_connect_async_cancel()to cancel the
 connection. | 
GTcpSocketConnectAsyncID gnet_tcp_socket_connect_async_full (const gchar *hostname, gint port, GTcpSocketConnectAsyncFunc func, gpointer data, GDestroyNotify notify, GMainContext *context, gint priority);
Asynchronously creates a GTcpSocket and connects to
 hostname:port.  The callback is called when the connection is
 made or an error occurs.  The callback will not be called during
 the call to this function.
| hostname: | host name | 
| port: | port | 
| func: | callback function | 
| data: | data to pass to funcon callback | 
| notify: | function to call to free data, or NULL | 
| context: | the GMainContext to use for notifications, or NULL for the default GLib main context. If in doubt, pass NULL. | 
| priority: | the priority with which to schedule notifications in the main context, e.g. G_PRIORITY_DEFAULT or G_PRIORITY_HIGH. | 
| Returns : | the ID of the connection; NULL on failure.  The ID can be
 used with gnet_tcp_socket_connect_async_cancel()to cancel the
 connection. | 
Since 2.0.8
void                gnet_tcp_socket_connect_async_cancel
                                                        (GTcpSocketConnectAsyncID id);
Cancels an asynchronous connection that was started with
 gnet_tcp_socket_connect_async().
| id: | ID of the connection | 
GTcpSocket* gnet_tcp_socket_new (const GInetAddr *addr);
Creates a GTcpSocket and connects to addr.  This function
 blocks.  SOCKS is used if SOCKS is enabled.
| addr: | address | 
| Returns : | a new GTcpSocket; NULL on error. | 
GTcpSocketNewAsyncID gnet_tcp_socket_new_async (const GInetAddr *addr, GTcpSocketNewAsyncFunc func, gpointer data);
Asynchronously creates a GTcpSocket and connects to addr.  The
 callback is called once the connection is made or an error occurs.
 The callback will not be called during the call to this function.
SOCKS is used if SOCKS is enabled. The SOCKS negotiation will block.
| addr: | address | 
| func: | callback function | 
| data: | data to pass to funcon callback | 
| Returns : | the ID of the connection; NULL on failure.  The ID can be
 used with gnet_tcp_socket_new_async_cancel()to cancel the
 connection. | 
GTcpSocketNewAsyncID gnet_tcp_socket_new_async_full (const GInetAddr *addr, GTcpSocketNewAsyncFunc func, gpointer data, GDestroyNotify notify, GMainContext *context, gint priority);
Asynchronously creates a GTcpSocket and connects to addr.  The
 callback is called once the connection is made or an error occurs.
 The callback will not be called during the call to this function.
SOCKS is used if SOCKS is enabled. The SOCKS negotiation will block.
| addr: | address | 
| func: | callback function | 
| data: | data to pass to funcon callback | 
| notify: | function to call to free data, or NULL | 
| context: | the GMainContext to use for notifications, or NULL for the default GLib main context. If in doubt, pass NULL. | 
| priority: | the priority with which to schedule notifications in the main context, e.g. G_PRIORITY_DEFAULT or G_PRIORITY_HIGH. | 
| Returns : | the ID of the connection; NULL on failure.  The ID can be
 used with gnet_tcp_socket_new_async_cancel()to cancel the
 connection. | 
Since 2.0.8
void gnet_tcp_socket_new_async_cancel (GTcpSocketNewAsyncID id);
Cancels an asynchronous GTcpSocket creation that was started with
 gnet_tcp_socket_new_async().
| id: | ID of the connection | 
void gnet_tcp_socket_delete (GTcpSocket *socket);
Deletes a GTcpSocket.
| socket: | a GTcpSocket | 
void gnet_tcp_socket_ref (GTcpSocket *socket);
Adds a reference to a GTcpSocket.
| socket: | a GTcpSocket | 
void gnet_tcp_socket_unref (GTcpSocket *socket);
Removes a reference from a GTcpSocket. A GTcpSocket is deleted when the reference count reaches 0.
| socket: | a GTcpSocket to unreference | 
GIOChannel* gnet_tcp_socket_get_io_channel (GTcpSocket *socket);
Gets the GIOChannel of a GTcpSocket.
For a client socket, the GIOChannel represents the data stream. Use it like you would any other GIOChannel.
 For a server socket however, the GIOChannel represents the
 listening socket.  When it's readable, there's a connection
 waiting to be accepted.  However, using
 gnet_tcp_socket_server_accept_async() is more elegant than
 watching the GIOChannel.
Every GTcpSocket has one and only one GIOChannel. If you ref the channel, then you must unref it eventually. Do not close the channel. The channel is closed by GNet when the socket is deleted.
| socket: | a GTcpSocket | 
| Returns : | a GIOChannel. | 
GInetAddr* gnet_tcp_socket_get_remote_inetaddr (const GTcpSocket *socket);
Gets the address of the remote host from a GTcpSocket. This function does not work on server sockets.
| socket: | a GTcpSocket | 
| Returns : | a GInetAddr. | 
GInetAddr* gnet_tcp_socket_get_local_inetaddr (const GTcpSocket *socket);
Gets the local host's address from a GTcpSocket.
| socket: | a GTcpSocket | 
| Returns : | a GInetAddr, or NULL on error.  Unref with gnet_inetaddr_unref()when no longer needed. | 
gint gnet_tcp_socket_get_port (const GTcpSocket *socket);
Gets the port a server GTcpSocket is bound to.
| socket: | a GTcpSocket | 
| Returns : | the port number. | 
typedef enum
{
  GNET_TOS_NONE,
  GNET_TOS_LOWDELAY,
  GNET_TOS_THROUGHPUT,
  GNET_TOS_RELIABILITY,
  GNET_TOS_LOWCOST
} GNetTOS;
Type-of-service.
void gnet_tcp_socket_set_tos (GTcpSocket *socket, GNetTOS tos);
Sets the type-of-service (TOS) of the socket. TOS theoretically controls the connection's quality of service, but most routers ignore it. Some systems don't even support this function. The function does nothing if the operating system does not support it.
| socket: | a GTcpSocket | 
| tos: | type of service | 
GTcpSocket* gnet_tcp_socket_server_new (void);
Creates a new GTcpSocket bound to all interfaces and an arbitrary port. SOCKS is used if SOCKS is enabled.
| Returns : | a new GTcpSocket; NULL on error. | 
GTcpSocket* gnet_tcp_socket_server_new_with_port (gint port);
Creates a new GTcpSocket bound to all interfaces and port port.
 If port is 0, an arbitrary port will be used.  SOCKS is used if
 SOCKS is enabled.
| port: | port to bind to (0 for an arbitrary port) | 
| Returns : | a new GTcpSocket; NULL on error. | 
GTcpSocket* gnet_tcp_socket_server_new_full (const GInetAddr *iface, gint port);
Creates and new GTcpSocket bound to interface iface and port
 port.  If iface is NULL, the socket is bound to all interfaces.
 If port is 0, the socket is bound to an arbitrary port.  SOCKS is
 used if SOCKS is enabled and the interface is NULL.
| iface: | Interface to bind to (NULL for all interfaces) | 
| port: | Port to bind to (0 for an arbitrary port) | 
| Returns : | a new GTcpSocket; NULL on error. | 
GTcpSocket* gnet_tcp_socket_server_accept (GTcpSocket *socket);
Accepts a connection from a GTcpSocket.  The socket must have
 been created using gnet_tcp_socket_server_new() (or equivalent).
 Even if the socket's GIOChannel is readable, the function may
 still block.
| socket: | a GTcpSocket | 
| Returns : | a new GTcpSocket representing a new connection; NULL on error. | 
GTcpSocket* gnet_tcp_socket_server_accept_nonblock (GTcpSocket *socket);
Accepts a connection from a GTcpSocket without blocking.  The
 socket must have been created using gnet_tcp_socket_server_new()
 (or equivalent).
Note that if the socket's GIOChannel is readable, then there is PROBABLY a new connection. It is possible for the connection to close by the time this function is called, so it may return NULL.
| socket: | a GTcpSocket | 
| Returns : | a new GTcpSocket representing a new connection; NULL otherwise. | 
void (*GTcpSocketAcceptFunc) (GTcpSocket *server, GTcpSocket *client, gpointer data);
Callback for gnet_tcp_socket_server_accept_async().  The socket
  had an irrecoverable error if client_socket is NULL.
| server: | Server socket | 
| client: | Client socket | 
| data: | User data | 
void gnet_tcp_socket_server_accept_async (GTcpSocket *socket, GTcpSocketAcceptFunc accept_func, gpointer user_data);
Asynchronously accepts a connection from a GTcpSocket.  The
 callback is called when a new client has connected or an error
 occurs.  The socket must have been created using
 gnet_tcp_socket_server_new() (or equivalent).
| socket: | a GTcpSocket | 
| accept_func: | callback function. | 
| user_data: | data to pass to funcon callback | 
void                gnet_tcp_socket_server_accept_async_cancel
                                                        (GTcpSocket *socket);
Stops asynchronously accepting connections for a GTcpSocket. The socket is not closed.
| socket: | a GTcpSocket | 
GTcpSocket* gnet_tcp_socket_new_direct (const GInetAddr *addr);
Creates a GTcpSocket and connects to addr without using SOCKS.
 This function blocks.  Most users should use
 gnet_tcp_socket_new().
| addr: | address | 
| Returns : | a new GTcpSocket; NULL on error. | 
GTcpSocketNewAsyncID gnet_tcp_socket_new_async_direct (const GInetAddr *addr, GTcpSocketNewAsyncFunc func, gpointer data);
Asynchronously creates a GTcpSocket and connects to addr without
 using SOCKS.  Most users should use gnet_tcp_socket_new_async()
 instead.  The callback is called once the connection is made or an
 error occurs.  The callback will not be called during the call to
 this function.
| addr: | address | 
| func: | callback function | 
| data: | data to pass to funcon callback | 
| Returns : | the ID of the connection; NULL on failure.  The ID can be
 used with gnet_tcp_socket_new_async_cancel()to cancel the
 connection. | 
GTcpSocketNewAsyncID gnet_tcp_socket_new_async_direct_full (const GInetAddr *addr, GTcpSocketNewAsyncFunc func, gpointer data, GDestroyNotify notify, GMainContext *context, gint priority);
Asynchronously creates a GTcpSocket and connects to addr without
 using SOCKS.  Most users should use gnet_tcp_socket_new_async()
 instead.  The callback is called once the connection is made or an
 error occurs.  The callback will not be called during the call to
 this function.
| addr: | address | 
| func: | callback function | 
| data: | data to pass to funcon callback | 
| notify: | function to call to free data, or NULL | 
| context: | the GMainContext to use for notifications, or NULL for the default GLib main context. If in doubt, pass NULL. | 
| priority: | the priority with which to schedule notifications in the main context, e.g. G_PRIORITY_DEFAULT or G_PRIORITY_HIGH. | 
| Returns : | the ID of the connection; NULL on failure.  The ID can be
 used with gnet_tcp_socket_new_async_cancel()to cancel the
 connection. | 
Since 2.0.8