InfXmppManager: libinfinity-0.7 Reference Manual

## InfXmppManager InfXmppManager — Reuse existing connections |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfXmppManager * | inf_xmpp_manager_new ()
InfXmppConnection * | inf_xmpp_manager_lookup_connection_by_address ()
InfXmppConnection * | inf_xmpp_manager_lookup_connection_by_hostname ()
gboolean | inf_xmpp_manager_contains_connection ()
void | inf_xmpp_manager_add_connection ()
void | inf_xmpp_manager_remove_connection ()

## Signals

void | connection-added | Run Last
void | connection-removed | Run Last

## Types and Values

struct | InfXmppManager
struct | InfXmppManagerClass

## Object Hierarchy

        GObject
        ╰── InfXmppManager

## Includes

    #include <libinfinity/common/inf-xmpp-manager.h>

## Description

InfXmppManager stores InfXmppConnection objects and allows to look them up by the IP address and port number of their underlaying InfTcpConnections. This can be used to reuse existing network connections instead of creating new ones.

Each object which needs to make connections should be passed a InfXmppManager. Then, when making a connection to a certain address/port pair, it should first look in the XMPP manager whether there is already an existing connection to the destination host, via `inf_xmpp_manager_lookup_connection_by_address()`. If there is, it should use it (maybe reopen it if it is closed). Otherwise, it should create a new connection and add it to the XMPP manager via `inf_xmpp_manager_add_connection()` for others to use.

The XMPP manager can also handle connections whose address is still to be looked up. Such connections are looked up by the hostname given to the name resolver. Once the hostname has been looked up, and if another connection with the same address and port number exists already, the new connection is removed in favor of the already existing one.

## Functions

### inf_xmpp_manager_new ()

    InfXmppManager *
    inf_xmpp_manager_new (void);

Creates a new xmpp manager.

[constructor]

#### Returns

A new InfXmppManager.

[transfer full]

### inf_xmpp_manager_lookup_connection_by_address ()

    InfXmppConnection *
    inf_xmpp_manager_lookup_connection_by_address
                                   (InfXmppManager *manager,
                                    const InfIpAddress *address,
                                    guint port);

Looks for a InfXmppConnection contained in `manager` whose underlaying InfTcpConnection has the given address and port set. Returns `NULL` if there is no such connection.

This function may also return a closed connection. You can then attempt to reopen it, or remove it from the manager using `inf_xmpp_manager_remove_connection()` when that fails.

#### Parameters

manager | A InfXmppManager. |
address | The remote InfIpAddress of the connection to look for. |
port | The remote port number of the connection to look for. |

#### Returns

A InfXmppConnection with the given address and port, or `NULL` if not found.

[transfer none][allow-none]

### inf_xmpp_manager_lookup_connection_by_hostname ()

    InfXmppConnection *
    inf_xmpp_manager_lookup_connection_by_hostname
                                   (InfXmppManager *manager,
                                    const gchar *hostname,
                                    const gchar *service,
                                    const gchar *srv);

Looks for a InfXmppConnection contained in `manager` whose underlaying InfTcpConnection has a InfNameResolver with the given properties.

This function may also return a closed connection. You can then attempt to reopen it, or remove it from the manager using `inf_xmpp_manager_remove_connection()` when that fails.

#### Parameters

manager | A InfXmppManager. |
hostname | The remote hostname to look for. |
service | The service string of the connection to look for. | [allow-none]
srv | The SRV record corresponding to the connection. | [allow-none]

#### Returns

A InfXmppConnection with the given hostname, service and srv, or `NULL` if not found.

[transfer none][allow-none]

### inf_xmpp_manager_contains_connection ()

    gboolean
    inf_xmpp_manager_contains_connection (InfXmppManager *manager,
                                          InfXmppConnection *connection);

Returns whether `connection` is contained in `manager` .

#### Parameters

manager | A InfXmppManager. |
connection | A InfXmppConnection. |

#### Returns

`TRUE` if `connection` is contained in `manager` , `FALSE` otherwise.

### inf_xmpp_manager_add_connection ()

    void
    inf_xmpp_manager_add_connection (InfXmppManager *manager,
                                     InfXmppConnection *connection);

Adds the given connection to `manager` so that it is found by `inf_xmpp_manager_lookup_connection_by_address()`, `inf_xmpp_manager_lookup_connection_by_hostname()` and `inf_xmpp_manager_contains_connection()`.

#### Parameters

manager | A InfXmppManager. |
connection | A InfXmppConnection not yet contained in `manager` . |

### inf_xmpp_manager_remove_connection ()

    void
    inf_xmpp_manager_remove_connection (InfXmppManager *manager,
                                        InfXmppConnection *connection);

Removes the given connection from `manager` .

#### Parameters

manager | A InfXmppManager. |
connection | A InfXmppConnection contained in `manager` . |

## Types and Values

### struct InfXmppManager

    struct InfXmppManager;

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

### struct InfXmppManagerClass

    struct InfXmppManagerClass {
      void(*connection_added)(InfXmppManager* manager,
                              InfXmppConnection* connection);
      void(*connection_removed)(InfXmppManager* manager,
                                InfXmppConnection* connection,
                                InfXmppConnection* replaced_by);
    };

This structure contains the default signal handlers for InfXmppManager.

#### Members

`connection_added` () | Default signal handler for the “connection-added” signal. |
`connection_removed` () | Default signal handler for the “connection-removed” signal. |

## Signal Details

### The `“connection-added”` signal

    void
    user_function (InfXmppManager    *xmpp_manager,
                   InfXmppConnection *connection,
                   gpointer           user_data)

This signal is emitted whenever a new connection has been added to the InfXmppManager, via `inf_xmpp_manager_add_connection()`.

#### Parameters

xmpp_manager | The InfXmppManager emitting the signal. |
connection | The InfXmppConnection that was added to `xmpp_manager` . |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“connection-removed”` signal

    void
    user_function (InfXmppManager    *infxmppmanager,
                   InfXmppConnection *arg1,
                   InfXmppConnection *arg2,
                   gpointer           user_data)

#### Parameters

infxmppmanager | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last