FPointer.h

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