![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
GdaMetaStore; enum GdaMetaStoreError; GdaMetaStoreChange; enum GdaMetaStoreChangeType; GdaMetaContext; GdaMetaStore * gda_meta_store_new (const gchar *cnc_string
); GdaMetaStore * gda_meta_store_new_with_file (const gchar *file_name
); gint gda_meta_store_get_version (GdaMetaStore *store
); gchar * gda_meta_store_sql_identifier_quote (const gchar *id
,GdaConnection *cnc
); GdaDataModel * gda_meta_store_extract (GdaMetaStore *store
,const gchar *select_sql
,GError **error
,...
); GdaDataModel * gda_meta_store_extract_v (GdaMetaStore *store
,const gchar *select_sql
,GHashTable *vars
,GError **error
); GdaMetaStruct * gda_meta_store_schema_get_structure (GdaMetaStore *store
,GError **error
); gboolean gda_meta_store_get_attribute_value (GdaMetaStore *store
,const gchar *att_name
,gchar **att_value
,GError **error
); gboolean gda_meta_store_set_attribute_value (GdaMetaStore *store
,const gchar *att_name
,const gchar *att_value
,GError **error
); gboolean gda_meta_store_schema_add_custom_object (GdaMetaStore *store
,const gchar *xml_description
,GError **error
); GdaConnection * gda_meta_store_get_internal_connection (GdaMetaStore *store
); gboolean gda_meta_store_declare_foreign_key (GdaMetaStore *store
,GdaMetaStruct *mstruct
,const gchar *fk_name
,const gchar *catalog
,const gchar *schema
,const gchar *table
,const gchar *ref_catalog
,const gchar *ref_schema
,const gchar *ref_table
,guint nb_cols
,gchar **colnames
,gchar **ref_colnames
,GError **error
); gboolean gda_meta_store_undeclare_foreign_key (GdaMetaStore *store
,GdaMetaStruct *mstruct
,const gchar *fk_name
,const gchar *catalog
,const gchar *schema
,const gchar *table
,const gchar *ref_catalog
,const gchar *ref_schema
,const gchar *ref_table
,GError **error
);
"catalog" gchar* : Write / Construct Only "cnc" GdaConnection* : Read / Write / Construct Only "cnc-string" gchar* : Write / Construct Only "schema" gchar* : Write / Construct Only
Previous versions of Libgda relied on an XML based file to store dictionary information, such as the database's schema (tables, views, etc) and various other information. The problems were that it was difficult for an application to integrate its own data into the dictionary and that there were some performances problems as the XML file needed to be parsed (and converted into its own in-memory structure) before any data could be read out of it.
The new dictionary now relies on a database structure to store its data (see the database schema section for a detailed description). The actual database can be a single file (using an SQLite database), an entirely in memory database (also using an SQLite database), or a more conventional backend such as a PostgreSQL database for a shared dictionary on a server.
The GdaMetaStore object is thread safe.
typedef enum { GDA_META_STORE_INCORRECT_SCHEMA_ERROR, GDA_META_STORE_UNSUPPORTED_PROVIDER_ERROR, GDA_META_STORE_INTERNAL_ERROR, GDA_META_STORE_META_CONTEXT_ERROR, GDA_META_STORE_MODIFY_CONTENTS_ERROR, GDA_META_STORE_EXTRACT_SQL_ERROR, GDA_META_STORE_ATTRIBUTE_NOT_FOUND_ERROR, GDA_META_STORE_ATTRIBUTE_ERROR, GDA_META_STORE_SCHEMA_OBJECT_NOT_FOUND_ERROR, GDA_META_STORE_SCHEMA_OBJECT_CONFLICT_ERROR, GDA_META_STORE_SCHEMA_OBJECT_DESCR_ERROR, GDA_META_STORE_TRANSACTION_ALREADY_STARTED_ERROR } GdaMetaStoreError;
typedef struct { /* change general information */ GdaMetaStoreChangeType c_type; gchar *table_name; GHashTable *keys; /* key = ('+' or '-') and a column position in @table (string) starting at 0, * value = a GValue pointer */ } GdaMetaStoreChange;
typedef enum { GDA_META_STORE_ADD, GDA_META_STORE_REMOVE, GDA_META_STORE_MODIFY } GdaMetaStoreChangeType;
typedef struct { gchar *table_name; gint size; gchar **column_names; GValue **column_values; } GdaMetaContext;
The GdaMetaContext represents a meta data modification
context: the how when used with gda_meta_store_modify_with_context()
,
and the what when used with gda_connection_update_meta_store()
.
The GdaMetaContext represents a meta data modification
context: the how when used with gda_meta_store_modify_with_context()
,
and the what when used with gda_connection_update_meta_store()
.
GdaMetaStore * gda_meta_store_new (const gchar *cnc_string
);
Create a new GdaMetaStore object.
|
a connection string, or NULL for an in-memory internal database. [allow-none]
|
Returns : |
the newly created object, or NULL if an error occurred. [transfer full]
|
GdaMetaStore * gda_meta_store_new_with_file (const gchar *file_name
);
Create a new GdaMetaStore object using file_name
as its internal
database
|
a file name |
Returns : |
the newly created object, or NULL if an error occurred. [transfer full]
|
gint gda_meta_store_get_version (GdaMetaStore *store
);
Get store
's internal schema's version
|
a GdaMetaStore object |
Returns : |
the version (incremented each time the schema changes, backward compatible) |
gchar * gda_meta_store_sql_identifier_quote (const gchar *id
,GdaConnection *cnc
);
Use this method to get a correctly quoted (if necessary) SQL identifier which can be used
to retrieve or filter information in a GdaMetaStore which stores meta data about cnc
.
The returned SQL identifier can be used in conjunction with gda_connection_update_meta_store()
,
gda_connection_get_meta_store_data()
, gda_connection_get_meta_store_data_v()
and
gda_meta_store_extract()
.
|
an SQL identifier |
|
a GdaConnection |
Returns : |
a new string, to free with g_free() once not needed anymore. [transfer full]
|
Since 4.0.3
GdaDataModel * gda_meta_store_extract (GdaMetaStore *store
,const gchar *select_sql
,GError **error
,...
);
Extracts some data stored in store
using a custom SELECT query. If the select_sql
filter involves
SQL identifiers (such as table or column names), then the values should have been adapted using
gda_meta_store_sql_identifier_quote()
.
For more information about
SQL identifiers are represented in store
, see the
meta data section about SQL identifiers.
|
a GdaMetaStore object |
|
a SELECT statement |
|
a place to store errors, or NULL . [allow-none]
|
|
a list of (variable name (gchar *), GValue *value) terminated with NULL, representing values for all the
variables mentioned in select_sql . If there is no variable then this part can be omitted. |
Returns : |
a new GdaDataModel, or NULL if an error occurred. [transfer full]
|
GdaDataModel * gda_meta_store_extract_v (GdaMetaStore *store
,const gchar *select_sql
,GHashTable *vars
,GError **error
);
Extracts some data stored in store
using a custom SELECT query. If the select_sql
filter involves
SQL identifiers (such as table or column names), then the values should have been adapted using
gda_meta_store_sql_identifier_quote()
.
For more information about
SQL identifiers are represented in store
, see the
meta data section about SQL identifiers.
|
a GdaMetaStore object |
|
a SELECT statement |
|
a hash table with all variables names as keys and GValue* as
value, representing values for all the variables mentioned in select_sql . If there is no variable then this part can be
omitted. [element-type utf8 GObject.Value][allow-none]
|
|
a place to store errors, or NULL
|
Returns : |
a new GdaDataModel, or NULL if an error occurred. [transfer full]
|
Since 4.2.6
GdaMetaStruct * gda_meta_store_schema_get_structure (GdaMetaStore *store
,GError **error
);
Creates a new GdaMetaStruct object representing store
's internal database structure.
|
a GdaMetaStore object |
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
a new GdaMetaStruct object, or NULL if an error occurred. [transfer full]
|
gboolean gda_meta_store_get_attribute_value (GdaMetaStore *store
,const gchar *att_name
,gchar **att_value
,GError **error
);
The GdaMetaStore object maintains a list of (name,value) attributes (attributes names starting with a '_'
character are for internal use only and cannot be altered). This method and the gda_meta_store_set_attribute_value()
method allows the user to add, set or remove attributes specific to their usage.
This method allows to get the value of a attribute stored in store
. The returned attribute value is
placed at att_value
, the caller is responsible for free that string.
If there is no attribute named att_name
then att_value
is set to NULL
and error
will contain the GDA_META_STORE_ATTRIBUTE_NOT_FOUND_ERROR error code, and FALSE is returned.
|
a GdaMetaStore object |
|
name of the attribute to get |
|
the place to store the attribute value. [out] |
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
TRUE if no error occurred |
gboolean gda_meta_store_set_attribute_value (GdaMetaStore *store
,const gchar *att_name
,const gchar *att_value
,GError **error
);
Set the value of the attribute named att_name
to att_value
; see gda_meta_store_get_attribute_value()
for
more information.
|
a GdaMetaStore object |
|
name of the attribute to set |
|
value of the attribute to set, or NULL to unset the attribute. [allow-none]
|
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
TRUE if no error occurred |
gboolean gda_meta_store_schema_add_custom_object (GdaMetaStore *store
,const gchar *xml_description
,GError **error
);
The internal database used by store
can be 'augmented' with some user-defined database objects
(such as tables or views). This method allows one to add a new database object.
If the internal database already contains the object, then:
if the object is equal to the provided description then TRUE is returned
if the object exists but differs from the provided description, then FALSE is returned, with the GDA_META_STORE_SCHEMA_OBJECT_CONFLICT_ERROR error code
The xml_description
defines the table of view's definition, for example:
<table name="mytable"> <column name="id" pkey="TRUE"/> <column name="value"/> </table>
The partial DTD for this XML description of the object to add is the following (the top node must be a <table> or a <view>):
<!ELEMENT table (column*,check*,fkey*,unique*)> <!ATTLIST table name NMTOKEN #REQUIRED> <!ELEMENT column EMPTY> <!ATTLIST column name NMTOKEN #REQUIRED type CDATA #IMPLIED pkey (TRUE|FALSE) #IMPLIED autoinc (TRUE|FALSE) #IMPLIED nullok (TRUE|FALSE) #IMPLIED> <!ELEMENT check (#PCDATA)> <!ELEMENT fkey (part+)> <!ATTLIST fkey ref_table NMTOKEN #REQUIRED> <!ELEMENT part EMPTY> <!ATTLIST part column NMTOKEN #IMPLIED ref_column NMTOKEN #IMPLIED> <!ELEMENT unique (column*)> <!ELEMENT view (definition)> <!ATTLIST view name NMTOKEN #REQUIRED descr CDATA #IMPLIED> <!ELEMENT definition (#PCDATA)>
|
a GdaMetaStore object |
|
an XML description of the table or view to add to store
|
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
TRUE if the new object has successfully been added |
GdaConnection * gda_meta_store_get_internal_connection
(GdaMetaStore *store
);
Get a pointer to the GdaConnection object internally used by store
to store
its contents.
The returned connection can be used to access some other data than the one managed by store
itself. The returned object is not owned by the caller (if you need to keep it, then use g_object_ref()
).
Do not close the connection.
|
a GdaMetaStore object |
Returns : |
a GdaConnection, or NULL . [transfer none]
|
gboolean gda_meta_store_declare_foreign_key (GdaMetaStore *store
,GdaMetaStruct *mstruct
,const gchar *fk_name
,const gchar *catalog
,const gchar *schema
,const gchar *table
,const gchar *ref_catalog
,const gchar *ref_schema
,const gchar *ref_table
,guint nb_cols
,gchar **colnames
,gchar **ref_colnames
,GError **error
);
Defines a new declared foreign key into store
. If another declared foreign key is already defined
between the two tables and with the same name, then it is first removed.
This method begins a transaction if possible (ie. none is already started), and if it can't, then if there is an error, the job may be partially done.
A check is always performed to make sure all the database objects actually
exist and returns an error if not. The check is performed using mstruct
if it's not NULL
(in
this case only the tables already represented in mstruct
will be considered, in other words: mstruct
will not be modified), and using an internal GdaMetaStruct is NULL
.
The catalog
, schema
, table
, ref_catalog
, ref_schema
and ref_table
must follow the SQL
identifiers naming convention, see the SQL identifiers
section. The same convention needs to be respected for the strings in conames
and ref_colnames
.
If catalog
is not NULL
, then schema
must also be not NULL
(the same restriction applies to
ref_catalog
and ref_schema
).
|
a GdaMetaStore |
|
a GdaMetaStruct, or NULL . [allow-none]
|
|
the name of the foreign key to declare |
|
the catalog in which the table (for which the foreign key is for) is, or NULL . [allow-none]
|
|
the schema in which the table (for which the foreign key is for) is, or NULL . [allow-none]
|
|
the name of the table (for which the foreign key is for) |
|
the catalog in which the referenced table is, or NULL . [allow-none]
|
|
the schema in which the referenced table is, or NULL . [allow-none]
|
|
the name of the referenced table |
|
the number of columns involved (>0) |
|
an array of column names from the table for which the foreign key is for. [array length=nb_cols] |
|
an array of column names from the referenced table. [array length=nb_cols] |
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
TRUE if no error occurred |
Since 4.2.4
gboolean gda_meta_store_undeclare_foreign_key (GdaMetaStore *store
,GdaMetaStruct *mstruct
,const gchar *fk_name
,const gchar *catalog
,const gchar *schema
,const gchar *table
,const gchar *ref_catalog
,const gchar *ref_schema
,const gchar *ref_table
,GError **error
);
Removes a declared foreign key from store
.
This method begins a transaction if possible (ie. none is already started), and if it can't, then if there is an error, the job may be partially done.
A check is always performed to make sure all the database objects actually
exist and returns an error if not. The check is performed using mstruct
if it's not NULL
(in
this case only the tables already represented in mstruct
will be considered, in other words: mstruct
will not be modified), and using an internal GdaMetaStruct is NULL
.
See gda_meta_store_declare_foreign_key()
for more information anout the catalog
, schema
, name
,
ref_catalog
, ref_schema
and ref_name
arguments.
|
a GdaMetaStore |
|
a GdaMetaStruct, or NULL . [allow-none]
|
|
the name of the foreign key to declare |
|
the catalog in which the table (for which the foreign key is for) is, or NULL . [allow-none]
|
|
the schema in which the table (for which the foreign key is for) is, or NULL . [allow-none]
|
|
the name of the table (for which the foreign key is for) |
|
the catalog in which the referenced table is, or NULL . [allow-none]
|
|
the schema in which the referenced table is, or NULL . [allow-none]
|
|
the name of the referenced table |
|
a place to store errors, or NULL . [allow-none]
|
Returns : |
TRUE if no error occurred |
Since 4.2.4
"catalog"
property "catalog" gchar* : Write / Construct Only
Catalog in which the database objects will be created.
Default value: NULL
"cnc"
property"cnc" GdaConnection* : Read / Write / Construct Only
Connection object internally used.
"cnc-string"
property "cnc-string" gchar* : Write / Construct Only
Connection string for the internal connection to use.
Default value: NULL
"meta-changed"
signalvoid user_function (GdaMetaStore *store,
GdaSList *changes,
gpointer user_data) : Run First
This signal is emitted when the store
's contents have changed (the changes are in the changes
list)
|
the GdaMetaStore instance that emitted the signal |
|
a list of changes made, as a GSList of pointers to GdaMetaStoreChange (which must not be modified). [element-type Gda.MetaStoreChange] |
|
user data set when the signal handler was connected. |
"meta-reset"
signalvoid user_function (GdaMetaStore *store,
gpointer user_data) : Run First
This signal is emitted when the store
's contents have been reset completely and when
no detailed changes are available
|
the GdaMetaStore instance that emitted the signal |
|
user data set when the signal handler was connected. |
"suggest-update"
signalGdaError* user_function (GdaMetaStore *store,
GdaMetaContext *suggest,
gpointer user_data) : Run Last
This signal is emitted when the contents of a table should be updated (data to update or insert only; deleting data is done automatically). This signal is used for internal purposes by the GdaConnection object.
|
the GdaMetaStore instance that emitted the signal |
|
the suggested update, as a GdaMetaContext structure |
|
user data set when the signal handler was connected. |
Returns : |
a new GError error structure if there was an error when processing the
signal, or NULL if signal propagation should continue |