Attributes manager: GNOME Data Access 5 manual

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;