TCP

TCP — TCP socket

Synopsis


#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);

Description

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.

Details

GTcpSocket

typedef struct _GTcpSocket GTcpSocket;

A GTcpSocket structure represents a TCP socket. The implementation is hidden.

GTcpSocketConnectAsyncID

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.

enum GTcpSocketConnectAsyncStatus

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.

GTCP_SOCKET_CONNECT_ASYNC_STATUS_OK Connection succeeded
GTCP_SOCKET_CONNECT_ASYNC_STATUS_INETADDR_ERROR Error, address lookup failed
GTCP_SOCKET_CONNECT_ASYNC_STATUS_TCP_ERROR Error, could not connect

GTcpSocketConnectAsyncFunc ()

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

GTcpSocketNewAsyncID

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.

GTcpSocketNewAsyncFunc ()

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

gnet_tcp_socket_connect ()

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.

gnet_tcp_socket_connect_async ()

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 func on 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.

gnet_tcp_socket_connect_async_full ()

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 func on 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

gnet_tcp_socket_connect_async_cancel ()

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

gnet_tcp_socket_new ()

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.

gnet_tcp_socket_new_async ()

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 func on 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.

gnet_tcp_socket_new_async_full ()

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 func on 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

gnet_tcp_socket_new_async_cancel ()

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

gnet_tcp_socket_delete ()

void                gnet_tcp_socket_delete              (GTcpSocket *socket);

Deletes a GTcpSocket.

socket : a GTcpSocket

gnet_tcp_socket_ref ()

void                gnet_tcp_socket_ref                 (GTcpSocket *socket);

Adds a reference to a GTcpSocket.

socket : a GTcpSocket

gnet_tcp_socket_unref ()

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

gnet_tcp_socket_get_io_channel ()

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.

gnet_tcp_socket_get_remote_inetaddr ()

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.

gnet_tcp_socket_get_local_inetaddr ()

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.

gnet_tcp_socket_get_port ()

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.

enum GNetTOS

typedef enum
{
  GNET_TOS_NONE,
  GNET_TOS_LOWDELAY,
  GNET_TOS_THROUGHPUT,
  GNET_TOS_RELIABILITY,
  GNET_TOS_LOWCOST

} GNetTOS;

Type-of-service.

GNET_TOS_NONE Unspecified
GNET_TOS_LOWDELAY Low delay
GNET_TOS_THROUGHPUT High throughput
GNET_TOS_RELIABILITY High reliability
GNET_TOS_LOWCOST Low cost

gnet_tcp_socket_set_tos ()

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

gnet_tcp_socket_server_new ()

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.

gnet_tcp_socket_server_new_with_port ()

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.

gnet_tcp_socket_server_new_full ()

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.

gnet_tcp_socket_server_accept ()

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.

gnet_tcp_socket_server_accept_nonblock ()

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.

GTcpSocketAcceptFunc ()

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

gnet_tcp_socket_server_accept_async ()

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 func on callback

gnet_tcp_socket_server_accept_async_cancel ()

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

gnet_tcp_socket_new_direct ()

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.

gnet_tcp_socket_new_async_direct ()

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 func on 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.

gnet_tcp_socket_new_async_direct_full ()

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 func on 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