AbstractBpsEventHandler

Since: BlackBerry 10.0.0

#include <bb/AbstractBpsEventHandler>

To link against this class, add the following line to your .pro file: LIBS += -lbb

Sub-class AbstractBpsEventHandler and implement event() to process raw BPS events.

The AbstractBpsEventHandler class is an abstract base class that consumers of BPS events must sub-class to implement the event() method. AbstractBpsEventHandler sub-classes register themselves to receive BPS events by calling subscribe() and providing a value returned by one of the xxx_get_domain() BPS functions (for example, clock_get_domain()). Any BPS event that matches this domain will be passed to the handler's event() method when it arrives. Handlers can register for multiple domains by calling subscribe() multiple times. BPS events for each domain are processed on the same thread as the corresponding call to subscribe(). Calling subscribe() on multiple threads using the same domain will result in events from that domain being received on each of those threads. A thread must have an event loop running in order to receive BPS events.

AbstractBpsEventHandler sub-classes are responsible for calling the appropriate function to start the flow of BPS events (for example, clock_request_events()). If you fail to do so and still call subscribe(), no events will ever be delivered to your handler.

Note most BPS functions operate on per thread global state and are sensitive to the calling thread. Be aware that it is not currently possible to call a BPS function from thread A that affects the flow of events in thread B. Consequently, if an AbstractBpsEventHandler subscribes to events on thread B, make sure you only call BPS functions for it on thread B.

Example usage:
class NavigatorBpsEventHandler: public AbstractBpsEventHandler {
public:
    NavigatorBpsEventHandler();
    virtual ~NavigatorBpsEventHandler();

    virtual void event(bps_event_t *event);
};
See full example


Overview

Public Functions Index

AbstractBpsEventHandler ()
virtual ~AbstractBpsEventHandler ()
voidevent (bps_event_t *event)=0

Protected Functions Index

voidsubscribe (int domain)
voidunsubscribe (int domain)

Public Functions

AbstractBpsEventHandler ()

Creates a new AbstractBpsEventHandler object.

Since:

BlackBerry 10.0.0

virtual~AbstractBpsEventHandler ()

Destructor.

Destroys this AbstractBpsEventHandler object and automatically unsubscribes it from all events. To avoid a race condition between unsubscribing and deleting, delete this object on the same thread that it receives events.

Since:

BlackBerry 10.0.0

void event (
  • bps_event_t *event)

Called when a BPS event arrives for a subscribed domain.

This method is invoked on the QThread that was active when subscribe() was called with this domain.

Parameters
event

The raw BPS event received by the QThread.

Example usage:
void NavigatorBpsEventHandler::event( bps_event_t *event ) {
    int domain = bps_event_get_domain(event);
    if (domain == navigator_get_domain()) {
        int code = bps_event_get_code(event);
        switch(code) {
            case NAVIGATOR_WINDOW_STATE:
                // Do something
                break;
        }
    }
}
See full example
Since:

BlackBerry 10.0.0

Protected Functions

void subscribe (
  • intdomain)

Register to receive BPS events of the specified domain on the current thread.

Register to receive BPS events, which match the provided domain, that arrive on the specified QThread. An instance of QAbstractEventDispatcher must exist for the current QThread or subscribing will fail. On the main thread, a QAbstractEventDispatcher is created when you create your application. On other threads, a QAbstractEventDispatcher is not available until QThread::exec() is called.

Parameters
domain

A value returned by one of the xxx_get_domain() BPS functions (for example, clock_get_domain()).

Example usage:
NavigatorBpsEventHandler::NavigatorBpsEventHandler() {
    subscribe(navigator_get_domain());
    bps_initialize();
    navigator_request_events(0);
}
See full example
Since:

BlackBerry 10.0.0

void unsubscribe (
  • intdomain)

Unregister the specified domain from the notifications to be received.

Unregister to receive BPS events previously subscribed to using subscribe(). To avoid a race condition between unsubscribing and receiving an event, unsubscribe on the same thread that this object receives events.

Parameters
domain

A value returned by one of the xxx_get_domain() BPS functions (for example, clock_get_domain()).

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus