Attributes manager

## Attributes manager Attributes manager — Manager for lists of attributes |

## Synopsis

    #define             GDA_ATTRIBUTE_NAME
    #define             GDA_ATTRIBUTE_DESCRIPTION
    #define             GDA_ATTRIBUTE_AUTO_INCREMENT
    #define             GDA_ATTRIBUTE_NUMERIC_PRECISION
    #define             GDA_ATTRIBUTE_NUMERIC_SCALE
    #define             GDA_ATTRIBUTE_IS_DEFAULT

                        GdaAttributesManager;
    void                (*GdaAttributesManagerSignal)       (GObject *obj,
                                                             const gchar *att_name,
                                                             const GValue *value,
                                                             gpointer data);
    void                (*GdaAttributesManagerFunc)         (const gchar *att_name,
                                                             const GValue *value,
                                                             gpointer data);
    GdaAttributesManager * gda_attributes_manager_new       (gboolean for_objects,
                                                             GdaAttributesManagerSignal signal_func,
                                                             gpointer signal_data);
    void                gda_attributes_manager_free         (GdaAttributesManager *mgr);
    void                gda_attributes_manager_set          (GdaAttributesManager *mgr,
                                                             gpointer ptr,
                                                             const gchar *att_name,
                                                             const GValue *value);
    void                gda_attributes_manager_set_full     (GdaAttributesManager *mgr,
                                                             gpointer ptr,
                                                             const gchar *att_name,
                                                             const GValue *value,
                                                             GDestroyNotify destroy);
    const GValue *      gda_attributes_manager_get          (GdaAttributesManager *mgr,
                                                             gpointer ptr,
                                                             const gchar *att_name);
    void                gda_attributes_manager_copy         (GdaAttributesManager *from_mgr,
                                                             gpointer *from,
                                                             GdaAttributesManager *to_mgr,
                                                             gpointer *to);
    void                gda_attributes_manager_clear        (GdaAttributesManager *mgr,
                                                             gpointer ptr);
    void                gda_attributes_manager_foreach      (GdaAttributesManager *mgr,
                                                             gpointer ptr,
                                                             GdaAttributesManagerFunc func,
                                                             gpointer data);

## Description

The GdaAttributesManager manages lists of named values (attibutes) for the benefit of others (objects or ressources for which only a pointer is known). It is used internally by Libgda whenever an object or a simple structure may have several attributes.

The features are similar to those of the `g_object_set_data()` and similar but with the following major differences:

- it works with GObject objects and also with simple pointers to data

- attributes names are considered static (they are not copied) and so they must either be static strings or allocated strings which exist (unchanged) while an attribute uses it as name

- it is possible to iterate through the attributes

- the associated values are expected to be GValue values

Attibute names can be any string, but Libgda reserves some for its own usage, see below.

The GdaAttributesManager implements its own locking mechanism so it is thread-safe.

## Details

### GDA_ATTRIBUTE_NAME

    #define GDA_ATTRIBUTE_NAME "__gda_attr_name" /* G_TYPE_STRING */

The corresponding attribute is the name of the object it refers to (value has a G_TYPE_STRING type).

### GDA_ATTRIBUTE_DESCRIPTION

    #define GDA_ATTRIBUTE_DESCRIPTION "__gda_attr_descr" /* G_TYPE_STRING */

The corresponding attribute is the description of the object it refers to (value has a G_TYPE_STRING type).

### GDA_ATTRIBUTE_AUTO_INCREMENT

    #define GDA_ATTRIBUTE_AUTO_INCREMENT "__gda_attr_autoinc" /* G_TYPE_BOOLEAN */

The corresponding attribute specifies if the object it refers to is auto incremented (value has a G_TYPE_BOOLEAN type).

### GDA_ATTRIBUTE_NUMERIC_PRECISION

    #define GDA_ATTRIBUTE_NUMERIC_PRECISION "__gda_attr_numeric_precision" /* G_TYPE_INT */

The corresponding attribute is the number of significant digits of the object it refers to (value has a G_TYPE_INT type).

### GDA_ATTRIBUTE_NUMERIC_SCALE

    #define GDA_ATTRIBUTE_NUMERIC_SCALE "__gda_attr_numeric_scale" /* G_TYPE_INT */

The corresponding attribute is the number of significant digits to the right of the decimal point of the object it refers to (value has a G_TYPE_INT type).

### GDA_ATTRIBUTE_IS_DEFAULT

    #define GDA_ATTRIBUTE_IS_DEFAULT "__gda_attr_is_default" /* G_TYPE_BOOLEAN */

The corresponding attribute specifies if the object it refers to has its value to default (value has a G_TYPE_BOOLEAN type).

### GdaAttributesManager

    typedef struct _GdaAttributesManager GdaAttributesManager;

### GdaAttributesManagerSignal ()

    void                (*GdaAttributesManagerSignal)       (GObject *obj,
                                                             const gchar *att_name,
                                                             const GValue *value,
                                                             gpointer data);

`obj` : |
`att_name` : |
`value` : |
`data` : |

### GdaAttributesManagerFunc ()

    void                (*GdaAttributesManagerFunc)         (const gchar *att_name,
                                                             const GValue *value,
                                                             gpointer data);

`att_name` : |
`value` : |
`data` : |

### gda_attributes_manager_new ()

    GdaAttributesManager * gda_attributes_manager_new       (gboolean for_objects,
                                                             GdaAttributesManagerSignal signal_func,
                                                             gpointer signal_data);

Creates a new GdaAttributesManager, which can store (name, value) attributes for pointers or GObject objects (in the latter case, the attibutes are destroyed when objects are also destroyed).

`for_objects` : | set to TRUE if attributes will be set on objects.
`signal_func` : | a function to be called whenever an attribute changes on an object (if `for_objects` is TRUE), or `NULL`
`signal_data` : | user data passed as last argument of `signal_func` when it is called
Returns : | the new GdaAttributesManager

### gda_attributes_manager_free ()

    void                gda_attributes_manager_free         (GdaAttributesManager *mgr);

Frees all the resssources managed by `mgr`

`mgr` : | a GdaAttributesManager

### gda_attributes_manager_set ()

    void                gda_attributes_manager_set          (GdaAttributesManager *mgr,
                                                             gpointer ptr,
                                                             const gchar *att_name,
                                                             const GValue *value);

Associates an attribute named `att_name` to `ptr`, with the value `value`. Any previous association is replaced by this one, and if `value` is `NULL` then the association is removed.

Note: `att_name` is *not* copied, so it should be a string which exists as long as `mgr` exists. Libgda provides several predefined names for common attributes, see this section.

If `att_name` needs to be freed when not used anymore, then use `gda_attributes_manager_set_full()`.

`mgr` : | a GdaAttributesManager
`ptr` : | a pointer to the ressources to which the attribute will apply
`att_name` : | an attribute's name
`value` : | a GValue, or `NULL`

### gda_attributes_manager_set_full ()

    void                gda_attributes_manager_set_full     (GdaAttributesManager *mgr,
                                                             gpointer ptr,
                                                             const gchar *att_name,
                                                             const GValue *value,
                                                             GDestroyNotify destroy);

Does the same as `gda_attributes_manager_set()` except that `destroy` is called when `att_name` needs to be freed.

`mgr` : | a GdaAttributesManager
`ptr` : | a pointer to the ressources to which the attribute will apply
`att_name` : | an attribute's name
`value` : | a GValue, or `NULL`
`destroy` : | function called when `att_name` has to be freed

### gda_attributes_manager_get ()

    const GValue *      gda_attributes_manager_get          (GdaAttributesManager *mgr,
                                                             gpointer ptr,
                                                             const gchar *att_name);

Retreives the value of an attribute previously set using `gda_attributes_manager_set()`.

`mgr` : | a GdaAttributesManager
`ptr` : | a pointer to the ressources to which the attribute will apply
`att_name` : | an attribute's name, as a *static* string
Returns : | the attribute's value, or `NULL` if the attribute is not set.

### gda_attributes_manager_copy ()

    void                gda_attributes_manager_copy         (GdaAttributesManager *from_mgr,
                                                             gpointer *from,
                                                             GdaAttributesManager *to_mgr,
                                                             gpointer *to);

For each attribute set for `from` (in `from_mgr`), set the same attribute to `to` (in `to_mgr`). `from_mgr` and `to_mgr` can be equal.

`from_mgr` : | a GdaAttributesManager
`from` : | a pointer from which attributes are copied
`to_mgr` : | a GdaAttributesManager
`to` : | a pointer to which attributes are copied

### gda_attributes_manager_clear ()

    void                gda_attributes_manager_clear        (GdaAttributesManager *mgr,
                                                             gpointer ptr);

Remove all the attributes managed by `mgr` for the `ptr` ressource.

`mgr` : | a GdaAttributesManager
`ptr` : | a pointer to the ressources for which all the attributes will be removed

### gda_attributes_manager_foreach ()

    void                gda_attributes_manager_foreach      (GdaAttributesManager *mgr,
                                                             gpointer ptr,
                                                             GdaAttributesManagerFunc func,
                                                             gpointer data);

Calls `func` for every attribute set to `ptr`.

`mgr` : | a GdaAttributesManager
`ptr` : | a pointer to the ressources for which all the attributes used
`func` : | a GdaAttributesManagerFunc function
`data` : | user data to be passed as last argument of `func` each time it is called