## TCP TCP — TCP socket |

## Synopsis

                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

### GTcpSocket

    typedef struct _GTcpSocket 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.