BlackBerry Platform Services

The core native libraries that are included in the BlackBerry 10 Native SDK typically provide lower-level APIs that let your apps access platform services directly. These libraries give you greater control over the features and resources that your app uses, and let you optimize your app's performance.

The BlackBerry Platform Services (BPS) library provides a consistent, event-driven interface to a wide range of platform services.

For a complete list of platform services that you can use with BPS, see the BlackBerry Platform Services Library documentation.

Using BPS

To use the BPS library in your app, in the Momentics IDE for BlackBerry, link the BPS library.

BPS provides a functional interface to platform services, along with an event-retrieval mechanism for asynchronous notification. Events represent changes to aspects of the device or the environment. For example, events are generated when the network connection status of the device changes, when the locale on the device changes, and 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.

Different platform services generate different events. Events are differentiated by their event domain (the service that generated the event) and their event code (the type of the event). In addition, events can have a payload that includes any information sent along from the service when it generated the event.

You can use an event loop to continuously process BPS events as they occur. When an event arrives in the event queue, your app detects the new event, retrieves it, and processes it accordingly. To learn more about this approach, see the BlackBerry Platform Services Library documentation.

When you want to use an event loop in your app, you make a request to each of the platform services that you want your app to receive events from. You create a loop to listen for the events, and your app's logic determines how each event is handled.

The following sample demonstrates using an event loop to handle any virtual keyboard, orientation, or navigator events:

/* Start BPS */
bps_initialize;

/* Request events */
virtualkeyboard_request_events(0);
orientation_request_events(0);
navigator_request_events(0);

/* Listen for and handle events */
while (!exit_app) {
    bps_event_t *event;
    
    /* Block until an event is received */
    bps_get_event(&event, -1);
    
    /* Pass event to a handling function */
    handle_event(&event);
}

/* Stop BPS */
bps_shutdown();
        

Alternatively, you can create a subclass of the AbstractBpsEventHandler class and use it to process BPS events. When an event arrives in the BPS event queue, the event is delivered automatically to your subclass through the event() function. You implement this function to process events in your app.

Initialize BPS

Before your app can start receiving events, you must initialize the BPS library. Call bps_initialize() to make the BPS library available to your app's current thread. You must call this function before you can use any other functions from the BPS library.

Not applicable

It's a good practice to initialize BPS in the constructor of your event handler class.

                    
MyBpsHandler::MyBpsHandler() {

    ...

    if (bps_initialize() != BPS_SUCCESS) {
      // Handle failure to initialize BPS library
    }
       
    ...
}
                

Initialize BPS before your event loop.

                    
if (bps_initialize() != BPS_SUCCESS) {
    /* Handle failure to initialize BPS library */
}                    
                

Subscribe to event domains

You can create a subclass of AbstractBpsEventHandler to process BPS events. This class includes an event() function, which you can implement to process an event when it arrives in the BPS event queue. If you use a subclass, you must subscribe to the event domains that you're interested in, to have event() called when those types of events occur. You can call subscribe(), which is part of AbstractBpsEventHandler, and pass in the domains (for example, network status or locale) of the events that you want your app to process.

Not applicable

It's a good practice to subscribe to domains in the constructor of your event handler class.

                    
MyBpsHandler::MyBpsHandler() {

    ...
    
    subscribe(netstatus_get_domain());
    subscribe(locale_get_domain());

    if (bps_initialize() != BPS_SUCCESS) { ... }
    
    ...
}
                

Not applicable

Request BPS events

You choose the types of events that you want your app to receive. For example, suppose that you call netstatus_request_events() and locale_request_events(). These calls request that network connection status and locale events be delivered to your app's BPS event queue. No other types of events are delivered to your app.

Not applicable

It's a good practice to request BPS events in the constructor of your event handler class.

MyBpsHandler::MyBpsHandler() {

    ...

    if (bps_initialize() != BPS_SUCCESS) {
        // Handle failure to initialize BPS library
    }

    ...

    if (netstatus_request_events(0 != BPS_SUCCESS) {
        // Failed to request events
    }
    if (locale_request_events(0) != BPS_SUCCESS) {
        // Failed to request events
    }

}
                

Request events before your event loop.

if (netstatus_request_events(0) != BPS_SUCCESS) {
    /* Failed to request events */
}
if (locale_request_events(0) != BPS_SUCCESS) {
    /* Failed to request events */
}                    
                

Process BPS events

You can use a similar approach to process BPS events regardless of whether you're developing your app in C or C++.

You can use the bps_event_get_domain() function to determine the service that generated a particular event based on the domain of that event. You can call bps_event_get_code() to determine the event code. Your app can use the event domain and the event code to determine how to process the event. Your app can also call individual accessor functions to extract payload data from the event as required by the app.

For more details on individual events, consult the documentation for the service that generates the event.

Not applicable

When you use a subclass of AbstractBpsEventHandler to process BPS events, you perform all of your event handling in the event() function of that subclass. For example, if you create MyBpsHandler as a subclass of AbstractBpsEventHandler, then you implement all of your event handling code in MyBpsHandler::event().

// Handle locale and netstatus events that are delivered
// to the app
void MyBpsHandler::event(bps_event_t *event)
{
    unsigned int eventCode = bps_event_get_code(event);

    eventDomain = bps_event_get_domain(event);
    if (eventDomain == locale_get_domain())
    {                
        // Handle locale event
        ...
    }
    else if (eventDomain == netstatus_get_domain())
    {
        // Handle netstatus event
        ...
    }
    
    return;
}            

When you develop your app in C, you can process BPS events in your event loop, or create one or more event handling functions to process BPS events. The following sample demonstrates a hybrid approach that uses the event type to determine which handling function to call. You must create the event handling code or functions that you want to use in your app.

unsigned int eventCode;
while (!exit_program)
{
    bps_event_t *currentEvent = NULL;
    bps_get_event(&currentEvent, -1);

    eventDomain = bps_event_get_domain(currentEvent);
    if (eventDomain == netstatus_get_domain())
    {
        handle_netstatus_event(currentEvent);
    }
    else if (eventDomain == locale_get_domain())
    {
        handle_locale_event(currentEvent);
    }    
}

Stop receiving BPS events

You can stop receiving events that you requested by calling the appropriate stop_events() function. For example, if you requested that locale events be sent to your app by calling local_request_events(), you can call locale_stop_events() to stop receiving locale events.

Not applicable

if (netstatus_stop_events() != BPS_SUCCESS) {
    // Failed to stop events
}

if (locale_stop_events() != BPS_SUCCESS) {
    // Failed to stop events
}
                
if (netstatus_stop_events() != BPS_SUCCESS) {
    /* Failed to stop events */
}

if (locale_stop_events() != BPS_SUCCESS) {
    /* Failed to stop events */
}                    

Close the BPS library

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

You must call bps_shutdown() the same number of times that you called bps_initialize().

Channels

BPS uses channels to receive platform service events. Each BPS channel has an event queue associated with it. BPS restricts ownership of a channel to the thread that created the channel because access to the event queue is not thread-safe. In QNX Neutrino, a process owns a channel, and any thread from that process can access that channel.

When you use the  bps_initialize() function, a default channel is created that is set as active. You can use the  bps_channel_create() function to create a channel on behalf of the app. The new channel can receive events when it is active. Active channels are used when you want to work with events and file descriptors in your app. You call bps_channel_set_active() to set a channel as active and you call bps_channel_destroy() to destroy a channel you created using the bps_channel_create() function.

Related resources

Sample apps

 
 

Last modified: 2015-03-31



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

comments powered by Disqus