Attributes manager

Attributes manager — Manager for lists of attributes

Stability Level

Stable, unless otherwise indicated

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


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;