## GdaDataHandler

GdaDataHandler — Interface which provides data handling capabilities

## Synopsis

                        GdaDataHandler;
    gchar*              gda_data_handler_get_sql_from_value (GdaDataHandler *dh,
                                                             const GValue *value);
    gchar*              gda_data_handler_get_str_from_value (GdaDataHandler *dh,
                                                             const GValue *value);
    GValue*             gda_data_handler_get_value_from_sql (GdaDataHandler *dh,
                                                             const gchar *sql,
                                                             GType type);
    GValue*             gda_data_handler_get_value_from_str (GdaDataHandler *dh,
                                                             const gchar *str,
                                                             GType type);
    GValue*             gda_data_handler_get_sane_init_value
                                                            (GdaDataHandler *dh,
                                                             GType type);
    guint               gda_data_handler_get_nb_g_types     (GdaDataHandler *dh);
    gboolean            gda_data_handler_accepts_g_type     (GdaDataHandler *dh,
                                                             GType type);
    GType               gda_data_handler_get_g_type_index   (GdaDataHandler *dh,
                                                             guint index);
    const gchar*        gda_data_handler_get_descr          (GdaDataHandler *dh);

## Object Hierarchy

      GInterface
       +----GdaDataHandler

## Prerequisites

GdaDataHandler requires GObject.

## Known Implementations

GdaDataHandler is implemented by GdaHandlerBoolean, GdaHandlerType, GdaHandlerBin, GdaHandlerNumerical, GdaHandlerTime and GdaHandlerString.

## Description

Because data types vary a lot from a DBMS to another, the GdaDataHandler interface helps designing modules which can handle very specific pieces of data through plugins. Each object which imlements the GdaDataHandler interface is expected to handle a subset of the possible libgda defined data types.

The GdaDataHandler object can convert a GValue to and from both SQL and 'STR'. The SQL representation of a value is the actual string which would be used in an SQL statement (for example a string's SQL representation is surrounded by quotes such as 'that\'s a string'). The 'STR' representation is a human-readable representation of a value appropriate for the user's current locale. The 'STR' respresentation of a string is simply the original string without quotes but a numerical value or date, for instance, will be formatted according to the user's current locale.

Only one object which implements this interface is needed for any given data type, and it mainly contains some methods to manage values (as GValue structures). The GnomeDbDataEntry interface is complementary to this one since it it implemented by widgets where the user can enter or modify some data.

## Details

### GdaDataHandler

    typedef struct _GdaDataHandler GdaDataHandler;

### gda_data_handler_get_sql_from_value ()

    gchar*              gda_data_handler_get_sql_from_value (GdaDataHandler *dh,
                                                             const GValue *value);

Creates a new string which is an SQL representation of the given value. If the value is NULL or is of type GDA_TYPE_NULL, the returned string is NULL.

`dh` : | an object which implements the GdaDataHandler interface
`value` : | the value to be converted to a string
Returns : | the new string.

### gda_data_handler_get_str_from_value ()

    gchar*              gda_data_handler_get_str_from_value (GdaDataHandler *dh,
                                                             const GValue *value);

Creates a new string which is a "user friendly" representation of the given value (in the users's locale, specially for the dates). If the value is NULL or is of type GDA_TYPE_NULL, the returned string is a copy of "" (empty string).

`dh` : | an object which implements the GdaDataHandler interface
`value` : | the value to be converted to a string
Returns : | the new string.

### gda_data_handler_get_value_from_sql ()

    GValue*             gda_data_handler_get_value_from_sql (GdaDataHandler *dh,
                                                             const gchar *sql,
                                                             GType type);

Creates a new GValue which represents the SQL value given as argument. This is the opposite of the function `gda_data_handler_get_sql_from_value()`. The type argument is used to determine the real data type requested for the returned value.

If the sql string is NULL, then the returned GValue is of type GDA_TYPE_NULL; if the sql string does not correspond to a valid SQL string for the requested type, then NULL is returned.

`dh` : | an object which implements the GdaDataHandler interface
`sql` : |
`type` : |
Returns : | the new GValue or NULL on error

### gda_data_handler_get_value_from_str ()

    GValue*             gda_data_handler_get_value_from_str (GdaDataHandler *dh,
                                                             const gchar *str,
                                                             GType type);

Creates a new GValue which represents the STR value given as argument. This is the opposite of the function `gda_data_handler_get_str_from_value()`. The type argument is used to determine the real data type requested for the returned value.

If the str string is NULL, then the returned GValue is of type GDA_TYPE_NULL; if the str string does not correspond to a valid STR string for the requested type, then NULL is returned.

`dh` : | an object which implements the GdaDataHandler interface
`str` : |
`type` : |
Returns : | the new GValue or NULL on error

### gda_data_handler_get_sane_init_value ()

    GValue*             gda_data_handler_get_sane_init_value
                                                            (GdaDataHandler *dh,
                                                             GType type);

Creates a new GValue which holds a sane initial value to be used if no value is specifically provided. For example for a simple string, this would return a new value containing the "" string.

`dh` : | an object which implements the GdaDataHandler interface
`type` : |
Returns : | the new GValue, or `NULL` if no such value can be created.

### gda_data_handler_get_nb_g_types ()

    guint               gda_data_handler_get_nb_g_types     (GdaDataHandler *dh);

Get the number of GType types the GdaDataHandler can handle correctly

`dh` : | an object which implements the GdaDataHandler interface
Returns : | the number.

### gda_data_handler_accepts_g_type ()

    gboolean            gda_data_handler_accepts_g_type     (GdaDataHandler *dh,
                                                             GType type);

Checks wether the GdaDataHandler is able to handle the gda type given as argument.

`dh` : | an object which implements the GdaDataHandler interface
`type` : |
Returns : | TRUE if the gda type can be handled

### gda_data_handler_get_g_type_index ()

    GType               gda_data_handler_get_g_type_index   (GdaDataHandler *dh,
                                                             guint index);

Get the GType handled by the GdaDataHandler, at the given position (starting at zero).

`dh` : | an object which implements the GdaDataHandler interface
`index` : |
Returns : | the GType

### gda_data_handler_get_descr ()

    const gchar*        gda_data_handler_get_descr          (GdaDataHandler *dh);

Get a short description of the GdaDataHandler

`dh` : | an object which implements the GdaDataHandler interface
Returns : | the description

## See Also

The GdaDictType class an the GnomeDbDataEntry interface.