![]() | ![]() | ![]() | GNet Network Library Reference Manual | ![]() |
---|
TCPTCP — TCP socket |
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);
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.
typedef struct _GTcpSocket GTcpSocket;
A GTcpSocket structure represents a TCP socket. The implementation is hidden.
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.
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 |
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 |
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.
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 |
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. |
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. |
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 |
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. |
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. |
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 |
void gnet_tcp_socket_delete (GTcpSocket *socket);
Deletes a GTcpSocket.
socket : | a GTcpSocket |
void gnet_tcp_socket_ref (GTcpSocket *socket);
Adds a reference to a GTcpSocket.
socket : | a GTcpSocket |
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 |
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. |
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. |
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. |
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. |
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 |
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 |
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. |
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. |
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. |
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. |
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. |
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 |
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 |
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 |
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. |
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. |
<< InetAddr | UDP >> |