CamelObject
3
CAMEL Library

# 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 *);
    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;
    struct              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);

## 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 unsigned int CamelObjectHookID;

### CamelObjectMeta

    typedef struct {
    	struct _CamelObjectMeta *next;

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

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

### camel_interface_type

    extern CamelType camel_interface_type;

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

### CAMEL_INTERFACE_TYPE

    #define CAMEL_INTERFACE_TYPE (camel_interface_type)

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

### CamelInterface

    typedef struct {
    	struct _CamelObjectClass type;
    };
    #endif /* CAMEL_DISABLE_DEPRECATED */

    /* The type system .... it's pretty simple..... */
    void camel_type_init (void);
    CamelType camel_type_register(CamelType parent, const char * name, /*unsigned int ver, unsigned int rev,*/
    			      size_t instance_size,
    			      size_t classfuncs_size,
    			      CamelObjectClassInitFunc class_init,
    			      CamelObjectClassFinalizeFunc  class_finalize,
    			      CamelObjectInitFunc instance_init,
    			      CamelObjectFinalizeFunc instance_finalize);

    #ifndef CAMEL_DISABLE_DEPRECATED
    CamelType camel_interface_register(CamelType parent, const char *name,
    				   size_t classfuncs_size,
    				   CamelObjectClassInitFunc class_init,
    				   CamelObjectClassFinalizeFunc class_finalize);
    #endif /* CAMEL_DISABLE_DEPRECATED */

    /* deprecated interface */
    #define camel_type_get_global_classfuncs(x) ((CamelObjectClass *)(x))

    /* object class methods (types == classes now) */
    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);
    #ifndef CAMEL_DISABLE_DEPRECATED
    void camel_object_class_add_interface(CamelObjectClass *klass, CamelType itype);
    #endif /* CAMEL_DISABLE_DEPRECATED */

    void camel_object_class_dump_tree (CamelType root);

    /* casting */
    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);

    #ifndef CAMEL_DISABLE_DEPRECATED
    CamelObjectClass *camel_interface_cast(CamelObjectClass *klass, CamelType ctype);
    gboolean camel_interface_is(CamelObjectClass *k, CamelType ctype);
    #endif /* CAMEL_DISABLE_DEPRECATED */

    CamelType camel_object_get_type (void);

    CamelObject *camel_object_new (CamelType type);

    void camel_object_ref(void *);
    void camel_object_unref(void *);

    #ifdef CAMEL_DEBUG
    #define camel_object_ref(o) (printf("%s (%s:%d):ref (%p)\n", __FUNCTION__, __FILE__, __LINE__, o), camel_object_ref(o))
    #define camel_object_unref(o) (printf("%s (%s:%d):unref (%p)\n", __FUNCTION__, __FILE__, __LINE__, o), camel_object_unref (o))
    #endif

    /* hooks */
    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);

    #ifndef CAMEL_DISABLE_DEPRECATED
    /* interfaces */
    void *camel_object_get_interface(void *vo, CamelType itype);
    #endif /* CAMEL_DISABLE_DEPRECATED */

    /* get/set methods */
    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 *);

    /* not very efficient one-time calls */
    void *camel_object_get_ptr(void *vo, CamelException *ex, int tag);
    int camel_object_get_int(void *vo, CamelException *ex, int tag);

    /* meta-data for user-specific data */
    char *camel_object_meta_get(void *vo, const char * name);
    gboolean camel_object_meta_set(void *vo, const char * name, const char *value);

    /* reads/writes the state from/to the CAMEL_OBJECT_STATE_FILE */
    int camel_object_state_read(void *vo);
    int camel_object_state_write(void *vo);

    /* free a retrieved object.  May be a noop for static data. */
    void camel_object_free(void *vo, guint32 tag, void *value);

    /* for managing bags of weakly-ref'd 'child' objects */
    typedef struct _CamelObjectBag CamelObjectBag;
    typedef 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 *vo);
    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)				\
    static CamelType type##_type;							\
    static pname##Class * type##_parent_class;					\
    										\
    CamelType									\
    type##_get_type(void)								\
    {										\
    	if (type##_type == 0) {							\
    		type##_parent_class = (pname##Class *)parent##_get_type();	\
    		type##_type = camel_type_register(				\
    			type##_parent_class, #tname "Class",			\
    			sizeof(tname),						\
    			sizeof(tname ## Class),					\
    			(CamelObjectClassInitFunc) type##_class_init,		\
    			NULL,							\
    			(CamelObjectInitFunc) type##_init,			\
    			(CamelObjectFinalizeFunc) type##_finalise);		\
    	}									\
    										\
    	return type##_type;							\
    }

    #ifndef CAMEL_DISABLE_DEPRECATED
    /* Utility functions, not object specific, but too small to separate */
    typedef struct _CamelIteratorVTable CamelIteratorVTable;
    typedef struct _CamelIterator CamelIterator;

    struct _CamelIteratorVTable {
    	/* 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);
    } CamelInterface;

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

### CamelObjectClassInitFunc ()

    void                (*CamelObjectClassInitFunc)         (CamelObjectClass *);

`Param1` :

### CamelObjectClassFinalizeFunc ()

    void                (*CamelObjectClassFinalizeFunc)     (CamelObjectClass *);

`Param1` :

### CamelObjectInitFunc ()

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

`Param1` :

`Param2` :

### CamelObjectFinalizeFunc ()

    void                (*CamelObjectFinalizeFunc)          (CamelObject *);

`Param1` :

### CamelObjectEventPrepFunc ()

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

`Param1` :

`Param2` :

Returns :

### CamelObjectEventHookFunc ()

    void                (*CamelObjectEventHookFunc)         (CamelObject *,
                                                             gpointer ,
                                                             gpointer );

`Param1` :

`Param2` :

`Param3` :

### CAMEL_INVALID_TYPE

    #define CAMEL_INVALID_TYPE (NULL)

### enum CamelObjectFlags

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

### struct CamelIterator

    struct CamelIterator {
    	CamelIteratorVTable *klass;

    	/* subclasses adds new fields afterwards */
    };

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

### camel_iterator_new ()

    void*               camel_iterator_new                  (CamelIteratorVTable *klass,
                                                             size_t size);

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

`klass` :

`size` :

Returns :

### camel_iterator_free ()

    void                camel_iterator_free                 (void *it);

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

`it` :

### camel_iterator_next ()

    const void*         camel_iterator_next                 (void *it,
                                                             CamelException *ex);

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

`it` :

`ex` :

Returns :

### camel_iterator_reset ()

    void                camel_iterator_reset                (void *it);

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

`it` :

### camel_iterator_length ()

    int                 camel_iterator_length               (void *it);

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

`it` :

Returns :