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