Andy K / FPointer

FPointer - A callback system that allows for 32bit unsigned ints to be passed to and from the callback.

Dependents:   FYPFinalProgram FYPFinalizeProgram KEYS SaveKeypad ... more

FPointer.h@2:56e309e76c19, 2011-01-18 (annotated)

Committer:
AjK
Date:
Tue Jan 18 23:09:32 2011 +0000
Revision:
2:56e309e76c19
Parent:
1:d7803001a259 
1.2 See ChangeLog.h

Who changed what in which revision?

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