InfTcpConnection

InfTcpConnection — Represents a TCP-based connection to a remote host

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

guint device-index Read / Write
char * device-name Read / Write
InfIo * io Read / Write / Construct Only
InfKeepalive * keepalive Read / Write
InfIpAddress * local-address Read
guint local-port Read
InfIpAddress * remote-address Read / Write
guint remote-port Read / Write
InfNameResolver * resolver Read / Write / Construct
InfTcpConnectionStatus status Read

Signals

void error Run Last
void received Run Last
void sent Run Last

Types and Values

Object Hierarchy

    GEnum
    ╰── InfTcpConnectionStatus
    GObject
    ╰── InfTcpConnection

Includes

#include <libinfinity/common/inf-tcp-connection.h>

Description

InfTcpConnection represents a TCP connection to a remove host. It is a wrapper around a native socket object and integrates into the main loop provided by InfIo. An arbitrary amount of data can be sent with the object, extra data will be buffered and automatically transmitted once kernel space becomes available.

The TCP connection properties should be set and then inf_tcp_connection_open() be called to open a connection. If the “resolver” property is set, then “remote-address” and “remote-port” are ignored, and the hostname as configured in the resolver will be resolved. When the hostname has been resolved and a connection has been made, the “remote-address” and “remote-port” properties are updated to reflect the address actually connected to.

Functions

inf_tcp_connection_new ()

InfTcpConnection *
inf_tcp_connection_new (InfIo *io,
                        const InfIpAddress *remote_addr,
                        guint remote_port);

Creates a new InfTcpConnection. The arguments are stored as properties for an eventual inf_tcp_connection_open() call, this function itself does not establish a connection.

[constructor]

Parameters

io

A InfIo object used to watch for activity.

 

remote_addr

The address to eventually connect to.

 

remote_port

The port to eventually connect to.

 

Returns

A new InfTcpConnection. Free with g_object_unref().

[transfer full]


inf_tcp_connection_new_and_open ()

InfTcpConnection *
inf_tcp_connection_new_and_open (InfIo *io,
                                 const InfIpAddress *remote_addr,
                                 guint remote_port,
                                 GError **error);

Creates a new InfTcpConnection and connects it to the given TCP endpoint. Like inf_tcp_connection_new(), but calls inf_tcp_connection_open().

[constructor]

Parameters

io

A InfIo object used to watch for activity.

 

remote_addr

The address to connect to.

 

remote_port

The port to connect to.

 

error

Location to store error information.

 

Returns

A new InfTcpConnection, or NULL on error. Free with g_object_unref().

[transfer full]


inf_tcp_connection_new_resolve ()

InfTcpConnection *
inf_tcp_connection_new_resolve (InfIo *io,
                                InfNameResolver *resolver);

Creates a new InfTcpConnection and instead of setting the remote IP address and port number directly, a hostname resolver is used to look up the remote hostname before connecting. This has the advantage that all available addresses for that hostname are tried before giving up.

The argument is stored as a property for an eventual inf_tcp_connection_open() call, this function itself does not establish a connection.

[constructor]

Parameters

io

A InfIo object used to watch for activity.

 

resolver

The hostname resolver object used to look up the remote hostname.

 

Returns

A new InfTcpConnection. Free with g_object_unref().

[transfer full]


inf_tcp_connection_open ()

gboolean
inf_tcp_connection_open (InfTcpConnection *connection,
                         GError **error);

Attempts to open connection . Make sure to have set the "remote-address" and "remote-port" property before calling this function. If an error occurs, the function returns FALSE and error is set. Note however that the connection might not be fully open when the function returns (check the "status" property if you need to know). If an asynchronous error occurs while the connection is being opened, the "error" signal is emitted.

Parameters

connection

A InfTcpConnection.

 

error

Location to store error information.

 

Returns

FALSE if an error occurred and TRUE otherwise.


inf_tcp_connection_close ()

void
inf_tcp_connection_close (InfTcpConnection *connection);

Closes a TCP connection that is either open or currently connecting.

Parameters

connection

A InfTcpConnection.

 

inf_tcp_connection_send ()

void
inf_tcp_connection_send (InfTcpConnection *connection,
                         gconstpointer data,
                         guint len);

Sends data through the TCP connection. The data is not sent immediately, but enqueued to a buffer and will be sent as soon as kernel space becomes available. The "sent" signal will be emitted when data has really been sent.

Parameters

connection

A InfTcpConnection with status INF_TCP_CONNECTION_CONNECTED.

 

data

The data to send.

[type guint8*][array length=len]

len

Number of bytes to send.

 

inf_tcp_connection_get_remote_address ()

InfIpAddress *
inf_tcp_connection_get_remote_address (InfTcpConnection *connection);

Returns the IP address of the remote site.

Parameters

connection

A InfTcpConnection.

 

Returns

A InfIpAddress owned by connection . You do not need to free it, but need to make your own copy if you want to keep it longer than connection 's lifetime.

[transfer none]


inf_tcp_connection_get_remote_port ()

guint
inf_tcp_connection_get_remote_port (InfTcpConnection *connection);

Returns the port of the remote site to which connection is (or was) connected or connecting.

Parameters

connection

A InfTcpConnection.

 

Returns

The port of the remote site.


inf_tcp_connection_set_keepalive ()

gboolean
inf_tcp_connection_set_keepalive (InfTcpConnection *connection,
                                  const InfKeepalive *keepalive,
                                  GError **error);

Sets the keepalive settings for connection . When this function is not called, the system defaults are used. If the connection is closed, then the function always succeeds and stores the keepalive values internally. The values are actually set on the underlying socket when the connection is opened. If the connection is already open, the function might fail if the system call fails.

Parameters

connection

A InfTcpConnection.

 

keepalive

New keepalive settings for the connection.

 

error

Location to store error information, if any, or NULL.

 

Returns

TRUE if the new keeplalive values were set, or FALSE on error.


inf_tcp_connection_get_keepalive ()

const InfKeepalive *
inf_tcp_connection_get_keepalive (InfTcpConnection *connection);

Returns the current keepalive settings for connection .

Parameters

connection

A InfTcpConnection.

 

Returns

The current keepalive configuration for connection , owned by connection .

Types and Values

enum InfTcpConnectionStatus

InfTcpConnectionStatus specifies the connection status of a InfTcpConnection.

Members

INF_TCP_CONNECTION_CONNECTING

A new connection is currently being established.

 

INF_TCP_CONNECTION_CONNECTED

The connection is ready to send and receive data.

 

INF_TCP_CONNECTION_CLOSED

The connection is closed. Before data can be transmitted, it needs to be opened with inf_tcp_connection_open().

 

struct InfTcpConnection

struct InfTcpConnection;

InfTcpConnection is an opaque data type. You should only access it via the public API functions.


struct InfTcpConnectionClass

struct InfTcpConnectionClass {
  /* Signals */
  void (*sent)(InfTcpConnection* connection,
               gconstpointer data,
               guint len);

  void (*received)(InfTcpConnection* connection,
                   gconstpointer data,
                   guint len);

  void (*error)(InfTcpConnection* connection,
                GError* error);
};

This structure contains the default signal handlers of InfTcpConnection.

Members

sent ()

Default signal handler for the “sent” signal.

 

received ()

Default signal handler for the “received” signal.

 

error ()

Default signal handler for the “error” signal.

 

Property Details

The “device-index” property

  “device-index”             guint

The index of the device to use for the connection.

Owner: InfTcpConnection

Flags: Read / Write

Default value: 0


The “device-name” property

  “device-name”              char *

The name of the device to use for the connection, such as `eth0'.

Owner: InfTcpConnection

Flags: Read / Write

Default value: NULL


The “io” property

  “io”                       InfIo *

I/O handler.

Owner: InfTcpConnection

Flags: Read / Write / Construct Only


The “keepalive” property

  “keepalive”                InfKeepalive *

The keepalive settings for the connection.

Owner: InfTcpConnection

Flags: Read / Write


The “local-address” property

  “local-address”            InfIpAddress *

The local address of the connection.

Owner: InfTcpConnection

Flags: Read


The “local-port” property

  “local-port”               guint

The local port of the connection.

Owner: InfTcpConnection

Flags: Read

Allowed values: <= 65535

Default value: 0


The “remote-address” property

  “remote-address”           InfIpAddress *

Address to connect to.

Owner: InfTcpConnection

Flags: Read / Write


The “remote-port” property

  “remote-port”              guint

Port to connect to.

Owner: InfTcpConnection

Flags: Read / Write

Allowed values: <= 65535

Default value: 0


The “resolver” property

  “resolver”                 InfNameResolver *

The hostname resolver.

Owner: InfTcpConnection

Flags: Read / Write / Construct


The “status” property

  “status”                   InfTcpConnectionStatus

Status of the TCP connection.

Owner: InfTcpConnection

Flags: Read

Default value: INF_TCP_CONNECTION_CLOSED

Signal Details

The “error” signal

void
user_function (InfTcpConnection *connection,
               GError           *error,
               gpointer          user_data)

This signal is emitted when an error occurred with the connection. If the error is fatal, the connection will change its status to INF_TCP_CONNECTION_CLOSED.

Parameters

connection

The erroneous InfTcpConnection.

 

error

A pointer to a GError object with details on the error.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “received” signal

void
user_function (InfTcpConnection *connection,
               gpointer          data,
               guint             length,
               gpointer          user_data)

This signal is emitted whenever data has been received from the connection.

Parameters

connection

The InfTcpConnection through which the data has been received.

 

data

A gpointer referring to the data that has been received.

 

length

A guint holding the number of bytes that has been received.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “sent” signal

void
user_function (InfTcpConnection *connection,
               gpointer          data,
               guint             length,
               gpointer          user_data)

This signal is emitted whenever data has been sent over the connection.

Parameters

connection

The InfTcpConnection through which the data has been sent.

 

data

A gpointer referring to the data that has been sent.

 

length

A guint holding the number of bytes that has been sent.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last