Subclassing GdaDataSelect: GNOME Data Access 5 manual

Subclassing GdaDataSelect

Subclassing GdaDataSelect — Base class for all the data models returned by DBMS providers when a SELECT statement is executed

Stability Level

Stable, unless otherwise indicated

Functions

void	gda_data_select_take_row ()
GdaRow *	gda_data_select_get_stored_row ()
GdaConnection *	gda_data_select_get_connection ()
void	gda_data_select_set_columns ()
void	gda_column_set_name ()
void	gda_column_set_description ()
void	gda_column_set_dbms_type ()
void	gda_column_set_g_type ()
void	gda_column_set_allow_null ()
void	gda_column_set_auto_increment ()
void	gda_column_set_position ()
void	gda_column_set_default_value ()
gchar *	gda_alphanum_to_text ()
gchar *	gda_text_to_alphanum ()
gboolean	gda_data_model_iter_move_next_default ()
gboolean	gda_data_model_iter_move_prev_default ()
void	gda_row_invalidate_value ()
void	gda_row_invalidate_value_e ()
gboolean	gda_row_value_is_valid ()
gboolean	gda_row_value_is_valid_e ()

Types and Values

struct

GdaDataSelectClass

Includes

#include <libgda/providers-support/gda-data-select-priv.h>

Description

All database providers should subclass this class when returning a data model after the execution of a SELECT statement. Specifically it has the following features:

Manages its list of GdaColumn using the list exported by the prepared statement object (GdaPStmt)
Allows random or cursor based access
Allows for efficient memory usage allowing the subclass to finely tune its memory usage
Provides a generic mechanism for writable data models

See the Virtual methods for recordsets section for more information about how to implement the virtual methods of the subclassed object.

This section documents the methods available for the database provider's implementations.

Functions

gda_data_select_take_row ()

void
gda_data_select_take_row (GdaDataSelect *model,
                          GdaRow *row,
                          gint rownum);

Stores row into model , externally advertized at row number rownum (if no row has been removed). The reference to row is stolen.

This function is used by database provider's implementations

Parameters

model	a GdaDataSelect data model
row	a GdaRow row.	[transfer full]
rownum	"external" advertized row number

gda_data_select_get_stored_row ()

GdaRow *
gda_data_select_get_stored_row (GdaDataSelect *model,
                                gint rownum);

Get the GdaRow object stored within model at row rownum (without taking care of removed rows)

Parameters

model	a GdaDataSelect data model
rownum	"external" advertized row number

Returns

the requested GdaRow, or NULL if not found.

[transfer none]

gda_data_select_get_connection ()

GdaConnection *
gda_data_select_get_connection (GdaDataSelect *model);

Get a pointer to the GdaConnection object which was used when model was created (and which may be used internally by model ).

Parameters

model

a GdaDataSelect data model

Returns

a pointer to the GdaConnection, or NULL.

[transfer none]

gda_data_select_set_columns ()

void
gda_data_select_set_columns (GdaDataSelect *model,
                             GSList *columns);

Makes columns the list of columns for model . Both the list and each GdaColumn object in the list are 'stolen' by model (ie. when this function returns the caller should not use anymore the list or each column object in it). This method should not be used directly, it is used by database provider's implementations.

Parameters

model	a GdaDataSelect data model
columns	a lis of GdaColumn objects.	[transfer full]

Since: 4.2.1

gda_column_set_name ()

void
gda_column_set_name (GdaColumn *column,
                     const gchar *name);

Sets the name of column to name .

Parameters

column	a GdaColumn.
name	the new name of `column` .

gda_column_set_description ()

void
gda_column_set_description (GdaColumn *column,
                            const gchar *title);

Sets the column's description

Parameters

column	a GdaColumn.
title	title name.

gda_column_set_dbms_type ()

void
gda_column_set_dbms_type (GdaColumn *column,
                          const gchar *dbms_type);

Defines column 's database type

Parameters

column	a GdaColumn
dbms_type	a string

gda_column_set_g_type ()

void
gda_column_set_g_type (GdaColumn *column,
                       GType type);

Sets the type of column to type .

Parameters

column	a GdaColumn.
type	the new type of `column` .

gda_column_set_allow_null ()

void
gda_column_set_allow_null (GdaColumn *column,
                           gboolean allow);

Sets the 'allow null' flag of the given column.

Parameters

column	a GdaColumn.
allow	whether the given column should allows null values or not.

gda_column_set_auto_increment ()

void
gda_column_set_auto_increment (GdaColumn *column,
                               gboolean is_auto);

Sets the auto increment flag for the given column.

Parameters

column	a GdaColumn.
is_auto	auto increment status.

gda_column_set_position ()

void
gda_column_set_position (GdaColumn *column,
                         gint position);

Sets the position of the column refer to in the containing data model.

Parameters

column	a GdaColumn.
position	the wanted position of the column in the containing data model.

gda_column_set_default_value ()

void
gda_column_set_default_value (GdaColumn *column,
                              const GValue *default_value);

Sets column 's default GValue.

Parameters

column	a GdaColumn.
default_value	default GValue for the column.	[allow-none]

gda_alphanum_to_text ()

gchar *
gda_alphanum_to_text (gchar *text);

Does the opposite of gda_text_to_alphanum(), in the same string

Parameters

text

a string

Returns

text if conversion succeeded or NULL if an error occurred

gda_text_to_alphanum ()

gchar *
gda_text_to_alphanum (const gchar *text);

The "encoding" consists in replacing non alphanumeric character with the string "__gdaXX" where XX is the hex. representation of the non alphanumeric char.

Parameters

text

the text to convert

Returns

a new string

gda_data_model_iter_move_next_default ()

gboolean
gda_data_model_iter_move_next_default (GdaDataModel *model,
                                       GdaDataModelIter *iter);

Method reserved to GdaDataModelIter implementations, should not be called directly.

[skip]

Parameters

model	a GdaDataModel
iter	a GdaDataModelIter iterating in `model`

Returns

TRUE if iter was moved correctly.

gda_data_model_iter_move_prev_default ()

gboolean
gda_data_model_iter_move_prev_default (GdaDataModel *model,
                                       GdaDataModelIter *iter);

Method reserved to GdaDataModelIter implementations, should not be called directly.

[skip]

Parameters

model	a GdaDataModel
iter	a GdaDataModelIter iterating in `model`

Returns

TRUE if iter was moved correctly.

gda_row_invalidate_value ()

void
gda_row_invalidate_value (GdaRow *row,
                          GValue *value);

Marks value as being invalid. This method is mainly used by database providers' implementations to report any error while reading a value from the database.

Parameters

row	a GdaRow
value	a GValue belonging to `row` (obtained with `gda_row_get_value()`).

gda_row_invalidate_value_e ()

void
gda_row_invalidate_value_e (GdaRow *row,
                            GValue *value,
                            GError *error);

Marks value as being invalid. This method is mainly used by database providers' implementations to report any error while reading a value from the database.

Parameters

row	a GdaRow
value	a GValue belonging to `row` (obtained with `gda_row_get_value()`).
error	the error which lead to the invalidation.	[allow-none][transfer full]

Since: 4.2.10

gda_row_value_is_valid ()

gboolean
gda_row_value_is_valid (GdaRow *row,
                        GValue *value);

Tells if value has been marked as being invalid by gda_row_invalidate_value(). This method is mainly used by database providers' implementations to report any error while reading a value from the database.

Parameters

row	a GdaRow.
value	a GValue belonging to `row` (obtained with `gda_row_get_value()`).

Returns

TRUE if value is valid

gda_row_value_is_valid_e ()

gboolean
gda_row_value_is_valid_e (GdaRow *row,
                          GValue *value,
                          GError **error);

Parameters

row	a GdaRow.
value	a GValue belonging to `row` (obtained with `gda_row_get_value()`).
error	a place to store the invalid error, or `NULL`.	[allow-none]

Returns

TRUE if value is valid

Since: 4.2.10

Types and Values

struct GdaDataSelectClass

struct GdaDataSelectClass {
	GObjectClass      parent_class;

	/* GDA_DATA_MODEL_ACCESS_RANDOM */
	gint             (*fetch_nb_rows) (GdaDataSelect *model);
	gboolean         (*fetch_random)  (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
	gboolean         (*store_all)     (GdaDataSelect *model, GError **error);

	/* GDA_STATEMENT_MODEL_CURSOR_* */
	gboolean         (*fetch_next)    (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
	gboolean         (*fetch_prev)    (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
	gboolean         (*fetch_at)      (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
};