|  |  |  | Camel Reference Manual |  | 
|---|---|---|---|---|
#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 *); void (*CamelObjectClassFinalizeFunc) (CamelObjectClass *); void (*CamelObjectInitFunc) (CamelObject *, CamelObjectClass *); void (*CamelObjectFinalizeFunc) (CamelObject *); gboolean (*CamelObjectEventPrepFunc) (CamelObject *, gpointer ); void (*CamelObjectEventHookFunc) (CamelObject *, gpointer , gpointer ); #define CAMEL_INVALID_TYPE enum CamelObjectFlags; void camel_type_init (void); CamelType camel_type_register (CamelType parent, const char *name, size_t instance_size, size_t classfuncs_size, CamelObjectClassInitFunc class_init, CamelObjectClassFinalizeFunc class_finalize, CamelObjectInitFunc instance_init, CamelObjectFinalizeFunc instance_finalize); CamelType camel_interface_register (CamelType parent, const char *name, size_t classfuncs_size, CamelObjectClassInitFunc class_init, CamelObjectClassFinalizeFunc class_finalize); #define camel_type_get_global_classfuncs (x) const char* camel_type_to_name (CamelType type); CamelType camel_name_to_type (const char *name); void camel_object_class_add_event (CamelObjectClass *klass, const char *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); CamelObject* camel_object_new_name (const char *name); void camel_object_ref (void *); void camel_object_unref (void *); CamelObjectHookID camel_object_hook_event (void *obj, const char *name, CamelObjectEventHookFunc hook, void *data); void camel_object_remove_event (void *obj, CamelObjectHookID id); void camel_object_unhook_event (void *obj, const char *name, CamelObjectEventHookFunc hook, void *data); void camel_object_trigger_event (void *obj, const char *name, void *event_data); void* camel_object_get_interface (void *vo, CamelType itype); int camel_object_set (void *obj, struct _CamelException *ex, ...); int camel_object_setv (void *obj, struct _CamelException *ex, CamelArgV *); int camel_object_get (void *obj, struct _CamelException *ex, ...); int camel_object_getv (void *obj, struct _CamelException *ex, CamelArgGetV *); void* camel_object_get_ptr (void *vo, CamelException *ex, int tag); int camel_object_get_int (void *vo, CamelException *ex, int tag); char* camel_object_meta_get (void *vo, const char *name); gboolean camel_object_meta_set (void *vo, const char *name, const char *value); int camel_object_state_read (void *vo); int camel_object_state_write (void *vo); void camel_object_free (void *vo, guint32 tag, void *value); CamelObjectBag; void* (*CamelCopyFunc) (const void *vo); CamelObjectBag* camel_object_bag_new (GHashFunc hash, GEqualFunc equal, CamelCopyFunc keycopy, GFreeFunc keyfree); void* camel_object_bag_get (CamelObjectBag *bag, const void *key); void* camel_object_bag_peek (CamelObjectBag *bag, const void *key); void* camel_object_bag_reserve (CamelObjectBag *bag, const void *key); void camel_object_bag_add (CamelObjectBag *bag, const void *key, void *o); void camel_object_bag_abort (CamelObjectBag *bag, const void *key); void camel_object_bag_rekey (CamelObjectBag *bag, void *o, const void *newkey); GPtrArray* camel_object_bag_list (CamelObjectBag *bag); void camel_object_bag_remove (CamelObjectBag *bag, void *o); void camel_object_bag_destroy (CamelObjectBag *bag); #define CAMEL_MAKE_CLASS (type, tname, parent, pname) CamelIteratorVTable; CamelIterator; void* camel_iterator_new (CamelIteratorVTable *klass, size_t size); void camel_iterator_free (void *it); const void* camel_iterator_next (void *it, CamelException *ex); void camel_iterator_reset (void *it); int camel_iterator_length (void *it);
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;
#define CAMEL_CHECK_CLASS_CAST(klass, ctype, ptype)
| klass: | |
| ctype: | |
| ptype: | 
#define CAMEL_CHECK_TYPE(obj, ctype) (camel_object_is ((CamelObject *)(obj), (CamelType)(ctype) ))
| obj: | |
| ctype: | 
#define CAMEL_CHECK_CLASS_TYPE(klass, ctype) (camel_object_class_is ((CamelObjectClass *)(klass), (CamelType)(ctype)))
| klass: | |
| ctype: | 
typedef struct {
	struct _CamelObjectMeta *next;
	char *value;
	char name[1];		/* allocated as part of structure */
} CamelObjectMeta;
void (*CamelObjectInitFunc) (CamelObject *, CamelObjectClass *);
| Param1: | |
| Param2: | 
gboolean (*CamelObjectEventPrepFunc) (CamelObject *, gpointer );
| Param1: | |
| Param2: | |
| Returns : | 
void (*CamelObjectEventHookFunc) (CamelObject *, gpointer , gpointer );
| Param1: | |
| Param2: | |
| Param3: | 
typedef enum _CamelObjectFlags {
	CAMEL_OBJECT_DESTROY = (1<<0),
} CamelObjectFlags;
CamelType camel_type_register (CamelType parent, const char *name, size_t instance_size, size_t 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 : | 
CamelType camel_interface_register (CamelType parent, const char *name, size_t classfuncs_size, CamelObjectClassInitFunc class_init, CamelObjectClassFinalizeFunc class_finalize);
| parent: | |
| name: | |
| classfuncs_size: | |
| class_init: | |
| class_finalize: | |
| Returns : | 
#define camel_type_get_global_classfuncs(x) ((CamelObjectClass *)(x))
| x: | 
void                camel_object_class_add_event        (CamelObjectClass *klass,
                                                         const char *name,
                                                         CamelObjectEventPrepFunc prep);
| klass: | |
| name: | |
| prep: | 
void                camel_object_class_add_interface    (CamelObjectClass *klass,
                                                         CamelType itype);
| klass: | |
| itype: | 
CamelObject* camel_object_cast (CamelObject *obj, CamelType ctype);
| obj: | |
| ctype: | |
| Returns : | 
gboolean camel_object_is (CamelObject *obj, CamelType ctype);
| obj: | |
| ctype: | |
| Returns : | 
CamelObjectClass*   camel_object_class_cast             (CamelObjectClass *klass,
                                                         CamelType ctype);
| klass: | |
| ctype: | |
| Returns : | 
gboolean camel_object_class_is (CamelObjectClass *klass, CamelType ctype);
| klass: | |
| ctype: | |
| Returns : | 
CamelObjectClass*   camel_interface_cast                (CamelObjectClass *klass,
                                                         CamelType ctype);
| klass: | |
| ctype: | |
| Returns : | 
gboolean camel_interface_is (CamelObjectClass *k, CamelType ctype);
| k: | |
| ctype: | |
| Returns : | 
CamelObjectHookID camel_object_hook_event (void *obj, const char *name, CamelObjectEventHookFunc hook, void *data);
| obj: | |
| name: | |
| hook: | |
| data: | |
| Returns : | 
void                camel_object_remove_event           (void *obj,
                                                         CamelObjectHookID id);
| obj: | |
| id: | 
void                camel_object_unhook_event           (void *obj,
                                                         const char *name,
                                                         CamelObjectEventHookFunc hook,
                                                         void *data);
| obj: | |
| name: | |
| hook: | |
| data: | 
void                camel_object_trigger_event          (void *obj,
                                                         const char *name,
                                                         void *event_data);
| obj: | |
| name: | |
| event_data: | 
void*               camel_object_get_interface          (void *vo,
                                                         CamelType itype);
| vo: | |
| itype: | |
| Returns : | 
int                 camel_object_set                    (void *obj,
                                                         struct _CamelException *ex,
                                                         ...);
| obj: | |
| ex: | |
| ...: | |
| Returns : | 
int                 camel_object_setv                   (void *obj,
                                                         struct _CamelException *ex,
                                                         CamelArgV *);
| obj: | |
| ex: | |
| Param3: | |
| Returns : | 
int                 camel_object_get                    (void *obj,
                                                         struct _CamelException *ex,
                                                         ...);
| obj: | |
| ex: | |
| ...: | |
| Returns : | 
int                 camel_object_getv                   (void *obj,
                                                         struct _CamelException *ex,
                                                         CamelArgGetV *);
| obj: | |
| ex: | |
| Param3: | |
| Returns : | 
void*               camel_object_get_ptr                (void *vo,
                                                         CamelException *ex,
                                                         int tag);
| vo: | |
| ex: | |
| tag: | |
| Returns : | 
int                 camel_object_get_int                (void *vo,
                                                         CamelException *ex,
                                                         int tag);
| vo: | |
| ex: | |
| tag: | |
| Returns : | 
char*               camel_object_meta_get               (void *vo,
                                                         const char *name);
Get a meta-data on an object.
| vo: | |
| name: | |
| Returns : | NULL if the meta-data is not set. | 
gboolean camel_object_meta_set (void *vo, const char *name, const char *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.
| vo: | |
| 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. | 
int camel_object_state_read (void *vo);
Read persistent object state from object_set(CAMEL_OBJECT_STATE_FILE).
| vo: | |
| Returns : | -1 on error. | 
int camel_object_state_write (void *vo);
Write persistent state to the file as set by object_set(CAMEL_OBJECT_STATE_FILE).
| vo: | |
| Returns : | -1 on error. | 
void                camel_object_free                   (void *vo,
                                                         guint32 tag,
                                                         void *value);
| vo: | |
| tag: | |
| value: | 
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.
| hash: | |
| equal: | |
| keycopy: | |
| keyfree: | |
| Returns : | 
void* camel_object_bag_get (CamelObjectBag *bag, const void *key);
Lookup an object by key.  If the key is currently reserved, then
wait until the key has been committed before continuing.
| bag: | |
| key: | |
| Returns : | NULL if the object corresponding to keyis not
in the bag.  Otherwise a ref'd object pointer which the caller owns
the ref to. | 
void* camel_object_bag_peek (CamelObjectBag *bag, const void *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.
| bag: | |
| key: | |
| Returns : | A referenced object, or NULL if keyis not
present in the bag. | 
void* camel_object_bag_reserve (CamelObjectBag *bag, const void *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.
| bag: | |
| key: | |
| Returns : | 
void camel_object_bag_add (CamelObjectBag *bag, const void *key, void *o);
Add an object vo to the object bag bag.  The key MUST have
previously been reserved using camel_object_bag_reserve().
| bag: | |
| key: | |
| o: | 
void camel_object_bag_abort (CamelObjectBag *bag, const void *key);
Abort a key reservation.
| bag: | |
| key: | 
void camel_object_bag_rekey (CamelObjectBag *bag, void *o, const void *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.
| bag: | |
| o: | |
| newkey: | 
#define CAMEL_MAKE_CLASS(type, tname, parent, pname)
| type: | |
| tname: | |
| parent: | |
| pname: | 
typedef struct {
	/* free fields, dont free base object */
	void (*free)(void *it);
	/* go to the next messageinfo */
	const void *(*next)(void *it, CamelException *ex);
	/* go back to the start */
	void (*reset)(void *it);
	/* *ESTIMATE* how many results are in the iterator */
	int (*length)(void *it);
} CamelIteratorVTable;
typedef struct {
	CamelIteratorVTable *klass;
	/* subclasses adds new fields afterwards */
} CamelIterator;
void* camel_iterator_new (CamelIteratorVTable *klass, size_t size);
| klass: | |
| size: | |
| Returns : | 
const void*         camel_iterator_next                 (void *it,
                                                         CamelException *ex);
| it: | |
| ex: | |
| Returns : |