## InfXmppManager InfXmppManager — Reuse existing connections |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        InfXmppManager;
    struct              InfXmppManagerClass;
    InfXmppManager *    inf_xmpp_manager_new                (void);
    InfXmppConnection * inf_xmpp_manager_lookup_connection_by_address
                                                            (InfXmppManager *manager,
                                                             InfIpAddress *address,
                                                             guint port);
    gboolean            inf_xmpp_manager_contains_connection
                                                            (InfXmppManager *manager,
                                                             InfXmppConnection *connection);
    void                inf_xmpp_manager_add_connection     (InfXmppManager *manager,
                                                             InfXmppConnection *connection);
    void                inf_xmpp_manager_remove_connection  (InfXmppManager *manager,
                                                             InfXmppConnection *connection);

## Object Hierarchy

      GObject
       +----InfXmppManager

## Signals

      "add-connection"                                 : Run Last
      "remove-connection"                              : Run Last

## 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 it to the XMPP manager via `inf_xmpp_manager_add_connection()` for others to use.

## Details

### InfXmppManager

    typedef struct _InfXmppManager InfXmppManager;

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

### struct InfXmppManagerClass

    struct InfXmppManagerClass {
      void(*add_connection)(InfXmppManager* manager,
                            InfXmppConnection* connection);
      void(*remove_connection)(InfXmppManager* manager,
                               InfXmppConnection* connection);
    };

This structure contains the default signal handlers for InfXmppManager.

`add_connection` () | Default signal handler for the "add-connection" signal. It adds the connection to the manager's internal storage.
`remove_connection` () | Default signal handler for the "remove-connection" signal. It removes the connection from the manager's internal storage.

### inf_xmpp_manager_new ()

    InfXmppManager *    inf_xmpp_manager_new                (void);

Creates a new xmpp manager.

Returns : | A new InfXmppManager.

### inf_xmpp_manager_lookup_connection_by_address ()

    InfXmppConnection * inf_xmpp_manager_lookup_connection_by_address
                                                            (InfXmppManager *manager,
                                                             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.

`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` on error.

### inf_xmpp_manager_contains_connection ()

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

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

`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()` and `inf_xmpp_manager_contains_connection()`.

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

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

## Signal Details

### The `"add-connection"` signal

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

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

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

### The `"remove-connection"` signal

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

This signal is emitted whenever a connection has been removed from the InfXmppManager, via `inf_xmpp_manager_remove_connection()`.

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