FPointer_vi.h

00001 /*
00002     Copyright (c) 2011 Andy Kirkham
00003     modified by Jochen Krapf
00004  
00005     Permission is hereby granted, free of charge, to any person obtaining a copy
00006     of this software and associated documentation files (the "Software"), to deal
00007     in the Software without restriction, including without limitation the rights
00008     to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00009     copies of the Software, and to permit persons to whom the Software is
00010     furnished to do so, subject to the following conditions:
00011  
00012     The above copyright notice and this permission notice shall be included in
00013     all copies or substantial portions of the Software.
00014  
00015     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00016     IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00017     FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00018     AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00019     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00020     OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00021     THE SOFTWARE.
00022 */
00023 
00024 #ifndef AJK_FPOINTER_H
00025 #define AJK_FPOINTER_H
00026 
00027 namespace AjK {
00028 
00029 class FPointerDummy;
00030 
00031 /** FPointer - Adds callbacks that take a 32bit uint32_t data type.
00032  *
00033  * The Mbed library supplies a callback using the FunctionPointer object as 
00034  * defined in FunctionPointer.h  However, this callback system does not allow
00035  * the caller to pass a value to the callback. Likewise, the callback itself
00036  * cannot return a value.
00037  *
00038  * FPointer operates in the same way but allows the callback function to be
00039  * passed one arg, a uint32_t value. Additionally, the callback can return
00040  * a single uint32_t value. The reason for using uint32_t is that the Mbed
00041  * and the microcontroller (LPC1768) have a natural data size of 32bits and
00042  * this means we can use the uint32_t as a pointer. See example1.h for more
00043  * information. This example passes an "int" by passing a pointer to that
00044  * int as a 32bit value. Using this technique you can pass any value you like.
00045  * All you have to do is pass a pointer to your value cast to (uint32_t). Your
00046  * callback can the deference it to get the original value.
00047  *
00048  * example2.h shows how to do the same thing but demostrates how to specify
00049  * the callback into a class object/method.
00050  *
00051  * Finally, example3.h shows how to pass multiple values. In this example we
00052  * define a data structure and in the callback we pass a pointer to that
00053  * data structure thus allowing the callback to again get the values.
00054  *
00055  * Note, when passing pointers to variables to the callback, if the callback
00056  * function/method changes that variable's value then it will also change the
00057  * value the caller sees. If C pointers are new to you, you are strongly
00058  * advised to read up on the subject. It's pointers that often get beginners
00059  * into trouble when mis-used.
00060  *
00061  * @see http://mbed.org/handbook/C-Data-Types
00062  * @see http://mbed.org/projects/libraries/svn/mbed/trunk/FunctionPointer.h
00063  */
00064 class FPointer_vi {
00065 
00066 protected:
00067 
00068     //! C callback function pointer.
00069     void (*c_callback)(int); 
00070     
00071     //! C++ callback object/method pointer (the object part).
00072     FPointerDummy  *obj_callback;
00073     
00074     //! C++ callback object/method pointer (the method part).
00075     void (FPointerDummy::*method_callback)(int);
00076 
00077 public:
00078     
00079     /** Constructor
00080      */
00081     FPointer_vi() {
00082         c_callback      = NULL;
00083         obj_callback    = NULL;
00084         method_callback = NULL;
00085     }
00086     
00087     /** attach - Overloaded attachment function.
00088      *
00089      * Attach a C type function pointer as the callback.
00090      *
00091      * Note, the callback function prototype must be:-
00092      * @code
00093      * void myCallbackFunction(int);
00094      * @endcode
00095      * @param A C function pointer to call.
00096      */
00097     void attach(void (*function)(int) = 0) { c_callback = function; }
00098     
00099     /** attach - Overloaded attachment function.
00100      *
00101      * Attach a C++ type object/method pointer as the callback.
00102      *
00103      * Note, the callback method prototype must be:-
00104      * @code
00105      *     public:
00106      *         void myCallbackFunction(int);
00107      * @endcode
00108      * @param A C++ object pointer.
00109      * @param A C++ method within the object to call.
00110      */
00111     template<class T> 
00112     void attach(T* item, void (T::*method)(int)) { 
00113         obj_callback    = (FPointerDummy *)item; 
00114         method_callback = (void (FPointerDummy::*)(int))method; 
00115     }
00116 
00117     /** call - Overloaded callback initiator.
00118      *
00119      * call the callback function.
00120      *
00121      * @param int The value to pass to the callback.
00122      */
00123     void call(int arg) {
00124         if (c_callback != NULL) {
00125             (*c_callback)(arg);
00126         }
00127         else {
00128             if (obj_callback  != NULL && method_callback != NULL) {
00129                 (obj_callback->*method_callback)(arg);
00130             }
00131         }
00132     }
00133     
00134 };
00135 
00136 }; // namespace AjK ends
00137 
00138 using namespace AjK;
00139 
00140 #endif