GdaDictDatabase

## GdaDictDatabase GdaDictDatabase — Represents a database structure in the DBMS server |

## Synopsis

                GdaDictDatabase;
    GObject*    gda_dict_database_new           (GdaDict *dict);
    void        gda_dict_database_add_constraint
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictConstraint *cstr);
    GdaDict*    gda_dict_database_get_dict      (GdaDictDatabase *mgdb);
    gboolean    gda_dict_database_update_dbms_data
                                                (GdaDictDatabase *mgdb,
                                                 GError **error);
    void        gda_dict_database_stop_update_dbms_data
                                                (GdaDictDatabase *mgdb);
    GSList*     gda_dict_database_get_tables    (GdaDictDatabase *mgdb);
    GdaDictTable* gda_dict_database_get_table_by_name
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *name);
    GdaDictTable* gda_dict_database_get_table_by_xml_id
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *xml_id);
    GdaDictField* gda_dict_database_get_field_by_name
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *fullname);
    GdaDictField* gda_dict_database_get_field_by_xml_id
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *xml_id);
    GdaDictSequence* gda_dict_database_get_sequence_by_name
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *name);
    GdaDictSequence* gda_dict_database_get_sequence_by_xml_id
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *xml_id);
    GdaDictSequence* gda_dict_database_get_sequence_to_field
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictField *field);
    void        gda_dict_database_link_sequence (GdaDictDatabase *mgdb,
                                                 GdaDictSequence *seq,
                                                 GdaDictField *field);
    void        gda_dict_database_unlink_sequence
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictSequence *seq,
                                                 GdaDictField *field);
    GSList*     gda_dict_database_get_all_constraints
                                                (GdaDictDatabase *mgdb);
    GSList*     gda_dict_database_get_table_constraints
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictTable *table);
    GSList*     gda_dict_database_get_all_fk_constraints
                                                (GdaDictDatabase *mgdb);
    GSList*     gda_dict_database_get_tables_fk_constraints
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictTable *table1,
                                                 GdaDictTable *table2,
                                                 gboolean table1_has_fk);

## Object Hierarchy

      GObject
       +----GdaObject
             +----GdaDictDatabase

## Implemented Interfaces

GdaDictDatabase implements GdaXmlStorage.

## Properties

      "prop"                 gpointer              : Read / Write

## Signal Prototypes

    "constraint-added"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "constraint-removed"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "constraint-updated"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "data-update-finished"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer user_data);
    "data-update-started"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer user_data);
    "field-added"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "field-removed"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "field-updated"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "fs-link-added"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer arg2,
                                                gpointer user_data);
    "fs-link-removed"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer arg2,
                                                gpointer user_data);
    "sequence-added"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "sequence-removed"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "sequence-updated"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "table-added"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "table-removed"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "table-updated"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);
    "update-progress"
                void        user_function      (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                guint arg2,
                                                guint arg3,
                                                gpointer user_data);

## Description

This object manages an internal dictionary mirroring the real database structure with objects such as GdaDictTable (composed of GdaDictfield objects) and GdaDictConstraint.

## Details

### GdaDictDatabase

    typedef struct _GdaDictDatabase GdaDictDatabase;

### gda_dict_database_new ()

    GObject*    gda_dict_database_new           (GdaDict *dict);

Creates a new GdaDictDatabase object

`dict` : | a GdaDict object
Returns : | the new object

### gda_dict_database_add_constraint ()

    void        gda_dict_database_add_constraint
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictConstraint *cstr);

Add the `cstr` constraint to the database. The `cstr` constraint is a user-defined constraint (which is not part of the database structure itself).

`mgdb` : | a GdaDictDatabase object
`cstr` : | a GdaDictConstraint

### gda_dict_database_get_dict ()

    GdaDict*    gda_dict_database_get_dict      (GdaDictDatabase *mgdb);

Fetch the GdaDict object to which the GdaDictDatabase belongs.

`mgdb` : | a GdaDictDatabase object
Returns : | the GdaDict object

### gda_dict_database_update_dbms_data ()

    gboolean    gda_dict_database_update_dbms_data
                                                (GdaDictDatabase *mgdb,
                                                 GError **error);

Synchronises the Table representation with the table structure which is stored in the DBMS. For this operation to succeed, the connection to the DBMS server MUST be opened (using the corresponding GdaConnection object).

`mgdb` : |
`error` : | location to store error, or `NULL`
Returns : | TRUE if no error

### gda_dict_database_stop_update_dbms_data ()

    void        gda_dict_database_stop_update_dbms_data
                                                (GdaDictDatabase *mgdb);

When the database updates its internal lists of DBMS objects, a call to this function will stop that update process. It has no effect when the database is not updating its DBMS data.

`mgdb` : | a GdaDictDatabase object

### gda_dict_database_get_tables ()

    GSList*     gda_dict_database_get_tables    (GdaDictDatabase *mgdb);

Get a list of all the tables within `mgdb`

`mgdb` : | a GdaDictDatabase object
Returns : | a new list of all the GdaDictTable objects

### gda_dict_database_get_table_by_name ()

    GdaDictTable* gda_dict_database_get_table_by_name
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *name);

Get a reference to a GdaDictTable using its name.

`mgdb` : | a GdaDictDatabase object
`name` : | the name of the requested table
Returns : | The GdaDictTable pointer or NULL if the requested table does not exist.

### gda_dict_database_get_table_by_xml_id ()

    GdaDictTable* gda_dict_database_get_table_by_xml_id
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *xml_id);

Get a reference to a GdaDictTable using its XML id.

`mgdb` : | a GdaDictDatabase object
`xml_id` : | the XML id of the requested table
Returns : | The GdaDictTable pointer or NULL if the requested table does not exist.

### gda_dict_database_get_field_by_name ()

    GdaDictField* gda_dict_database_get_field_by_name
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *fullname);

Get a reference to a GdaDictField specifying the full name (table_name.field_name) of the requested field.

`mgdb` : | a GdaDictDatabase object
`fullname` : | the name of the requested table field
Returns : | The GdaDictField pointer or NULL if the requested field does not exist.

### gda_dict_database_get_field_by_xml_id ()

    GdaDictField* gda_dict_database_get_field_by_xml_id
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *xml_id);

Get a reference to a GdaDictField specifying its XML id

`mgdb` : | a GdaDictDatabase object
`xml_id` : | the XML id of the requested table field
Returns : | The GdaDictField pointer or NULL if the requested field does not exist.

### gda_dict_database_get_sequence_by_name ()

    GdaDictSequence* gda_dict_database_get_sequence_by_name
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *name);

Get a reference to a GdaDictSequence specifying its name

`mgdb` : | a GdaDictDatabase object
`name` : | the name of the requested sequence
Returns : | The GdaDictSequence pointer or NULL if the requested sequence does not exist.

### gda_dict_database_get_sequence_by_xml_id ()

    GdaDictSequence* gda_dict_database_get_sequence_by_xml_id
                                                (GdaDictDatabase *mgdb,
                                                 const gchar *xml_id);

Get a reference to a GdaDictSequence specifying its XML id.

`mgdb` : | a GdaDictDatabase object
`xml_id` : | the XML id of the requested sequence
Returns : | The GdaDictSequence pointer or NULL if the requested sequence does not exist.

### gda_dict_database_get_sequence_to_field ()

    GdaDictSequence* gda_dict_database_get_sequence_to_field
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictField *field);

Get a reference to a GdaDictSequence which is "linked" to the GdaDictField given as parameter. This "link" means that each new value of the field will be given by the returned sequence

`mgdb` : | a GdaDictDatabase object
`field` : | a GdaDictField object
Returns : | The GdaDictSequence pointer or NULL if there is no sequence for this job.

### gda_dict_database_link_sequence ()

    void        gda_dict_database_link_sequence (GdaDictDatabase *mgdb,
                                                 GdaDictSequence *seq,
                                                 GdaDictField *field);

Tells the database that each new value of the field given as argument should be obtained from the specified sequence (this is usefull when the field is a simple primary key for example).

`mgdb` : | a GdaDictDatabase object
`seq` : |
`field` : |

### gda_dict_database_unlink_sequence ()

    void        gda_dict_database_unlink_sequence
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictSequence *seq,
                                                 GdaDictField *field);

Tells the database that each new value of the field given as argument should not be obtained from the specified sequence (this is usefull when the field is a simple primary key for example). This is the opposite of the `gda_dict_database_link_sequence()` method.

`mgdb` : | a GdaDictDatabase object
`seq` : |
`field` : |

### gda_dict_database_get_all_constraints ()

    GSList*     gda_dict_database_get_all_constraints
                                                (GdaDictDatabase *mgdb);

Get a list of all the constraints applied to the database. Constraints are represented as GdaDictConstraint objects and represent any type of constraint.

`mgdb` : | a GdaDictDatabase object
Returns : | a new list of the constraints

### gda_dict_database_get_table_constraints ()

    GSList*     gda_dict_database_get_table_constraints
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictTable *table);

Get all the constraints applicable to `table`

`mgdb` : | a GdaDictDatabase object
`table` : | a GdaDictTable, part of `mgdb`
Returns : | a new GSList of GdaDictConstraint objects

### gda_dict_database_get_all_fk_constraints ()

    GSList*     gda_dict_database_get_all_fk_constraints
                                                (GdaDictDatabase *mgdb);

Get a list of all the constraints applied to the database which represent a foreign constrains. Constraints are represented as GdaDictConstraint objects.

`mgdb` : | a GdaDictDatabase object
Returns : | a new list of the constraints

### gda_dict_database_get_tables_fk_constraints ()

    GSList*     gda_dict_database_get_tables_fk_constraints
                                                (GdaDictDatabase *mgdb,
                                                 GdaDictTable *table1,
                                                 GdaDictTable *table2,
                                                 gboolean table1_has_fk);

Get a list of all the constraints applied to the database which represent a foreign key constrains, between `table1` and `table2`. If `table1` or `table2` are `NULL`, then the returned foreign key constraints are the ones between any table and `table1` or `table2`.

Constraints are represented as GdaDictConstraint objects.

`mgdb` : | a GdaDictDatabase object
`table1` : | a GdaDictTable, or `NULL`
`table2` : | a GdaDictTable, or `NULL`
`table1_has_fk` : | TRUE if the returned constraints are the one for which `table1` contains the foreign key
Returns : | a new list of the constraints

## Properties

### The "`prop`" property

      "prop"                 gpointer              : Read / Write

## Signals

### The "constraint-added" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "constraint-removed" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "constraint-updated" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "data-update-finished" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "data-update-started" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "field-added" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "field-removed" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "field-updated" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "fs-link-added" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer arg2,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The "fs-link-removed" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer arg2,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The "sequence-added" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "sequence-removed" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "sequence-updated" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "table-added" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "table-removed" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "table-updated" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "update-progress" signal

    void        user_function                  (GdaDictDatabase *gdadictdatabase,
                                                gpointer arg1,
                                                guint arg2,
                                                guint arg3,
                                                gpointer user_data);

`dbdatabase` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.