## MgConf

MgConf — Main object: manages all the data dictionnary of the library.

## Synopsis

    struct      MgConf;
    struct      MgConfPrivate;
    guint       mg_conf_get_type                (void);
    GObject*    mg_conf_new                     (void);
    gchar*      mg_conf_compute_xml_filename    (MgConf *conf,
                                                 const gchar *datasource,
                                                 const gchar *app_id,
                                                 GError **error);
    void        mg_conf_set_xml_filename        (MgConf *conf,
                                                 const gchar *xmlfile);
    const gchar* mg_conf_get_xml_filename       (MgConf *conf);
    gboolean    mg_conf_load_xml                (MgConf *conf,
                                                 GError **error);
    gboolean    mg_conf_save_xml                (MgConf *conf,
                                                 GError **error);
    gboolean    mg_conf_load_xml_file           (MgConf *conf,
                                                 const gchar *xmlfile,
                                                 GError **error);
    gboolean    mg_conf_save_xml_file           (MgConf *conf,
                                                 const gchar *xmlfile,
                                                 GError **error);
    void        mg_conf_declare_query           (MgConf *conf,
                                                 MgQuery *query);
    void        mg_conf_assume_query            (MgConf *conf,
                                                 MgQuery *query);
    void        mg_conf_unassume_query          (MgConf *conf,
                                                 MgQuery *query);
    GSList*     mg_conf_get_queries             (MgConf *conf);
    MgQuery*    mg_conf_get_query_by_xml_id     (MgConf *conf,
                                                 const gchar *xml_id);
    void        mg_conf_declare_graph           (MgConf *conf,
                                                 MgGraph *graph);
    void        mg_conf_assume_graph            (MgConf *conf,
                                                 MgGraph *graph);
    void        mg_conf_unassume_graph          (MgConf *conf,
                                                 MgGraph *graph);
    GSList*     mg_conf_get_graphs              (MgConf *conf);
    MgGraph*    mg_conf_get_graph_by_xml_id     (MgConf *conf,
                                                 const gchar *xml_id);
    MgGraph*    mg_conf_get_graph_for_object    (MgConf *conf,
                                                 GObject *obj);
    void        mg_conf_declare_layout          (MgConf *conf,
                                                 MgCustomLayout *layout);
    void        mg_conf_assume_layout           (MgConf *conf,
                                                 MgCustomLayout *layout);
    void        mg_conf_unassume_layout         (MgConf *conf,
                                                 MgCustomLayout *layout);
    GSList*     mg_conf_get_layouts             (MgConf *conf);
    MgCustomLayout* mg_conf_get_layout_by_xml_id
                                                (MgConf *conf,
                                                 const gchar *xml_id);
    MgServer*   mg_conf_get_server              (MgConf *conf);
    MgDatabase* mg_conf_get_database            (MgConf *conf);
    GSList*     mg_conf_get_entities_fk_constraints
                                                (MgConf *conf,
                                                 MgEntity *entity1,
                                                 MgEntity *entity2,
                                                 gboolean entity1_has_fk);
    void        mg_conf_dump                    (MgConf *conf);

## Object Hierarchy

      GObject
       +----MgConf

## Properties

      "graph-serial"         guint                : Read
      "layout-serial"        guint                : Read
      "query-serial"         guint                : Read

## Signal Prototypes

    "changed"   void        user_function      (MgConf *mgconf,
                                                gpointer user_data);
    "graph-added"
                void        user_function      (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);
    "graph-removed"
                void        user_function      (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);
    "graph-updated"
                void        user_function      (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);
    "layout-added"
                void        user_function      (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);
    "layout-removed"
                void        user_function      (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);
    "layout-updated"
                void        user_function      (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);
    "query-added"
                void        user_function      (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);
    "query-removed"
                void        user_function      (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);
    "query-updated"
                void        user_function      (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

## Description

This object is a "container" for all the objects which are used within the libmergeant library: connection to the DBMS server (through a MgServer object), database structure (through a MgDatabase object) and queries (MgQuery objects).

There MUST be a MgConf object for each connection to a DBMS, and there can be several ones at the same time. The MgConf object, when instantiated, will create a MgServer and a MgDatabase objects; the other objects will be created as necessary when an XML file is loaded.

## Details

### struct MgConf

    struct MgConf;

### struct MgConfPrivate

    struct MgConfPrivate;

### mg_conf_get_type ()

    guint       mg_conf_get_type                (void);

Returns : |

### mg_conf_new ()

    GObject*    mg_conf_new                     (void);

Create a new MgConf object.

Returns : | the newly created object.

### mg_conf_compute_xml_filename ()

    gchar*      mg_conf_compute_xml_filename    (MgConf *conf,
                                                 const gchar *datasource,
                                                 const gchar *app_id,
                                                 GError **error);

Get the prefered filename which represents the data dictionnary associated to the `datasource` data source. Using the returned value in conjunction with `mg_conf_load_xml_file()` and mg_conf_save_xml_file has the advantage of letting the library handle file naming onventions.

The `app_id` argument allows to give an extra identification to the request, when some special features must be saved but not interfere with the default dictionnary.

`conf` : | a MgConf object
`datasource` : | a data source
`app_id` : | an extra identification, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | a new string

### mg_conf_set_xml_filename ()

    void        mg_conf_set_xml_filename        (MgConf *conf,
                                                 const gchar *xmlfile);

Sets the filename `conf` will use when `mg_conf_save_xml()` and `mg_conf_load_xml()` are called.

`conf` : | a MgConf object
`xmlfile` : | a file name

### mg_conf_get_xml_filename ()

    const gchar* mg_conf_get_xml_filename       (MgConf *conf);

Get the filename `conf` will use when `mg_conf_save_xml()` and `mg_conf_load_xml()` are called.

`conf` : | a MgConf object
Returns : | the filename, or `NULL` if none have been set.

### mg_conf_load_xml ()

    gboolean    mg_conf_load_xml                (MgConf *conf,
                                                 GError **error);

Loads an XML file which respects the Mergeant DTD, and creates all the necessary objects that are defined within the XML file. During the creation of the other objects, all the normal signals are emitted.

If the MgConf object already has some contents, then it is first of all nullified (to return its state as when it was first created).

If an error occurs during loading then the MgConf object is left as empty as when it is first created.

The file loaded is the one specified using `mg_conf_set_xml_filename()`

`conf` : | a MgConf object
`error` : | location to store error, or `NULL`
Returns : | TRUE if loading was successfull and FALSE otherwise.

### mg_conf_save_xml ()

    gboolean    mg_conf_save_xml                (MgConf *conf,
                                                 GError **error);

Saves the contents of a MgConf object to a file which is specified using the `mg_conf_set_xml_filename()` method.

`conf` : | a MgConf object
`error` : | location to store error, or `NULL`
Returns : | TRUE if saving was successfull and FALSE otherwise.

### mg_conf_load_xml_file ()

    gboolean    mg_conf_load_xml_file           (MgConf *conf,
                                                 const gchar *xmlfile,
                                                 GError **error);

Loads an XML file which respects the Mergeant DTD, and creates all the necessary objects that are defined within the XML file. During the creation of the other objects, all the normal signals are emitted.

If the MgConf object already has some contents, then it is first of all nullified (to return its state as when it was first created).

If an error occurs during loading then the MgConf object is left as empty as when it is first created.

`conf` : | a MgConf object
`xmlfile` : | the name of the file to which the XML will be written to
`error` : | location to store error, or `NULL`
Returns : | TRUE if loading was successfull and FALSE otherwise.

### mg_conf_save_xml_file ()

    gboolean    mg_conf_save_xml_file           (MgConf *conf,
                                                 const gchar *xmlfile,
                                                 GError **error);

Saves the contents of a MgConf object to a file which is given as argument.

`conf` : | a MgConf object
`xmlfile` : | the name of the file to which the XML will be written to
`error` : | location to store error, or `NULL`
Returns : | TRUE if saving was successfull and FALSE otherwise.

### mg_conf_declare_query ()

    void        mg_conf_declare_query           (MgConf *conf,
                                                 MgQuery *query);

Declares the existence of a new query to `conf`. All the MgQuery objects MUST be declared to the corresponding MgConf object for the library to work correctly. Once `query` has been declared, `conf` does not hold any reference to `query`. If `conf` must hold such a reference, then use `mg_conf_assume_query()`.

This functions is called automatically from each mg_query_new* function, and it should not be necessary to call it except for classes extending the MgQuery class.

`conf` : | a MgConf object
`query` : | a MgQuery object

### mg_conf_assume_query ()

    void        mg_conf_assume_query            (MgConf *conf,
                                                 MgQuery *query);

Force `conf` to manage `query`: it will get a reference to it.

`conf` : | a MgConf object
`query` : | a MgQuery object

### mg_conf_unassume_query ()

    void        mg_conf_unassume_query          (MgConf *conf,
                                                 MgQuery *query);

Forces `conf` to lose a reference it has on `query`

`conf` : | a MgConf object
`query` : | a MgQuery object

### mg_conf_get_queries ()

    GSList*     mg_conf_get_queries             (MgConf *conf);

Get a list of all the non interdependant queries managed by `conf` (only queries with no parent query are listed)

`conf` : | a MgConf object
Returns : | a new list of MgQuery objects

### mg_conf_get_query_by_xml_id ()

    MgQuery*    mg_conf_get_query_by_xml_id     (MgConf *conf,
                                                 const gchar *xml_id);

Find a MgQuery object from its XML Id

`conf` : | a MgConf object
`xml_id` : | the XML Id of the query being searched
Returns : | the MgQuery object, or NULL if not found

### mg_conf_declare_graph ()

    void        mg_conf_declare_graph           (MgConf *conf,
                                                 MgGraph *graph);

Declares the existence of a new graph to `conf`. All the MgGraph objects MUST be declared to the corresponding MgConf object for the library to work correctly. Once `graph` has been declared, `conf` does not hold any reference to `graph`. If `conf` must hold such a reference, then use `mg_conf_assume_graph()`.

This functions is called automatically from each mg_graph_new* function, and it should not be necessary to call it except for classes extending the MgGraph class.

`conf` : | a MgConf object
`graph` : | a MgGraph object

### mg_conf_assume_graph ()

    void        mg_conf_assume_graph            (MgConf *conf,
                                                 MgGraph *graph);

Force `conf` to manage `graph`: it will get a reference to it.

`conf` : | a MgConf object
`graph` : | a MgGraph object

### mg_conf_unassume_graph ()

    void        mg_conf_unassume_graph          (MgConf *conf,
                                                 MgGraph *graph);

Forces `conf` to lose a reference it has on `graph`

`conf` : | a MgConf object
`graph` : | a MgGraph object

### mg_conf_get_graphs ()

    GSList*     mg_conf_get_graphs              (MgConf *conf);

Get a list of all the graphs managed by `conf`

`conf` : | a MgConf object
Returns : | a new list of MgGraph objects

### mg_conf_get_graph_by_xml_id ()

    MgGraph*    mg_conf_get_graph_by_xml_id     (MgConf *conf,
                                                 const gchar *xml_id);

Find a MgGraph object from its XML Id

`conf` : | a MgConf object
`xml_id` : | the XML Id of the graph being searched
Returns : | the MgGraph object, or NULL if not found

### mg_conf_get_graph_for_object ()

    MgGraph*    mg_conf_get_graph_for_object    (MgConf *conf,
                                                 GObject *obj);

Find a MgGraph object guiven the object it is related to.

`conf` : | a MgConf object
`obj` : | a Gobject object
Returns : | the MgGraph object, or NULL if not found

### mg_conf_declare_layout ()

    void        mg_conf_declare_layout          (MgConf *conf,
                                                 MgCustomLayout *layout);

Declares the existence of a new layout to `conf`. All the MgCustomLayout objects MUST be declared to the corresponding MgConf object for the library to work correctly. Once `layout` has been declared, `conf` does not hold any reference to `layout`. If `conf` must hold such a reference, then use `mg_conf_assume_layout()`.

This functions is called automatically from each mg_layout_new* function, and it should not be necessary to call it except for classes extending the MgCustomLayout class.

`conf` : | a MgConf object
`layout` : | a MgLayout object

### mg_conf_assume_layout ()

    void        mg_conf_assume_layout           (MgConf *conf,
                                                 MgCustomLayout *layout);

Force `conf` to manage `layout`: it will get a reference to it.

`conf` : | a MgConf object
`layout` : | a MgCustomLayout object

### mg_conf_unassume_layout ()

    void        mg_conf_unassume_layout         (MgConf *conf,
                                                 MgCustomLayout *layout);

Forces `conf` to lose a reference it has on `layout`

`conf` : | a MgConf object
`layout` : | a MgCustomLayout object

### mg_conf_get_layouts ()

    GSList*     mg_conf_get_layouts             (MgConf *conf);

Get a list of all the layouts managed by `conf`

`conf` : | a MgConf object
Returns : | a new list of MgCustomLayout objects

### mg_conf_get_layout_by_xml_id ()

    MgCustomLayout* mg_conf_get_layout_by_xml_id
                                                (MgConf *conf,
                                                 const gchar *xml_id);

Find a MgCustomLayout object from its XML Id

`conf` : | a MgConf object
`xml_id` : | the XML Id of the layout being searched
Returns : | the MgCustomLayout object, or NULL if not found

### mg_conf_get_server ()

    MgServer*   mg_conf_get_server              (MgConf *conf);

Fetch a pointer to the MgServer used by the MgConf object.

`conf` : | a MgConf object
Returns : | a pointer to the MgServer

### mg_conf_get_database ()

    MgDatabase* mg_conf_get_database            (MgConf *conf);

Fetch a pointer to the MgDatabase used by the MgConf object.

`conf` : | a MgConf object
Returns : | a pointer to the MgDatabase

### mg_conf_get_entities_fk_constraints ()

    GSList*     mg_conf_get_entities_fk_constraints
                                                (MgConf *conf,
                                                 MgEntity *entity1,
                                                 MgEntity *entity2,
                                                 gboolean entity1_has_fk);

Get a list of all the constraints which represent a foreign constrains, between `entity1` and `entity2`. If `entity1` and `entity2` are MgDbTable objects, then the constraints are the ones from the database.

Constraints are represented as MgDbConstraint objects.

`conf` : | a MgConf object
`entity1` : | an object implementing the MgEntity interface
`entity2` : | an object implementing the MgEntity interface
`entity1_has_fk` : | TRUE if the returned constraints are the one for which `entity1` contains the foreign key
Returns : | a new list of the constraints

### mg_conf_dump ()

    void        mg_conf_dump                    (MgConf *conf);

Dumps the whole dictionnary managed by the MgConf object

`conf` : | a MgConf object

## Properties

"`graph-serial`" (guint : Read) |
"`layout-serial`" (guint : Read) |
"`query-serial`" (guint : Read) |

## Signals

### The "changed" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer user_data);

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

### The "graph-added" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "graph-removed" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "graph-updated" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "layout-added" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "layout-removed" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "layout-updated" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "query-added" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

Emitted when a MgQuery object has been added to the list of queries assumed by `mgconf` (using the `mg_conf_assume_query()`).

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

### The "query-removed" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

Emitted when a MgQuery object has been removed from the list of queries assumed by `mgconf` (using the `mg_conf_unassume_query()`).

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

### The "query-updated" signal

    void        user_function                  (MgConf *mgconf,
                                                gpointer arg1,
                                                gpointer user_data);

Emitted when a MgQuery object assumed by `mgconf` has changed.

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