Gnet Network Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# TCP module

## Name

TCP module -- Tcp socket (stream) functions.

## Synopsis

    GTcpSocket* gnet_tcp_socket_connect         (gchar *hostname,
                                                 gint port);
    GTcpSocketConnectAsyncID gnet_tcp_socket_connect_async
                                                (gchar *hostname,
                                                 gint port,
                                                 GTcpSocketConnectAsyncFunc func,
                                                 gpointer data);
    void        gnet_tcp_socket_connect_async_cancel
                                                (GTcpSocketConnectAsyncID id);
    typedef     GTcpSocketConnectAsyncID;
    void        (*GTcpSocketConnectAsyncFunc)   (GTcpSocket *socket,
                                                 GInetAddr *ia,
                                                 GTcpSocketConnectAsyncStatus status,
                                                 gpointer data);
    enum        GTcpSocketConnectAsyncStatus;
    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);
    typedef     GTcpSocketNewAsyncID;
    void        (*GTcpSocketNewAsyncFunc)       (GTcpSocket *socket,
                                                 GTcpSocketNewAsyncStatus status,
                                                 gpointer data);
    enum        GTcpSocketNewAsyncStatus;
    void        gnet_tcp_socket_delete          (GTcpSocket *s);
    void        gnet_tcp_socket_ref             (GTcpSocket *s);
    void        gnet_tcp_socket_unref           (GTcpSocket *s);
    GIOChannel* gnet_tcp_socket_get_iochannel   (GTcpSocket *socket);
    GInetAddr*  gnet_tcp_socket_get_inetaddr    (const GTcpSocket *socket);
    gint        gnet_tcp_socket_get_port        (const GTcpSocket *socket);
    GTcpSocket* gnet_tcp_socket_server_new      (const gint port);
    GTcpSocket* gnet_tcp_socket_server_accept   (GTcpSocket *socket);
    GTcpSocket* gnet_tcp_socket_server_accept_nonblock
                                                (GTcpSocket *socket);

## Description

TcpSocket represents an open TCP (stream) socket. Create a TcpSocket by calling tcp_socket_new or tcp_socket_port_new.

## Details

### gnet_tcp_socket_connect ()

    GTcpSocket* gnet_tcp_socket_connect         (gchar *hostname,
                                                 gint port);

A quick and easy GTcpSocket constructor. This connects to the specified address and port. This function does block (gnet_tcp_socket_connect_async() does not). Use this function when you're a client connecting to a server and you don't mind blocking and don't want to mess with GInetAddr's. You can get the InetAddr of the socket by calling gnet_tcp_socket_get_inetaddr().

`hostname` : | Name of host to connect to
`port` : | Port to connect to
Returns : | A new GTcpSocket, or NULL if there was a failure.

### gnet_tcp_socket_connect_async ()

    GTcpSocketConnectAsyncID gnet_tcp_socket_connect_async
                                                (gchar *hostname,
                                                 gint port,
                                                 GTcpSocketConnectAsyncFunc func,
                                                 gpointer data);

A quick and easy non-blocking GTcpSocket constructor. This connects to the specified address and port and then calls the callback with the data. Use this function when you're a client connecting to a server and you don't want to block or mess with GInetAddr's. It may call the callback before the function returns. It will call the callback if there is a failure.

`hostname` : | Name of host to connect to
`port` : | Port to connect to
`func` : | Callback function
`data` : | User data passed when callback function is called.
Returns : | ID of the connection which can be used with gnet_tcp_socket_connect_async_cancel() to cancel it; NULL on failure.

### gnet_tcp_socket_connect_async_cancel ()

    void        gnet_tcp_socket_connect_async_cancel
                                                (GTcpSocketConnectAsyncID id);

Cancel an asynchronous connection that was started with gnet_tcp_socket_connect_async().

`id` : | ID of the connection.

### GTcpSocketConnectAsyncID

    typedef gpointer GTcpSocketConnectAsyncID;

### GTcpSocketConnectAsyncFunc ()

    void        (*GTcpSocketConnectAsyncFunc)   (GTcpSocket *socket,
                                                 GInetAddr *ia,
                                                 GTcpSocketConnectAsyncStatus status,
                                                 gpointer data);

`socket` : |
`ia` : |
`status` : |
`data` : |

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

### gnet_tcp_socket_new ()

    GTcpSocket* gnet_tcp_socket_new             (const GInetAddr *addr);

Connect to a specified address. Use this sort of socket when you're a client connecting to a server. This function will block to connect.

`addr` : | Address to connect to.
Returns : | a new GTcpSocket, or NULL if there was a failure.

### gnet_tcp_socket_new_async ()

    GTcpSocketNewAsyncID gnet_tcp_socket_new_async
                                                (const GInetAddr *addr,
                                                 GTcpSocketNewAsyncFunc func,
                                                 gpointer data);

Connect to a specifed address asynchronously. When the connection is complete or there is an error, it will call the callback. It may call the callback before the function returns. It will call the callback if there is a failure.

`addr` : | Address to connect to.
`func` : | Callback function.
`data` : | User data passed when callback function is called.
Returns : | ID of the connection which can be used with gnet_tcp_socket_connect_async_cancel() to cancel it; NULL on failure.

### gnet_tcp_socket_new_async_cancel ()

    void        gnet_tcp_socket_new_async_cancel
                                                (GTcpSocketNewAsyncID id);

Cancel an asynchronous connection that was started with gnet_tcp_socket_new_async().

`id` : | ID of the connection.

### GTcpSocketNewAsyncID

    typedef gpointer GTcpSocketNewAsyncID;

### GTcpSocketNewAsyncFunc ()

    void        (*GTcpSocketNewAsyncFunc)       (GTcpSocket *socket,
                                                 GTcpSocketNewAsyncStatus status,
                                                 gpointer data);

`socket` : |
`status` : |
`data` : |

### enum GTcpSocketNewAsyncStatus

    typedef enum {
      GTCP_SOCKET_NEW_ASYNC_STATUS_OK,
      GTCP_SOCKET_NEW_ASYNC_STATUS_ERROR
    } GTcpSocketNewAsyncStatus;

### gnet_tcp_socket_delete ()

    void        gnet_tcp_socket_delete          (GTcpSocket *s);

Close and delete a GTcpSocket.

`s` : | TcpSocket to delete.

### gnet_tcp_socket_ref ()

    void        gnet_tcp_socket_ref             (GTcpSocket *s);

Increment the reference counter of the GTcpSocket.

`s` : | GTcpSocket to reference

### gnet_tcp_socket_unref ()

    void        gnet_tcp_socket_unref           (GTcpSocket *s);

Remove a reference from the GTcpSocket. When reference count reaches 0, the socket is deleted.

`s` : | GTcpSocket to unreference

### gnet_tcp_socket_get_iochannel ()

    GIOChannel* gnet_tcp_socket_get_iochannel   (GTcpSocket *socket);

Get the GIOChannel for the 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 incoming connections. If you can read from it, there's a connection waiting.

There is one channel for every socket. This function refs the channel before returning it. You should unref the channel when you are done with it. However, you should not close the channel - this is done when you delete the socket.

`socket` : | GTcpSocket to get GIOChannel from.
Returns : | A GIOChannel; NULL on failure.

### gnet_tcp_socket_get_inetaddr ()

    GInetAddr*  gnet_tcp_socket_get_inetaddr    (const GTcpSocket *socket);

Get the address of the socket. If the socket is client socket, the address is the address of the remote host it is connected to. If the socket is a server socket, the address is the address of the local host. (Though you should use gnet_inetaddr_gethostaddr() to get the GInetAddr of the local host.)

`socket` : | GTcpSocket to get address of.
Returns : | GInetAddr of socket; NULL on failure.

### gnet_tcp_socket_get_port ()

    gint        gnet_tcp_socket_get_port        (const GTcpSocket *socket);

Get the port number the socket is bound to.

`socket` : | GTcpSocket to get the port number of.
Returns : | Port number of the socket.

### gnet_tcp_socket_server_new ()

    GTcpSocket* gnet_tcp_socket_server_new      (const gint port);

Create and open a new GTcpSocket with the specified port number. Use this sort of socket when your are a server and you know what the port number should be (or pass 0 if you don't care what the port is).

`port` : | Port number for the socket (0 if you don't care).
Returns : | a new GTcpSocket, or NULL if there was a failure.

### gnet_tcp_socket_server_accept ()

    GTcpSocket* gnet_tcp_socket_server_accept   (GTcpSocket *socket);

Accept a connection from the socket. The socket must have been created using gnet_tcp_socket_server_new(). This function will block (use gnet_tcp_socket_server_accept_nonblock() if you don't want to block). If the socket's GIOChannel is readable, it DOES NOT mean that this function will not block.

`socket` : | GTcpSocket to accept connections from.
Returns : | a new GTcpSocket if there is another connect, or NULL if there's an error.

### gnet_tcp_socket_server_accept_nonblock ()

    GTcpSocket* gnet_tcp_socket_server_accept_nonblock
                                                (GTcpSocket *socket);

Accept a connection from the socket without blocking. The socket must have been created using gnet_tcp_socket_server_new(). This function is best used with the sockets GIOChannel. If the channel is readable, then you PROBABLY have a connection. It is possible for the connection to close by the time you call this, so it may return NULL even if the channel was readable.

`socket` : | GTcpSocket to accept connections from.
Returns : | a new GTcpSocket if there is another connect, or NULL otherwise.

<<< Previous Page | Home | Up | Next Page >>>
Multicast module | UDP module