GdaDict

GdaDict — GDA dictionary

Synopsis

                    GdaDict;
GdaDict *           gda_dict_new                        (void);
void                gda_dict_extend_with_functions      (GdaDict *dict);
void                gda_dict_set_connection             (GdaDict *dict,
                                                         GdaConnection *cnc);
GdaConnection *     gda_dict_get_connection             (GdaDict *dict);
GdaDictDatabase *   gda_dict_get_database               (GdaDict *dict);
void                gda_dict_declare_object_string_id_change
                                                        (GdaDict *dict,
                                                         GdaObject *obj,
                                                         const gchar *oldid);
GdaObject *         gda_dict_get_object_by_string_id    (GdaDict *dict,
                                                         const gchar *strid);
gboolean            gda_dict_update_dbms_meta_data      (GdaDict *dict,
                                                         GType limit_to_type,
                                                         const gchar *limit_obj_name,
                                                         GError **error);
void                gda_dict_stop_update_dbms_meta_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);
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);
GdaDataHandler *    gda_dict_get_handler                (GdaDict *dict,
                                                         GType for_type);
GdaDataHandler *    gda_dict_get_default_handler        (GdaDict *dict,
                                                         GType for_type);
#define             gda_dict_get_queries                (dict)
#define             gda_dict_get_query_by_xml_id        (dict,
                                                         xml_id)
#define             gda_dict_get_dict_types             (dict)
#define             gda_dict_get_dict_type_by_name      (dict,
                                                         type_name)
#define             gda_dict_get_dict_type_by_xml_id    (dict,
                                                         xml_id)
#define             gda_dict_get_functions              (dict)
#define             gda_dict_get_functions_by_name      (dict,
                                                         funcname)
#define             gda_dict_get_function_by_name_arg   (dict,
                                                         funcname,
                                                         argtypes)
#define             gda_dict_get_function_by_xml_id     (dict,
                                                         xml_id)
#define             gda_dict_get_function_by_dbms_id    (dict,
                                                         dbms_id)
#define             gda_dict_get_aggregates             (dict)
#define             gda_dict_get_aggregates_by_name     (dict,
                                                         aggname)
#define             gda_dict_get_aggregate_by_name_arg  (dict,
                                                         argname,
                                                         argtype)
#define             gda_dict_get_aggregate_by_xml_id    (dict,
                                                         xml_id)
#define             gda_dict_get_aggregate_by_dbms_id   (dict,
                                                         dbmsid)
void                gda_dict_declare_object             (GdaDict *dict,
                                                         GdaObject *object);
void                gda_dict_declare_object_as          (GdaDict *dict,
                                                         GdaObject *object,
                                                         GType as_type);
void                gda_dict_assume_object              (GdaDict *dict,
                                                         GdaObject *object);
void                gda_dict_assume_object_as           (GdaDict *dict,
                                                         GdaObject *object,
                                                         GType as_type);
void                gda_dict_unassume_object            (GdaDict *dict,
                                                         GdaObject *object);
gboolean            gda_dict_object_is_assumed          (GdaDict *dict,
                                                         GdaObject *object);
GSList *            gda_dict_get_objects                (GdaDict *dict,
                                                         GType type);
GdaObject *         gda_dict_get_object_by_name         (GdaDict *dict,
                                                         GType type,
                                                         const gchar *name);
GdaObject *         gda_dict_get_object_by_xml_id       (GdaDict *dict,
                                                         GType type,
                                                         const gchar *xml_id);

Object Hierarchy

  GObject
   +----GdaDict

Properties

  "dsn"                      gchar*                : Read / Write
  "username"                 gchar*                : Read / Write

Signals

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

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.

Details

GdaDict

typedef struct _GdaDict GdaDict;


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

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)

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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

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)


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


gda_dict_get_dict_types()

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


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


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


gda_dict_get_functions()

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


gda_dict_get_functions_by_name()

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


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


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


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.

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)


gda_dict_get_aggregates_by_name()

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


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


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


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


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

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

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.

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

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.

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

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

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.

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.

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

Property Details

The "dsn" property

  "dsn"                      gchar*                : Read / Write

Default value: NULL


The "username" property

  "username"                 gchar*                : Read / Write

Default value: NULL

Signal Details

The "changed" signal

void                user_function                      (GdaDict *gdadict,
                                                        gpointer user_data)      : Run First

dbdict :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "data-update-finished" signal

void                user_function                      (GdaDict *gdadict,
                                                        gpointer user_data)      : Run First

gdadict :

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                      (GdaDict *gdadict,
                                                        gpointer user_data)      : Run First

gdadict :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "object-act-changed" signal

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

gdadict :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "object-added" signal

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

gdadict :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "object-removed" signal

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

gdadict :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "object-updated" signal

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

gdadict :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "update-progress" signal

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

gdadict :

the object which received the signal.

user_data :

user data set when the signal handler was connected.