![]() |
![]() |
![]() |
GNOME Data Access manual | ![]() |
---|
GdaDictGdaDict — GDA dictionary |
GdaDict; GObject* gda_dict_new (void); gboolean gda_dict_load_xml_file (GdaDict *dict, const gchar *xmlfile, GError **error); gboolean gda_dict_save_xml_file (GdaDict *dict, const gchar *xmlfile, GError **error); void gda_dict_declare_query (GdaDict *dict, GdaQuery *query); void gda_dict_assume_query (GdaDict *dict, GdaQuery *query); void gda_dict_unassume_query (GdaDict *dict, GdaQuery *query); GSList* gda_dict_get_queries (GdaDict *dict); GdaQuery* gda_dict_get_query_by_xml_id (GdaDict *dict, const gchar *xml_id); void gda_dict_declare_graph (GdaDict *dict, GdaGraph *graph); void gda_dict_assume_graph (GdaDict *dict, GdaGraph *graph); void gda_dict_unassume_graph (GdaDict *dict, GdaGraph *graph); GSList* gda_dict_get_graphs (GdaDict *dict, GdaGraphType type_of_graphs); GdaGraph* gda_dict_get_graph_by_xml_id (GdaDict *dict, const gchar *xml_id); GdaGraph* gda_dict_get_graph_for_object (GdaDict *dict, GObject *obj); GdaConnection* gda_dict_get_connection (GdaDict *dict); void gda_dict_set_connection (GdaDict *dict, GdaConnection *cnc); GdaDictDatabase* gda_dict_get_database (GdaDict *dict); void gda_dict_dump (GdaDict *dict); gboolean gda_dict_update_dbms_data (GdaDict *dict, GError **error); void gda_dict_stop_update_dbms_data (GdaDict *dict); gchar* gda_dict_compute_xml_filename (GdaDict *dict, const gchar *datasource, const gchar *app_id, GError **error); void gda_dict_set_xml_filename (GdaDict *dict, const gchar *xmlfile); const gchar* gda_dict_get_xml_filename (GdaDict *dict); gboolean gda_dict_load (GdaDict *dict, GError **error); gboolean gda_dict_save (GdaDict *dict, GError **error); GSList* gda_dict_get_entities_fk_constraints (GdaDict *dict, GdaEntity *entity1, GdaEntity *entity2, gboolean entity1_has_fk); GSList* gda_dict_get_data_types (GdaDict *dict); GdaDictType* gda_dict_get_data_type_by_name (GdaDict *dict, const gchar *type_name); void gda_connection_add_data_type (GdaDict *dict, GdaDictType *datatype); GdaDictType* gda_dict_get_data_type_by_xml_id (GdaDict *dict, const gchar *xml_id); gboolean gda_dict_declare_custom_data_type (GdaDict *dict, GdaDictType *type); GSList* gda_dict_get_functions (GdaDict *dict); GSList* gda_dict_get_functions_by_name (GdaDict *dict, const gchar *funcname); GdaDictFunction* gda_dict_get_function_by_name_arg (GdaDict *dict, const gchar *funcname, const GSList *argtypes); GdaDictFunction* gda_dict_get_function_by_dbms_id (GdaDict *dict, const gchar *dbms_id); GdaDictFunction* gda_dict_get_function_by_xml_id (GdaDict *dict, const gchar *xml_id); GSList* gda_dict_get_aggregates (GdaDict *dict); GSList* gda_dict_get_aggregates_by_name (GdaDict *dict, const gchar *aggname); GdaDictAggregate* gda_dict_get_aggregate_by_name_arg (GdaDict *dict, const gchar *aggname, GdaDictType *argtype); GdaDictAggregate* gda_dict_get_aggregate_by_dbms_id (GdaDict *dict, const gchar *dbms_id); GdaDictAggregate* gda_dict_get_aggregate_by_xml_id (GdaDict *dict, const gchar *xml_id); GdaDataHandler* gda_dict_get_default_handler (GdaDict *dict, GdaValueType for_type);
"dsn" gchararray : Read / Write "graph-serial" guint : Read "query-serial" guint : Read "username" gchararray : Read / Write "with-functions" gboolean : Read / Write
"aggregate-added" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "aggregate-removed" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "aggregate-updated" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "changed" void user_function (GdaDict *gdadict, gpointer user_data); "data-type-added" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "data-type-removed" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "data-type-updated" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "data-update-finished" void user_function (GdaDict *gdadict, gpointer user_data); "data-update-started" void user_function (GdaDict *gdadict, gpointer user_data); "function-added" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "function-removed" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "function-updated" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "graph-added" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "graph-removed" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "graph-updated" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "query-added" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "query-removed" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "query-updated" void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data); "update-progress" void user_function (GdaDict *gdadict, gpointer arg1, guint arg2, guint arg3, gpointer user_data);
This object is a "proxy repository" for all the objects:
existing within a database such as data types (see the GdaDictType object), functions (see the GdaDictFunction object), aggregates (see the GdaDictAggregate object), and the database structure (through the GdaDictDatabase and associated object)
pre-defined queries as GdaQuery objects
graphs as GdaGraph objects
Each GdaDict object can be saved to an XML file and loaded back in an efficient way; any GdaDict object can be assigned a GdaConnection object which tells it how to use a real connection to a data source.
The GdaDict object is responsible for the life management of all the objects it handles; see the GdaObject object for more information.
GObject* gda_dict_new (void);
Create a new GdaDict object.
Returns : | the newly created object. |
gboolean gda_dict_load_xml_file (GdaDict *dict, const gchar *xmlfile, GError **error);
Loads an XML file which respects the Libgda 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 GdaDict object already has some contents, then it is first of all destroyed (to return its state as when it was first created).
If an error occurs during loading then the GdaDict object is left as empty as when it is first created.
dict : |
a GdaDict 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. |
gboolean gda_dict_save_xml_file (GdaDict *dict, const gchar *xmlfile, GError **error);
Saves the contents of a GdaDict object to a file which is given as argument.
dict : |
a GdaDict 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. |
void gda_dict_declare_query (GdaDict *dict, GdaQuery *query);
Declares the existence of a new query to dict
. All the GdaQuery objects MUST
be declared to the corresponding GdaDict 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 gda_dict_assume_query()
.
This functions is called automatically from each gda_query_new* function, and it should not be necessary to call it except for classes extending the GdaQuery class.
void gda_dict_assume_query (GdaDict *dict, GdaQuery *query);
Force dict
to manage query
: it will get a reference to it.
void gda_dict_unassume_query (GdaDict *dict, GdaQuery *query);
Forces dict
to lose a reference it has on query
GSList* gda_dict_get_queries (GdaDict *dict);
Get a list of all the non interdependant queries managed by dict
(only queries with no parent query are listed)
GdaQuery* gda_dict_get_query_by_xml_id (GdaDict *dict, const gchar *xml_id);
Find a GdaQuery object from its XML Id
void gda_dict_declare_graph (GdaDict *dict, GdaGraph *graph);
Declares the existence of a new graph to dict
. All the GdaGraph objects MUST
be declared to the corresponding GdaDict 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 gda_dict_assume_graph()
.
This functions is called automatically from each gda_graph_new* function, and it should not be necessary to call it except for classes extending the GdaGraph class.
void gda_dict_assume_graph (GdaDict *dict, GdaGraph *graph);
Force dict
to manage graph
: it will get a reference to it.
void gda_dict_unassume_graph (GdaDict *dict, GdaGraph *graph);
Forces dict
to lose a reference it has on graph
GSList* gda_dict_get_graphs (GdaDict *dict, GdaGraphType type_of_graphs);
Get a list of the graphs managed by dict
, which are of the
requested type.
GdaGraph* gda_dict_get_graph_by_xml_id (GdaDict *dict, const gchar *xml_id);
Find a GdaGraph object from its XML Id
GdaGraph* gda_dict_get_graph_for_object (GdaDict *dict, GObject *obj);
Find a GdaGraph object guiven the object it is related to.
GdaConnection* gda_dict_get_connection (GdaDict *dict);
Fetch a pointer to the GdaConnection used by the GdaDict object.
dict : |
a GdaDict object |
Returns : | a pointer to the GdaConnection, if one has been assigned to dict
|
void gda_dict_set_connection (GdaDict *dict, GdaConnection *cnc);
Sets the associated connection to dict
. This connection is then used when the dictionary
synchronises itself.
dict : |
a GdaDict object |
cnc : |
a GdaConnection object |
GdaDictDatabase* gda_dict_get_database (GdaDict *dict);
Fetch a pointer to the GdaDictDatabase used by the GdaDict object.
dict : |
a GdaDict object |
Returns : | a pointer to the GdaDictDatabase |
void gda_dict_dump (GdaDict *dict);
Dumps the whole dictionary managed by the GdaDict object
dict : |
a GdaDict object |
gboolean gda_dict_update_dbms_data (GdaDict *dict, GError **error);
Updates the list of data types, functions, tables, etc from the database,
which means that the dict
object uses an opened connection to the DBMS.
Use gda_dict_set_connection()
to set a GdaConnection to dict
.
dict : |
a GdaDict object |
error : |
location to store error, or NULL
|
Returns : | TRUE if no error |
void gda_dict_stop_update_dbms_data (GdaDict *dict);
When the dictionary updates its internal lists of DBMS objects, a call to this function will stop that update process. It has no effect when the dictionary is not updating its DBMS data.
dict : |
a GdaDict object |
gchar* gda_dict_compute_xml_filename (GdaDict *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 gda_dict_load_xml_file()
and gda_dict_save_xml_file()
has
the advantage of letting the library handle file naming onventions.
if datasource
is NULL
, and a GdaConnection object has been assigned to dict
, then the returned
string will take into account the data source used by that connection.
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 GdaDict object |
datasource : |
a data source, or NULL
|
app_id : |
an extra identification, or NULL
|
error : |
location to store error, or NULL
|
Returns : | a new string |
void gda_dict_set_xml_filename (GdaDict *dict, const gchar *xmlfile);
Sets the filename dict
will use when gda_dict_save_xml()
and gda_dict_load_xml()
are called.
dict : |
a GdaDict object |
xmlfile : |
a file name |
const gchar* gda_dict_get_xml_filename (GdaDict *dict);
Get the filename dict
will use when gda_dict_save_xml()
and gda_dict_load_xml()
are called.
dict : |
a GdaDict object |
Returns : | the filename, or NULL if none have been set.
|
gboolean gda_dict_load (GdaDict *dict, GError **error);
Loads an XML file which respects the Libgda 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 GdaDict object already has some contents, then it is first of all destroyed (to return its state as when it was first created).
If an error occurs during loading then the GdaDict object is left as empty as when it is first created.
The file loaded is the one specified using gda_dict_set_xml_filename()
dict : |
a GdaDict object |
error : |
location to store error, or NULL
|
Returns : | TRUE if loading was successfull and FALSE otherwise. |
gboolean gda_dict_save (GdaDict *dict, GError **error);
Saves the contents of a GdaDict object to a file which is specified using the
gda_dict_set_xml_filename()
method.
dict : |
a GdaDict object |
error : |
location to store error, or NULL
|
Returns : | TRUE if saving was successfull and FALSE otherwise. |
GSList* gda_dict_get_entities_fk_constraints (GdaDict *dict, GdaEntity *entity1, GdaEntity *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 GdaDictTable objects, then the
constraints are the ones from the database.
Constraints are represented as GdaDictConstraint objects.
GSList* gda_dict_get_data_types (GdaDict *dict);
Get the list of data types;
dict : |
a GdaDict object |
Returns : | the list (the caller must free the list after usage) |
GdaDictType* gda_dict_get_data_type_by_name (GdaDict *dict, const gchar *type_name);
Find a data type from its DBMS name or from one of its synonyms if it has some.
dict : |
a GdaDict object |
type_name : |
the name of the requested data type |
Returns : | the data type or NULL if it cannot be found
|
void gda_connection_add_data_type (GdaDict *dict, GdaDictType *datatype);
dict : |
|
datatype : |
GdaDictType* gda_dict_get_data_type_by_xml_id (GdaDict *dict, const gchar *xml_id);
To find a GdaDictType using its XML id.
dict : |
a GdaDict object |
xml_id : |
the XML identifier of the data type to be found |
Returns : | the data type or NULL if it cannot be found
|
gboolean gda_dict_declare_custom_data_type (GdaDict *dict, GdaDictType *type);
Forces dict
to consider type
as a new data type even though that data type
is not declared by the database to which dict
can be connected to.
dict : |
a GdaDict object |
type : |
a GdaDictType object |
Returns : | TRUE if the data type does not already exist, and FALSE if it does. |
GSList* gda_dict_get_functions (GdaDict *dict);
To get the complete list of functions
dict : |
a GdaDict object |
Returns : | the allocated list of functions |
GSList* gda_dict_get_functions_by_name (GdaDict *dict, const gchar *funcname);
To get the list of DBMS functions which match the given name.
dict : |
a GdaDict object |
funcname : |
name of the function |
Returns : | the allocated list of functions |
GdaDictFunction* gda_dict_get_function_by_name_arg (GdaDict *dict, const gchar *funcname, const GSList *argtypes);
To find a DBMS function which is uniquely identified by its name and the type(s) of its argument(s).
About the functions accepting any data type for one of their argument: if the corresponding data type in
argtypes
is not NULL
, then such a function will be a candidate, and if the corresponding data type in
argtypes
is NULL
, then only such a function will be a candidate.
dict : |
a GdaDict object |
funcname : |
name of the function |
argtypes : |
a list of GdaDictType objects |
Returns : | The function or NULL if not found |
GdaDictFunction* gda_dict_get_function_by_dbms_id (GdaDict *dict, const gchar *dbms_id);
To find a DBMS functions which is uniquely identified by its DBMS identifier
dict : |
a GdaDict object |
dbms_id : |
|
Returns : | The function or NULL if not found |
GdaDictFunction* gda_dict_get_function_by_xml_id (GdaDict *dict, const gchar *xml_id);
To find a DBMS functions which is uniquely identified by its XML identifier
dict : |
a GdaDict object |
xml_id : |
|
Returns : | The function or NULL if not found |
GSList* gda_dict_get_aggregates (GdaDict *dict);
To get the complete list of aggregates
dict : |
a GdaDict object |
Returns : | the allocated list of aggregates |
GSList* gda_dict_get_aggregates_by_name (GdaDict *dict, const gchar *aggname);
To get the list of DBMS aggregates which match the given name.
dict : |
a GdaDict object |
aggname : |
the name of the aggregate |
Returns : | the allocated list of aggregates |
GdaDictAggregate* gda_dict_get_aggregate_by_name_arg (GdaDict *dict, const gchar *aggname, GdaDictType *argtype);
To find a DBMS aggregate which is uniquely identified by its name and the type of its argument.
About the aggregates accepting any data type for their argument: if argtype
is not NULL
then such an aggregate will be a candidate, and if argtype
is NULL
then only such an aggregate will be a candidate.
If several aggregates are found, then the aggregate completely matching will be returned, or
an aggregate where the argument type has the same GDA typa as the argtype
, or lastly an
aggregate accepting any data type as argument.
dict : |
a GdaDict object |
aggname : |
the name of the aggregate |
argtype : |
the type of argument or NULL
|
Returns : | The aggregate or NULL if not found |
GdaDictAggregate* gda_dict_get_aggregate_by_dbms_id (GdaDict *dict, const gchar *dbms_id);
To find a DBMS functions which is uniquely identified by its name and the type of its argument.
dict : |
a GdaDict object |
dbms_id : |
|
Returns : | The aggregate or NULL if not found |
GdaDictAggregate* gda_dict_get_aggregate_by_xml_id (GdaDict *dict, const gchar *xml_id);
To find a DBMS aggregates which is uniquely identified by its XML identifier
dict : |
a GdaDict object |
xml_id : |
|
Returns : | The aggregate or NULL if not found |
GdaDataHandler* gda_dict_get_default_handler (GdaDict *dict, GdaValueType for_type);
Obtain a pointer to a GdaDataHandler which can manage
GdaValue values of type for_type
The returned pointer is NULL
if for_type
is GDA_VALUE_TYPE_NULL,
or if there is no default data handler available.
dict : |
a GdaDict object |
for_type : |
a GdaValueType type |
Returns : | a GdaDataHandler |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer user_data);
dbdict : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer user_data);
gdadict : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer user_data);
gdadict : |
the object which received the signal. |
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
dbdict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
dbdict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
dbdict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
dbdict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
dbdict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, gpointer user_data);
dbdict : |
the object which received the signal. |
arg1 : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (GdaDict *gdadict, gpointer arg1, guint arg2, guint arg3, gpointer user_data);
gdadict : |
the object which received the signal. |
arg1 : |
|
arg2 : |
|
arg3 : |
|
user_data : |
user data set when the signal handler was connected. |
<< Dictionary and related objects | GdaDictType >> |