GnomeDbDict

GnomeDbDict — GnomeDb dictionary

Synopsis




            GnomeDbDict;
            GnomeDbDictPrivate;
GType       gnome_db_dict_get_type          (void);
GObject*    gnome_db_dict_new               (void);
gchar*      gnome_db_dict_compute_xml_filename
                                            (GnomeDbDict *dict,
                                             const gchar *datasource,
                                             const gchar *app_id,
                                             GError **error);
void        gnome_db_dict_set_xml_filename  (GnomeDbDict *dict,
                                             const gchar *xmlfile);
const gchar* gnome_db_dict_get_xml_filename (GnomeDbDict *dict);
gboolean    gnome_db_dict_load_xml          (GnomeDbDict *dict,
                                             GError **error);
gboolean    gnome_db_dict_save_xml          (GnomeDbDict *dict,
                                             GError **error);
gboolean    gnome_db_dict_load_xml_file     (GnomeDbDict *dict,
                                             const gchar *xmlfile,
                                             GError **error);
gboolean    gnome_db_dict_save_xml_file     (GnomeDbDict *dict,
                                             const gchar *xmlfile,
                                             GError **error);
void        gnome_db_dict_declare_query     (GnomeDbDict *dict,
                                             GnomeDbQuery *query);
void        gnome_db_dict_assume_query      (GnomeDbDict *dict,
                                             GnomeDbQuery *query);
void        gnome_db_dict_unassume_query    (GnomeDbDict *dict,
                                             GnomeDbQuery *query);
GSList*     gnome_db_dict_get_queries       (GnomeDbDict *dict);
GnomeDbQuery* gnome_db_dict_get_query_by_xml_id
                                            (GnomeDbDict *dict,
                                             const gchar *xml_id);
void        gnome_db_dict_declare_graph     (GnomeDbDict *dict,
                                             GnomeDbGraph *graph);
void        gnome_db_dict_assume_graph      (GnomeDbDict *dict,
                                             GnomeDbGraph *graph);
void        gnome_db_dict_unassume_graph    (GnomeDbDict *dict,
                                             GnomeDbGraph *graph);
GSList*     gnome_db_dict_get_graphs        (GnomeDbDict *dict,
                                             GnomeDbGraphType type_of_graphs);
GnomeDbGraph* gnome_db_dict_get_graph_by_xml_id
                                            (GnomeDbDict *dict,
                                             const gchar *xml_id);
GnomeDbGraph* gnome_db_dict_get_graph_for_object
                                            (GnomeDbDict *dict,
                                             GObject *obj);
void        gnome_db_dict_declare_layout    (GnomeDbDict *dict,
                                             GnomeDbCustomLayout *layout);
void        gnome_db_dict_assume_layout     (GnomeDbDict *dict,
                                             GnomeDbCustomLayout *layout);
void        gnome_db_dict_unassume_layout   (GnomeDbDict *dict,
                                             GnomeDbCustomLayout *layout);
GSList*     gnome_db_dict_get_layouts       (GnomeDbDict *dict);
GnomeDbCustomLayout* gnome_db_dict_get_layout_by_xml_id
                                            (GnomeDbDict *dict,
                                             const gchar *xml_id);
GnomeDbServer* gnome_db_dict_get_server     (GnomeDbDict *dict);
GnomeDbDatabase* gnome_db_dict_get_database (GnomeDbDict *dict);
GSList*     gnome_db_dict_get_entities_fk_constraints
                                            (GnomeDbDict *dict,
                                             GnomeDbEntity *entity1,
                                             GnomeDbEntity *entity2,
                                             gboolean entity1_has_fk);
void        gnome_db_dict_dump              (GnomeDbDict *dict);

Object Hierarchy


  GObject
   +----GnomeDbDict

Properties


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

Signals


"changed"   void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     user_data)      : Run first
"graph-added"
            void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first
"graph-removed"
            void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first
"graph-updated"
            void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first
"layout-added"
            void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first
"layout-removed"
            void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first
"layout-updated"
            void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first
"query-added"
            void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first
"query-removed"
            void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first
"query-updated"
            void        user_function      (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

Description

This object is a "container" for all the objects which are used within the libgnomedb library: connection to the DBMS server (through a GnomeDbServer object), database structure (through a GnomeDbDatabase object) and queries (GnomeDbQuery objects).

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

When the GnomeDbDict object is destroyed, it calls mg_base_nullify() on _ALL_ the GnomeDbQuery objects which have been defined at any point using that GnomeDbDict object. So, this means that any object/widget creating GnomeDbQuery objects for their own purpose must make sure to listen to the "nullified" signal of every GnomeDbQuery they created (and release any reference they might have using g_object_unref()), unless of course they are always destroyed before the GnomeDbDict object is itself destroyed.

The libgnomedb library has de default builtin dictionary object created when the gnome_db_init() function is called, which can be retreived using the gnome_db_get_default_dict() function.

Details

GnomeDbDict

typedef struct _GnomeDbDict GnomeDbDict;


GnomeDbDictPrivate

typedef struct _GnomeDbDictPrivate GnomeDbDictPrivate;


gnome_db_dict_get_type ()

GType       gnome_db_dict_get_type          (void);

Returns :

gnome_db_dict_new ()

GObject*    gnome_db_dict_new               (void);

Create a new GnomeDbDict object.

Returns : the newly created object.

gnome_db_dict_compute_xml_filename ()

gchar*      gnome_db_dict_compute_xml_filename
                                            (GnomeDbDict *dict,
                                             const gchar *datasource,
                                             const gchar *app_id,
                                             GError **error);

Get the prefered filename which represents the data dictionary associated to the datasource data source. Using the returned value in conjunction with gnome_db_dict_load_xml_file() and gnome_db_dict_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 dictionary.

dict : a GnomeDbDict object
datasource : a data source
app_id : an extra identification, or NULL
error : location to store error, or NULL
Returns : a new string

gnome_db_dict_set_xml_filename ()

void        gnome_db_dict_set_xml_filename  (GnomeDbDict *dict,
                                             const gchar *xmlfile);

Sets the filename dict will use when gnome_db_dict_save_xml() and gnome_db_dict_load_xml() are called.

dict : a GnomeDbDict object
xmlfile : a file name

gnome_db_dict_get_xml_filename ()

const gchar* gnome_db_dict_get_xml_filename (GnomeDbDict *dict);

Get the filename dict will use when gnome_db_dict_save_xml() and gnome_db_dict_load_xml() are called.

dict : a GnomeDbDict object
Returns : the filename, or NULL if none have been set.

gnome_db_dict_load_xml ()

gboolean    gnome_db_dict_load_xml          (GnomeDbDict *dict,
                                             GError **error);

Loads an XML file which respects the Libgnomedb 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 GnomeDbDict 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 GnomeDbDict object is left as empty as when it is first created.

The file loaded is the one specified using gnome_db_dict_set_xml_filename()

dict : a GnomeDbDict object
error : location to store error, or NULL
Returns : TRUE if loading was successfull and FALSE otherwise.

gnome_db_dict_save_xml ()

gboolean    gnome_db_dict_save_xml          (GnomeDbDict *dict,
                                             GError **error);

Saves the contents of a GnomeDbDict object to a file which is specified using the gnome_db_dict_set_xml_filename() method.

dict : a GnomeDbDict object
error : location to store error, or NULL
Returns : TRUE if saving was successfull and FALSE otherwise.

gnome_db_dict_load_xml_file ()

gboolean    gnome_db_dict_load_xml_file     (GnomeDbDict *dict,
                                             const gchar *xmlfile,
                                             GError **error);

Loads an XML file which respects the Libgnomedb 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 GnomeDbDict 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 GnomeDbDict object is left as empty as when it is first created.

dict : a GnomeDbDict 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.

gnome_db_dict_save_xml_file ()

gboolean    gnome_db_dict_save_xml_file     (GnomeDbDict *dict,
                                             const gchar *xmlfile,
                                             GError **error);

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

dict : a GnomeDbDict 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.

gnome_db_dict_declare_query ()

void        gnome_db_dict_declare_query     (GnomeDbDict *dict,
                                             GnomeDbQuery *query);

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

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

dict : a GnomeDbDict object
query : a GnomeDbQuery object

gnome_db_dict_assume_query ()

void        gnome_db_dict_assume_query      (GnomeDbDict *dict,
                                             GnomeDbQuery *query);

Force dict to manage query: it will get a reference to it.

dict : a GnomeDbDict object
query : a GnomeDbQuery object

gnome_db_dict_unassume_query ()

void        gnome_db_dict_unassume_query    (GnomeDbDict *dict,
                                             GnomeDbQuery *query);

Forces dict to lose a reference it has on query

dict : a GnomeDbDict object
query : a GnomeDbQuery object

gnome_db_dict_get_queries ()

GSList*     gnome_db_dict_get_queries       (GnomeDbDict *dict);

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

dict : a GnomeDbDict object
Returns : a new list of GnomeDbQuery objects

gnome_db_dict_get_query_by_xml_id ()

GnomeDbQuery* gnome_db_dict_get_query_by_xml_id
                                            (GnomeDbDict *dict,
                                             const gchar *xml_id);

Find a GnomeDbQuery object from its XML Id

dict : a GnomeDbDict object
xml_id : the XML Id of the query being searched
Returns : the GnomeDbQuery object, or NULL if not found

gnome_db_dict_declare_graph ()

void        gnome_db_dict_declare_graph     (GnomeDbDict *dict,
                                             GnomeDbGraph *graph);

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

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

dict : a GnomeDbDict object
graph : a GnomeDbGraph object

gnome_db_dict_assume_graph ()

void        gnome_db_dict_assume_graph      (GnomeDbDict *dict,
                                             GnomeDbGraph *graph);

Force dict to manage graph: it will get a reference to it.

dict : a GnomeDbDict object
graph : a GnomeDbGraph object

gnome_db_dict_unassume_graph ()

void        gnome_db_dict_unassume_graph    (GnomeDbDict *dict,
                                             GnomeDbGraph *graph);

Forces dict to lose a reference it has on graph

dict : a GnomeDbDict object
graph : a GnomeDbGraph object

gnome_db_dict_get_graphs ()

GSList*     gnome_db_dict_get_graphs        (GnomeDbDict *dict,
                                             GnomeDbGraphType type_of_graphs);

Get a list of the graphs managed by dict, which are of the requested type.

dict : a GnomeDbDict object
type_of_graphs : the requested type of graphs
Returns : a new list of GnomeDbGraph objects

gnome_db_dict_get_graph_by_xml_id ()

GnomeDbGraph* gnome_db_dict_get_graph_by_xml_id
                                            (GnomeDbDict *dict,
                                             const gchar *xml_id);

Find a GnomeDbGraph object from its XML Id

dict : a GnomeDbDict object
xml_id : the XML Id of the graph being searched
Returns : the GnomeDbGraph object, or NULL if not found

gnome_db_dict_get_graph_for_object ()

GnomeDbGraph* gnome_db_dict_get_graph_for_object
                                            (GnomeDbDict *dict,
                                             GObject *obj);

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

dict : a GnomeDbDict object
obj : a Gobject object
Returns : the GnomeDbGraph object, or NULL if not found

gnome_db_dict_declare_layout ()

void        gnome_db_dict_declare_layout    (GnomeDbDict *dict,
                                             GnomeDbCustomLayout *layout);

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

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

dict : a GnomeDbDict object
layout : a GnomeDbLayout object

gnome_db_dict_assume_layout ()

void        gnome_db_dict_assume_layout     (GnomeDbDict *dict,
                                             GnomeDbCustomLayout *layout);

Force dict to manage layout: it will get a reference to it.

dict : a GnomeDbDict object
layout : a GnomeDbCustomLayout object

gnome_db_dict_unassume_layout ()

void        gnome_db_dict_unassume_layout   (GnomeDbDict *dict,
                                             GnomeDbCustomLayout *layout);

Forces dict to lose a reference it has on layout

dict : a GnomeDbDict object
layout : a GnomeDbCustomLayout object

gnome_db_dict_get_layouts ()

GSList*     gnome_db_dict_get_layouts       (GnomeDbDict *dict);

Get a list of all the layouts managed by dict

dict : a GnomeDbDict object
Returns : a new list of GnomeDbCustomLayout objects

gnome_db_dict_get_layout_by_xml_id ()

GnomeDbCustomLayout* gnome_db_dict_get_layout_by_xml_id
                                            (GnomeDbDict *dict,
                                             const gchar *xml_id);

Find a GnomeDbCustomLayout object from its XML Id

dict : a GnomeDbDict object
xml_id : the XML Id of the layout being searched
Returns : the GnomeDbCustomLayout object, or NULL if not found

gnome_db_dict_get_server ()

GnomeDbServer* gnome_db_dict_get_server     (GnomeDbDict *dict);

Fetch a pointer to the GnomeDbServer used by the GnomeDbDict object.

dict : a GnomeDbDict object
Returns : a pointer to the GnomeDbServer

gnome_db_dict_get_database ()

GnomeDbDatabase* gnome_db_dict_get_database (GnomeDbDict *dict);

Fetch a pointer to the GnomeDbDatabase used by the GnomeDbDict object.

dict : a GnomeDbDict object
Returns : a pointer to the GnomeDbDatabase

gnome_db_dict_get_entities_fk_constraints ()

GSList*     gnome_db_dict_get_entities_fk_constraints
                                            (GnomeDbDict *dict,
                                             GnomeDbEntity *entity1,
                                             GnomeDbEntity *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 GnomeDbTable objects, then the constraints are the ones from the database.

Constraints are represented as GnomeDbConstraint objects.

dict : a GnomeDbDict object
entity1 : an object implementing the GnomeDbEntity interface
entity2 : an object implementing the GnomeDbEntity 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

gnome_db_dict_dump ()

void        gnome_db_dict_dump              (GnomeDbDict *dict);

Dumps the whole dictionary managed by the GnomeDbDict object

dict : a GnomeDbDict object

Property Details

The "graph-serial" property

  "graph-serial"         guint                 : Read

Allowed values: >= 1

Default value: 1


The "layout-serial" property

  "layout-serial"        guint                 : Read

Allowed values: >= 1

Default value: 1


The "query-serial" property

  "query-serial"         guint                 : Read

Allowed values: >= 1

Default value: 1

Signal Details

The "changed" signal

void        user_function                  (GnomeDbDict *dbdict,
                                            gpointer     user_data)      : Run first

dbdict : the object which received the signal.
user_data : user data set when the signal handler was connected.

The "graph-added" signal

void        user_function                  (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

dbdict : 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                  (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

dbdict : 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                  (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

dbdict : 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                  (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

dbdict : 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                  (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

dbdict : 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                  (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

dbdict : 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                  (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

dbdict : 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                  (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

dbdict : 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                  (GnomeDbDict *dbdict,
                                            gpointer     arg1,
                                            gpointer     user_data)      : Run first

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