CamelObject

CamelObject

Synopsis

#define             CAMEL_OBJECT_TRACK_INSTANCES
typedef             CamelType;
                    CamelObject;
#define             CAMEL_CHECK_CAST                    (obj,
                                                         ctype,
                                                         ptype)
#define             CAMEL_CHECK_CLASS_CAST              (klass,
                                                         ctype,
                                                         ptype)
#define             CAMEL_CHECK_TYPE                    (obj,
                                                         ctype)
#define             CAMEL_CHECK_CLASS_TYPE              (klass,
                                                         ctype)
extern              CamelType camel_object_type;
#define             CAMEL_OBJECT_TYPE
#define             CAMEL_OBJECT_GET_TYPE               (o)
typedef             CamelObjectHookID;
                    CamelObjectMeta;
extern              CamelType camel_interface_type;
#define             CAMEL_INTERFACE_TYPE
                    CamelInterface;
void                (*CamelObjectClassInitFunc)         (CamelObjectClass *Param1);
void                (*CamelObjectClassFinalizeFunc)     (CamelObjectClass *Param1);
void                (*CamelObjectInitFunc)              (CamelObject *Param1,
                                                         CamelObjectClass *Param2);
void                (*CamelObjectFinalizeFunc)          (CamelObject *Param1);
gboolean            (*CamelObjectEventPrepFunc)         (CamelObject *Param1,
                                                         gpointer Param2);
void                (*CamelObjectEventHookFunc)         (CamelObject *Param1,
                                                         gpointer Param2,
                                                         gpointer Param3);
#define             CAMEL_INVALID_TYPE
enum                CamelObjectFlags;
void                camel_type_init                     (void);
CamelType           camel_type_register                 (CamelType parent,
                                                         const gchar *name,
                                                         gsize instance_size,
                                                         gsize classfuncs_size,
                                                         CamelObjectClassInitFunc class_init,
                                                         CamelObjectClassFinalizeFunc class_finalize,
                                                         CamelObjectInitFunc instance_init,
                                                         CamelObjectFinalizeFunc instance_finalize);
CamelType           camel_interface_register            (CamelType parent,
                                                         const gchar *name,
                                                         gsize classfuncs_size,
                                                         CamelObjectClassInitFunc class_init,
                                                         CamelObjectClassFinalizeFunc class_finalize);
#define             camel_type_get_global_classfuncs    (x)
const gchar *       camel_type_to_name                  (CamelType type);
CamelType           camel_name_to_type                  (const gchar *name);
void                camel_object_class_add_event        (CamelObjectClass *klass,
                                                         const gchar *name,
                                                         CamelObjectEventPrepFunc prep);
void                camel_object_class_add_interface    (CamelObjectClass *klass,
                                                         CamelType itype);
void                camel_object_class_dump_tree        (CamelType root);
CamelObject *       camel_object_cast                   (CamelObject *obj,
                                                         CamelType ctype);
gboolean            camel_object_is                     (CamelObject *obj,
                                                         CamelType ctype);
CamelObjectClass *  camel_object_class_cast             (CamelObjectClass *klass,
                                                         CamelType ctype);
gboolean            camel_object_class_is               (CamelObjectClass *klass,
                                                         CamelType ctype);
CamelObjectClass *  camel_interface_cast                (CamelObjectClass *klass,
                                                         CamelType ctype);
gboolean            camel_interface_is                  (CamelObjectClass *k,
                                                         CamelType ctype);
CamelObject *       camel_object_new                    (CamelType type);
void                camel_object_ref                    (gpointer Param1);
void                camel_object_unref                  (gpointer Param1);
CamelObjectHookID   camel_object_hook_event             (gpointer obj,
                                                         const gchar *name,
                                                         CamelObjectEventHookFunc hook,
                                                         gpointer data);
void                camel_object_remove_event           (gpointer obj,
                                                         CamelObjectHookID id);
void                camel_object_unhook_event           (gpointer obj,
                                                         const gchar *name,
                                                         CamelObjectEventHookFunc hook,
                                                         gpointer data);
void                camel_object_trigger_event          (gpointer obj,
                                                         const gchar *name,
                                                         gpointer event_data);
gpointer            camel_object_get_interface          (gpointer vo,
                                                         CamelType itype);
gint                camel_object_set                    (gpointer obj,
                                                         struct _CamelException *ex,
                                                         ...);
gint                camel_object_setv                   (gpointer obj,
                                                         struct _CamelException *ex,
                                                         CamelArgV *Param3);
gint                camel_object_get                    (gpointer obj,
                                                         struct _CamelException *ex,
                                                         ...);
gint                camel_object_getv                   (gpointer obj,
                                                         struct _CamelException *ex,
                                                         CamelArgGetV *Param3);
gpointer            camel_object_get_ptr                (gpointer vo,
                                                         CamelException *ex,
                                                         gint tag);
gint                camel_object_get_int                (gpointer vo,
                                                         CamelException *ex,
                                                         gint tag);
gchar *             camel_object_meta_get               (gpointer vo,
                                                         const gchar *name);
gboolean            camel_object_meta_set               (gpointer vo,
                                                         const gchar *name,
                                                         const gchar *value);
gint                camel_object_state_read             (gpointer vo);
gint                camel_object_state_write            (gpointer vo);
void                camel_object_free                   (gpointer vo,
                                                         guint32 tag,
                                                         gpointer value);
                    CamelObjectBag;
gpointer            (*CamelCopyFunc)                    (gconstpointer vo);
CamelObjectBag *    camel_object_bag_new                (GHashFunc hash,
                                                         GEqualFunc equal,
                                                         CamelCopyFunc keycopy,
                                                         GFreeFunc keyfree);
gpointer            camel_object_bag_get                (CamelObjectBag *bag,
                                                         gconstpointer key);
gpointer            camel_object_bag_peek               (CamelObjectBag *bag,
                                                         gconstpointer key);
gpointer            camel_object_bag_reserve            (CamelObjectBag *bag,
                                                         gconstpointer key);
void                camel_object_bag_add                (CamelObjectBag *bag,
                                                         gconstpointer key,
                                                         gpointer vo);
void                camel_object_bag_abort              (CamelObjectBag *bag,
                                                         gconstpointer key);
void                camel_object_bag_rekey              (CamelObjectBag *bag,
                                                         gpointer o,
                                                         gconstpointer newkey);
GPtrArray *         camel_object_bag_list               (CamelObjectBag *bag);
void                camel_object_bag_remove             (CamelObjectBag *bag,
                                                         gpointer o);
void                camel_object_bag_destroy            (CamelObjectBag *bag);
#define             CAMEL_MAKE_CLASS                    (type,
                                                         tname,
                                                         parent,
                                                         pname)
                    CamelIteratorVTable;
                    CamelIterator;
gpointer            camel_iterator_new                  (CamelIteratorVTable *klass,
                                                         gsize size);
void                camel_iterator_free                 (gpointer it);
gconstpointer       camel_iterator_next                 (gpointer it,
                                                         CamelException *ex);
void                camel_iterator_reset                (gpointer it);
gint                camel_iterator_length               (gpointer it);

Description

Details

CAMEL_OBJECT_TRACK_INSTANCES

#define CAMEL_OBJECT_TRACK_INSTANCES


CamelType

typedef struct _CamelObjectClass *CamelType;


CamelObject

typedef struct {
	struct _CamelObjectClass *klass;

	guint32 magic;		/* only really needed for debugging ... */

	/* current hooks on this object */
	struct _CamelHookList *hooks;

	guint32 ref_count:24;
	guint32 flags:8;

#ifdef CAMEL_OBJECT_TRACK_INSTANCES
	struct _CamelObject *next, *prev;
#endif
} CamelObject;


CAMEL_CHECK_CAST()

#define             CAMEL_CHECK_CAST(obj, ctype, ptype)

obj :

ctype :

ptype :


CAMEL_CHECK_CLASS_CAST()

#define             CAMEL_CHECK_CLASS_CAST(klass, ctype, ptype)

klass :

ctype :

ptype :


CAMEL_CHECK_TYPE()

#define CAMEL_CHECK_TYPE(obj, ctype)                (camel_object_is ((CamelObject *)(obj), (CamelType)(ctype) ))

obj :

ctype :


CAMEL_CHECK_CLASS_TYPE()

#define CAMEL_CHECK_CLASS_TYPE(klass, ctype)        (camel_object_class_is ((CamelObjectClass *)(klass), (CamelType)(ctype)))

klass :

ctype :


camel_object_type

extern CamelType camel_object_type;


CAMEL_OBJECT_TYPE

#define CAMEL_OBJECT_TYPE        (camel_object_type)


CAMEL_OBJECT_GET_TYPE()

#define CAMEL_OBJECT_GET_TYPE(o)  ((CamelType)(CAMEL_OBJECT(o))->klass)

o :


CamelObjectHookID

typedef guint CamelObjectHookID;


CamelObjectMeta

typedef struct {
	struct _CamelObjectMeta *next;

	gchar *value;
	gchar name[1];		/* allocated as part of structure */
} CamelObjectMeta;

Warning

CamelObjectMeta is deprecated and should not be used in newly-written code.


camel_interface_type

extern CamelType camel_interface_type;

Warning

camel_interface_type is deprecated and should not be used in newly-written code.


CAMEL_INTERFACE_TYPE

#define CAMEL_INTERFACE_TYPE (camel_interface_type)

Warning

CAMEL_INTERFACE_TYPE is deprecated and should not be used in newly-written code.


CamelInterface

typedef struct {
	struct _CamelObjectClass type;
} CamelInterface;

Warning

CamelInterface is deprecated and should not be used in newly-written code.


CamelObjectClassInitFunc ()

void                (*CamelObjectClassInitFunc)         (CamelObjectClass *Param1);

Param1 :


CamelObjectClassFinalizeFunc ()

void                (*CamelObjectClassFinalizeFunc)     (CamelObjectClass *Param1);

Param1 :


CamelObjectInitFunc ()

void                (*CamelObjectInitFunc)              (CamelObject *Param1,
                                                         CamelObjectClass *Param2);

Param1 :

Param2 :


CamelObjectFinalizeFunc ()

void                (*CamelObjectFinalizeFunc)          (CamelObject *Param1);

Param1 :


CamelObjectEventPrepFunc ()

gboolean            (*CamelObjectEventPrepFunc)         (CamelObject *Param1,
                                                         gpointer Param2);

Param1 :

Param2 :

Returns :


CamelObjectEventHookFunc ()

void                (*CamelObjectEventHookFunc)         (CamelObject *Param1,
                                                         gpointer Param2,
                                                         gpointer Param3);

Param1 :

Param2 :

Param3 :


CAMEL_INVALID_TYPE

#define CAMEL_INVALID_TYPE (NULL)


enum CamelObjectFlags

typedef enum _CamelObjectFlags {
	CAMEL_OBJECT_DESTROY = (1<<0)
} CamelObjectFlags;


camel_type_init ()

void                camel_type_init                     (void);


camel_type_register ()

CamelType           camel_type_register                 (CamelType parent,
                                                         const gchar *name,
                                                         gsize instance_size,
                                                         gsize classfuncs_size,
                                                         CamelObjectClassInitFunc class_init,
                                                         CamelObjectClassFinalizeFunc class_finalize,
                                                         CamelObjectInitFunc instance_init,
                                                         CamelObjectFinalizeFunc instance_finalize);

parent :

name :

instance_size :

classfuncs_size :

class_init :

class_finalize :

instance_init :

instance_finalize :

Returns :


camel_interface_register ()

CamelType           camel_interface_register            (CamelType parent,
                                                         const gchar *name,
                                                         gsize classfuncs_size,
                                                         CamelObjectClassInitFunc class_init,
                                                         CamelObjectClassFinalizeFunc class_finalize);

Warning

camel_interface_register is deprecated and should not be used in newly-written code.

parent :

name :

classfuncs_size :

class_init :

class_finalize :

Returns :


camel_type_get_global_classfuncs()

#define camel_type_get_global_classfuncs(x) ((CamelObjectClass *)(x))

x :


camel_type_to_name ()

const gchar *       camel_type_to_name                  (CamelType type);

type :

Returns :


camel_name_to_type ()

CamelType           camel_name_to_type                  (const gchar *name);

name :

Returns :


camel_object_class_add_event ()

void                camel_object_class_add_event        (CamelObjectClass *klass,
                                                         const gchar *name,
                                                         CamelObjectEventPrepFunc prep);

klass :

name :

prep :


camel_object_class_add_interface ()

void                camel_object_class_add_interface    (CamelObjectClass *klass,
                                                         CamelType itype);

Warning

camel_object_class_add_interface is deprecated and should not be used in newly-written code.

klass :

itype :


camel_object_class_dump_tree ()

void                camel_object_class_dump_tree        (CamelType root);

root :


camel_object_cast ()

CamelObject *       camel_object_cast                   (CamelObject *obj,
                                                         CamelType ctype);

obj :

ctype :

Returns :


camel_object_is ()

gboolean            camel_object_is                     (CamelObject *obj,
                                                         CamelType ctype);

obj :

ctype :

Returns :


camel_object_class_cast ()

CamelObjectClass *  camel_object_class_cast             (CamelObjectClass *klass,
                                                         CamelType ctype);

klass :

ctype :

Returns :


camel_object_class_is ()

gboolean            camel_object_class_is               (CamelObjectClass *klass,
                                                         CamelType ctype);

klass :

ctype :

Returns :


camel_interface_cast ()

CamelObjectClass *  camel_interface_cast                (CamelObjectClass *klass,
                                                         CamelType ctype);

Warning

camel_interface_cast is deprecated and should not be used in newly-written code.

klass :

ctype :

Returns :


camel_interface_is ()

gboolean            camel_interface_is                  (CamelObjectClass *k,
                                                         CamelType ctype);

Warning

camel_interface_is is deprecated and should not be used in newly-written code.

k :

ctype :

Returns :


camel_object_new ()

CamelObject *       camel_object_new                    (CamelType type);

type :

Returns :


camel_object_ref ()

void                camel_object_ref                    (gpointer Param1);

Param1 :


camel_object_unref ()

void                camel_object_unref                  (gpointer Param1);

Param1 :


camel_object_hook_event ()

CamelObjectHookID   camel_object_hook_event             (gpointer obj,
                                                         const gchar *name,
                                                         CamelObjectEventHookFunc hook,
                                                         gpointer data);

obj :

name :

hook :

data :

Returns :


camel_object_remove_event ()

void                camel_object_remove_event           (gpointer obj,
                                                         CamelObjectHookID id);

obj :

id :


camel_object_unhook_event ()

void                camel_object_unhook_event           (gpointer obj,
                                                         const gchar *name,
                                                         CamelObjectEventHookFunc hook,
                                                         gpointer data);

obj :

name :

hook :

data :


camel_object_trigger_event ()

void                camel_object_trigger_event          (gpointer obj,
                                                         const gchar *name,
                                                         gpointer event_data);

obj :

name :

event_data :


camel_object_get_interface ()

gpointer            camel_object_get_interface          (gpointer vo,
                                                         CamelType itype);

Warning

camel_object_get_interface is deprecated and should not be used in newly-written code.

vo :

itype :

Returns :


camel_object_set ()

gint                camel_object_set                    (gpointer obj,
                                                         struct _CamelException *ex,
                                                         ...);

obj :

ex :

... :

Returns :


camel_object_setv ()

gint                camel_object_setv                   (gpointer obj,
                                                         struct _CamelException *ex,
                                                         CamelArgV *Param3);

obj :

ex :

Param3 :

Returns :


camel_object_get ()

gint                camel_object_get                    (gpointer obj,
                                                         struct _CamelException *ex,
                                                         ...);

obj :

ex :

... :

Returns :


camel_object_getv ()

gint                camel_object_getv                   (gpointer obj,
                                                         struct _CamelException *ex,
                                                         CamelArgGetV *Param3);

obj :

ex :

Param3 :

Returns :


camel_object_get_ptr ()

gpointer            camel_object_get_ptr                (gpointer vo,
                                                         CamelException *ex,
                                                         gint tag);

vo :

ex :

tag :

Returns :


camel_object_get_int ()

gint                camel_object_get_int                (gpointer vo,
                                                         CamelException *ex,
                                                         gint tag);

vo :

ex :

tag :

Returns :


camel_object_meta_get ()

gchar *             camel_object_meta_get               (gpointer vo,
                                                         const gchar *name);

Get a meta-data on an object.

Returns :

NULL if the meta-data is not set.

camel_object_meta_set ()

gboolean            camel_object_meta_set               (gpointer vo,
                                                         const gchar *name,
                                                         const gchar *value);

Set a meta-data item on an object. If the object supports persistent data, then the meta-data will be persistent across sessions.

If the meta-data changes, is added, or removed, then a "meta_changed" event will be triggered with the name of the changed data.

name :

Name of meta-data. Should be prefixed with class of setter.

value :

Value to set. If NULL, then the meta-data is removed.

Returns :

TRUE if the setting caused a change to the object's metadata.

camel_object_state_read ()

gint                camel_object_state_read             (gpointer vo);

Read persistent object state from object_set(CAMEL_OBJECT_STATE_FILE).

Returns :

-1 on error.

camel_object_state_write ()

gint                camel_object_state_write            (gpointer vo);

Write persistent state to the file as set by object_set(CAMEL_OBJECT_STATE_FILE).

Returns :

-1 on error.

camel_object_free ()

void                camel_object_free                   (gpointer vo,
                                                         guint32 tag,
                                                         gpointer value);

vo :

tag :

value :


CamelObjectBag

typedef struct _CamelObjectBag CamelObjectBag;


CamelCopyFunc ()

gpointer            (*CamelCopyFunc)                    (gconstpointer vo);

vo :

Returns :


camel_object_bag_new ()

CamelObjectBag *    camel_object_bag_new                (GHashFunc hash,
                                                         GEqualFunc equal,
                                                         CamelCopyFunc keycopy,
                                                         GFreeFunc keyfree);

Allocate a new object bag. Object bag's are key'd hash tables of camel-objects which can be updated atomically using transaction semantics.

Returns :


camel_object_bag_get ()

gpointer            camel_object_bag_get                (CamelObjectBag *bag,
                                                         gconstpointer key);

Lookup an object by key. If the key is currently reserved, then wait until the key has been committed before continuing.

Returns :

NULL if the object corresponding to key is not in the bag. Otherwise a ref'd object pointer which the caller owns the ref to.

camel_object_bag_peek ()

gpointer            camel_object_bag_peek               (CamelObjectBag *bag,
                                                         gconstpointer key);

Lookup the object key in bag, ignoring any reservations. If it isn't committed, then it isn't considered. This should only be used where reliable transactional-based state is not required.

Unlike other 'peek' operations, the object is still reffed if found.

Returns :

A referenced object, or NULL if key is not present in the bag.

camel_object_bag_reserve ()

gpointer            camel_object_bag_reserve            (CamelObjectBag *bag,
                                                         gconstpointer key);

Reserve a key in the object bag. If the key is already reserved in another thread, then wait until the reservation has been committed.

After reserving a key, you either get a reffed pointer to the object corresponding to the key, similar to object_bag_get, or you get NULL, signifying that you then MIST call either object_bag_add or object_bag_abort.

You may reserve multiple keys from the same thread, but they should always be reserved in the same order, to avoid deadlocks.

Returns :


camel_object_bag_add ()

void                camel_object_bag_add                (CamelObjectBag *bag,
                                                         gconstpointer key,
                                                         gpointer vo);

Add an object vo to the object bag bag. The key MUST have previously been reserved using camel_object_bag_reserve().


camel_object_bag_abort ()

void                camel_object_bag_abort              (CamelObjectBag *bag,
                                                         gconstpointer key);

Abort a key reservation.


camel_object_bag_rekey ()

void                camel_object_bag_rekey              (CamelObjectBag *bag,
                                                         gpointer o,
                                                         gconstpointer newkey);

Re-key an object, atomically. The key for object o is set to newkey, in an atomic manner.

It is an api (fatal) error if o is not currently in the bag.


camel_object_bag_list ()

GPtrArray *         camel_object_bag_list               (CamelObjectBag *bag);

bag :

Returns :


camel_object_bag_remove ()

void                camel_object_bag_remove             (CamelObjectBag *bag,
                                                         gpointer o);

bag :

o :


camel_object_bag_destroy ()

void                camel_object_bag_destroy            (CamelObjectBag *bag);

bag :


CAMEL_MAKE_CLASS()

#define             CAMEL_MAKE_CLASS(type, tname, parent, pname)

type :

tname :

parent :

pname :


CamelIteratorVTable

typedef struct {
	/* free fields, dont free base object */
	void (*free)(gpointer it);
	/* go to the next messageinfo */
	gconstpointer (*next)(gpointer it, CamelException *ex);
	/* go back to the start */
	void (*reset)(gpointer it);
	/* *ESTIMATE* how many results are in the iterator */
	gint (*length)(gpointer it);
} CamelIteratorVTable;

Warning

CamelIteratorVTable is deprecated and should not be used in newly-written code.


CamelIterator

typedef struct {
	CamelIteratorVTable *klass;

	/* subclasses adds new fields afterwards */
} CamelIterator;

Warning

CamelIterator is deprecated and should not be used in newly-written code.


camel_iterator_new ()

gpointer            camel_iterator_new                  (CamelIteratorVTable *klass,
                                                         gsize size);

Warning

camel_iterator_new is deprecated and should not be used in newly-written code.

klass :

size :

Returns :


camel_iterator_free ()

void                camel_iterator_free                 (gpointer it);

Warning

camel_iterator_free is deprecated and should not be used in newly-written code.

it :


camel_iterator_next ()

gconstpointer       camel_iterator_next                 (gpointer it,
                                                         CamelException *ex);

Warning

camel_iterator_next is deprecated and should not be used in newly-written code.

it :

ex :

Returns :


camel_iterator_reset ()

void                camel_iterator_reset                (gpointer it);

Warning

camel_iterator_reset is deprecated and should not be used in newly-written code.

it :


camel_iterator_length ()

gint                camel_iterator_length               (gpointer it);

Warning

camel_iterator_length is deprecated and should not be used in newly-written code.

it :

Returns :