## GnomeDbEntity

GnomeDbEntity — Interface to represent a generic entity (for tables, views or queries)

##

# Synopsis

    struct      GnomeDbEntity;
    GType       gnome_db_entity_get_type        (void);
    gboolean    gnome_db_entity_has_field       (GnomeDbEntity *iface,
                                                 GnomeDbField *field);
    GSList*     gnome_db_entity_get_fields      (GnomeDbEntity *iface);
    gint        gnome_db_entity_get_n_fields    (GnomeDbEntity *iface);
    GnomeDbField* gnome_db_entity_get_field_by_name
                                                (GnomeDbEntity *iface,
                                                 const gchar *name);
    GnomeDbField* gnome_db_entity_get_field_by_xml_id
                                                (GnomeDbEntity *iface,
                                                 const gchar *xml_id);
    GnomeDbField* gnome_db_entity_get_field_by_index
                                                (GnomeDbEntity *iface,
                                                 gint index);
    gint        gnome_db_entity_get_field_index (GnomeDbEntity *iface,
                                                 GnomeDbField *field);
    void        gnome_db_entity_add_field       (GnomeDbEntity *iface,
                                                 GnomeDbField *field);
    void        gnome_db_entity_add_field_before
                                                (GnomeDbEntity *iface,
                                                 GnomeDbField *field,
                                                 GnomeDbField *field_before);
    void        gnome_db_entity_swap_fields     (GnomeDbEntity *iface,
                                                 GnomeDbField *field1,
                                                 GnomeDbField *field2);
    void        gnome_db_entity_remove_field    (GnomeDbEntity *iface,
                                                 GnomeDbField *field);
    gboolean    gnome_db_entity_is_writable     (GnomeDbEntity *iface);
    GSList*     gnome_db_entity_get_parameters  (GnomeDbEntity *iface);
    GnomeDbDataSet* gnome_db_entity_get_exec_dataset
                                                (GnomeDbEntity *iface);

## Object Hierarchy

      GInterface
       +----GnomeDbEntity

## Prerequisites

GnomeDbEntity requires GnomeDbBase.

## Known Derived Interfaces

GnomeDbEntity is required by GnomeDbDataModel.

## Known Implementations

GnomeDbEntity is implemented by GnomeDbQuery, GnomeDbTable, GnomeDbModelWrapper and GnomeDbResultSet.

## Signal Prototypes

    "field-added"
                void        user_function      (GnomeDbEntity *dbentity,
                                                gpointer arg1,
                                                gpointer user_data);
    "field-removed"
                void        user_function      (GnomeDbEntity *dbentity,
                                                gpointer arg1,
                                                gpointer user_data);
    "field-updated"
                void        user_function      (GnomeDbEntity *dbentity,
                                                gpointer arg1,
                                                gpointer user_data);
    "fields-order-changed"
                void        user_function      (GnomeDbEntity *dbentity,
                                                gpointer user_data);

## Description

## Details

### struct GnomeDbEntity

    struct GnomeDbEntity;

### gnome_db_entity_get_type ()

    GType       gnome_db_entity_get_type        (void);

Returns : |

### gnome_db_entity_has_field ()

    gboolean    gnome_db_entity_has_field       (GnomeDbEntity *iface,
                                                 GnomeDbField *field);

Tells if `field` belongs to the `iface` entity

`iface` : | an object implementing the GnomeDbEntity interface
`field` : | an object implementing the GnomeDbField interface
Returns : | TRUE if `field` belongs to the `iface` entity

### gnome_db_entity_get_fields ()

    GSList*     gnome_db_entity_get_fields      (GnomeDbEntity *iface);

Get a new list containing all the GnomeDbField objects held within the object implementing the GnomeDbEntity interface.

The returned list nodes are in the order in which the fields are within the entity.

`iface` : | an object implementing the GnomeDbEntity interface
Returns : | the new list.

### gnome_db_entity_get_n_fields ()

    gint        gnome_db_entity_get_n_fields    (GnomeDbEntity *iface);

Get the number of fields in `iface`

`iface` : | an object implementing the GnomeDbEntity interface
Returns : | the number of fields, or -1 if an error occured

### gnome_db_entity_get_field_by_name ()

    GnomeDbField* gnome_db_entity_get_field_by_name
                                                (GnomeDbEntity *iface,
                                                 const gchar *name);

Get a GnomeDbField using its name. The notion of "field name" is the string returned by `gnome_db_field_get_name()` on each of the fields composing `iface`. However, if that definition does not return any field, then each particular implementation of `iface` may try to give an extra definition to the notion of "field name".

For instance, in the case of the GnomeDbQuery object, the `gnome_db_field_get_name()` is used as a first try to find a field, and if that fails, then the object tries to find fields from their SQL naming.

In the case where there can be more than one field with the same name (depending on `iface`'s implementation), then the returned value is `NULL`.

`iface` : | an object implementing the GnomeDbEntity interface
`name` : |
Returns : | the requested GnomeDbField or `NULL` if the field cannot be found, or if more than one field has been found.

### gnome_db_entity_get_field_by_xml_id ()

    GnomeDbField* gnome_db_entity_get_field_by_xml_id
                                                (GnomeDbEntity *iface,
                                                 const gchar *xml_id);

`iface` : | an object implementing the GnomeDbEntity interface
`xml_id` : |
Returns : | the requested GnomeDbField

### gnome_db_entity_get_field_by_index ()

    GnomeDbField* gnome_db_entity_get_field_by_index
                                                (GnomeDbEntity *iface,
                                                 gint index);

`iface` : | an object implementing the GnomeDbEntity interface
`index` : |
Returns : | the requested GnomeDbField or NULL if the index is out of bounds

### gnome_db_entity_get_field_index ()

    gint        gnome_db_entity_get_field_index (GnomeDbEntity *iface,
                                                 GnomeDbField *field);

Get the position of the field in the given entity. Positions start at 0. `field` MUST be a visible field.

`iface` : | an object implementing the GnomeDbEntity interface
`field` : | an object implementing the GnomeDbField interface
Returns : | the position or -1 if the field is not in the entity or is not visible

### gnome_db_entity_add_field ()

    void        gnome_db_entity_add_field       (GnomeDbEntity *iface,
                                                 GnomeDbField *field);

Add `field` to `iface`'s fields (at the end of the list)

`iface` : | an object implementing the GnomeDbEntity interface
`field` : | an object implementing the GnomeDbField interface to add

### gnome_db_entity_add_field_before ()

    void        gnome_db_entity_add_field_before
                                                (GnomeDbEntity *iface,
                                                 GnomeDbField *field,
                                                 GnomeDbField *field_before);

Add `field` to `iface`'s fields, before `field_before` if it is not `NULL`, or at the end if `field_before` is `NULL`.

`iface` : | an object implementing the GnomeDbEntity interface
`field` : | an object implementing the GnomeDbField interface to add
`field_before` : | an object implementing the GnomeDbField interface before which `field` will be added, or `NULL`

### gnome_db_entity_swap_fields ()

    void        gnome_db_entity_swap_fields     (GnomeDbEntity *iface,
                                                 GnomeDbField *field1,
                                                 GnomeDbField *field2);

`iface` : | an object implementing the GnomeDbEntity interface
`field1` : | an object implementing the GnomeDbField interface
`field2` : | an object implementing the GnomeDbField interface

### gnome_db_entity_remove_field ()

    void        gnome_db_entity_remove_field    (GnomeDbEntity *iface,
                                                 GnomeDbField *field);

`iface` : | an object implementing the GnomeDbEntity interface
`field` : | an object implementing the GnomeDbField interface to remove

### gnome_db_entity_is_writable ()

    gboolean    gnome_db_entity_is_writable     (GnomeDbEntity *iface);

Tells if the real entity (the corresponding DBMS object) represented by `iface` can be written to.

`iface` : | an object implementing the GnomeDbEntity interface
Returns : | TRUE if it is possible to write to `iface`

### gnome_db_entity_get_parameters ()

    GSList*     gnome_db_entity_get_parameters  (GnomeDbEntity *iface);

Get a list of parameters required before `iface` can be used. Usualy this function is used with queries to grab the required parameters before executing a query.

This function is usually not used directly, but rather through `gnome_db_entity_get_exec_dataset()`.

`iface` : | an object implementing the GnomeDbEntity interface
Returns : | a new list of GnomeDbParameter objects. `iface` DOES NOT hold any reference to any of the listed parameter.

### gnome_db_entity_get_exec_dataset ()

    GnomeDbDataSet* gnome_db_entity_get_exec_dataset
                                                (GnomeDbEntity *iface);

Creates a new GnomeDbDataSet object which contains all the parameters required to use `iface`. This function is similar to `gnome_db_entity_get_parameters()` except that it also creates a GnomeDbDataSet object to help manage all the parameters.

`iface` : | an object implementing the GnomeDbEntity interface
Returns : | a new GnomeDbDataSet object

## Signals

### The "field-added" signal

    void        user_function                  (GnomeDbEntity *dbentity,
                                                gpointer arg1,
                                                gpointer user_data);

`dbentity` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "field-removed" signal

    void        user_function                  (GnomeDbEntity *dbentity,
                                                gpointer arg1,
                                                gpointer user_data);

`dbentity` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "field-updated" signal

    void        user_function                  (GnomeDbEntity *dbentity,
                                                gpointer arg1,
                                                gpointer user_data);

`dbentity` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "fields-order-changed" signal

    void        user_function                  (GnomeDbEntity *dbentity,
                                                gpointer user_data);

`dbentity` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.