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

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;


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


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