GdaDict

GdaDict — GDA dictionary

Functions

GdaDict * gda_dict_new ()
void gda_dict_extend_with_functions ()
void gda_dict_set_connection ()
GdaConnection * gda_dict_get_connection ()
GdaDictDatabase * gda_dict_get_database ()
void gda_dict_declare_object_string_id_change ()
GdaObject * gda_dict_get_object_by_string_id ()
gboolean gda_dict_update_dbms_meta_data ()
void gda_dict_stop_update_dbms_meta_data ()
gchar * gda_dict_compute_xml_filename ()
void gda_dict_set_xml_filename ()
const gchar * gda_dict_get_xml_filename ()
gboolean gda_dict_load ()
gboolean gda_dict_save ()
gboolean gda_dict_load_xml_file ()
gboolean gda_dict_save_xml_file ()
GdaDataHandler * gda_dict_get_handler ()
GdaDataHandler * gda_dict_get_default_handler ()
#define gda_dict_get_queries()
#define gda_dict_get_query_by_xml_id()
#define gda_dict_get_dict_types()
#define gda_dict_get_dict_type_by_name()
#define gda_dict_get_dict_type_by_xml_id()
#define gda_dict_get_functions()
#define gda_dict_get_functions_by_name()
#define gda_dict_get_function_by_name_arg()
#define gda_dict_get_function_by_xml_id()
#define gda_dict_get_function_by_dbms_id()
#define gda_dict_get_aggregates()
#define gda_dict_get_aggregates_by_name()
#define gda_dict_get_aggregate_by_name_arg()
#define gda_dict_get_aggregate_by_xml_id()
#define gda_dict_get_aggregate_by_dbms_id()
void gda_dict_declare_object ()
void gda_dict_declare_object_as ()
void gda_dict_assume_object ()
void gda_dict_assume_object_as ()
void gda_dict_unassume_object ()
gboolean gda_dict_object_is_assumed ()
GSList * gda_dict_get_objects ()
GdaObject * gda_dict_get_object_by_name ()
GdaObject * gda_dict_get_object_by_xml_id ()

Properties

gchar * dsn Read / Write
gchar * username Read / Write

Signals

void changed Run First
void data-update-finished Run First
void data-update-started Run First
void object-act-changed Run First
void object-added Run First
void object-removed Run First
void object-updated Run First
void update-progress Run First

Types and Values

  GdaDict

Object Hierarchy

    GObject
    ╰── GdaDict

Description

This object is a "proxy repository" for all the 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.

Functions

gda_dict_new ()

GdaDict *
gda_dict_new (void);

Create a new GdaDict object.

Returns

the newly created object.


gda_dict_extend_with_functions ()

void
gda_dict_extend_with_functions (GdaDict *dict);

Make dict handle functions and aggregates

Parameters

dict

a GdaDict object

 

gda_dict_set_connection ()

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, and when manipulating data (the gda_dict_get_handler() method). Sets the associated connection to dict. This connection is then used when the dictionary is synchronised (using the gda_dict_update_dbms_meta_data() method), when manipulating data (using the gda_dict_get_handler() method) and when executing GdaQuery queries (using the gda_query_execute() method)

Parameters

dict

a GdaDict object

 

cnc

a GdaConnection object

 

gda_dict_get_connection ()

GdaConnection *
gda_dict_get_connection (GdaDict *dict);

Fetch a pointer to the GdaConnection used by the GdaDict object.

Parameters

dict

a GdaDict object

 

Returns

a pointer to the GdaConnection, if one has been assigned to dict


gda_dict_get_database ()

GdaDictDatabase *
gda_dict_get_database (GdaDict *dict);

Fetch a pointer to the GdaDictDatabase used by the GdaDict object.

Parameters

dict

a GdaDict object

 

Returns

a pointer to the GdaDictDatabase


gda_dict_declare_object_string_id_change ()

void
gda_dict_declare_object_string_id_change
                               (GdaDict *dict,
                                GdaObject *obj,
                                const gchar *oldid);

Internal function, not to be used directly.


gda_dict_get_object_by_string_id ()

GdaObject *
gda_dict_get_object_by_string_id (GdaDict *dict,
                                  const gchar *strid);

Fetch a pointer to the GdaObject which has the strid string ID.

Parameters

dict

a GdaDict object

 

strid

a string

 

Returns

the corresponding GdaObject, or NULL if none found


gda_dict_update_dbms_meta_data ()

gboolean
gda_dict_update_dbms_meta_data (GdaDict *dict,
                                GType limit_to_type,
                                const gchar *limit_obj_name,
                                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 .

Parameters

dict

a GdaDict object

 

limit_to_type

limit the DBMS update to this type, or 0 for no limit

 

limit_obj_name

limit the DBMS update to objects of this name, or NULL for no limit

 

error

location to store error, or NULL

 

Returns

TRUE if no error


gda_dict_stop_update_dbms_meta_data ()

void
gda_dict_stop_update_dbms_meta_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.

Parameters

dict

a GdaDict object

 

gda_dict_compute_xml_filename ()

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.

Parameters

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


gda_dict_set_xml_filename ()

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.

Parameters

dict

a GdaDict object

 

xmlfile

a file name

 

gda_dict_get_xml_filename ()

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.

Parameters

dict

a GdaDict object

 

Returns

the filename, or NULL if none have been set.


gda_dict_load ()

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()

Parameters

dict

a GdaDict object

 

error

location to store error, or NULL

 

Returns

TRUE if loading was successfull and FALSE otherwise.


gda_dict_save ()

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.

Parameters

dict

a GdaDict object

 

error

location to store error, or NULL

 

Returns

TRUE if saving was successfull and FALSE otherwise.


gda_dict_load_xml_file ()

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.

Parameters

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.


gda_dict_save_xml_file ()

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.

Parameters

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.


gda_dict_get_handler ()

GdaDataHandler *
gda_dict_get_handler (GdaDict *dict,
                      GType for_type);

Obtain a pointer to a GdaDataHandler which can convert GValue values of type for_type .

Unlike the gda_dict_get_default_handler() method, this method asks the provider (for the connection assigned to dict using gda_dict_set_connection()) if there is any.

It fallbacks to the same data handler as gda_dict_get_default_handler() if no connection has been assigned, or if the assigned'd provider offers no data handler for that type.

The returned pointer is NULL if there is no data handler available for the for_type type.

Parameters

dict

a GdaDict object

 

for_type

a GType type

 

Returns

a GdaDataHandler


gda_dict_get_default_handler ()

GdaDataHandler *
gda_dict_get_default_handler (GdaDict *dict,
                              GType for_type);

Obtain a pointer to a GdaDataHandler which can manage GValue values of type for_type

The returned pointer is NULL if there is no default data handler available for the for_type data type

Parameters

dict

a GdaDict object

 

for_type

a GType type

 

Returns

a GdaDataHandler


gda_dict_get_queries()

#define gda_dict_get_queries(dict) gda_dict_get_objects((dict), GDA_TYPE_QUERY)

Returns


gda_dict_get_query_by_xml_id()

#define gda_dict_get_query_by_xml_id(dict,xml_id) ((GdaQuery*)gda_dict_get_object_by_xml_id((dict), GDA_TYPE_QUERY, (xml_id)))

Returns


gda_dict_get_dict_types()

#define gda_dict_get_dict_types(dict) gda_dict_get_objects((dict), GDA_TYPE_DICT_TYPE)

Returns


gda_dict_get_dict_type_by_name()

#define gda_dict_get_dict_type_by_name(dict,type_name) ((GdaDictType*)gda_dict_get_object_by_name((dict), GDA_TYPE_DICT_TYPE, (type_name)))

Returns


gda_dict_get_dict_type_by_xml_id()

#define gda_dict_get_dict_type_by_xml_id(dict,xml_id) ((GdaDictType*)gda_dict_get_object_by_xml_id((dict), GDA_TYPE_DICT_TYPE, (xml_id)))

Returns


gda_dict_get_functions()

#define gda_dict_get_functions(dict) gda_dict_get_objects ((dict), GDA_TYPE_DICT_FUNCTION)

Returns


gda_dict_get_functions_by_name()

#define gda_dict_get_functions_by_name(dict,funcname) gda_functions_get_by_name ((dict), (funcname))

Returns


gda_dict_get_function_by_name_arg()

#define gda_dict_get_function_by_name_arg(dict,funcname,argtypes) gda_functions_get_by_name_arg ((dict), (funcname), (argtypes))

Returns


gda_dict_get_function_by_xml_id()

#define gda_dict_get_function_by_xml_id(dict,xml_id) gda_dict_get_object_by_xml_id ((dict), GDA_TYPE_DICT_FUNCTION, (xml_id))

Returns


gda_dict_get_function_by_dbms_id()

#define gda_dict_get_function_by_dbms_id(dict,dbms_id) gda_functions_get_by_dbms_id ((dict), (dbms_id))

To find a DBMS functions which is uniquely identified by its name and the type of its argument.

Parameters

dict

a GdaDict object

 

Returns

The function or NULL if not found


gda_dict_get_aggregates()

#define gda_dict_get_aggregates(dict) gda_dict_get_objects((dict), GDA_TYPE_DICT_AGGREGATE)

Returns


gda_dict_get_aggregates_by_name()

#define gda_dict_get_aggregates_by_name(dict,aggname) gda_aggregates_get_by_name((dict), (aggname))

Returns


gda_dict_get_aggregate_by_name_arg()

#define gda_dict_get_aggregate_by_name_arg(dict,argname,argtype) gda_aggregates_get_by_name_arg ((dict), (argname), (argtype))

Returns


gda_dict_get_aggregate_by_xml_id()

#define gda_dict_get_aggregate_by_xml_id(dict,xml_id) gda_dict_get_object_by_xml_id((dict), GDA_TYPE_DICT_AGGREGATE, (xml_id))

Returns


gda_dict_get_aggregate_by_dbms_id()

#define gda_dict_get_aggregate_by_dbms_id(dict,dbmsid) gda_aggregates_get_by_dbms_id((dict),(dbmsid))

Returns


gda_dict_declare_object ()

void
gda_dict_declare_object (GdaDict *dict,
                         GdaObject *object);

Declares the existence of a new object to dict : dict knows about object but does not hold any reference to it. If dict must hold such a reference, then use gda_dict_assume_object().

Parameters

dict

a GdaDict object

 

object

a GdaObject object

 

gda_dict_declare_object_as ()

void
gda_dict_declare_object_as (GdaDict *dict,
                            GdaObject *object,
                            GType as_type);

Same as gda_dict_declare_object() but forces to use the as_type type instead of object 's realtype

Parameters

dict

a GdaDict object

 

object

a GdaObject object

 

as_type

type parent type of object to take into account

 

gda_dict_assume_object ()

void
gda_dict_assume_object (GdaDict *dict,
                        GdaObject *object);

Declares the existence of a new object to dict , and force dict to hold a reference to object so it is not destroyed.

Parameters

dict

a GdaDict object

 

object

a GdaObject object

 

gda_dict_assume_object_as ()

void
gda_dict_assume_object_as (GdaDict *dict,
                           GdaObject *object,
                           GType as_type);

Same as gda_dict_assume_object() but forces to use the as_type type instead of object 's realtype

Parameters

dict

a GdaDict object

 

object

a GdaObject object

 

as_type

parent type of object to take into account

 

gda_dict_unassume_object ()

void
gda_dict_unassume_object (GdaDict *dict,
                          GdaObject *object);

Makes dict release its reference on object .

Parameters

dict

a GdaDict object

 

object

a GdaObject object

 

gda_dict_object_is_assumed ()

gboolean
gda_dict_object_is_assumed (GdaDict *dict,
                            GdaObject *object);

Tests if object is assumed by dict

Parameters

dict

a GdaDict object

 

object

a GdaObject object

 

Returns

TRUE if object is assumed by dict


gda_dict_get_objects ()

GSList *
gda_dict_get_objects (GdaDict *dict,
                      GType type);

Parameters

dict

a GdaDict object

 

type

a Gtype type of object

 

Returns

a new list of all the objects of type type managed by dict .


gda_dict_get_object_by_name ()

GdaObject *
gda_dict_get_object_by_name (GdaDict *dict,
                             GType type,
                             const gchar *name);

Tries to find an object from its name, among the objects managed by dict of type type .

Parameters

dict

a GdaDict object

 

type

a Gtype type of object

 

name

the requested name

 

Returns

a pointer to the requested object, or NULL if the object was not found


gda_dict_get_object_by_xml_id ()

GdaObject *
gda_dict_get_object_by_xml_id (GdaDict *dict,
                               GType type,
                               const gchar *xml_id);

For the objects which implement the GdaXmlStorage interface, this function allows to find an object from its XML Id. The object is looked from the managed objects of type type , and also from the list of all declared objects.

Parameters

dict

a GdaDict object

 

type

a Gtype type of object

 

Returns

a pointer to the requested object, or NULL if the object was not found

Types and Values

GdaDict

typedef struct _GdaDict GdaDict;

Property Details

The “dsn” property

  “dsn”                      gchar *

Flags: Read / Write

Default value: NULL


The “username” property

  “username”                 gchar *

Flags: Read / Write

Default value: NULL

Signal Details

The “changed” signal

void
user_function (GdaDict *gdadict,
               gpointer user_data)

Parameters

dbdict

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “data-update-finished” signal

void
user_function (GdaDict *gdadict,
               gpointer user_data)

Parameters

gdadict

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “data-update-started” signal

void
user_function (GdaDict *gdadict,
               gpointer user_data)

Parameters

gdadict

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “object-act-changed” signal

void
user_function (GdaDict   *gdadict,
               GdaObject *arg1,
               gpointer   user_data)

Parameters

gdadict

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “object-added” signal

void
user_function (GdaDict   *gdadict,
               GdaObject *arg1,
               gpointer   user_data)

Parameters

gdadict

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “object-removed” signal

void
user_function (GdaDict   *gdadict,
               GdaObject *arg1,
               gpointer   user_data)

Parameters

gdadict

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “object-updated” signal

void
user_function (GdaDict   *gdadict,
               GdaObject *arg1,
               gpointer   user_data)

Parameters

gdadict

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “update-progress” signal

void
user_function (GdaDict *gdadict,
               gchar   *arg1,
               guint    arg2,
               guint    arg3,
               gpointer user_data)

Parameters

gdadict

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First