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.