dt/dnotifier.h

   1 /**
   2  * \file
   3  * <!--
   4  * Copyright 2005 Develer S.r.l. (http://www.develer.com/)
   5  * -->
   6  *
   7  * \version $Id$
   8  *
   9  * \brief Notifier obj (interface).
  10  *
  11  * \version $Id$
  12  * \author Bernardo Innocenti <bernie@develer.com>
  13  * \author Francesco Sacchi <batt@develer.com>
  14  */
  15
  16 /*#*
  17  *#* $Log$
  18  *#* Revision 1.2  2006/07/19 12:56:26  bernie
  19  *#* Convert to new Doxygen style.
  20  *#*
  21  *#* Revision 1.1  2005/11/04 18:26:38  bernie
  22  *#* Import into DevLib.
  23  *#*
  24  *#* Revision 1.4  2005/06/09 13:23:58  batt
  25  *#* Add some comments.
  26  *#*
  27  *#* Revision 1.3  2005/06/08 17:32:33  batt
  28  *#* Switch to new messaging system.
  29  *#*
  30  *#* Revision 1.2  2005/06/06 11:04:12  batt
  31  *#* Add some comments.
  32  *#*
  33  *#* Revision 1.1  2005/05/26 08:32:53  batt
  34  *#* Add new Develer widget system :)
  35  *#*
  36  *#*/
  37 #ifndef DT_DNOTIFIER_H
  38 #define DT_DNOTIFIER_H
  39
  40 #include <cfg/debug.h>
  41 #include <dt/dtag.h>
  42 #include <mware/list.h>
  43
  44 //Fwd declaretion.
  45 struct DNotifier;
  46 struct DFilter;
  47
  48 typedef void (* update_func_ptr)(struct DNotifier *, dtag_t, dval_t);
  49 typedef void (* update_filter_ptr)(struct DFilter *, dtag_t, dval_t);
  50
  51 /**
  52  * Base object for receive and forward messages.
  53  * It contains an update function used to update itslef and a list to
  54  * notify other DNotifer eventually connected.
  55  */
  56 typedef struct DNotifier
  57 {
  58         /// Receive new attributes from other notifiers.
  59         update_func_ptr update;
  60
  61         /// List of target notifiers to set new attributes to.
  62         List targets;
  63 } DNotifier;
  64
  65 /**
  66  * Map for messages.
  67  * Used to translate src message to dst message.
  68  */
  69 typedef struct DFilterMap
  70 {
  71         DTagItem src;
  72         DTagItem dst;
  73 } DFilterMap;
  74
  75
  76 /**
  77  * A filter is an interface between two notifier.
  78  * It can translate messages between them through a map (if it is not null).
  79  */
  80 typedef struct DFilter
  81 {
  82         /// Allow creating a list of dfilter objects.
  83         Node link;
  84
  85         /// Target of the filter
  86         DNotifier *target;
  87
  88         /// Update function called by the source dnotifier
  89         update_filter_ptr update;
  90
  91         ///Map for translating messages for target
  92         const DFilterMap *map;
  93
  94         ///Used in debug to prevent inserting this filter in more than one list
  95         DB(uint8_t magic;)
  96 } DFilter;
  97
  98 /// Type for filter-mask checking
  99 typedef uint16_t dfilter_mask_t;
 100
 101 /// Filter init
 102 void filter_init(DFilter *f, const DFilterMap *map, bool masked, DNotifier *source, DNotifier *target);
 103
 104 /// Filter update function without masking capabilities.
 105 void filter_update(DFilter *f, dtag_t tag, dval_t val);
 106
 107 /// Filter update function with masking capabilities.
 108 void filter_mask_update(DFilter *f, dtag_t tag, dval_t val);
 109
 110 /// Notifier init
 111 void notifier_init(DNotifier *n);
 112
 113
 114 /**
 115  * Macro to notify the target object.
 116  */
 117 INLINE void dnotify(DNotifier *target, dtag_t tag, dval_t val)
 118 {
 119         if (target)
 120                 target->update(target, tag, val);
 121 }
 122
 123 /**
 124  * Macro to notify all the targets of \a target object.
 125  */
 126 INLINE void dnotify_targets(DNotifier *target, dtag_t tag, dval_t val)
 127 {
 128         DFilter *f;
 129         if (!ISLISTEMPTY(&target->targets))
 130                 FOREACHNODE(f, &target->targets)
 131                         f->update(f, tag, val);
 132 }
 133
 134
 135 /**
 136  * Macro that connect \a src notifier to \a tgt using \a map and passing \a opt for filtering option.
 137  * It declares a static filter to achieve connection and messages translation.
 138  * \note Due its static filter declaration, DCONNECT MUST NOT be used inside loops or in functions called multiple times.
 139  * Failing to do so will lead to unpredictable connections between notifiers.
 140  */
 141 #define DCONNECT(src, tgt, map, opt) \
 142         do { \
 143                 static DFilter _filter_; /* Declare a filter */ \
 144                 filter_init(&(_filter_), map, opt, src, tgt); /* Init it. */ \
 145         } while (0)
 146
 147
 148 #endif /* DT_DNOTIFIER_H */