# TCP

## Name

TCP -- TCP socket

## Synopsis

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

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

### >struct GTcpSocket

    struct GTcpSocket;

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

### >GTcpSocketConnectAsyncID

    typedef gpointer 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 gpointer 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_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_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.

### >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.