Handling BPS events

There are Cascades APIs available for almost anything that you need to do in your apps. Cascades includes APIs that let you create UIs, APIs that help you access device features such as sensors and notifications, and APIs that let you integrate with other apps on a device.

However, you might want to use features of the BlackBerry Application Platform that aren't available using Cascades APIs. In these cases, you can use other core native libraries that are included in the BlackBerry 10 Native SDK. These libraries typically provide lower-level APIs that let your apps access platform services directly. You might choose to use these libraries if you can't find an equivalent API in Cascades or if you want greater control over the features and resources that your app uses, letting you squeeze out every last bit of performance for your app.

One of the core native libraries that you can use is the BlackBerry Platform Services (BPS) library. This library provides a consistent, event-driven interface that lets you access a wide range of platform services. To learn about all of the platform services that you can use with BPS, see the BlackBerry Platform Services Library documentation.

To use the BPS library in your app, you should add it to your project in the Momentics IDE by using the Add Library Wizard. Right-click your project and click Configure > Add Library. Select the Standard BlackBerry platform library option, and then select the BlackBerry Platform Services check box (in the Platform section).

Using the BPS event queue

The BPS library is based on events, which represent changes to an aspect of the device or environment. For example, an event is generated when the network connection status of the device changes, when the locale on the device changes, or when the virtual keyboard is displayed or hidden. In your app, you can specify the types of events that you're interested in, and these events are delivered to an event queue that your app can access. Your app can listen for new events to enter the event queue and then respond to these events in any way you want.

If you create a core native app (that is, one that doesn't use any Cascades APIs), you would create an event loop that continuously checks for and processes BPS events as they occur. When an event arrives in the event queue, your app would detect the new event, retrieve it, and process it accordingly. To learn more about this approach, see the BlackBerry Platform Services Library documentation.

If you create a Cascades app, you don't need to implement an event loop yourself. Instead, you can use a class called AbstractBpsEventHandler, which is designed to help you handle BPS events. You can create your own handler class that inherits from AbstractBpsEventHandler, and when an event arrives in the BPS event queue, the event is delivered automatically to your class by using the event() function. You can then implement this function to handle events in any way you want.

The following diagram demonstrates how to use the BPS event queue in your Cascades app. Each step includes some example code that you might use to accomplish that step.

Diagram illustrating how to use BPS in a Cascades app.

Initialize the BPS library

Before your app can start receiving events, you need to initialize the BPS library. The bps_initialize() function makes the BPS library available to your app's current thread. This function must be the first BPS function that you call when you want to use other BPS library functions.

Subscribe to domains

To process BPS events in a Cascades app, you can inherit from the AbstractBpsEventHandler class. This class includes an event() function, which you can implement to handle an event when it arrives in the BPS event queue. In order for event() to be called when an event arrives, you need to subscribe to the event domains that you're interested in. You can call subscribe(), which is part of AbstractBpsEventHandler, and pass in the domains (for example, network status or locale) for the events that you want to handle.

Request events

You can choose the types of events that you want your app to receive. For example, you might want to respond only to changes in network connection status or locale, so you can request that only these events are delivered to the BPS event queue. You can call the appropriate *_request_events() functions to request events for a particular platform service (for example, netstatus_request_events() for network status events, locale_request_events() for locale events, and so on).

Inherit from the AbstractBpsEvent Handler class

The AbstractBpsEventHandler class lets your app be notified when a new event arrives in the event queue. To handle these events, you can create a class that inherits from AbstractBpsEventHandler. This class that you create can take care of all of the BPS event handling for your app.

Implement the event() function

As mentioned above, the AbstractBpsEventHandler class includes an event() function that's called when an event arrives in the event queue. By implementing this function in your app, you can handle events as they arrive.

Handle events

After an event arrives in the event queue and your event() function is called, your app can process the event and take any appropriate actions. Each platform service generates a different kind of event, and events are identified by the event domain (the service that generated the event) and an event code (the type of the event).

You can determine the platform service that generated the event by using bps_event_get_domain() and comparing the return value to the domain of the service you're interested in. For example, the domain of the network status service is represented by the netstatus_get_domain() function. You typically include this code in the same loop that you use to retrieve new events from the queue, as described above.

Close the BPS library

When your app is finished receiving BPS events, you need to close the BPS library by calling bps_shutdown(). This function frees the platform service resources that were allocated for your app's thread.

Even though the BPS library is a core native library, you can still use it in your Cascades project alongside other C/C++ classes and functions that your app might use. Here's an example of a C/C++ source file that demonstrates how to use the BPS event queue:

// BpsSample.cpp

// Include the corresponding header file
#include "BpsSample.h"

// You might choose to include setup operations, such as
// initializing the BPS library and requesting events, in
// a constructor.
BpsSample::BpsSample() {
    // Initialize the BPS library
    bps_initialize();

    // Subscribe to domains
    subscribe(netstatus_get_domain());
    subscribe(locale_get_domain());

    // Request events
    virtualkeyboard_request_events(0);
    netstatus_request_events(0);
    locale_request_events(0);
}

BpsSample::~BpsSample() {
    // Close the BPS library
    bps_shutdown();
}

// Implement the event() function in your handler class
void BpsSample::event(bps_event_t *event)
{
    // Handle events
    if (bps_event_get_domain(event) == netstatus_get_domain()) {
        // Handle network status events
        // ...
    } else if (bps_event_get_domain(event) == locale_get_domain()) {
        // Handle locale events
        // ...
    }
}

Here's what the corresponding header file might look like:

// BpsSample.h

// Include the required header files for the platform services
// that you want to use. Note that bps.h is always required.
#include <bps/bps.h>
#include <bps/virtualkeyboard.h>
#include <bps/netstatus.h>
#include <bps/locale.h>

// Define a handler class that inherits from AbstractBpsEventHandler.
// Make sure that you always inherit from QObject first.
class BpsSample : public QObject, public bb::AbstractBpsEventHandler
{
    Q_OBJECT

public:
    BpsSample();
    ~BpsSample();
    virtual void event(bps_event_t *event);
};

Related resources

Sample apps

 
 

Last modified: 2013-12-21

comments powered by Disqus