GdaVconnectionHub

## GdaVconnectionHub GdaVconnectionHub — Virtual connection which bind together connections |

## Synopsis

                        GdaVconnectionHub;
    void                (*GdaVConnectionHubFunc)            (GdaConnection *cnc,
                                                             const gchar *ns,
                                                             gpointer data);
    gboolean            gda_vconnection_hub_add             (GdaVconnectionHub *hub,
                                                             GdaConnection *cnc,
                                                             const gchar *ns,
                                                             GError **error);
    gboolean            gda_vconnection_hub_remove          (GdaVconnectionHub *hub,
                                                             GdaConnection *cnc,
                                                             GError **error);
    GdaConnection *     gda_vconnection_hub_get_connection  (GdaVconnectionHub *hub,
                                                             const gchar *ns);
    void                gda_vconnection_hub_foreach         (GdaVconnectionHub *hub,
                                                             GdaVConnectionHubFunc func,
                                                             gpointer data);

## Object Hierarchy

      GObject
       +----GdaConnection
             +----GdaVirtualConnection
                   +----GdaVconnectionDataModel
                         +----GdaVconnectionHub

## Implemented Interfaces

GdaVconnectionHub implements GdaLockable.

## Description

The GdaVconnectionHub object "binds" together the tables from other (opened) connections to make it possible to run SQL queries on data from several connections at once.

A GdaVconnectionHub connection can bind several other connections, each separated in its own namespace (which is specified when adding a connection using `gda_vconnection_hub_add()`).

For example if a connection A has two tables 'table_1' and 'table_2', then after `gda_vconnection_hub_add()` has been called with A as connection argument and with a "c1" namespace, then in the corresponding GdaVconnectionHub connection, table 'table_1' must be refered to as 'c1.table_1' and 'table_2' must be refered to as 'c1.table_2'.

Note that virtual connections have some inherent limitations [3]due to the implementation.

## Details

### GdaVconnectionHub

    typedef struct _GdaVconnectionHub GdaVconnectionHub;

### GdaVConnectionHubFunc ()

    void                (*GdaVConnectionHubFunc)            (GdaConnection *cnc,
                                                             const gchar *ns,
                                                             gpointer data);

`cnc` : |
`ns` : |
`data` : |

### gda_vconnection_hub_add ()

    gboolean            gda_vconnection_hub_add             (GdaVconnectionHub *hub,
                                                             GdaConnection *cnc,
                                                             const gchar *ns,
                                                             GError **error);

Make all the tables of `cnc` appear as tables (of the same name) in the `hub` connection. If the `ns` is not `NULL`, then within `hub`, the tables will be accessible using the '`ns`.`table_name`' notation.

Within any instance of `hub`, there can be only one added connection where `ns` is `NULL`.

`hub` : | a GdaVconnectionHub connection
`cnc` : | a GdaConnection
`ns` : | a namespace, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_vconnection_hub_remove ()

    gboolean            gda_vconnection_hub_remove          (GdaVconnectionHub *hub,
                                                             GdaConnection *cnc,
                                                             GError **error);

Remove all the tables in `hub` representing `cnc`'s tables.

`hub` : | a GdaVconnectionHub connection
`cnc` : | a GdaConnection
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_vconnection_hub_get_connection ()

    GdaConnection *     gda_vconnection_hub_get_connection  (GdaVconnectionHub *hub,
                                                             const gchar *ns);

Find the GdaConnection object in `hub` associated to the `ns` name space

`hub` : | a GdaVconnectionHub connection
`ns` : | a name space, or `NULL`
Returns : | the GdaConnection, or `NULL` if no connection is associated to `ns`

### gda_vconnection_hub_foreach ()

    void                gda_vconnection_hub_foreach         (GdaVconnectionHub *hub,
                                                             GdaVConnectionHubFunc func,
                                                             gpointer data);

Call `func` for each GdaConnection represented in `hub`.

`hub` : | a GdaVconnectionHub connection
`func` : | a GdaVconnectionDataModelFunc function pointer
`data` : | data to pass to `cunc` calls

[3] As virtual connections are implemented using SQLite's virtual table features, the SQL dialect which can be used is the SQLite one (see the SQL as Understood By SQLite page), and there are a few limitations inherent to this implementation (see link for more information).

Also note that it is possible to create temporary tables in virtual connections using "CREATE TEMP TABLE..." statements, but the contents of such tables will be lost once the connection is closed.