BlackBerry Platform Services

The BlackBerry Platform Services (BPS) library provides an application with a single consistent interface to a number of different platform services:

BlackBerry Platform Services for C/C++ Developers

The BlackBerry Platform Services (BPS) library provides an application with a single consistent interface to a number of different platform services:

• Accelerometer

• Audio Devices

• Audio Mixer

• Clock

• Device Information

• Dialogs

• Events

• Geolocation

• LED

• Locale

• Multimedia Renderer

• Navigator

• Network Status

• Orientation

• Payment Services

• Screen

• Sensor

• Sound Player

• Virtual Keyboard

BPS provides a functional interface to platform services, along with an event-retrieval mechanism for asynchronous notification.

Requesting and Listening for Events

The BPS library provides a high-level view of various platform services. Each client application simply make one request to the platform services that it wants to receive events for. A loop is set up to listen for the events and the client application determines how to handle the event using custom application logic.

Events are then generated and processed, and the application can interact with the platform service as necessary.

Using an Event Queue

// 1. Start the library
bps_initialize();

// 2. Request events to flow into the event queue
virtualkeyboard_request_events(0);
orientation_request_events(0);
navigator_request_events(0);

// 3. Use any service at any time
virtualkeyboard_show(); // Show the virtual keyboard

// 4. Listen for events
for (;;) {
    // get an event
    bps_event_t *event;
    bps_get_event(&event, -1); // blocking

    // handle it
    handle_event(&event);
}

bps_shutdown();

Events

Different platform services generate different events. Events are differentiated by the event domain (the service that generated the event) and the 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 the bps_event_get_domain() function to determine the service (event domain) that generated a particular event. The event code can be determined with the bps_event_get_code() function. Normally, an event handler uses the event domain and event code to determine what the event is. Once the event is known, it can be handled properly. For example, individual accessor functions can be used to extract the payload data appropriate to the event.

For example:

    if (bps_event_get_domain(event) == virtualkeyboard_get_domain()) {
        uint16_t code = bps_event_get_code(event);
        if (code == VIRTUALKEYBOARD_EVENT_VISIBLE) {
            // Keyboard is now visible. Handle event...
        } else if (code == 
        } else if (code == VIRTUALKEYBOARD_EVENT_INFO) {
            // Extract the keyboard height
            int height = virtualkeyboard_event_get_height(event)
            // Handle...
        }
    }

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

Service Functions

Many services provide functions that a client can invoke. These functions are documented individually with each service. The BPS library provides simple functions to invoke these service functions.

For example:

    // show the keyboard
    virtualkeyboard_show();

BlackBerry Platform Services Channels

The BlackBerry Platform Services (BPS) uses channels to receive platform service events. BPS channels have 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. This differs from channels created directly in QNX Neutrino, where a channel is owned by a process and therefore, channels can be accessed by any thread owned by the process.

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 new channel on behalf of the application. The new channel can receive events once it is active. Active channels are used when you want to work with events and file descriptors in your application. You use the bps_channel_set_active() to set a channel as active and bps_channel_destroy() to destroy a channel you created using the bps_channel_create() function.