fsdfds
Dependencies: BLE_API mbed-dev-bin nRF51822
Fork of microbit-dal by
MicroBitMessageBus Class Reference
Class definition for the MicroBitMessageBus. More...
#include <MicroBitMessageBus.h>
Inherits EventModel, and MicroBitComponent.
Public Member Functions | |
MicroBitMessageBus () | |
Default constructor. | |
virtual int | send (MicroBitEvent evt) |
Queues the given event to be sent to all registered recipients. | |
int | process (MicroBitEvent &evt, bool urgent=false) |
Internal function, used to deliver the given event to all relevant recipients. | |
virtual MicroBitListener * | elementAt (int n) |
Returns the microBitListener with the given position in our list. | |
~MicroBitMessageBus () | |
Destructor for MicroBitMessageBus, where we deregister this instance from the array of fiber components. | |
virtual int | add (MicroBitListener *newListener) |
Add the given MicroBitListener to the list of event handlers, unconditionally. | |
virtual int | remove (MicroBitListener *newListener) |
Remove the given MicroBitListener from the list of event handlers. | |
int | listen (int id, int value, void(*handler)(MicroBitEvent), uint16_t flags=EVENT_LISTENER_DEFAULT_FLAGS) |
Register a listener function. | |
int | listen (int id, int value, void(*handler)(MicroBitEvent, void *), void *arg, uint16_t flags=EVENT_LISTENER_DEFAULT_FLAGS) |
Register a listener function. | |
template<typename T > | |
int | listen (uint16_t id, uint16_t value, T *object, void(T::*handler)(MicroBitEvent), uint16_t flags=EVENT_LISTENER_DEFAULT_FLAGS) |
Register a listener function. | |
int | ignore (int id, int value, void(*handler)(MicroBitEvent)) |
Unregister a listener function. | |
int | ignore (int id, int value, void(*handler)(MicroBitEvent, void *)) |
Unregister a listener function. | |
template<typename T > | |
int | ignore (uint16_t id, uint16_t value, T *object, void(T::*handler)(MicroBitEvent)) |
Unregister a listener function. | |
virtual void | systemTick () |
The system timer will call this member function once the component has been added to the array of system components using system_timer_add_component. | |
Static Public Member Functions | |
static int | setDefaultEventModel (EventModel &model) |
Define the default EventModel to use for events raised and consumed by the microbit-dal runtime. | |
Static Public Attributes | |
static EventModel * | defaultEventBus = NULL |
Class definition for a MicroBitEvent. |
Detailed Description
Class definition for the MicroBitMessageBus.
The MicroBitMessageBus is the common mechanism to deliver asynchronous events on the MicroBit platform. It serves a number of purposes:
1) It provides an eventing abstraction that is independent of the underlying substrate.
2) It provides a mechanism to decouple user code from trusted system code i.e. the basis of a message passing nano kernel.
3) It allows a common high level eventing abstraction across a range of hardware types.e.g. buttons, BLE...
4) It provides a mechanim for extensibility - new devices added via I/O pins can have OO based drivers and communicate via the message bus with minima impact on user level languages.
5) It allows for the possiblility of event / data aggregation, which in turn can save energy.
It has the following design principles:
1) Maintain a low RAM footprint where possible
2) Make few assumptions about the underlying platform, but allow optimizations where possible.
Definition at line 60 of file MicroBitMessageBus.h.
Constructor & Destructor Documentation
Default constructor.
Class definition for the MicroBitMessageBus.
Adds itself as a fiber component, and also configures itself to be the default EventModel if defaultEventBus is NULL.
The MicroBitMessageBus is the common mechanism to deliver asynchronous events on the MicroBit platform. It serves a number of purposes:
1) It provides an eventing abstraction that is independent of the underlying substrate.
2) It provides a mechanism to decouple user code from trusted system code i.e. the basis of a message passing nano kernel.
3) It allows a common high level eventing abstraction across a range of hardware types.e.g. buttons, BLE...
4) It provides a mechanim for extensibility - new devices added via I/O pins can have OO based drivers and communicate via the message bus with minima impact on user level languages.
5) It allows for the possiblility of event / data aggregation, which in turn can save energy.
It has the following design principles:
1) Maintain a low RAM footprint where possible
2) Make few assumptions about the underlying platform, but allow optimizations where possible. Default constructor.
Adds itself as a fiber component, and also configures itself to be the default EventModel if defaultEventBus is NULL.
Definition at line 61 of file MicroBitMessageBus.cpp.
~MicroBitMessageBus | ( | ) |
Destructor for MicroBitMessageBus, where we deregister this instance from the array of fiber components.
Definition at line 546 of file MicroBitMessageBus.cpp.
Member Function Documentation
int add | ( | MicroBitListener * | newListener ) | [virtual] |
Add the given MicroBitListener to the list of event handlers, unconditionally.
- Parameters:
-
listener The MicroBitListener to add.
- Returns:
- MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.
Reimplemented from EventModel.
Definition at line 392 of file MicroBitMessageBus.cpp.
MicroBitListener * elementAt | ( | int | n ) | [virtual] |
Returns the microBitListener with the given position in our list.
- Parameters:
-
n The position in the list to return.
- Returns:
- the MicroBitListener at postion n in the list, or NULL if the position is invalid.
Reimplemented from EventModel.
Definition at line 527 of file MicroBitMessageBus.cpp.
int ignore | ( | int | id, |
int | value, | ||
void(*)(MicroBitEvent) | handler | ||
) | [inherited] |
Unregister a listener function.
Listeners are identified by the Event ID, Event value and handler registered using listen().
- Parameters:
-
id The Event ID used to register the listener. value The Event value used to register the listener. handler The function used to register the listener.
- Returns:
- MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler given is NULL.
Example:
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);
Definition at line 283 of file EventModel.h.
int ignore | ( | int | id, |
int | value, | ||
void(*)(MicroBitEvent, void *) | handler | ||
) | [inherited] |
Unregister a listener function.
Listeners are identified by the Event ID, Event value and handler registered using listen().
- Parameters:
-
id The Event ID used to register the listener. value The Event value used to register the listener. handler The function used to register the listener.
- Returns:
- MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler given is NULL.
Example:
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);
Definition at line 318 of file EventModel.h.
int ignore | ( | uint16_t | id, |
uint16_t | value, | ||
T * | object, | ||
void(T::*)(MicroBitEvent) | handler | ||
) | [inherited] |
Unregister a listener function.
Listners are identified by the Event ID, Event value and handler registered using listen().
- Parameters:
-
id The Event ID used to register the listener. value The Event value used to register the listener. handler The function used to register the listener.
- Returns:
- MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object pointers are NULL.
Example:
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);
Definition at line 419 of file EventModel.h.
int listen | ( | int | id, |
int | value, | ||
void(*)(MicroBitEvent, void *) | handler, | ||
void * | arg, | ||
uint16_t | flags = EVENT_LISTENER_DEFAULT_FLAGS |
||
) | [inherited] |
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.
- Parameters:
-
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. 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. handler The function to call when an event is received. arg Provide the callback with in an additional argument. flags User specified, implementation specific flags, that allow behaviour of this events listener to be tuned.
- Returns:
- MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation simply returns MICROBIT_NOT_SUPPORTED.
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);
Definition at line 212 of file EventModel.h.
int listen | ( | uint16_t | id, |
uint16_t | value, | ||
T * | object, | ||
void(T::*)(MicroBitEvent) | handler, | ||
uint16_t | flags = EVENT_LISTENER_DEFAULT_FLAGS |
||
) | [inherited] |
Register a listener function.
A registration function to allow C++ member functions (methods) to be registered as an event listener.
- Parameters:
-
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. 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. hander The function to call when an event is received. flags User specified, implementation specific flags, that allow behaviour of this events listener to be tuned.
- Returns:
- MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object pointers are NULL.
void SomeClass::onButtonBClicked(MicroBitEvent) { //do something } SomeClass s = new SomeClass(); uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, s, &SomeClass::onButtonBClick);
- Parameters:
-
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. 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. object The object on which the method should be invoked. handler The method to call when an event is received.
- Returns:
- MICROBIT_OK on success or MICROBIT_INVALID_PARAMETER if the handler or object pointers are NULL.
Definition at line 378 of file EventModel.h.
int listen | ( | int | id, |
int | value, | ||
void(*)(MicroBitEvent) | handler, | ||
uint16_t | flags = EVENT_LISTENER_DEFAULT_FLAGS |
||
) | [inherited] |
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.
- Parameters:
-
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. 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. handler The function to call when an event is received. flags User specified, implementation specific flags, that allow behaviour of this events listener to be tuned.
- Returns:
- MICROBIT_OK on success, or any valid error code defined in "ErrNo.h". The default implementation simply returns MICROBIT_NOT_SUPPORTED.
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);
Definition at line 164 of file EventModel.h.
int process | ( | MicroBitEvent & | evt, |
bool | urgent = false |
||
) |
Internal function, used to deliver the given event to all relevant recipients.
Normally, this is called once an event has been removed from the event queue.
- Parameters:
-
evt The event to send. urgent The type of listeners to process (optional). If set to true, only listeners defined as urgent and non-blocking will be processed otherwise, all other (standard) listeners will be processed. Defaults to false.
- Returns:
- 1 if all matching listeners were processed, 0 if further processing is required.
- Note:
- It is recommended that all external code uses the send() function instead of this function, or the constructors provided by MicrobitEvent.
Definition at line 340 of file MicroBitMessageBus.cpp.
int remove | ( | MicroBitListener * | listener ) | [virtual] |
Remove the given MicroBitListener from the list of event handlers.
- Parameters:
-
listener The MicroBitListener to remove.
- Returns:
- MICROBIT_OK if the listener is valid, MICROBIT_INVALID_PARAMETER otherwise.
Reimplemented from EventModel.
Definition at line 483 of file MicroBitMessageBus.cpp.
int send | ( | MicroBitEvent | evt ) | [virtual] |
Queues the given event to be sent to all registered recipients.
- Parameters:
-
evt The event to send.
MicroBitMessageBus bus; // Creates and sends the MicroBitEvent using bus. MicrobitEvent evt(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK); // Creates the MicrobitEvent, but delays the sending of that event. MicrobitEvent evt1(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK, CREATE_ONLY); bus.send(evt1); // This has the same effect! evt1.fire()
Reimplemented from EventModel.
Definition at line 317 of file MicroBitMessageBus.cpp.
static int setDefaultEventModel | ( | EventModel & | model ) | [static, inherited] |
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.
- Parameters:
-
model A new instance of an EventModel to use as the default.
- Returns:
- MICROBIT_OK on success.
Example:
Definition at line 127 of file EventModel.h.
virtual void systemTick | ( | ) | [virtual, inherited] |
The system timer will call this member function once the component has been added to the array of system components using system_timer_add_component.
This callback will be in interrupt context.
Reimplemented in MicroBitSystemTimerCallback, MicroBitButton, and MicroBitDisplay.
Definition at line 125 of file MicroBitComponent.h.
Field Documentation
EventModel * defaultEventBus = NULL [static, inherited] |
Class definition for a MicroBitEvent.
It represents a common event that is generated by the various components on the micro:bit.
Definition at line 58 of file EventModel.h.
Generated on Wed Jul 13 2022 00:58:04 by 1.7.2