src/libs/FPointer.h

   1 /*
   2 Copyright (c) 2011 Andy Kirkham
   3 Permission is hereby granted, free of charge, to any person obtaining a copy
   4 of this software and associated documentation files (the "Software"), to deal
   5 in the Software without restriction, including without limitation the rights
   6 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   7 copies of the Software, and to permit persons to whom the Software is
   8 furnished to do so, subject to the following conditions:
   9 The above copyright notice and this permission notice shall be included in
  10 all copies or substantial portions of the Software.
  11 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  12 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  13 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  14 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  15 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  16 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  17 THE SOFTWARE.
  18 */
  19
  20 #ifndef AJK_FPOINTER_H
  21 #define AJK_FPOINTER_H
  22 #ifndef NULL
  23 #define NULL 0
  24 #endif
  25 namespace AjK {
  26
  27 class FPointerDummy;
  28
  29 /** FPointer - Adds callbacks that take and return a 32bit uint32_t data type.
  30 *
  31 * The Mbed library supplies a callback using the FunctionPointer object as
  32 * defined in FunctionPointer.h However, this callback system does not allow
  33 * the caller to pass a value to the callback. Likewise, the callback itself
  34 * cannot return a value.
  35 *
  36 * FPointer operates in the same way but allows the callback function to be
  37 * passed one arg, a uint32_t value. Additionally, the callback can return
  38 * a single uint32_t value. The reason for using uint32_t is that the Mbed
  39 * and the microcontroller (LPC1768) have a natural data size of 32bits and
  40 * this means we can use the uint32_t as a pointer. See example1.h for more
  41 * information. This example passes an "int" by passing a pointer to that
  42 * int as a 32bit value. Using this technique you can pass any value you like.
  43 * All you have to do is pass a pointer to your value cast to (uint32_t). Your
  44 * callback can the deference it to get the original value.
  45 *
  46 * example2.h shows how to do the same thing but demostrates how to specify
  47 * the callback into a class object/method.
  48 *
  49 * Finally, example3.h shows how to pass multiple values. In this example we
  50 * define a data structure and in the callback we pass a pointer to that
  51 * data structure thus allowing the callback to again get the values.
  52 *
  53 * Note, when passing pointers to variables to the callback, if the callback
  54 * function/method changes that variable's value then it will also change the
  55 * value the caller sees. If C pointers are new to you, you are strongly
  56 * advised to read up on the subject. It's pointers that often get beginners
  57 * into trouble when mis-used.
  58 *
  59 * @see example1.h
  60 * @see example2.h
  61 * @see example3.h
  62 * @see http://mbed.org/handbook/C-Data-Types
  63 * @see http://mbed.org/projects/libraries/svn/mbed/trunk/FunctionPointer.h
  64 */
  65 class FPointer {
  66
  67 protected:
  68
  69     //! C callback function pointer.
  70     uint32_t (*c_callback)(uint32_t);
  71
  72     //! C++ callback object/method pointer (the object part).
  73     FPointerDummy *obj_callback;
  74
  75     //! C++ callback object/method pointer (the method part).
  76     uint32_t (FPointerDummy::*method_callback)(uint32_t);
  77
  78 public:
  79
  80     /** Constructor
  81 */
  82     FPointer() {
  83         c_callback = NULL;
  84         obj_callback = NULL;
  85         method_callback = NULL;
  86     }
  87
  88     /** attach - Overloaded attachment function.
  89 *
  90 * Attach a C type function pointer as the callback.
  91 *
  92 * Note, the callback function prototype must be:-
  93 * @code
  94 * uint32_t myCallbackFunction(uint32_t);
  95 * @endcode
  96 * @param A C function pointer to call.
  97 */
  98     void attach(uint32_t (*function)(uint32_t) = 0) { c_callback = function; }
  99
 100     /** attach - Overloaded attachment function.
 101 *
 102 * Attach a C++ type object/method pointer as the callback.
 103 *
 104 * Note, the callback method prototype must be:-
 105 * @code
 106 * public:
 107 * uint32_t myCallbackFunction(uint32_t);
 108 * @endcode
 109 * @param A C++ object pointer.
 110 * @param A C++ method within the object to call.
 111 */
 112     template<class T>
 113     void attach(T* item, uint32_t (T::*method)(uint32_t)) {
 114         obj_callback = (FPointerDummy *)item;
 115         method_callback = (uint32_t (FPointerDummy::*)(uint32_t))method;
 116     }
 117
 118     /** call - Overloaded callback initiator.
 119 *
 120 * call the callback function.
 121 *
 122 * @param uint32_t The value to pass to the callback.
 123 * @return uint32_t The value the callback returns.
 124 */
 125     uint32_t call(uint32_t arg) {
 126         if (c_callback != NULL) {
 127             return (*c_callback)(arg);
 128         }
 129         else {
 130             if (obj_callback != NULL && method_callback != NULL) {
 131                 return (obj_callback->*method_callback)(arg);
 132             }
 133         }
 134         return (uint32_t)NULL;
 135     }
 136
 137     /** call - Overloaded callback initiator.
 138 *
 139 * Call the callback function without passing an argument.
 140 * The callback itself is passed NULL. Note, the callback
 141 * prototype should still be <b>uint32_t callback(uint32_t)</b>.
 142 *
 143 * @return uint32_t The value the callback returns.
 144 */
 145     uint32_t call(void) {
 146         if (c_callback != NULL) {
 147             return (*c_callback)((uint32_t)NULL);
 148         }
 149         else {
 150             if (obj_callback != NULL && method_callback != NULL) {
 151                 return (obj_callback->*method_callback)((uint32_t)NULL);
 152             }
 153         }
 154         return (uint32_t)NULL;
 155     }
 156 };
 157
 158 }; // namespace AjK ends
 159
 160 using namespace AjK;
 161
 162 #endif