GTcpConnection

GTcpConnection — The main connection object.

Synopsis




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


Object Hierarchy


  GObject
   +----GTcpConnection

Properties


  "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

Signal Prototypes


"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);

Description

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.

Details

struct GTcpConnection

struct GTcpConnection;

The GTcpConnection struct contains only read-only fields. They should never be set by an application.


enum GTcpLookupStatus

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_PROGRESSCurrently in progress, should never be returned.
GTCP_LOOKUP_OKThe lookup succeeded.
GTCP_LOOKUP_ERROR_NOT_FOUNDThere is no DNS record for the address.
GTCP_LOOKUP_ERROR_NO_RECOVERYThe DNS server could not be found.
GTCP_LOOKUP_ERROR_TRY_AGAINA temporary error occured. Try later.
GTCP_LOOKUP_ERROR_IPV4_IPV6_MISMATCHThe network is misconfigured.
GTCP_LOOKUP_ERROR_THREAD_ERRORA problem with the GLib thread system occured.

enum GTcpConnectionStatus

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_REFUSEDThe server refused your attempt.
GTCP_CONNECTION_ERROR_TIMEOUTThe server never responded.
GTCP_CONNECTION_ERROR_NETWORK_UNREACHABLEThe specified network is not available to you (typically the network connection is not up).
GTCP_CONNECTION_ERROR_BAD_BROADCAST_OR_FIREWALLYou 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_INTERNALLibGTcpSocket encountered an unrecoverable error inside the library.
GTCP_CONNECTION_ERROR_THREAD_ERRORA problem with the GLib thread system occured.
GTCP_CONNECTION_ERROR_PROXY_ERRORThe proxy server could not be contacted.
GTCP_CONNECTION_CLOSINGThe GTcpConnection is closing.
GTCP_CONNECTION_CLOSEDThe GTcpConnection is closed.
GTCP_CONNECTION_CONNECTEDThe GTcpConnection is open and ready.
GTCP_CONNECTION_CONNECTINGThe GTcpConnection is still connecting.

enum GTcpConnectionStyle

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_HTTPConnect through an HTTP proxy.
GTCP_CONNECTION_FTPConnect through an FTP proxy (not implemented).
GTCP_CONNECTION_OTHERConnect through a SOCKS server.

enum GTcpSendStatus

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_QUEUEDThe data is queued for sending, and will be sent shortly.
GTCP_SEND_ERRORThe data could not be sent.
GTCP_SEND_ERROR_NOT_OPENThe GTcpConnection is not open.
GTCP_SEND_ERROR_NULL_DATAThere is no data to send.

GTCP_SOCKET_DEFAULT_BUFFER_SIZE

#	define GTCP_SOCKET_DEFAULT_BUFFER_SIZE 2048

The default buffer size for new connections.


gtcp_connection_new ()

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


gtcp_connection_open ()

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


gtcp_connection_close ()

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


gtcp_connection_send ()

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


gtcp_connection_get_address ()

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


gtcp_connection_set_address ()

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


gtcp_connection_get_port ()

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


gtcp_connection_set_port ()

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


gtcp_connection_get_use_ssl ()

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


gtcp_connection_set_use_ssl ()

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


gtcp_connection_get_conn_style ()

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


gtcp_connection_set_conn_style ()

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


gtcp_connection_get_ip_address ()

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


gtcp_connection_set_buffer_size ()

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


gtcp_connection_get_buffer_size ()

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


gtcp_connection_get_bytes_read ()

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


gtcp_connection_get_bytes_written ()

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

Properties

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

Signals

The "closed" signal

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.

The "connect-done" signal

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.

The "lookup-done" signal

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.

The "recv" signal

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.

The "send" signal

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.