camel/camel-object.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
   2 /* camel-object.h: Base class for Camel */
   3 /*
   4  * Authors:
   5  *  Dan Winship <danw@ximian.com>
   6  *  Michael Zucchi <notzed@ximian.com>
   7  *
   8  * Copyright 2000-2004 Novell, Inc. (www.novell.com)
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of version 2 of the GNU Lesser General Public
  12  * License as published by the Free Software Foundation.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
  22  * USA
  23  */
  24
  25 #ifndef CAMEL_OBJECT_H
  26 #define CAMEL_OBJECT_H 1
  27
  28 #include <glib.h>
  29 #include <stdio.h>              /* FILE */
  30 #include <stdlib.h>             /* size_t */
  31 #include <stdarg.h>
  32 #include <pthread.h>
  33
  34 #include <camel/camel-arg.h>
  35 #include <camel/camel-types.h>  /* this is a @##$@#SF stupid header */
  36
  37 /* turn on so that camel_object_class_dump_tree() dumps object instances as well */
  38 #define CAMEL_OBJECT_TRACK_INSTANCES
  39
  40 G_BEGIN_DECLS
  41
  42 typedef struct _CamelObjectClass *CamelType;
  43
  44 #ifdef G_DISABLE_CHECKS
  45 #define CAMEL_CHECK_CAST(obj, ctype, ptype)         ((ptype *) obj)
  46 #define CAMEL_CHECK_CLASS_CAST(klass, ctype, ptype) ((ptype *) klass)
  47 #else
  48 #define CAMEL_CHECK_CAST(obj, ctype, ptype)         ((ptype *) camel_object_cast ((CamelObject *)(obj), (CamelType)(ctype)))
  49 #define CAMEL_CHECK_CLASS_CAST(klass, ctype, ptype) ((ptype *) camel_object_class_cast ((CamelObjectClass *)(klass), (CamelType)(ctype) ))
  50 #endif
  51 #define CAMEL_CHECK_TYPE(obj, ctype)                (camel_object_is ((CamelObject *)(obj), (CamelType)(ctype) ))
  52 #define CAMEL_CHECK_CLASS_TYPE(klass, ctype)        (camel_object_class_is ((CamelObjectClass *)(klass), (CamelType)(ctype)))
  53
  54 extern CamelType camel_object_type;
  55
  56 #define CAMEL_OBJECT_TYPE        (camel_object_type)
  57
  58 /* we can't check casts till we've got the type, use the global type variable because its cheaper */
  59 #define CAMEL_OBJECT(obj)        (CAMEL_CHECK_CAST((obj), camel_object_type, CamelObject))
  60 #define CAMEL_OBJECT_CLASS(k)    (CAMEL_CHECK_CLASS_CAST ((k), camel_object_type, CamelObjectClass))
  61 #define CAMEL_IS_OBJECT(o)       (CAMEL_CHECK_TYPE((o), camel_object_type))
  62 #define CAMEL_IS_OBJECT_CLASS(k) (CAMEL_CHECK_CLASS_TYPE((k), camel_object_type))
  63
  64 #define CAMEL_OBJECT_GET_CLASS(o) ((CamelObjectClass *)(CAMEL_OBJECT(o))->klass)
  65 #define CAMEL_OBJECT_GET_TYPE(o)  ((CamelType)(CAMEL_OBJECT(o))->klass)
  66
  67 typedef struct _CamelObjectClass CamelObjectClass;
  68 typedef struct _CamelObject CamelObject;
  69 typedef unsigned int CamelObjectHookID;
  70 typedef struct _CamelObjectMeta CamelObjectMeta;
  71
  72 extern CamelType camel_interface_type;
  73 #define CAMEL_INTERFACE_TYPE (camel_interface_type)
  74 typedef struct _CamelInterface CamelInterface;
  75
  76 typedef void (*CamelObjectClassInitFunc) (CamelObjectClass *);
  77 typedef void (*CamelObjectClassFinalizeFunc) (CamelObjectClass *);
  78 typedef void (*CamelObjectInitFunc) (CamelObject *, CamelObjectClass *);
  79 typedef void (*CamelObjectFinalizeFunc) (CamelObject *);
  80
  81 typedef gboolean (*CamelObjectEventPrepFunc) (CamelObject *, gpointer);
  82 typedef void (*CamelObjectEventHookFunc) (CamelObject *, gpointer, gpointer);
  83
  84 #define CAMEL_INVALID_TYPE (NULL)
  85
  86 /* camel object args. */
  87 enum {
  88         /* Get a description of the object. */
  89         CAMEL_OBJECT_ARG_DESCRIPTION = CAMEL_ARG_FIRST, /* Get a copy of the meta-data list (should be freed) */
  90         CAMEL_OBJECT_ARG_METADATA,
  91         CAMEL_OBJECT_ARG_STATE_FILE,
  92         CAMEL_OBJECT_ARG_PERSISTENT_PROPERTIES,
  93 };
  94
  95 enum {
  96         CAMEL_OBJECT_DESCRIPTION = CAMEL_OBJECT_ARG_DESCRIPTION | CAMEL_ARG_STR,
  97         /* Returns a CamelObjectMeta list */
  98         CAMEL_OBJECT_METADATA = CAMEL_OBJECT_ARG_METADATA | CAMEL_ARG_PTR,
  99         /* sets where the persistent data should reside, otherwise it isn't persistent */
 100         CAMEL_OBJECT_STATE_FILE = CAMEL_OBJECT_ARG_STATE_FILE | CAMEL_ARG_STR,
 101         /* returns a GSList CamelProperties of persistent properties */
 102         CAMEL_OBJECT_PERSISTENT_PROPERTIES = CAMEL_OBJECT_ARG_PERSISTENT_PROPERTIES | CAMEL_ARG_PTR,
 103 };
 104
 105 typedef enum _CamelObjectFlags {
 106         CAMEL_OBJECT_DESTROY = (1<<0),
 107 } CamelObjectFlags;
 108
 109 /* returned by get::CAMEL_OBJECT_METADATA */
 110 struct _CamelObjectMeta {
 111         struct _CamelObjectMeta *next;
 112
 113         char *value;
 114         char name[1];           /* allocated as part of structure */
 115 };
 116
 117 /* TODO: create a simpleobject which has no events on it, or an interface for events */
 118 struct _CamelObject {
 119         struct _CamelObjectClass *klass;
 120
 121         guint32 magic;          /* only really needed for debugging ... */
 122
 123         /* current hooks on this object */
 124         struct _CamelHookList *hooks;
 125
 126         guint32 ref_count:24;
 127         guint32 flags:8;
 128
 129 #ifdef CAMEL_OBJECT_TRACK_INSTANCES
 130         struct _CamelObject *next, *prev;
 131 #endif
 132 };
 133
 134 struct _CamelObjectClass
 135 {
 136         struct _CamelObjectClass *parent;
 137
 138         guint32 magic;          /* in same spot for validation */
 139
 140         struct _CamelObjectClass *next, *child; /* maintain heirarchy, just for kicks */
 141
 142         const char *name;
 143
 144         void *lock;             /* lock when used in threading, else just pads struct */
 145
 146         /*unsigned short version, revision;*/
 147
 148         /* if the object's bigger than 64K, it could use redesigning */
 149         unsigned short object_size/*, object_data*/;
 150         unsigned short klass_size/*, klass_data*/;
 151
 152         /* available hooks for this class */
 153         struct _CamelHookPair *hooks;
 154
 155         /* memchunks for this type */
 156         struct _EMemChunk *instance_chunks;
 157 #ifdef CAMEL_OBJECT_TRACK_INSTANCES
 158         struct _CamelObject *instances;
 159 #endif
 160
 161         /* init class */
 162         void (*klass_init)(struct _CamelObjectClass *);
 163         void (*klass_finalise)(struct _CamelObjectClass *);
 164
 165         /* init/finalise object */
 166         void (*init)(struct _CamelObject *, struct _CamelObjectClass *);
 167         void (*finalise)(struct _CamelObject *);
 168
 169         /* root-class fields follow, type system above */
 170
 171         /* get/set interface */
 172         int (*setv)(struct _CamelObject *, struct _CamelException *ex, CamelArgV *args);
 173         int (*getv)(struct _CamelObject *, struct _CamelException *ex, CamelArgGetV *args);
 174         /* we only free 1 at a time, and only pointer types, obviously */
 175         void (*free)(struct _CamelObject *, guint32 tag, void *ptr);
 176
 177         /* get/set meta-data interface */
 178         char *(*meta_get)(struct _CamelObject *, const char * name);
 179         gboolean (*meta_set)(struct _CamelObject *, const char * name, const char *value);
 180
 181         /* persistence stuff */
 182         int (*state_read)(struct _CamelObject *, FILE *fp);
 183         int (*state_write)(struct _CamelObject *, FILE *fp);
 184 };
 185
 186 /* an interface is just a class with no instance data */
 187 struct _CamelInterface {
 188         struct _CamelObjectClass type;
 189 };
 190
 191 /* The type system .... it's pretty simple..... */
 192 void camel_type_init (void);
 193 CamelType camel_type_register(CamelType parent, const char * name, /*unsigned int ver, unsigned int rev,*/
 194                               size_t instance_size,
 195                               size_t classfuncs_size,
 196                               CamelObjectClassInitFunc class_init,
 197                               CamelObjectClassFinalizeFunc  class_finalize,
 198                               CamelObjectInitFunc instance_init,
 199                               CamelObjectFinalizeFunc instance_finalize);
 200
 201 CamelType camel_interface_register(CamelType parent, const char *name,
 202                                    size_t classfuncs_size,
 203                                    CamelObjectClassInitFunc class_init,
 204                                    CamelObjectClassFinalizeFunc class_finalize);
 205
 206 /* deprecated interface */
 207 #define camel_type_get_global_classfuncs(x) ((CamelObjectClass *)(x))
 208
 209 /* object class methods (types == classes now) */
 210 const char *camel_type_to_name (CamelType type);
 211 CamelType camel_name_to_type (const char *name);
 212 void camel_object_class_add_event (CamelObjectClass *klass, const char *name, CamelObjectEventPrepFunc prep);
 213 void camel_object_class_add_interface(CamelObjectClass *klass, CamelType itype);
 214
 215 void camel_object_class_dump_tree (CamelType root);
 216
 217 /* casting */
 218 CamelObject *camel_object_cast(CamelObject *obj, CamelType ctype);
 219 gboolean camel_object_is(CamelObject *obj, CamelType ctype);
 220
 221 CamelObjectClass *camel_object_class_cast (CamelObjectClass *klass, CamelType ctype);
 222 gboolean camel_object_class_is (CamelObjectClass *klass, CamelType ctype);
 223
 224 CamelObjectClass *camel_interface_cast(CamelObjectClass *klass, CamelType ctype);
 225 gboolean camel_interface_is(CamelObjectClass *k, CamelType ctype);
 226
 227 CamelType camel_object_get_type (void);
 228
 229 CamelObject *camel_object_new (CamelType type);
 230 CamelObject *camel_object_new_name (const char *name);
 231
 232 void camel_object_ref(void *);
 233 void camel_object_unref(void *);
 234
 235 #ifdef CAMEL_DEBUG
 236 #define camel_object_ref(o) (printf("%s (%s:%d):ref (%p)\n", __FUNCTION__, __FILE__, __LINE__, o), camel_object_ref(o))
 237 #define camel_object_unref(o) (printf("%s (%s:%d):unref (%p)\n", __FUNCTION__, __FILE__, __LINE__, o), camel_object_unref (o))
 238 #endif
 239
 240 /* hooks */
 241 CamelObjectHookID camel_object_hook_event(void *obj, const char *name, CamelObjectEventHookFunc hook, void *data);
 242 void camel_object_remove_event(void *obj, CamelObjectHookID id);
 243 void camel_object_unhook_event(void *obj, const char *name, CamelObjectEventHookFunc hook, void *data);
 244 void camel_object_trigger_event(void *obj, const char *name, void *event_data);
 245
 246 /* interfaces */
 247 void *camel_object_get_interface(void *vo, CamelType itype);
 248
 249 /* get/set methods */
 250 int camel_object_set(void *obj, struct _CamelException *ex, ...);
 251 int camel_object_setv(void *obj, struct _CamelException *ex, CamelArgV *);
 252 int camel_object_get(void *obj, struct _CamelException *ex, ...);
 253 int camel_object_getv(void *obj, struct _CamelException *ex, CamelArgGetV *);
 254
 255 /* not very efficient one-time calls */
 256 void *camel_object_get_ptr(void *vo, CamelException *ex, int tag);
 257 int camel_object_get_int(void *vo, CamelException *ex, int tag);
 258
 259 /* meta-data for user-specific data */
 260 char *camel_object_meta_get(void *vo, const char * name);
 261 gboolean camel_object_meta_set(void *vo, const char * name, const char *value);
 262
 263 /* reads/writes the state from/to the CAMEL_OBJECT_STATE_FILE */
 264 int camel_object_state_read(void *vo);
 265 int camel_object_state_write(void *vo);
 266
 267 /* free a retrieved object.  May be a noop for static data. */
 268 void camel_object_free(void *vo, guint32 tag, void *value);
 269
 270 /* for managing bags of weakly-ref'd 'child' objects */
 271 typedef struct _CamelObjectBag CamelObjectBag;
 272 typedef void *(*CamelCopyFunc)(const void *vo);
 273
 274 CamelObjectBag *camel_object_bag_new(GHashFunc hash, GEqualFunc equal, CamelCopyFunc keycopy, GFreeFunc keyfree);
 275 void *camel_object_bag_get(CamelObjectBag *bag, const void *key);
 276 void *camel_object_bag_peek(CamelObjectBag *bag, const void *key);
 277 void *camel_object_bag_reserve(CamelObjectBag *bag, const void *key);
 278 void camel_object_bag_add(CamelObjectBag *bag, const void *key, void *o);
 279 void camel_object_bag_abort(CamelObjectBag *bag, const void *key);
 280 void camel_object_bag_rekey(CamelObjectBag *bag, void *o, const void *newkey);
 281 GPtrArray *camel_object_bag_list(CamelObjectBag *bag);
 282 void camel_object_bag_remove(CamelObjectBag *bag, void *o);
 283 void camel_object_bag_destroy(CamelObjectBag *bag);
 284
 285 #define CAMEL_MAKE_CLASS(type, tname, parent, pname)                            \
 286 static CamelType type##_type;                                                   \
 287 static pname##Class * type##_parent_class;                                      \
 288                                                                                 \
 289 CamelType                                                                       \
 290 type##_get_type(void)                                                           \
 291 {                                                                               \
 292         if (type##_type == 0) {                                                 \
 293                 type##_parent_class = (pname##Class *)parent##_get_type();      \
 294                 type##_type = camel_type_register(                              \
 295                         type##_parent_class, #tname "Class",                    \
 296                         sizeof(tname),                                          \
 297                         sizeof(tname ## Class),                                 \
 298                         (CamelObjectClassInitFunc) type##_class_init,           \
 299                         NULL,                                                   \
 300                         (CamelObjectInitFunc) type##_init,                      \
 301                         (CamelObjectFinalizeFunc) type##_finalise);             \
 302         }                                                                       \
 303                                                                                 \
 304         return type##_type;                                                     \
 305 }
 306
 307 /* Utility functions, not object specific, but too small to separate */
 308 typedef struct _CamelIteratorVTable CamelIteratorVTable;
 309 typedef struct _CamelIterator CamelIterator;
 310
 311 struct _CamelIteratorVTable {
 312         /* free fields, dont free base object */
 313         void (*free)(void *it);
 314         /* go to the next messageinfo */
 315         const void *(*next)(void *it, CamelException *ex);
 316         /* go back to the start */
 317         void (*reset)(void *it);
 318         /* *ESTIMATE* how many results are in the iterator */
 319         int (*length)(void *it);
 320 };
 321
 322 struct _CamelIterator {
 323         CamelIteratorVTable *klass;
 324
 325         /* subclasses adds new fields afterwards */
 326 };
 327
 328 void *camel_iterator_new(CamelIteratorVTable *klass, size_t size);
 329 void camel_iterator_free(void *it);
 330 const void *camel_iterator_next(void *it, CamelException *ex);
 331 void camel_iterator_reset(void *it);
 332 int camel_iterator_length(void *it);
 333
 334 G_END_DECLS
 335
 336 #endif /* CAMEL_OBJECT_H */