![]() | ![]() | ![]() | GTcpSocket Library Manual | ![]() |
---|
GTcpConnection — The main connection object.
struct GTcpConnection; enum GTcpLookupStatus; enum GTcpConnectionStatus; enum GTcpConnectionStyle; enum GTcpSendStatus; #define GTCP_SOCKET_DEFAULT_BUFFER_SIZE GObject* gtcp_connection_new (const gchar *address, guint port, GTcpConnectionStyle conn_style, gboolean use_ssl); void gtcp_connection_open (GTcpConnection *conn); void gtcp_connection_close (GTcpConnection *conn); GTcpSendStatus gtcp_connection_send (GTcpConnection *conn, gconstpointer data, gssize length); G_CONST_RETURN gchar* gtcp_connection_get_address (GTcpConnection *conn); void gtcp_connection_set_address (GTcpConnection *conn, const gchar *address); guint gtcp_connection_get_port (GTcpConnection *conn); void gtcp_connection_set_port (GTcpConnection *conn, guint port); gboolean gtcp_connection_get_use_ssl (GTcpConnection *conn); gboolean gtcp_connection_set_use_ssl (GTcpConnection *conn, gboolean use_ssl); GTcpConnectionStyle gtcp_connection_get_conn_style (GTcpConnection *conn); void gtcp_connection_set_conn_style (GTcpConnection *conn, GTcpConnectionStyle conn_style); G_CONST_RETURN gchar* gtcp_connection_get_ip_address (GTcpConnection *conn); void gtcp_connection_set_buffer_size (GTcpConnection *conn, gsize buffer_size); gsize gtcp_connection_get_buffer_size (GTcpConnection *conn); gulong gtcp_connection_get_bytes_read (GTcpConnection *conn); gulong gtcp_connection_get_bytes_written (GTcpConnection *conn);
GObject +----GTcpConnection
"address" gchararray : Read / Write / Construct "buffer-size" guint : Read / Write / Construct "bytes-read" gulong : Read "bytes-written" gulong : Read "connection-style" GTcpConnectionStyle : Read / Write / Construct "ip-address" gchararray : Read / Write / Construct "is-server" gboolean : Read / Write / Construct "local-address" gchararray : Read / Write / Construct "local-port" guint : Read / Write / Construct "port" guint : Read / Write / Construct "socket-fd" gint : Write "status" GTcpConnectionStatus : Read / Write / Construct "use-ssl" gboolean : Read / Write / Construct
"closed" void user_function (GTcpConnection *gtcpconnection, gboolean arg1, gpointer user_data); "connect-done" void user_function (GTcpConnection *gtcpconnection, GTcpConnectionStatus arg1, gpointer user_data); "lookup-done" void user_function (GTcpConnection *gtcpconnection, GTcpLookupStatus arg1, gpointer user_data); "recv" void user_function (GTcpConnection *gtcpconnection, gpointer arg1, guint arg2, gpointer user_data); "send" void user_function (GTcpConnection *gtcpconnection, gpointer arg1, guint arg2, gpointer user_data);
The GTcpConnection and associated functions provides the easiest way to create a TCP/IP networking connection. Simply start the Glib main loop, create a new GTcpConnection, connect to the signals, and open it.
struct GTcpConnection;
The GTcpConnection struct contains only read-only fields. They should never be set by an application.
typedef enum /*< prefix=GTCP_LOOKUP > */ { GTCP_LOOKUP_IN_PROGRESS = -1, GTCP_LOOKUP_OK = 0, GTCP_LOOKUP_ERROR_NOT_FOUND, GTCP_LOOKUP_ERROR_NO_RECOVERY, GTCP_LOOKUP_ERROR_TRY_AGAIN, GTCP_LOOKUP_ERROR_IPV4_IPV6_MISMATCH, GTCP_LOOKUP_ERROR_THREAD_ERROR } GTcpLookupStatus;
Used by gtcp_dns_get() callbacks and the "GTcpConnection-lookup-done" signal. User applications should use gtcp_error_get_lookup_status_message() to get a properly formatted error string for use in an error message box.
GTCP_LOOKUP_IN_PROGRESS | Currently in progress, should never be returned. |
GTCP_LOOKUP_OK | The lookup succeeded. |
GTCP_LOOKUP_ERROR_NOT_FOUND | There is no DNS record for the address. |
GTCP_LOOKUP_ERROR_NO_RECOVERY | The DNS server could not be found. |
GTCP_LOOKUP_ERROR_TRY_AGAIN | A temporary error occured. Try later. |
GTCP_LOOKUP_ERROR_IPV4_IPV6_MISMATCH | The network is misconfigured. |
GTCP_LOOKUP_ERROR_THREAD_ERROR | A problem with the GLib thread system occured. |
typedef enum /*< prefix=GTCP_CONNECTION > */ { GTCP_CONNECTION_ERROR_CONNECTION_REFUSED, GTCP_CONNECTION_ERROR_TIMEOUT, GTCP_CONNECTION_ERROR_NETWORK_UNREACHABLE, GTCP_CONNECTION_ERROR_BAD_BROADCAST_OR_FIREWALL, GTCP_CONNECTION_ERROR_INTERNAL, GTCP_CONNECTION_ERROR_THREAD_ERROR, GTCP_CONNECTION_ERROR_PROXY_ERROR, GTCP_CONNECTION_CLOSING, GTCP_CONNECTION_CLOSED, GTCP_CONNECTION_CONNECTED, GTCP_CONNECTION_CONNECTING } GTcpConnectionStatus;
Used by the "GTcpConnection-connect-done" signal. User applications should use gtcp_error_get_connection_status_message() to get a properly formatted error string for use in an error message box.
GTCP_CONNECTION_ERROR_CONNECTION_REFUSED | The server refused your attempt. |
GTCP_CONNECTION_ERROR_TIMEOUT | The server never responded. |
GTCP_CONNECTION_ERROR_NETWORK_UNREACHABLE | The specified network is not available to you (typically the network connection is not up). |
GTCP_CONNECTION_ERROR_BAD_BROADCAST_OR_FIREWALL | You are attempting to use a broadcast address and do not have permission to do so, or a firewall rule is preventing the connection. |
GTCP_CONNECTION_ERROR_INTERNAL | LibGTcpSocket encountered an unrecoverable error inside the library. |
GTCP_CONNECTION_ERROR_THREAD_ERROR | A problem with the GLib thread system occured. |
GTCP_CONNECTION_ERROR_PROXY_ERROR | The proxy server could not be contacted. |
GTCP_CONNECTION_CLOSING | The GTcpConnection is closing. |
GTCP_CONNECTION_CLOSED | The GTcpConnection is closed. |
GTCP_CONNECTION_CONNECTED | The GTcpConnection is open and ready. |
GTCP_CONNECTION_CONNECTING | The GTcpConnection is still connecting. |
typedef enum /*< prefix=GTCP_CONNECTION > */ { GTCP_CONNECTION_HTTP, GTCP_CONNECTION_FTP, GTCP_CONNECTION_OTHER } GTcpConnectionStyle;
The GTcpConnection style, used in conjunction with the "use-ssl" property to determine what proxy to use. See also GTcpProxyType.
GTCP_CONNECTION_HTTP | Connect through an HTTP proxy. |
GTCP_CONNECTION_FTP | Connect through an FTP proxy (not implemented). |
GTCP_CONNECTION_OTHER | Connect through a SOCKS server. |
typedef enum /*< prefix=GTCP_SEND > */ { GTCP_SEND_DATA_QUEUED, GTCP_SEND_ERROR, GTCP_SEND_ERROR_NOT_OPEN, GTCP_SEND_ERROR_NULL_DATA } GTcpSendStatus;
Returned by gtcp_connection_send().
GTCP_SEND_DATA_QUEUED | The data is queued for sending, and will be sent shortly. |
GTCP_SEND_ERROR | The data could not be sent. |
GTCP_SEND_ERROR_NOT_OPEN | The GTcpConnection is not open. |
GTCP_SEND_ERROR_NULL_DATA | There is no data to send. |
# define GTCP_SOCKET_DEFAULT_BUFFER_SIZE 2048
The default buffer size for new connections.
GObject* gtcp_connection_new (const gchar *address, guint port, GTcpConnectionStyle conn_style, gboolean use_ssl);
Creates a new GTcpConnection ready to connect to address:port. The type argument is used to determine what proxy to connect through, so it must be set correctly. The use_ssl argument is dependent on GTcpSocket being compiled with SSL support.
address : | the remote address to connect to. |
port : | the remote port to connect to. |
conn_style : | the GTcpConnectionStyle for this connection. |
use_ssl : | whether to use SSL or not. |
Returns : | a new GTcpConnection. |
Since 1.0
void gtcp_connection_open (GTcpConnection *conn);
This starts the process to open an already-created GTcpConnection object. You should connect all the event signals you want to listen for and set the buffer size (if you want to use a buffer size other than GTCP_SOCKET_DEFAULT_BUFFER_SIZE) before calling this function.
conn : | the GTcpConnection to open. |
Since 1.0
void gtcp_connection_close (GTcpConnection *conn);
This closes a GTcpConnection if it is open, or stops the connection process if it's already running. Nothing happens if the connection is already closed.
conn : | the GTcpConnection to close. |
Since 1.0
GTcpSendStatus gtcp_connection_send (GTcpConnection *conn, gconstpointer data, gssize length);
This sends length bytes of data over an open GTcpConnection. Do not pass -1 for the length if data is not nul-terminated, this will cause a crash. NOTE: This function will only return a value other than GTCP_SEND_DATA_QUEUED if it doesn't know of a reason to not send the data or queue for sending later. When the data is actually sent, the "send" signal will be emitted.
conn : | the GTcpConnection to send data through. |
data : | the data to send. GTcpConnection copies this data, so the programmer should free it after it is no longer needed. |
length : | the number of bytes in data, or -1 if data is null-terminated. NOTE: If length is greater than the current buffer size (or if it is determined to be greater if -1 is passed), the data will be split into buffer-sized blocks before sending. |
Returns : | GTcpSendStatus indicating how the data was handled. |
Since 1.0
G_CONST_RETURN gchar* gtcp_connection_get_address (GTcpConnection *conn);
This gets the destination of a GTcpConnection. This value should not be modified.
conn : | the GTcpConnection to retrieve the address of |
Returns : | The destination IP address or hostname string. |
Since 1.0
void gtcp_connection_set_address (GTcpConnection *conn, const gchar *address);
This changes the destination of a closed GTcpConnection.
conn : | the closed GTcpConnection to change the address of. |
address : | the new address. |
Since 1.0
guint gtcp_connection_get_port (GTcpConnection *conn);
This retrieves the destination port of a GTcpConnection.
conn : | the GTcpConnection to get the destination port of. |
Returns : | the destination port. |
Since 1.0
void gtcp_connection_set_port (GTcpConnection *conn, guint port);
This sets the destination port of a closed GTcpConnection.
conn : | the closed GTcpConnection to change the destination port of. |
port : | the new port. |
Since 1.0
gboolean gtcp_connection_get_use_ssl (GTcpConnection *conn);
This retrieves whether or not SSL will be used in this GTcpConnection.
conn : | the GTcpConnection to modify. |
Returns : | whether or not SSL will be used in this GTcpConnection. |
Since 1.0
gboolean gtcp_connection_set_use_ssl (GTcpConnection *conn, gboolean use_ssl);
This sets whether or not to encrypt connections over this closed GTcpConnection. It will return TRUE if SSL is supported, or FALSE, if it is not.
conn : | the closed GTcpConnection to modify. |
use_ssl : | whether or not to use ssl. |
Returns : | whether or not SSL is supported. |
Since 1.0
GTcpConnectionStyle gtcp_connection_get_conn_style (GTcpConnection *conn);
This retrieves the connection type of a closed GTcpConnection. The connection type is used (in conjunction with the SSL option and the destination address) to determine which proxy to use, if any.
conn : | the GTcpConnection to retrieve the connection type of. |
Returns : | the current GTcpConnectionStyle. |
Since 1.0
void gtcp_connection_set_conn_style (GTcpConnection *conn, GTcpConnectionStyle conn_style);
This changes the connection type of closed GTcpConnection. The connection type is used (in conjunction with the SSL option and the destination address) to determine which proxy to use, if any.
conn : | the closed GTcpConnection to change the connection type of. |
conn_style : | the new connection style. |
Since 1.0
G_CONST_RETURN gchar* gtcp_connection_get_ip_address (GTcpConnection *conn);
This gets the destination IP of a GTcpConnection. This value should not be modified, and may be NULL if the address could not resolve to an IP address, or the connection is closed.
conn : | the GTcpConnection to retrieve the address of. |
Returns : | the destination IP address. |
Since 1.0
void gtcp_connection_set_buffer_size (GTcpConnection *conn, gsize buffer_size);
This sets the buffer size of a closed GTcpConnection. See also: GTCP_SOCKET_DEFAULT_BUFFER_SIZE.
conn : | the GTcpConnection to change the buffer size of. |
buffer_size : | the new buffer size. |
Since 1.0
gsize gtcp_connection_get_buffer_size (GTcpConnection *conn);
This retrieves the buffer size of a closed GTcpConnection. See also: GTCP_SOCKET_DEFAULT_BUFFER_SIZE.
conn : | the GTcpConnection to retrieve the buffer size of. |
Returns : | the current buffer size. |
Since 1.0
gulong gtcp_connection_get_bytes_read (GTcpConnection *conn);
This gets the number of bytes recieved by a GTcpConnection for this connection. This counter is reset to zero when the connection is opened, so if you close the GTcpConnection, then open it, the counter will be reset.
conn : | the GTcpConnection to get the number of bytes read from. |
Returns : | the number of bytes read so far. |
Since 1.0
gulong gtcp_connection_get_bytes_written (GTcpConnection *conn);
This gets the number of bytes recieved by a GTcpConnection for this connection. This counter is reset to zero when the connection is opened, so if you close the GTcpConnection, then open it, the counter will be reset.
conn : | the GTcpConnection to get the number of bytes written to. |
Returns : | the number of bytes sent so far. |
Since 1.0
"address" (gchararray : Read / Write / Construct) | The remote host's IP address or hostname used for the connection. |
"buffer-size" (guint : Read / Write / Construct) | The read/write buffer size (limited by the system). See also: GTCP_SOCKET_DEFAULT_BUFFER_SIZE. |
"bytes-read" (gulong : Read) | The number of bytes received over this connection. |
"bytes-written" (gulong : Read) | The number of bytes sent over this connection. |
"connection-style" (GTcpConnectionStyle : Read / Write / Construct) | The connection style used to determine exact proxy settings. |
"ip-address" (gchararray : Read / Write / Construct) | The remote host's IP address. |
"is-server" (gboolean : Read / Write / Construct) | This property is for use only by GTcpserver. |
"local-address" (gchararray : Read / Write / Construct) | The local IP address used for the connection. |
"local-port" (guint : Read / Write / Construct) | The local port number used for this connection. |
"port" (guint : Read / Write / Construct) | The remote port used for the connection. |
"socket-fd" (gint : Write) | This property is for use only by GTcpserver. |
"status" (GTcpConnectionStatus : Read / Write / Construct) | The status of the connection (typically not needed). |
"use-ssl" (gboolean : Read / Write / Construct) | Whether or not to encrypt the connection with SSL. |
void user_function (GTcpConnection *gtcpconnection, gboolean arg1, gpointer user_data);
This signal is emitted when the connection is closed, either by the application calling gtcp_connection_close(), the connection being lost, or the connection being closed by the remote host.
gtcpconnection : | the object which received the signal. |
arg1 : | TRUE if the connection was closed with gtcp_connection_close(), FALSE if the connection was lost or closed by the remote system. |
user_data : | user data set when the signal handler was connected. |
void user_function (GTcpConnection *gtcpconnection, GTcpConnectionStatus arg1, gpointer user_data);
This signal is emitted when GTcpConnection has completed it's attempt to connect to the remote host.
gtcpconnection : | the object which received the signal. |
arg1 : | The GTcpConnectionStatus code. |
user_data : | user data set when the signal handler was connected. |
void user_function (GTcpConnection *gtcpconnection, GTcpLookupStatus arg1, gpointer user_data);
This signal is emitted when GTcpConnection has finished its lookup attempt, and started the connection process.
gtcpconnection : | The object which received the signal. |
arg1 : | The GTcpLookupStatus code. |
user_data : | user data set when the signal handler was connected. |
void user_function (GTcpConnection *gtcpconnection, gpointer arg1, guint arg2, gpointer user_data);
This signal is emitted when data is received by the GTcpConnection. The application should not free the data (it will be freed by GTcpConnection after all the connected handlers have been called), and should copy it if the application wishes to keep it around.
gtcpconnection : | the object which received the signal. |
arg1 : | A constant pointer to the received data. |
arg2 : | The number of bytes in arg1. |
user_data : | user data set when the signal handler was connected. |
void user_function (GTcpConnection *gtcpconnection, gpointer arg1, guint arg2, gpointer user_data);
This signal is emitted after data has been sent by the GTcpConnection to the remote host. The application should not free the data (it will be freed by GTcpConnection after all the connected handlers have been called), and should copy it if the application wishes to keep it around.
gtcpconnection : | the object which received the signal. |
arg1 : | A constant pointer to the sent data. |
arg2 : | The number of bytes which have been sent, and the size of arg1. |
user_data : | user data set when the signal handler was connected. |
<< API Reference | GTcpServer >> |