Diff: inc/core/EventModel.h

Revision:

1:8aa5cdb4ab67

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/core/EventModel.h	Thu Apr 07 01:33:22 2016 +0100
@@ -0,0 +1,430 @@
+/*
+The MIT License (MIT)
+
+Copyright (c) 2016 British Broadcasting Corporation.
+This software is provided by Lancaster University by arrangement with the BBC.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef EVENT_MODEL_H
+#define EVENT_MODEL_H
+
+#include "mbed.h"
+#include "MicroBitConfig.h"
+#include "MicroBitComponent.h"
+#include "MicroBitEvent.h"
+#include "MicroBitListener.h"
+#include "ErrorNo.h"
+
+/**
+  * Class definition for the micro:bit EventModel.
+  *
+  * It is common to need to send events from one part of a program (or system) to another.
+  * The way that these events are stored and delivered is known as an Event Model...
+  *
+  * The micro:bit can be programmed in a number of languages, and it not be good to
+  * constrain those languages to any particular event model (e.g. they may have their own already).
+  *
+  * This class defines the functionality an event model needs to have to be able to interact
+  * with events generated and/or used by the micro:bit runtime. Programmer may choose to implement
+  * such funcitonality to integrate their own event models.
+  *
+  * This is an example of a key principle in computing - ABSTRACTION. This is now part of the
+  * UK's Computing curriculum in schools... so ask your teacher about it. :-)
+  *
+  * An EventModel implementation is provided in the MicroBitMessageBus class.
+  */
+class EventModel
+{
+    public:
+
+    static EventModel *defaultEventBus;
+
+	/**
+	  * Queues the given event to be sent to all registered recipients.
+      * The method of delivery will vary depending on the underlying implementation.
+	  *
+	  * @param The event to send.
+      *
+      * @return This default implementation simply returns MICROBIT_NOT_SUPPORTED.
+	  */
+	virtual int send(MicroBitEvent evt)
+    {
+        (void) evt;
+        return MICROBIT_NOT_SUPPORTED;
+    }
+
+    /**
+     * Add the given MicroBitListener to the list of event handlers, unconditionally.
+     *
+     * @param listener The MicroBitListener to validate.
+     *
+     * @return This default implementation simply returns MICROBIT_NOT_SUPPORTED.
+     */
+    virtual int add(MicroBitListener *listener)
+    {
+        (void) listener;
+        return MICROBIT_NOT_SUPPORTED;
+    }
+
+    /**
+     * Remove the given MicroBitListener from the list of event handlers.
+     *
+     * @param listener The MicroBitListener to remove.
+     *
+     * @return This default implementation simply returns MICROBIT_NOT_SUPPORTED.
+     */
+    virtual int remove(MicroBitListener *listener)
+    {
+        (void) listener;
+        return MICROBIT_NOT_SUPPORTED;
+    }
+
+    /**
+      * Returns the MicroBitListener at the given position in the list.
+      *
+      * @param n The index of the desired MicroBitListener.
+      *
+      * @return This default implementation simply returns NULL.
+      */
+    MicroBitListener *elementAt(int n)
+    {
+        (void) n;
+        return NULL;
+    }
+
+	/**
+	  * Define the default EventModel to use for events raised and consumed by the microbit-dal runtime.
+      * The default EventModel may be changed at any time.
+      *
+	  * @param model A new instance of an EventModel to use as the default.
+      *
+      * @return MICROBIT_OK on success.
+	  *
+      * Example:
+      * @code
+      * MicroBitMessageBus b();
+      * EventModel:setDefaultEventModel(b);
+      * @endcode
+	  */
+	static int setDefaultEventModel(EventModel &model)
+    {
+        EventModel::defaultEventBus = &model;
+        return MICROBIT_OK;
+    }
+
+	/**
+	  * Register a listener function.
+      *
+      * An EventModel implementing this interface may optionally choose to override this method,
+      * if that EventModel supports asynchronous callbacks to user code, but there is no
+      * requirement to do so.
+      *
+	  * @param id The source of messages to listen for. Events sent from any other IDs will be filtered.
+	  * Use MICROBIT_ID_ANY to receive events from all components.
+	  *
+	  * @param value The value of messages to listen for. Events with any other values will be filtered.
+	  * Use MICROBIT_EVT_ANY to receive events of any value.
+	  *
+	  * @param handler The function to call when an event is received.
+      *
+      * @param flags User specified, implementation specific flags, that allow behaviour of this events listener
+      * to be tuned.
+      *
+      * @return MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation
+      * simply returns MICROBIT_NOT_SUPPORTED.
+	  *
+      * @code
+      * void onButtonBClicked(MicroBitEvent)
+      * {
+      * 	//do something
+      * }
+      *
+      * // call onButtonBClicked when ever a click event from buttonB is detected.
+      * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
+      * @endcode
+	  */
+	int listen(int id, int value, void (*handler)(MicroBitEvent), uint16_t flags = EVENT_LISTENER_DEFAULT_FLAGS)
+    {
+        if (handler == NULL)
+            return MICROBIT_INVALID_PARAMETER;
+
+        MicroBitListener *newListener = new MicroBitListener(id, value, handler, flags);
+
+        if(add(newListener) == MICROBIT_OK)
+            return MICROBIT_OK;
+
+        delete newListener;
+
+        return MICROBIT_NOT_SUPPORTED;
+    }
+
+    /**
+	  * Register a listener function.
+      *
+      * An EventModel implementing this interface may optionally choose to override this method,
+      * if that EventModel supports asynchronous callbacks to user code, but there is no
+      * requirement to do so.
+      *
+	  * @param id The source of messages to listen for. Events sent from any other IDs will be filtered.
+	  * Use MICROBIT_ID_ANY to receive events from all components.
+	  *
+	  * @param value The value of messages to listen for. Events with any other values will be filtered.
+	  * Use MICROBIT_EVT_ANY to receive events of any value.
+	  *
+	  * @param handler The function to call when an event is received.
+      *
+      * @param arg Provide the callback with in an additional argument.
+      *
+      * @param flags User specified, implementation specific flags, that allow behaviour of this events listener
+      * to be tuned.
+      *
+      * @return MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation
+      * simply returns MICROBIT_NOT_SUPPORTED.
+	  *
+      * @code
+      * void onButtonBClicked(MicroBitEvent, void* data)
+      * {
+      * 	//do something
+      * }
+      *
+      * // call onButtonBClicked when ever a click event from buttonB is detected.
+      * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
+      * @endcode
+	  */
+    int listen(int id, int value, void (*handler)(MicroBitEvent, void*), void* arg, uint16_t flags = EVENT_LISTENER_DEFAULT_FLAGS)
+    {
+        if (handler == NULL)
+            return MICROBIT_INVALID_PARAMETER;
+
+        MicroBitListener *newListener = new MicroBitListener(id, value, handler, arg, flags);
+
+        if(add(newListener) == MICROBIT_OK)
+            return MICROBIT_OK;
+
+        delete newListener;
+
+        return MICROBIT_NOT_SUPPORTED;
+    }
+
+	/**
+	  * Register a listener function.
+	  *
+	  * @param id The source of messages to listen for. Events sent from any other IDs will be filtered.
+	  * Use MICROBIT_ID_ANY to receive events from all components.
+	  *
+	  * @param value The value of messages to listen for. Events with any other values will be filtered.
+	  * Use MICROBIT_EVT_ANY to receive events of any value.
+	  *
+	  * @param hander The function to call when an event is received.
+      *
+      * @param flags User specified, implementation specific flags, that allow behaviour of this events listener
+      * to be tuned.
+      *
+      * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object
+      *         pointers are NULL.
+      *
+      * @code
+      * void SomeClass::onButtonBClicked(MicroBitEvent)
+      * {
+      * 	//do something
+      * }
+      *
+      * SomeClass s = new SomeClass();
+      *
+      * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
+      * @endcode
+	  */
+    template <typename T>
+	int listen(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent), uint16_t flags = EVENT_LISTENER_DEFAULT_FLAGS);
+
+
+	/**
+	  * Unregister a listener function.
+      * Listeners are identified by the Event ID, Event value and handler registered using listen().
+	  *
+	  * @param id The Event ID used to register the listener.
+	  * @param value The Event value used to register the listener.
+	  * @param handler The function used to register the listener.
+      *
+      * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler
+      *         given is NULL.
+	  *
+      * Example:
+      * @code
+      * void onButtonBClick(MicroBitEvent)
+      * {
+      * 	//do something
+      * }
+      *
+      * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
+      *
+      * // the previously created listener is now ignored.
+      * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
+      * @endcode
+	  */
+	int ignore(int id, int value, void (*handler)(MicroBitEvent))
+    {
+        if (handler == NULL)
+            return MICROBIT_INVALID_PARAMETER;
+
+        MicroBitListener listener(id, value, handler);
+        remove(&listener);
+
+        return MICROBIT_OK;
+    }
+
+    /**
+	  * Unregister a listener function.
+      * Listeners are identified by the Event ID, Event value and handler registered using listen().
+	  *
+	  * @param id The Event ID used to register the listener.
+	  * @param value The Event value used to register the listener.
+	  * @param handler The function used to register the listener.
+      *
+      * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler
+      *         given is NULL.
+	  *
+      * Example:
+      * @code
+      * void onButtonBClick(MicroBitEvent, void* data)
+      * {
+      * 	//do something
+      * }
+      *
+      * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
+      *
+      * // the previously created listener is now ignored.
+      * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick);
+      * @endcode
+	  */
+	int ignore(int id, int value, void (*handler)(MicroBitEvent, void*))
+    {
+        if (handler == NULL)
+            return MICROBIT_INVALID_PARAMETER;
+
+        MicroBitListener listener(id, value, handler, NULL);
+        remove(&listener);
+
+        return MICROBIT_OK;
+    }
+
+	/**
+	  * Unregister a listener function.
+      * Listners are identified by the Event ID, Event value and handler registered using listen().
+	  *
+	  * @param id The Event ID used to register the listener.
+	  * @param value The Event value used to register the listener.
+	  * @param handler The function used to register the listener.
+      *
+      * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object
+      *         pointers are NULL.
+	  *
+      * Example:
+      * @code
+      *
+      * void SomeClass::onButtonBClick()
+      * {
+      * 	//do something
+      * }
+      *
+      * SomeClass s = new SomeClass();
+      * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
+      *
+      * // the previously created listener is now ignored.
+      * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
+      * @endcode
+	  */
+    template <typename T>
+	int ignore(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent));
+
+};
+
+/**
+  * A registration function to allow C++ member functions (methods) to be registered as an event
+  * listener.
+  *
+  * @param id The source of messages to listen for. Events sent from any other IDs will be filtered.
+  * Use MICROBIT_ID_ANY to receive events from all components.
+  *
+  * @param value The value of messages to listen for. Events with any other values will be filtered.
+  * Use MICROBIT_EVT_ANY to receive events of any value.
+  *
+  * @param object The object on which the method should be invoked.
+  *
+  * @param handler The method to call when an event is received.
+  *
+  * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object
+  *         pointers are NULL.
+  */
+template <typename T>
+int EventModel::listen(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent), uint16_t flags)
+{
+	if (object == NULL || handler == NULL)
+		return MICROBIT_INVALID_PARAMETER;
+
+	MicroBitListener *newListener = new MicroBitListener(id, value, object, handler, flags);
+
+    if(add(newListener) == MICROBIT_OK)
+        return MICROBIT_OK;
+
+    delete newListener;
+    return MICROBIT_NOT_SUPPORTED;
+}
+
+/**
+  * Unregister a listener function.
+  * Listners are identified by the Event ID, Event value and handler registered using listen().
+  *
+  * @param id The Event ID used to register the listener.
+  * @param value The Event value used to register the listener.
+  * @param handler The function used to register the listener.
+  *
+  * @return MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object
+  *         pointers are NULL.
+  *
+  * Example:
+  * @code
+  *
+  * void SomeClass::onButtonBClick()
+  * {
+  * 	//do something
+  * }
+  *
+  * SomeClass s = new SomeClass();
+  * uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
+  *
+  * // the previously created listener is now ignored.
+  * uBit.messageBus.ignore(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
+  * @endcode
+  */
+template <typename T>
+int EventModel::ignore(uint16_t id, uint16_t value, T* object, void (T::*handler)(MicroBitEvent))
+{
+	if (handler == NULL)
+		return MICROBIT_INVALID_PARAMETER;
+
+	MicroBitListener listener(id, value, object, handler);
+    remove(&listener);
+
+    return MICROBIT_OK;
+}
+
+#endif