GTcpConnection

GTcpConnection — The main connection object.

Synopsis




struct      GTcpConnection;
struct      GTcpConnectionClass;
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 object 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.


struct GTcpConnectionClass

struct GTcpConnectionClass {

	/* Signals */
	void (*lookup_done)   (GTcpConnection * conn,
	                       GTcpLookupStatus status);
	void (*connect_done)  (GTcpConnection * conn,
	                       GTcpConnectionStatus status);
	void (*recv)          (GTcpConnection * conn,
	                       gconstpointer data,
	                       gsize length);
	void (*send)          (GTcpConnection * conn,
	                       gconstpointer data,
	                       gsize length);
	void (*closed)        (GTcpConnection * conn,
	                       gboolean requested);

};


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

Since 1.0


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_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 an unrecoverable internal error occurred inside the GTcpSocket Library (usually indicative of a larger system problem).
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 connection is in the process of closing.
GTCP_CONNECTION_CLOSED the connection is closed.
GTCP_CONNECTION_CONNECTED the connection is open and ready.
GTCP_CONNECTION_CONNECTING the connection is trying to connect.

Since 1.0.


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_HTTP connect through an HTTP proxy.
GTCP_CONNECTION_FTP connect through an FTP proxy (not yet implemented).
GTCP_CONNECTION_OTHER connect through a SOCKS server.

Since 1.0.


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

Since 1.0


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. Parent relative.

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. Parent relative.

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. Parent relative.

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. Parent relative.

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. Parent relative.

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.