Subclassing GdaDataSelect

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

## Synopsis

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

                        GdaDataSelectClass;
    void                gda_data_select_take_row            (GdaDataSelect *model,
                                                             GdaRow *row,
                                                             gint rownum);
    GdaRow *            gda_data_select_get_stored_row      (GdaDataSelect *model,
                                                             gint rownum);
    GdaConnection *     gda_data_select_get_connection      (GdaDataSelect *model);

    void                gda_column_set_name                 (GdaColumn *column,
                                                             const gchar *name);
    void                gda_column_set_description          (GdaColumn *column,
                                                             const gchar *title);
    void                gda_column_set_dbms_type            (GdaColumn *column,
                                                             const gchar *dbms_type);
    void                gda_column_set_g_type               (GdaColumn *column,
                                                             GType type);
    void                gda_column_set_allow_null           (GdaColumn *column,
                                                             gboolean allow);
    void                gda_column_set_auto_increment       (GdaColumn *column,
                                                             gboolean is_auto);
    void                gda_column_set_position             (GdaColumn *column,
                                                             gint position);
    void                gda_column_set_default_value        (GdaColumn *column,
                                                             const GValue *default_value);

    gchar *             gda_alphanum_to_text                (gchar *text);
    gchar *             gda_text_to_alphanum                (const gchar *text);

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

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

## 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.

## Details

### GdaDataSelectClass

    typedef struct {
    	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);

    	/* Padding for future expansion */
    	void (*_gda_reserved1) (void);
    	void (*_gda_reserved2) (void);
    	void (*_gda_reserved3) (void);
    	void (*_gda_reserved4) (void);
    } GdaDataSelectClass;

GObjectClass `parent_class`; | parent object class
`fetch_nb_rows` () | virtual method which must be implemented when access method is GDA_DATA_MODEL_ACCESS_RANDOM
`fetch_random` () | virtual method which must be implemented when access method is GDA_DATA_MODEL_ACCESS_RANDOM
`store_all` () |
`fetch_next` () | virtual method which must be implemented when access method is GDA_DATA_MODEL_ACCESS_CURSOR_FORWARD
`fetch_prev` () | virtual method which must be implemented when access method is GDA_DATA_MODEL_ACCESS_CURSOR_BACKWARD
`fetch_at` () | virtual method which can be implemented when access method is GDA_DATA_MODEL_ACCESS_CURSOR_FORWARD or GDA_DATA_MODEL_ACCESS_CURSOR_BACKWARD
`_gda_reserved1` () |
`_gda_reserved2` () |
`_gda_reserved3` () |
`_gda_reserved4` () |

### 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.

`model` : | a GdaDataSelect data model
`row` : | a GdaRow row
`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)

`model` : | a GdaDataSelect data model
`rownum` : | "external" advertized row number
Returns : | the requested GdaRow, or `NULL` if not found

### 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`).

`model` : | a GdaDataSelect data model
Returns : | a pointer to the GdaConnection, or `NULL`

### gda_column_set_name ()

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

Sets the name of `column` to `name`.

`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

`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

`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`.

`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.

`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.

`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.

`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.

`column` : | a GdaColumn.
`default_value` : | default GValue for the column

### gda_alphanum_to_text ()

    gchar *             gda_alphanum_to_text                (gchar *text);

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

`text` : | a string
Returns : | `text` if conversion succedded 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.

`text` : |
Returns : | a new string

### gda_data_model_iter_move_next_default ()

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

`model` : |
`iter` : |
Returns : |

### gda_data_model_iter_move_prev_default ()

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

`model` : |
`iter` : |
Returns : |

### 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.

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

### 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.

`row` : | a GdaRow.
`value` : | a GValue belonging to `row` (obtained with `gda_row_get_value()`).
Returns : | TRUE if `value` is valid