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

# tcp

## Name

tcp --

## Synopsis

    struct      GTcpSocket;
    typedef     GTcpSocketConnectAsyncID;
    enum        GTcpSocketConnectAsyncStatus;
    void        (*GTcpSocketConnectAsyncFunc)   (GTcpSocket *socket,
                                                 GInetAddr *ia,
                                                 GTcpSocketConnectAsyncStatus status,
                                                 gpointer data);
    typedef     GTcpSocketNewAsyncID;
    enum        GTcpSocketNewAsyncStatus;
    void        (*GTcpSocketNewAsyncFunc)       (GTcpSocket *socket,
                                                 GTcpSocketNewAsyncStatus status,
                                                 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 async_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 async_id);
    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);
    enum        GNetTOS;
    void        gnet_tcp_socket_set_tos         (GTcpSocket *socket,
                                                 GNetTOS tos);
    GTcpSocket* gnet_tcp_socket_server_new      (gint port);
    GTcpSocket* gnet_tcp_socket_server_new_interface
                                                (const GInetAddr *iface);
    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

## Details

### struct GTcpSocket

    struct GTcpSocket;

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

### GTcpSocketConnectAsyncFunc ()

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

Callback for gnet_tcp_socket_connect_async().

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

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

### enum GTcpSocketNewAsyncStatus

    typedef enum {
      GTCP_SOCKET_NEW_ASYNC_STATUS_OK,
      GTCP_SOCKET_NEW_ASYNC_STATUS_ERROR
    } GTcpSocketNewAsyncStatus;

### GTcpSocketNewAsyncFunc ()

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

Callback for gnet_tcp_socket_new_async().

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

### gnet_tcp_socket_connect ()

    GTcpSocket* gnet_tcp_socket_connect         (const 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` : |
`port` : |
Returns : |

### gnet_tcp_socket_connect_async ()

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

A quick and easy asynchronous 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 will call the callback if there is a failure. It will never call the callback before the function returns.

`hostname` : |
`port` : |
`func` : |
`data` : |
Returns : |

### gnet_tcp_socket_connect_async_cancel ()

    void        gnet_tcp_socket_connect_async_cancel
                                                (GTcpSocketConnectAsyncID async_id);

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

`async_id` : |

### 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. SOCKS is used if SOCKS is enabled.

`addr` : |
Returns : |

### 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. SOCKS is used if SOCKS is enabled. The SOCKS negotiation will block.

`addr` : |
`func` : |
`data` : |
Returns : |

### gnet_tcp_socket_new_async_cancel ()

    void        gnet_tcp_socket_new_async_cancel
                                                (GTcpSocketNewAsyncID async_id);

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

`async_id` : |

### gnet_tcp_socket_delete ()

    void        gnet_tcp_socket_delete          (GTcpSocket *s);

Close and delete a GTcpSocket.

`s` : |

### gnet_tcp_socket_ref ()

    void        gnet_tcp_socket_ref             (GTcpSocket *s);

Increment the reference counter of the GTcpSocket.

`s` : |

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

### 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` : |
Returns : |

### 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` : |
Returns : |

### gnet_tcp_socket_get_port ()

    gint        gnet_tcp_socket_get_port        (const GTcpSocket *socket);

Get the port number the socket is bound to.

`socket` : |
Returns : |

### enum GNetTOS

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

    } GNetTOS;

### gnet_tcp_socket_set_tos ()

    void        gnet_tcp_socket_set_tos         (GTcpSocket *socket,
                                                 GNetTOS tos);

Set the type-of-service of the socket. Usually, routers don't honor this. Some systems don't support this function. If the operating system does not support it, the function does nothing.

`socket` : |
`tos` : |

### gnet_tcp_socket_server_new ()

    GTcpSocket* gnet_tcp_socket_server_new      (gint port);

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

`port` : |
Returns : |

### gnet_tcp_socket_server_new_interface ()

    GTcpSocket* gnet_tcp_socket_server_new_interface
                                                (const GInetAddr *iface);

Create and open a new GTcpSocket bound to the specified interface. Use this sort of socket when your are a server and have a specific address the server must be bound to. If the port number of the interface address is 0, the OS will use the interface specified but choose the port itself. If the interface address is NULL, the OS will choose both the interface and port. If the interface address was created by gnet_inetaddr_new_any(), the OS will use all interfaces. If the port number is also set, it will use that port number. SOCKS is used if SOCKS is enabled and the interface is NULL.

`iface` : |
Returns : |

### 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` : |
Returns : |

### 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 socket's 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` : |
Returns : |

### 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` : |
`client` : |
`data` : |

### gnet_tcp_socket_server_accept_async ()

    void        gnet_tcp_socket_server_accept_async
                                                (GTcpSocket *socket,
                                                 GTcpSocketAcceptFunc accept_func,
                                                 gpointer user_data);

Accept a connection from the socket asynchronously. The callback is called when a client has connection or the socket has an error.

`socket` : |
`accept_func` : |
`user_data` : |

### gnet_tcp_socket_server_accept_async_cancel ()

    void        gnet_tcp_socket_server_accept_async_cancel
                                                (GTcpSocket *socket);

Stops accepting connections asynchronously from the socket. This does not close the socket.

`socket` : |

### gnet_tcp_socket_new_direct ()

    GTcpSocket* gnet_tcp_socket_new_direct      (const GInetAddr *addr);

Connect directly to a specified address and do not use SOCKS even if SOCKS is enabled. Most users should use gnet_tcp_socket_new(). This is used internally to implement SOCKS.

`addr` : |
Returns : |

### gnet_tcp_socket_new_async_direct ()

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

Connect directly to a specified address asynchronously and do not use SOCKS even if SOCKS is enabled. Most users should use gnet_tcp_socket_new_async(). This is used internally to implement SOCKS.

`addr` : |
`func` : |
`data` : |
Returns : |

<<< Previous Page | Home | Up | Next Page >>>
inetaddr | unix