InfTcpConnection: libinfinity-0.7 Reference Manual

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

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfTcpConnection * | inf_tcp_connection_new ()
InfTcpConnection * | inf_tcp_connection_new_and_open ()
InfTcpConnection * | inf_tcp_connection_new_resolve ()
gboolean | inf_tcp_connection_open ()
void | inf_tcp_connection_close ()
void | inf_tcp_connection_send ()
InfIpAddress * | inf_tcp_connection_get_remote_address ()
guint | inf_tcp_connection_get_remote_port ()
gboolean | inf_tcp_connection_set_keepalive ()
const InfKeepalive * | inf_tcp_connection_get_keepalive ()

## Properties

guint | device-index | Read / Write
gchar * | 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

enum | InfTcpConnectionStatus
struct | InfTcpConnection
struct | InfTcpConnectionClass

## 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 occured 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.

Flags: Read / Write

Default value: 0

### The `“device-name”` property

      “device-name”              gchar *

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

Flags: Read / Write

Default value: NULL

### The `“io”` property

      “io”                       InfIo *

I/O handler.

Flags: Read / Write / Construct Only

### The `“keepalive”` property

      “keepalive”                InfKeepalive *

The keepalive settings for the connection.

Flags: Read / Write

### The `“local-address”` property

      “local-address”            InfIpAddress *

The local address of the connection.

Flags: Read

### The `“local-port”` property

      “local-port”               guint

The local port of the connection.

Flags: Read

Allowed values: <= 65535

Default value: 0

### The `“remote-address”` property

      “remote-address”           InfIpAddress *

Address to connect to.

Flags: Read / Write

### The `“remote-port”` property

      “remote-port”              guint

Port to connect to.

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

### The `“resolver”` property

      “resolver”                 InfNameResolver *

The hostname resolver.

Flags: Read / Write / Construct

### The `“status”` property

      “status”                   InfTcpConnectionStatus

Status of the TCP connection.

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 occured 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 refering 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 refering 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