## Attributes manager

Attributes manager — Manager for lists of attributes

## Stability Level

Stable, unless otherwise indicated

## Functions

void | (*GdaAttributesManagerSignal) ()
void | (*GdaAttributesManagerFunc) ()
GdaAttributesManager * | gda_attributes_manager_new ()
void | gda_attributes_manager_free ()
void | gda_attributes_manager_set ()
void | gda_attributes_manager_set_full ()
const GValue * | gda_attributes_manager_get ()
void | gda_attributes_manager_copy ()
void | gda_attributes_manager_clear ()
void | gda_attributes_manager_foreach ()

## Types and Values

#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
#define | GDA_ATTRIBUTE_TREE_NODE_UNKNOWN_CHILDREN
| GdaAttributesManager

## Description

he GdaAttributesManager manages lists of named values (attributes) for the benefit of others (objects or resources 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.

## Functions

### GdaAttributesManagerSignal ()

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

### GdaAttributesManagerFunc ()

    void
    (*GdaAttributesManagerFunc) (const gchar *att_name,
                                 const GValue *value,
                                 gpointer 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 attributes are destroyed when objects are also destroyed).

Free-function: gda_attributes_manager_free

#### Parameters

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`. | [allow-none]
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`

#### Parameters

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()`.

#### Parameters

mgr | a GdaAttributesManager |
ptr | a pointer to the resources to which the attribute will apply |
att_name | an attribute's name |
value | a GValue, or `NULL`. | [transfer none][allow-none]

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

#### Parameters

mgr | a GdaAttributesManager |
ptr | a pointer to the resources to which the attribute will apply |
att_name | an attribute's name |
value | a GValue, or `NULL`. | [allow-none]
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);

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

#### Parameters

mgr | a GdaAttributesManager |
ptr | a pointer to the resources to which the attribute will apply |
att_name | an attribute's name |

#### Returns

the attribute's value, or `NULL` if the attribute is not set.

[tranfer none]

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

#### Parameters

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` resource.

#### Parameters

mgr | a GdaAttributesManager |
ptr | a pointer to the resources 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` .

#### Parameters

mgr | a GdaAttributesManager |
ptr | a pointer to the resources for which all the attributes used |
func | a GdaAttributesManagerFunc function. | [scope call]
data | user data to be passed as last argument of `func` each time it is called. | [closure]

## Types and Values

### GDA_ATTRIBUTE_NAME

    #define GDA_ATTRIBUTE_NAME "__gda_attr_name"

### GDA_ATTRIBUTE_DESCRIPTION

    #define GDA_ATTRIBUTE_DESCRIPTION "__gda_attr_descr"

### GDA_ATTRIBUTE_AUTO_INCREMENT

    #define GDA_ATTRIBUTE_AUTO_INCREMENT "__gda_attr_autoinc"

### GDA_ATTRIBUTE_NUMERIC_PRECISION

    #define GDA_ATTRIBUTE_NUMERIC_PRECISION "__gda_attr_numeric_precision"

### GDA_ATTRIBUTE_NUMERIC_SCALE

    #define GDA_ATTRIBUTE_NUMERIC_SCALE "__gda_attr_numeric_scale"

### GDA_ATTRIBUTE_IS_DEFAULT

    #define GDA_ATTRIBUTE_IS_DEFAULT "__gda_attr_is_default"

### GDA_ATTRIBUTE_TREE_NODE_UNKNOWN_CHILDREN

    #define GDA_ATTRIBUTE_TREE_NODE_UNKNOWN_CHILDREN "__gda_attr_tnuchild"

### GdaAttributesManager

    typedef struct _GdaAttributesManager GdaAttributesManager;