Solution for Bluetooth SIG hands-on training course
Dependencies: BLE_API mbed-dev-bin nRF51822-bluetooth-mdw
Fork of microbit-dal-bluetooth-mdw_starter by
EventModel.h
00001 /* 00002 The MIT License (MIT) 00003 00004 Copyright (c) 2016 British Broadcasting Corporation. 00005 This software is provided by Lancaster University by arrangement with the BBC. 00006 00007 Permission is hereby granted, free of charge, to any person obtaining a 00008 copy of this software and associated documentation files (the "Software"), 00009 to deal in the Software without restriction, including without limitation 00010 the rights to use, copy, modify, merge, publish, distribute, sublicense, 00011 and/or sell copies of the Software, and to permit persons to whom the 00012 Software is furnished to do so, subject to the following conditions: 00013 00014 The above copyright notice and this permission notice shall be included in 00015 all copies or substantial portions of the Software. 00016 00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 00023 DEALINGS IN THE SOFTWARE. 00024 */ 00025 00026 #ifndef EVENT_MODEL_H 00027 #define EVENT_MODEL_H 00028 00029 #include "mbed.h" 00030 #include "MicroBitConfig.h" 00031 #include "MicroBitComponent.h" 00032 #include "MicroBitEvent.h" 00033 #include "MicroBitListener.h" 00034 #include "ErrorNo.h" 00035 00036 /** 00037 * Class definition for the micro:bit EventModel. 00038 * 00039 * It is common to need to send events from one part of a program (or system) to another. 00040 * The way that these events are stored and delivered is known as an Event Model... 00041 * 00042 * The micro:bit can be programmed in a number of languages, and it not be good to 00043 * constrain those languages to any particular event model (e.g. they may have their own already). 00044 * 00045 * This class defines the functionality an event model needs to have to be able to interact 00046 * with events generated and/or used by the micro:bit runtime. Programmer may choose to implement 00047 * such funcitonality to integrate their own event models. 00048 * 00049 * This is an example of a key principle in computing - ABSTRACTION. This is now part of the 00050 * UK's Computing curriculum in schools... so ask your teacher about it. :-) 00051 * 00052 * An EventModel implementation is provided in the MicroBitMessageBus class. 00053 */ 00054 class EventModel 00055 { 00056 public: 00057 00058 static EventModel *defaultEventBus; 00059 00060 /** 00061 * Queues the given event to be sent to all registered recipients. 00062 * The method of delivery will vary depending on the underlying implementation. 00063 * 00064 * @param The event to send. 00065 * 00066 * @return This default implementation simply returns MICROBIT_NOT_SUPPORTED. 00067 */ 00068 virtual int send(MicroBitEvent evt) 00069 { 00070 (void) evt; 00071 return MICROBIT_NOT_SUPPORTED; 00072 } 00073 00074 /** 00075 * Add the given MicroBitListener to the list of event handlers, unconditionally. 00076 * 00077 * @param listener The MicroBitListener to validate. 00078 * 00079 * @return This default implementation simply returns MICROBIT_NOT_SUPPORTED. 00080 */ 00081 virtual int add(MicroBitListener *listener) 00082 { 00083 (void) listener; 00084 return MICROBIT_NOT_SUPPORTED; 00085 } 00086 00087 /** 00088 * Remove the given MicroBitListener from the list of event handlers. 00089 * 00090 * @param listener The MicroBitListener to remove. 00091 * 00092 * @return This default implementation simply returns MICROBIT_NOT_SUPPORTED. 00093 */ 00094 virtual int remove(MicroBitListener *listener) 00095 { 00096 (void) listener; 00097 return MICROBIT_NOT_SUPPORTED; 00098 } 00099 00100 /** 00101 * Returns the MicroBitListener at the given position in the list. 00102 * 00103 * @param n The index of the desired MicroBitListener. 00104 * 00105 * @return This default implementation simply returns NULL. 00106 */ 00107 MicroBitListener *elementAt(int n) 00108 { 00109 (void) n; 00110 return NULL; 00111 } 00112 00113 /** 00114 * Define the default EventModel to use for events raised and consumed by the microbit-dal runtime. 00115 * The default EventModel may be changed at any time. 00116 * 00117 * @param model A new instance of an EventModel to use as the default. 00118 * 00119 * @return MICROBIT_OK on success. 00120 * 00121 * Example: 00122 * @code 00123 * MicroBitMessageBus b(); 00124 * EventModel:setDefaultEventModel(b); 00125 * @endcode 00126 */ 00127 static int setDefaultEventModel(EventModel &model) 00128 { 00129 EventModel::defaultEventBus = &model; 00130 return MICROBIT_OK; 00131 } 00132 00133 /** 00134 * Register a listener function. 00135 * 00136 * An EventModel implementing this interface may optionally choose to override this method, 00137 * if that EventModel supports asynchronous callbacks to user code, but there is no 00138 * requirement to do so. 00139 * 00140 * @param id The source of messages to listen for. Events sent from any other IDs will be filtered. 00141 * Use MICROBIT_ID_ANY to receive events from all components. 00142 * 00143 * @param value The value of messages to listen for. Events with any other values will be filtered. 00144 * Use MICROBIT_EVT_ANY to receive events of any value. 00145 * 00146 * @param handler The function to call when an event is received. 00147 * 00148 * @param flags User specified, implementation specific flags, that allow behaviour of this events listener 00149 * to be tuned. 00150 * 00151 * @return MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation 00152 * simply returns MICROBIT_NOT_SUPPORTED. 00153 * 00154 * @code 00155 * void onButtonBClicked(MicroBitEvent) 00156 * { 00157 * //do something 00158 * } 00159 * 00160 * // call onButtonBClicked when ever a click event from buttonB is detected. 00161 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick); 00162 * @endcode 00163 */ 00164 int listen(int id, int value, void (*handler)(MicroBitEvent), uint16_t flags = EVENT_LISTENER_DEFAULT_FLAGS) 00165 { 00166 if (handler == NULL) 00167 return MICROBIT_INVALID_PARAMETER; 00168 00169 MicroBitListener *newListener = new MicroBitListener(id, value, handler, flags); 00170 00171 if(add(newListener) == MICROBIT_OK) 00172 return MICROBIT_OK; 00173 00174 delete newListener; 00175 00176 return MICROBIT_NOT_SUPPORTED; 00177 } 00178 00179 /** 00180 * Register a listener function. 00181 * 00182 * An EventModel implementing this interface may optionally choose to override this method, 00183 * if that EventModel supports asynchronous callbacks to user code, but there is no 00184 * requirement to do so. 00185 * 00186 * @param id The source of messages to listen for. Events sent from any other IDs will be filtered. 00187 * Use MICROBIT_ID_ANY to receive events from all components. 00188 * 00189 * @param value The value of messages to listen for. Events with any other values will be filtered. 00190 * Use MICROBIT_EVT_ANY to receive events of any value. 00191 * 00192 * @param handler The function to call when an event is received. 00193 * 00194 * @param arg Provide the callback with in an additional argument. 00195 * 00196 * @param flags User specified, implementation specific flags, that allow behaviour of this events listener 00197 * to be tuned. 00198 * 00199 * @return MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation 00200 * simply returns MICROBIT_NOT_SUPPORTED. 00201 * 00202 * @code 00203 * void onButtonBClicked(MicroBitEvent, void* data) 00204 * { 00205 * //do something 00206 * } 00207 * 00208 * // call onButtonBClicked when ever a click event from buttonB is detected. 00209 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick); 00210 * @endcode 00211 */ 00212 int listen(int id, int value, void (*handler)(MicroBitEvent, void*), void* arg, uint16_t flags = EVENT_LISTENER_DEFAULT_FLAGS) 00213 { 00214 if (handler == NULL) 00215 return MICROBIT_INVALID_PARAMETER; 00216 00217 MicroBitListener *newListener = new MicroBitListener(id, value, handler, arg, flags); 00218 00219 if(add(newListener) == MICROBIT_OK) 00220 return MICROBIT_OK; 00221 00222 delete newListener; 00223 00224 return MICROBIT_NOT_SUPPORTED; 00225 } 00226 00227 /** 00228 * Register a listener function. 00229 * 00230 * @param id The source of messages to listen for. Events sent from any other IDs will be filtered. 00231 * Use MICROBIT_ID_ANY to receive events from all components. 00232 * 00233 * @param value The value of messages to listen for. Events with any other values will be filtered. 00234 * Use MICROBIT_EVT_ANY to receive events of any value. 00235 * 00236 * @param hander The function to call when an event is received. 00237 * 00238 * @param flags User specified, implementation specific flags, that allow behaviour of this events listener 00239 * to be tuned. 00240 * 00241 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object 00242 * pointers are NULL. 00243 * 00244 * @code 00245 * void SomeClass::onButtonBClicked(MicroBitEvent) 00246 * { 00247 * //do something 00248 * } 00249 * 00250 * SomeClass s = new SomeClass(); 00251 * 00252 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick); 00253 * @endcode 00254 */ 00255 template <typename T> 00256 int listen(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent), uint16_t flags = EVENT_LISTENER_DEFAULT_FLAGS); 00257 00258 00259 /** 00260 * Unregister a listener function. 00261 * Listeners are identified by the Event ID, Event value and handler registered using listen(). 00262 * 00263 * @param id The Event ID used to register the listener. 00264 * @param value The Event value used to register the listener. 00265 * @param handler The function used to register the listener. 00266 * 00267 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler 00268 * given is NULL. 00269 * 00270 * Example: 00271 * @code 00272 * void onButtonBClick(MicroBitEvent) 00273 * { 00274 * //do something 00275 * } 00276 * 00277 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick); 00278 * 00279 * // the previously created listener is now ignored. 00280 * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick); 00281 * @endcode 00282 */ 00283 int ignore(int id, int value, void (*handler)(MicroBitEvent)) 00284 { 00285 if (handler == NULL) 00286 return MICROBIT_INVALID_PARAMETER; 00287 00288 MicroBitListener listener(id, value, handler); 00289 remove(&listener); 00290 00291 return MICROBIT_OK; 00292 } 00293 00294 /** 00295 * Unregister a listener function. 00296 * Listeners are identified by the Event ID, Event value and handler registered using listen(). 00297 * 00298 * @param id The Event ID used to register the listener. 00299 * @param value The Event value used to register the listener. 00300 * @param handler The function used to register the listener. 00301 * 00302 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler 00303 * given is NULL. 00304 * 00305 * Example: 00306 * @code 00307 * void onButtonBClick(MicroBitEvent, void* data) 00308 * { 00309 * //do something 00310 * } 00311 * 00312 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick); 00313 * 00314 * // the previously created listener is now ignored. 00315 * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick); 00316 * @endcode 00317 */ 00318 int ignore(int id, int value, void (*handler)(MicroBitEvent, void*)) 00319 { 00320 if (handler == NULL) 00321 return MICROBIT_INVALID_PARAMETER; 00322 00323 MicroBitListener listener(id, value, handler, NULL); 00324 remove(&listener); 00325 00326 return MICROBIT_OK; 00327 } 00328 00329 /** 00330 * Unregister a listener function. 00331 * Listners are identified by the Event ID, Event value and handler registered using listen(). 00332 * 00333 * @param id The Event ID used to register the listener. 00334 * @param value The Event value used to register the listener. 00335 * @param handler The function used to register the listener. 00336 * 00337 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object 00338 * pointers are NULL. 00339 * 00340 * Example: 00341 * @code 00342 * 00343 * void SomeClass::onButtonBClick() 00344 * { 00345 * //do something 00346 * } 00347 * 00348 * SomeClass s = new SomeClass(); 00349 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick); 00350 * 00351 * // the previously created listener is now ignored. 00352 * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick); 00353 * @endcode 00354 */ 00355 template <typename T> 00356 int ignore(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent)); 00357 00358 }; 00359 00360 /** 00361 * A registration function to allow C++ member functions (methods) to be registered as an event 00362 * listener. 00363 * 00364 * @param id The source of messages to listen for. Events sent from any other IDs will be filtered. 00365 * Use MICROBIT_ID_ANY to receive events from all components. 00366 * 00367 * @param value The value of messages to listen for. Events with any other values will be filtered. 00368 * Use MICROBIT_EVT_ANY to receive events of any value. 00369 * 00370 * @param object The object on which the method should be invoked. 00371 * 00372 * @param handler The method to call when an event is received. 00373 * 00374 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object 00375 * pointers are NULL. 00376 */ 00377 template <typename T> 00378 int EventModel::listen(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent), uint16_t flags) 00379 { 00380 if (object == NULL || handler == NULL) 00381 return MICROBIT_INVALID_PARAMETER; 00382 00383 MicroBitListener *newListener = new MicroBitListener(id, value, object, handler, flags); 00384 00385 if(add(newListener) == MICROBIT_OK) 00386 return MICROBIT_OK; 00387 00388 delete newListener; 00389 return MICROBIT_NOT_SUPPORTED; 00390 } 00391 00392 /** 00393 * Unregister a listener function. 00394 * Listners are identified by the Event ID, Event value and handler registered using listen(). 00395 * 00396 * @param id The Event ID used to register the listener. 00397 * @param value The Event value used to register the listener. 00398 * @param handler The function used to register the listener. 00399 * 00400 * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object 00401 * pointers are NULL. 00402 * 00403 * Example: 00404 * @code 00405 * 00406 * void SomeClass::onButtonBClick() 00407 * { 00408 * //do something 00409 * } 00410 * 00411 * SomeClass s = new SomeClass(); 00412 * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick); 00413 * 00414 * // the previously created listener is now ignored. 00415 * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick); 00416 * @endcode 00417 */ 00418 template <typename T> 00419 int EventModel::ignore(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent)) 00420 { 00421 if (handler == NULL) 00422 return MICROBIT_INVALID_PARAMETER; 00423 00424 MicroBitListener listener(id, value, object, handler); 00425 remove(&listener); 00426 00427 return MICROBIT_OK; 00428 } 00429 00430 #endif
Generated on Tue Jul 12 2022 20:39:13 by 1.7.2