gda_data_model_get_n_rows ()

gint
gda_data_model_get_n_rows (GdaDataModel *model);

[virtual i_get_n_rows]

gda_data_model_get_n_columns ()

gint
gda_data_model_get_n_columns (GdaDataModel *model);

[virtual i_get_n_columns]

gda_data_model_get_exceptions ()

GError **
gda_data_model_get_exceptions (GdaDataModel *model);

Get the global data model exception(s) that occurred when using model . This is useful for example for the LDAP related data models where some rows may be missing because the LDAP search has reached a limit imposed by the LDAP server.

[virtual i_get_exceptions]

Since: 4.2.6

gda_data_model_describe_column ()

GdaColumn *
gda_data_model_describe_column (GdaDataModel *model,
                                gint col);

Queries the underlying data model implementation for a description of a given column. That description is returned in the form of a GdaColumn structure, which contains all the information about the given column in the data model.

WARNING: the returned GdaColumn object belongs to the model model and and should not be destroyed; any modification will affect the whole data model.

[virtual i_describe_column]

gda_data_model_get_column_index ()

gint
gda_data_model_get_column_index (GdaDataModel *model,
                                 const gchar *name);

Get the index of the first column named name in model .

gda_data_model_get_column_name ()

const gchar *
gda_data_model_get_column_name (GdaDataModel *model,
                                gint col);

Since: 3.2

gda_data_model_get_column_title ()

const gchar *
gda_data_model_get_column_title (GdaDataModel *model,
                                 gint col);

gda_data_model_get_access_flags ()

GdaDataModelAccessFlags
gda_data_model_get_access_flags (GdaDataModel *model);

Get the attributes of model such as how to access the data it contains if it's modifiable, etc.

[virtual i_get_access_flags]

gda_data_model_create_iter ()

GdaDataModelIter *
gda_data_model_create_iter (GdaDataModel *model);

Creates a new iterator object GdaDataModelIter object which can be used to iterate through rows in model . The new GdaDataModelIter does not hold any reference to model (ie. if model is destroyed at some point, the new iterator will become useless but in any case it will not prevent the data model from being destroyed).

Depending on the data model's implementation, a new GdaDataModelIter object may be created, or a reference to an already existing GdaDataModelIter may be returned. For example if model only supports being accessed using a forward moving cursor (say a the result of a SELECT executed by SQLite with a cursor access mode specified), then this method will always return the same iterator.

If a new GdaDataModelIter is created, then the row it represents is undefined.

For models which can be accessed randomly, any row can be set using gda_data_model_iter_move_to_row(), and for models which are accessible sequentially only then use gda_data_model_iter_move_next() (and gda_data_model_iter_move_prev() if supported).

Note: for the GdaDataProxy data model (which proxies any GdaDataModel for modifications and has twice the number of columns of the proxied data model), this method will create an iterator in which only the columns of the proxied data model appear. If you need to have a GdaDataModelIter in which all the proxy's columns appear, create it using:

iter = g_object_new (GDA_TYPE_DATA_MODEL_ITER, "data-model", proxy, NULL);

[virtual i_create_iter]

gda_data_model_get_value_at ()

const GValue *
gda_data_model_get_value_at (GdaDataModel *model,
                             gint col,
                             gint row,
                             GError **error);

Retrieves the data stored in the given position (identified by the col and row parameters) on a data model.

Upon errors NULL will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

This is the main function for accessing data in a model which allows random access to its data. To access data in a data model using a cursor, use a GdaDataModelIter object, obtained using gda_data_model_create_iter().

Note1: the returned GValue must not be modified directly (unexpected behaviours may occur if you do so).

Note2: the returned value may become invalid as soon as any Libgda part is executed again, which means if you want to keep the value, a copy must be made, however it will remain valid as long as the only Libgda usage is calling gda_data_model_get_value_at() for different values of the same row.

If you want to modify a value stored in a GdaDataModel, use the gda_data_model_set_value_at() or gda_data_model_set_values() methods.

Upon errors NULL will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

[virtual i_get_value_at]

gda_data_model_get_typed_value_at ()

const GValue *
gda_data_model_get_typed_value_at (GdaDataModel *model,
                                   gint col,
                                   gint row,
                                   GType expected_type,
                                   gboolean nullok,
                                   GError **error);

Upon errors NULL will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

This method is similar to gda_data_model_get_value_at(), except that it also allows one to specify the expected GType of the value to get: if the data model returned a GValue of a type different than the expected one, then this method returns NULL and an error code.

Note: the same limitations and usage instructions apply as for gda_data_model_get_value_at().

Upon errors NULL will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

gda_data_model_set_value_at ()

gboolean
gda_data_model_set_value_at (GdaDataModel *model,
                             gint col,
                             gint row,
                             const GValue *value,
                             GError **error);

Modifies a value in model , at (col , row ).

Upon errors FALSE will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

[virtual i_set_value_at]

gda_data_model_set_values ()

gboolean
gda_data_model_set_values (GdaDataModel *model,
                           gint row,
                           GList *values,
                           GError **error);

In a similar way to gda_data_model_set_value_at(), this method modifies a data model's contents by setting several values at once.

If any value in values is actually NULL, then the value in the corresponding column is left unchanged.

Upon errors FALSE will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

[virtual i_set_values]

gda_data_model_get_attributes_at ()

GdaValueAttribute
gda_data_model_get_attributes_at (GdaDataModel *model,
                                  gint col,
                                  gint row);

Get the attributes of the value stored at (row, col) in model , which is an ORed value of GdaValueAttribute flags. As a special case, if row is -1, then the attributes returned correspond to a "would be" value if a row was added to model .

[virtual i_get_attributes_at]

gda_data_model_append_values ()

gint
gda_data_model_append_values (GdaDataModel *model,
                              const GList *values,
                              GError **error);

Appends a row to the given data model. If any value in values is actually NULL, then it is considered as a default value. If values is NULL then all values are set to their default value.

Upon errors -1 will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

[virtual i_append_values]

gda_data_model_append_row ()

gint
gda_data_model_append_row (GdaDataModel *model,
                           GError **error);

Appends a row to the data model (the new row will possibly have NULL values for all columns, or some other values depending on the data model implementation)

Upon errors -1 will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

[virtual i_append_row]

gda_data_model_remove_row ()

gboolean
gda_data_model_remove_row (GdaDataModel *model,
                           gint row,
                           GError **error);

Removes a row from the data model.

Upon errors FALSE will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

[virtual i_remove_row]

gda_data_model_get_row_from_values ()

gint
gda_data_model_get_row_from_values (GdaDataModel *model,
                                    GSList *values,
                                    gint *cols_index);

Returns the first row where all the values in values at the columns identified at cols_index match. If the row can't be identified, then returns -1;

NOTE: the cols_index array MUST contain a column index for each value in values

[virtual i_find_row]

gda_data_model_send_hint ()

void
gda_data_model_send_hint (GdaDataModel *model,
                          GdaDataModelHint hint,
                          const GValue *hint_value);

Sends a hint to the data model. The hint may or may not be handled by the data model, depending on its implementation

[virtual i_send_hint]

gda_data_model_export_to_string ()

gchar *
gda_data_model_export_to_string (GdaDataModel *model,
                                 GdaDataModelIOFormat format,
                                 const gint *cols,
                                 gint nb_cols,
                                 const gint *rows,
                                 gint nb_rows,
                                 GdaSet *options);

Exports data contained in model to a string; the format is specified using the format argument, see the gda_data_model_export_to_file() documentation for more information about the options argument (except for the "OVERWRITE" option).

Warning: this function uses a GdaDataModelIter iterator, and if model does not offer a random access (check using gda_data_model_get_access_flags()), the iterator will be the same as normally used to access data in model previously to calling this method, and this iterator will be moved (point to another row).

See also gda_data_model_dump_as_string();

gda_data_model_export_to_file ()

gboolean
gda_data_model_export_to_file (GdaDataModel *model,
                               GdaDataModelIOFormat format,
                               const gchar *file,
                               const gint *cols,
                               gint nb_cols,
                               const gint *rows,
                               gint nb_rows,
                               GdaSet *options,
                               GError **error);

Exports data contained in model to the file file; the format is specified using the format argument. Note that the date format used is the one used by the connection from which the data model has been made (as the result of a SELECT statement), or, for other kinds of data models, the default format (refer to gda_data_handler_get_default()) unless the "cnc" property has been set and points to a GdaConnection to use that connection's date format.

Specifically, the parameters in the options list can be:

Warning: this function uses a GdaDataModelIter iterator, and if model does not offer a random access (check using gda_data_model_get_access_flags()), the iterator will be the same as normally used to access data in model previously to calling this method, and this iterator will be moved (point to another row).

Upon errors FALSE will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

gda_data_model_add_data_from_xml_node ()

gboolean
gda_data_model_add_data_from_xml_node (GdaDataModel *model,
                                       xmlNodePtr node,
                                       GError **error);

Adds the data from an XML node to the given data model (see the DTD for that node in the $prefix/share/libgda/dtd/libgda-array.dtd file).

Upon errors FALSE will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

gda_data_model_import_from_model ()

gboolean
gda_data_model_import_from_model (GdaDataModel *to,
                                  GdaDataModel *from,
                                  gboolean overwrite,
                                  GHashTable *cols_trans,
                                  GError **error);

Copy the contents of the from data model to the to data model. The copy stops as soon as an error orrurs.

The cols_trans is a hash table for which keys are to columns numbers and the values are the corresponding column numbers in the from data model. To set the values of a column in to to NULL, create an entry in the hash table with a negative value. For example:

GHashTable *hash;
gint *ptr;
hash = g_hash_table_new_full (g_int_hash, g_int_equal, g_free, NULL);
ptr = g_new (gint, 1);
*ptr = 2;
g_hash_table_insert (hash, ptr, GINT_TO_POINTER (3));
gda_data_model_import_from_model (...);
g_hash_table_free (hash);

Upon errors FALSE will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

gda_data_model_import_from_string ()

gboolean
gda_data_model_import_from_string (GdaDataModel *model,
                                   const gchar *string,
                                   GHashTable *cols_trans,
                                   GdaSet *options,
                                   GError **error);

Loads the data from string into model .

Upon errors FALSE will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

gda_data_model_import_from_file ()

gboolean
gda_data_model_import_from_file (GdaDataModel *model,
                                 const gchar *file,
                                 GHashTable *cols_trans,
                                 GdaSet *options,
                                 GError **error);

Imports data contained in the file file into model ; the format is detected.

Upon errors FALSE will be returned and error will be assigned a GError from the GDA_DATA_MODEL_ERROR domain.

gda_data_model_dump ()

void
gda_data_model_dump (GdaDataModel *model,
                     FILE *to_stream);

Dumps a textual representation of the model to the to_stream stream

The following environment variables can affect the resulting output:

gda_data_model_dump_as_string ()

gchar *
gda_data_model_dump_as_string (GdaDataModel *model);

Dumps a textual representation of the model into a new string. The main differences with gda_data_model_export_to_string() are that the formatting options are passed using environment variables, and that the data is dumped regardless of the user locale (e.g. dates are not formatted according to the locale).

The following environment variables can affect the resulting output:

gda_data_model_set_column_name ()

void
gda_data_model_set_column_name (GdaDataModel *model,
                                gint col,
                                const gchar *name);

Sets the name of the given col in model , and if its title is not set, also sets the title to name .

Since: 3.2

gda_data_model_set_column_title ()

void
gda_data_model_set_column_title (GdaDataModel *model,
                                 gint col,
                                 const gchar *title);

Sets the title of the given col in model .

gda_data_model_row_inserted ()

void
gda_data_model_row_inserted (GdaDataModel *model,
                             gint row);

Emits the 'row_inserted' and 'changed' signals on model .

This method should only be used by GdaDataModel implementations to signal that a row has been inserted.

gda_data_model_row_updated ()

void
gda_data_model_row_updated (GdaDataModel *model,
                            gint row);

Emits the 'row_updated' and 'changed' signals on model .

This method should only be used by GdaDataModel implementations to signal that a row has been updated.

gda_data_model_row_removed ()

void
gda_data_model_row_removed (GdaDataModel *model,
                            gint row);

Emits the 'row_removed' and 'changed' signal on model .

This method should only be used by GdaDataModel implementations to signal that a row has been removed

gda_data_model_reset ()

void
gda_data_model_reset (GdaDataModel *model);

Emits the 'reset' and 'changed' signal on model .

gda_data_model_freeze ()

void
gda_data_model_freeze (GdaDataModel *model);

Disables notifications of changes on the given data model. To re-enable notifications again, you should call the gda_data_model_thaw function.

gda_data_model_thaw ()

void
gda_data_model_thaw (GdaDataModel *model);

Re-enables notifications of changes on the given data model.

GdaDataModel

typedef struct _GdaDataModel GdaDataModel;

enum GdaDataModelError

enum GdaDataModelAccessFlags

enum GdaDataModelHint

enum GdaDataModelIOFormat

Format to use when exporting a data model, see gda_data_model_export_to_string() and gda_data_model_export_to_file()

The “access-changed” signal

void
user_function (GdaDataModel *model,
               gpointer      user_data)

Gets emitted when model 's access flags have changed. Use gda_data_model_get_access_flags() to get the access flags.

Flags: Run Last

The “changed” signal

void
user_function (GdaDataModel *model,
               gpointer      user_data)

Gets emitted when any value in model has been changed

Flags: Run Last

The “reset” signal

void
user_function (GdaDataModel *model,
               gpointer      user_data)

Gets emitted when model 's contents has been completely reset (the number and type of columns may also have changed)

Flags: Run Last

The “row-inserted” signal

void
user_function (GdaDataModel *model,
               int           row,
               gpointer      user_data)

Gets emitted when a row has been inserted in model

Flags: Run Last

The “row-removed” signal

void
user_function (GdaDataModel *model,
               int           row,
               gpointer      user_data)

Gets emitted when a row has been removed from model

Flags: Run Last

The “row-updated” signal

void
user_function (GdaDataModel *model,
               int           row,
               gpointer      user_data)

Gets emitted when a row has been modified in model

Flags: Run Last