GdaDataHandler: GNOME Data Access 5 manual

## GdaDataHandler GdaDataHandler — Interface which provides data handling (conversions) capabilities |

## Stability Level

Stable, unless otherwise indicated

## Functions

gchar * | gda_data_handler_get_sql_from_value ()
gchar * | gda_data_handler_get_str_from_value ()
GValue * | gda_data_handler_get_value_from_sql ()
GValue * | gda_data_handler_get_value_from_str ()
GValue * | gda_data_handler_get_sane_init_value ()
gboolean | gda_data_handler_accepts_g_type ()
const gchar * | gda_data_handler_get_descr ()
GdaDataHandler * | gda_data_handler_get_default ()

## Types and Values

| GdaDataHandler

## Object Hierarchy

        GInterface
        ╰── GdaDataHandler

## Prerequisites

GdaDataHandler requires GObject.

## Known Implementations

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

## Includes

    #include <libgda/gda-blob-op.h>

## Description

Because data types vary a lot from a DBMS to another, the GdaDataHandler interface helps managing data in its various representations, and converting from one to another:

- as a GValue which is a generic value container for the C language

- as a human readable string (in the user defined locale)

- as an SQL string (a string which can be used in SQL statements)

For each data type, a corresponding GdaDataHandler object can be requested using the

`gda_data_handler_get_default()` function. However, when working

with a specific database provider, it's better to use a GdaDataHandler which may be specific to the database provider which will correctly handle each database specifics using

`gda_server_provider_get_data_handler_g_type()` or `gda_server_provider_get_data_handler_dbms()`.

## Functions

### 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, the returned string can be used directly in an SQL statement. For example if `value` is a G_TYPE_STRING, then the returned string will be correctly quoted. Note however that it is a better practice to use variables in statements instead of value literals, see the GdaSqlParser for more information.

If the value is NULL or is of type GDA_TYPE_NULL, or is a G_TYPE_STRING and `g_value_get_string()` returns `NULL`, the returned string is "NULL".

#### Parameters

dh | an object which implements the GdaDataHandler interface |
value | the value to be converted to a string, or `NULL`. | [allow-none]

#### Returns

the new string, or `NULL` if an error occurred.

[transfer full]

### 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 user'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).

Note: the returned value will be in the current locale representation.

#### Parameters

dh | an object which implements the GdaDataHandler interface |
value | the value to be converted to a string, or `NULL`. | [allow-none]

#### Returns

the new string, or `NULL` if an error occurred.

[transfer full]

### 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 the `NULL` is returned.

#### Parameters

dh | an object which implements the GdaDataHandler interface |
sql | an SQL string, or `NULL`. | [allow-none][transfer none]
type | a GType |

#### Returns

the new GValue or `NULL` on error.

[transfer full]

### 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 string for the requested type, then `NULL` is returned.

Note: the `str` string must be in the current locale representation

#### Parameters

dh | an object which implements the GdaDataHandler interface |
str | a string or `NULL`. | [allow-none][transfer none]
type | a GType |

#### Returns

the new GValue or `NULL` on error.

[transfer full]

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

#### Parameters

dh | an object which implements the GdaDataHandler interface |
type | a GType |

#### Returns

the new GValue, or `NULL` if no such value can be created.

[allow-none][transfer full]

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

#### Parameters

dh | an object which implements the GdaDataHandler interface |
type | a GType |

#### Returns

`TRUE` if the gda type can be handled

### gda_data_handler_get_descr ()

    const gchar *
    gda_data_handler_get_descr (GdaDataHandler *dh);

Get a short description of the GdaDataHandler

#### Parameters

dh | an object which implements the GdaDataHandler interface |

#### Returns

the description.

[transfer none]

### gda_data_handler_get_default ()

    GdaDataHandler *
    gda_data_handler_get_default (GType for_type);

Obtain a pointer to a GdaDataHandler which can manage GValue values of type `for_type` . The returned data handler will be adapted to use the current locale information (for example dates will be formatted taking into account the locale).

The returned pointer is `NULL` if there is no default data handler available for the `for_type` data type

#### Parameters

for_type | a GType type |

#### Returns

a GdaDataHandler which must not be modified or destroyed.

[transfer none]

Since: 4.2.3

## Types and Values

### GdaDataHandler

    typedef struct _GdaDataHandler GdaDataHandler;