## MgDataHandler

MgDataHandler — Interface which provides data handling capabilities

## Synopsis

    struct      MgDataHandler;
    struct      MgDataHandlerIface;
    guint       mg_data_handler_get_type        (void);
    MgDataEntry* mg_data_handler_get_entry_from_value
                                                (MgDataHandler *dh,
                                                 const GdaValue *value,
                                                 GdaValueType type);
    GtkCellRenderer* mg_data_handler_get_cell_renderer
                                                (MgDataHandler *dh,
                                                 GdaValueType type);
    gchar*      mg_data_handler_get_sql_from_value
                                                (MgDataHandler *dh,
                                                 const GdaValue *value);
    gchar*      mg_data_handler_get_str_from_value
                                                (MgDataHandler *dh,
                                                 const GdaValue *value);
    GdaValue*   mg_data_handler_get_value_from_sql
                                                (MgDataHandler *dh,
                                                 const gchar *sql,
                                                 GdaValueType type);
    GdaValue*   mg_data_handler_get_value_from_str
                                                (MgDataHandler *dh,
                                                 const gchar *str,
                                                 GdaValueType type);
    GdaValue*   mg_data_handler_get_sane_init_value
                                                (MgDataHandler *dh,
                                                 GdaValueType type);
    guint       mg_data_handler_get_nb_gda_types
                                                (MgDataHandler *dh);
    GdaValueType mg_data_handler_get_gda_type_index
                                                (MgDataHandler *dh,
                                                 guint index);
    gboolean    mg_data_handler_accepts_gda_type
                                                (MgDataHandler *dh,
                                                 GdaValueType type);
    const gchar* mg_data_handler_get_descr      (MgDataHandler *dh);
    const gchar* mg_data_handler_get_descr_detail
                                                (MgDataHandler *dh);
    const gchar* mg_data_handler_get_version    (MgDataHandler *dh);
    gboolean    mg_data_handler_is_plugin       (MgDataHandler *dh);
    const gchar* mg_data_handler_get_plugin_name
                                                (MgDataHandler *dh);
    const gchar* mg_data_handler_get_plugin_file
                                                (MgDataHandler *dh);
    gchar*      mg_data_handler_get_key         (MgDataHandler *dh);

## Object Hierarchy

      GInterface
       +----MgDataHandler

## Known Implementations

MgDataHandler is implemented by MgHandlerBoolean, MgHandlerTime, MgHandlerPassmd5, MgHandlerString, MgHandlerNumerical, MgHandlerNone, MgHandlerCidr and MgHandlerText.

## Description

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

The MgDataHandler object can convert a GdaValue 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 user friendly representation of a value (and the previous example would simply be: that's a string).

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

For a given data type, the MgServer (found in the correspoding MgConf object) will provide a reference to a valid MgDataHandler to handle values of that data type.

Libmergeant provides some default MgDataHandler objects for the most common data types (strings with a MgHandlerString, booleans with a MgHandlerBoolean, etc) and some other as plugins.

## Details

### struct MgDataHandler

    struct MgDataHandler;

### struct MgDataHandlerIface

    struct MgDataHandlerIface {

    	GTypeInterface           g_iface;

    	/* virtual table */
    	MgDataEntry     *(* get_entry_from_value) (MgDataHandler *dh, const GdaValue *value, GdaValueType type);
    	gchar           *(* get_sql_from_value)   (MgDataHandler *dh, const GdaValue *value);
    	gchar           *(* get_str_from_value)   (MgDataHandler *dh, const GdaValue *value);
    	GdaValue        *(* get_value_from_sql)   (MgDataHandler *dh, const gchar *sql, GdaValueType type);
    	GdaValue        *(* get_value_from_str)   (MgDataHandler *dh, const gchar *str, GdaValueType type);
    	GdaValue        *(* get_sane_init_value)  (MgDataHandler *dh, GdaValueType type);
    	GtkCellRenderer *(* get_cell_renderer)    (MgDataHandler *dh, GdaValueType type);

    	guint            (* get_nb_gda_types)     (MgDataHandler * dh);
    	GdaValueType     (* get_gda_type_index)   (MgDataHandler * dh, guint index);
    	gboolean         (* accepts_gda_type)     (MgDataHandler * dh, GdaValueType type);

    	const gchar     *(* get_descr)            (MgDataHandler * dh);
    	const gchar     *(* get_descr_detail)     (MgDataHandler * dh);
    	const gchar     *(* get_version)          (MgDataHandler * dh);
    	gboolean         (* is_plugin)            (MgDataHandler * dh);
    	const gchar     *(* get_plugin_name)      (MgDataHandler * dh);
    	const gchar     *(* get_plugin_file)      (MgDataHandler * dh);
    	gchar           *(* get_key)              (MgDataHandler * dh);

    };

### mg_data_handler_get_type ()

    guint       mg_data_handler_get_type        (void);

Returns : |

### mg_data_handler_get_entry_from_value ()

    MgDataEntry* mg_data_handler_get_entry_from_value
                                                (MgDataHandler *dh,
                                                 const GdaValue *value,
                                                 GdaValueType type);

Create a new MgDataEntry widget to edit the given value. If the value is NULL or of type GDA_VALUE_TYPE_NULL, then the type argument is used and determines the real requested type (it is otherwise ignored).

Also, if the value is NULL or of type GDA_VALUE_TYPE_NULL, then the initial edited value in the widget will be the sane initial value provided by the MgDataHandler object.

`dh` : | an object which implements the MgDataHandler interface
`value` : | the original value to display or `NULL`
`type` : | the requested data type (if `value` is not `NULL` or of type NULL, then this parameter is ignored)
Returns : | the new widget

### mg_data_handler_get_cell_renderer ()

    GtkCellRenderer* mg_data_handler_get_cell_renderer
                                                (MgDataHandler *dh,
                                                 GdaValueType type);

Creates a new GtkCellRenderer object to handle `type` of data.

`dh` : | an object which implements the MgDataHandler interface
`type` : | the requested data type
Returns : | the new cell renderer

### mg_data_handler_get_sql_from_value ()

    gchar*      mg_data_handler_get_sql_from_value
                                                (MgDataHandler *dh,
                                                 const GdaValue *value);

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

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

### mg_data_handler_get_str_from_value ()

    gchar*      mg_data_handler_get_str_from_value
                                                (MgDataHandler *dh,
                                                 const GdaValue *value);

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

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

### mg_data_handler_get_value_from_sql ()

    GdaValue*   mg_data_handler_get_value_from_sql
                                                (MgDataHandler *dh,
                                                 const gchar *sql,
                                                 GdaValueType type);

Creates a new GdaValue which represents the SQL value given as argument. This is the opposite of the function `mg_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 GdaValue is of type GDA_VALUE_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 MgDataHandler interface
`sql` : |
`type` : |
Returns : | the new GdaValue or NULL on error

### mg_data_handler_get_value_from_str ()

    GdaValue*   mg_data_handler_get_value_from_str
                                                (MgDataHandler *dh,
                                                 const gchar *str,
                                                 GdaValueType type);

Creates a new GdaValue which represents the STR value given as argument. This is the opposite of the function `mg_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 GdaValue is of type GDA_VALUE_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 MgDataHandler interface
`str` : |
`type` : |
Returns : | the new GdaValue or NULL on error

### mg_data_handler_get_sane_init_value ()

    GdaValue*   mg_data_handler_get_sane_init_value
                                                (MgDataHandler *dh,
                                                 GdaValueType type);

Creates a new GdaValue which holds a sane initial value to be used if no value is specifically provided. For example for a simple string, this would return gda_value_new_string ("").

`dh` : | an object which implements the MgDataHandler interface
`type` : |
Returns : | the new GdaValue.

### mg_data_handler_get_nb_gda_types ()

    guint       mg_data_handler_get_nb_gda_types
                                                (MgDataHandler *dh);

Get the number of GdaValueType types the MgDataHandler can handle correctly

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

### mg_data_handler_get_gda_type_index ()

    GdaValueType mg_data_handler_get_gda_type_index
                                                (MgDataHandler *dh,
                                                 guint index);

Get the GdaValueType handled by the MgDataHandler, at the given position (starting at zero).

`dh` : | an object which implements the MgDataHandler interface
`index` : |
Returns : | the GdaValueType

### mg_data_handler_accepts_gda_type ()

    gboolean    mg_data_handler_accepts_gda_type
                                                (MgDataHandler *dh,
                                                 GdaValueType type);

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

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

### mg_data_handler_get_descr ()

    const gchar* mg_data_handler_get_descr      (MgDataHandler *dh);

Get a short description of the MgDataHandler

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

### mg_data_handler_get_descr_detail ()

    const gchar* mg_data_handler_get_descr_detail
                                                (MgDataHandler *dh);

Get a detailled description of the MgDataHandler

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

### mg_data_handler_get_version ()

    const gchar* mg_data_handler_get_version    (MgDataHandler *dh);

Get the MgDataHandler's version

`dh` : | an object which implements the MgDataHandler interface
Returns : | the version

### mg_data_handler_is_plugin ()

    gboolean    mg_data_handler_is_plugin       (MgDataHandler *dh);

Get wether the MgDataHandler is a plugin or not

`dh` : | an object which implements the MgDataHandler interface
Returns : | TRUE if the MgDataHandler is a plugin

### mg_data_handler_get_plugin_name ()

    const gchar* mg_data_handler_get_plugin_name
                                                (MgDataHandler *dh);

Get the name of the MgDataHandler if it is a plugin

`dh` : | an object which implements the MgDataHandler interface
Returns : | the name of the MgDataHandler if it is a plugin or NULL

### mg_data_handler_get_plugin_file ()

    const gchar* mg_data_handler_get_plugin_file
                                                (MgDataHandler *dh);

Get the file name (.so on Unix) of the MgDataHandler if it is a plugin

`dh` : | an object which implements the MgDataHandler interface
Returns : | the file name of the MgDataHandler if it is a plugin or NULL

### mg_data_handler_get_key ()

    gchar*      mg_data_handler_get_key         (MgDataHandler *dh);

Get a unique identifier for the MgDataHandler

`dh` : | an object which implements the MgDataHandler interface
Returns : | the identifier

## See Also

The MgServerDataType class an the MgDataEntry interface.