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

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);

for_objects :

signal_func :

signal_data :

Returns :


gda_attributes_manager_free ()

void                gda_attributes_manager_free         (GdaAttributesManager *mgr);

Frees all the resssources managed by mgr


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 resources 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 resources 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);

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

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.

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.

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.

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]