A headless application runs in the background on the BlackBerry 10 OS. Unlike other applications with a UI and an associated Active Frame, a headless app is not under the direct control of a user.
There are two main types of headless apps:
- Short-running apps: These headless apps don't need to be running at all times, but instead they are typically triggered by some type of event and run for a limited amount of time. These apps might include push message or port-directed SMS message receivers, downloaders (for podcasts or magazine subscriptions), or coarse-grained location trackers.
- Long-running apps: These headless apps usually run for a long period of time to monitor the device for certain activity. These apps might include instant messaging clients, fine-grained location trackers, or activity loggers.
Both of these types of headless apps use triggers. A trigger is simply an event that prompts the headless app to start. This event might be a new SMS message, a change to the location of the device, or something else that you want your headless app to respond to. After a headless app is triggered, it can run as either a short-running app or a long-running app, depending on what tasks it needs to perform to handle the event. To learn more about triggers and which ones are available, see Triggers.
Enabling an app to run in the background is simple. Just create the two required parts of the app (UI part and headless part), modify the entry points of the app, request the user's permission, and use the invocation framework to enable the app to be triggered when a particular event occurs (for example, when some content is received). To learn how to create a headless app from start to finish, see Creating a headless app.
The following diagram provides an overview of the headless app process:
When an event (called the trigger source) occurs that you want your app to handle, the invocation framework handles the request and opens the headless part of your app. This part can then notify the user that the event occurred by using notifications, and the user can choose to open the UI part of the app to respond to the event.
Application life cycle
Headless apps can be stopped and started again based on resource availability. If the BlackBerry device is running low on system resources, such as battery power level or RAM, the headless app receives a stop message and is given time to save its state and prepare for exit.
When the device resources are running low, processes are stopped depending on their importance to the user. This perceived importance of the processes is calculated using the ranking provided in the table below. The critical processes are considered the most important and the stop processes are considered the least important to the user.
Processes that must run at all times (for example, system processes)
Processes that run in the foreground
Processes that run in the background
Processes that are loaded to RAM without running
By default, headless apps can occupy only 3 MB of memory. It's important to note that this limit applies only to the headless part of the app; the UI part can occupy more than 3 MB of memory, if necessary. This amount of memory should be sufficient for most headless apps because the headless part doesn't include UI elements, such as image assets.
The CPU that's allocated to a headless app is between 7% and 25% when running in the background. The important part to remember about CPU allocation is that the headless part of your app receives a limited amount of CPU time compared to a normal app. The headless part might receive as little as 7%, or as much as 25%, of the CPU. You should keep this range in mind as you develop the headless part of your app, and make sure that intensive operations or long-running calculations aren't performed in the headless part, if possible.
Performance and battery life optimization
Headless apps should run for as little time as possible to minimize the consumption of battery power and optimize BlackBerry device performance. For this reason, headless apps are time-constrained. By default, a short-running headless app runs for 20 seconds each time it's invoked (triggered). However, with extra system permissions (namely, the _sys_headless_nostop permission), a long-running headless app can run for a longer period of time (even indefinitely) when it's triggered.
To learn more about the permissions that a headless app requires, see Specify the appropriate permissions.
When a headless app needs to let the user know that a particular event has occurred, depending on the user settings, the app can send a notification to the user.
To provide a better user experience, headless apps can't bring their associated UIs to the foreground directly. Instead, headless apps use the notification service to do so. Note that the user can configure the notification settings for your app by using the Settings app on the device.
In addition to playing audible notifications and vibrating the device, a headless app can use the following types of notifications to bring something to the user's attention:
- Notifications in the BlackBerry Hub for events that do not require immediate attention.
- Instant previews for events that require immediate attention. The application should not be running in the foreground for it to be instantly previewed.
Both of these notification types provide an option to the user to bring the UI part of the app to the foreground. You must implement the logic in your code in such a way that, when it's triggered, your app sends a notification to the BlackBerry Hub or the Active Frame. These types of notifications might require additional permissions.
Communicating between the UI and headless parts
In many headless apps that you develop, you may need to send information from the UI part of the app to the headless part, as well as from the headless part to the UI part. You could send user input from your app's UI to the headless part, or you might need to send event information from the headless part to display in the UI. You can use interprocess communication (IPC) techniques to send this information.
You can use any IPC technique you want to communicate between the parts of your headless app; it's completely up to you. You should determine the communication needs of your app and choose a solution (or a combination of solutions) that makes the most sense for you. Here are a few approaches that you can consider to implement IPC in your headless app.
You can use the invocation framework to invoke the headless part of your app from the UI part. For example, you might provide an option in your UI to start monitoring for incoming messages. When a user selects this option, the UI part of the app starts the headless part, which does the work of monitoring for new messages.
If the UI and the headless parts of your app need to communicate directly in real time, you can connect them using local sockets, such as the one that's implemented in QTcpSocket. You can also take a look at the Socket API, which is included as part of the core APIs and might provide the functionality that you need.
Sockets can be useful as an IPC mechanism in cases where the UI part and headless part need to set up a data stream for connection-oriented data transfer. For example, you might use this type of approach for a Voice over Internet Protocol (VOIP) app. You can use both TCP and UDP sockets, depending on how much error control your app requires.
QSettings and file monitoring
In many cases, the UI part of a headless app lets a user control the behavior of the headless part by using persistent settings. For example, you might provide a UI option that controls how often the headless part checks for updated data on a server, or another option that determines what action to take when a new message is received.
To implement this type of communication, you can use a QSettings object, or a file in the file system, that's shared between the two parts. Each part monitors the shared object or file and is notified when any changes occur.
Debugging and profiling
You can debug and profile your headless app just like any other apps that you develop. You can use the debugging and profiling tools that are available in the Momentics IDE for BlackBerry, as well as other techniques such as qDebug() logging.
Closing a headless app
A user can close a headless app by navigating to Settings > App Manager > Device Monitor > Name of the application > CPU > Stop.
When you're designing your headless app, you should consider how (and when) you want to close the headless part of the app. Remember that, by default, the headless part of a short-running app runs for 20 seconds when it's invoked. This is usually plenty of time to perform whatever operations are needed, so you may want to stop the headless part before the 20 seconds have elapsed. The UI part of your app can query to determine whether the headless part is running, and it can send a signal to indicate that the headless part should close. The headless part can also terminate itself when it's finished all of its work. Conversely, if a user starts the UI part but the headless part isn't running, you may want to start the headless part automatically.
For long-running headless apps, you should carefully consider in what circumstances (if any) the headless part should close. By anticipating situations where the headless part doesn't need to be running, you can proactively terminate it and save battery power and CPU.
To explore different approaches to closing a headless app, see Sample applications.
To help you learn about the different types of headless apps and how you can create one effectively, you can take a look at a few sample apps. These sample apps are available in GitHub. For more sample apps, see the Sample apps page.
- PushCollector: A short-running headless app that shows you how to receive and process push messages
- XandOs and XandOsDroid: A long-running headless app that shows you how to implement IPC using invocation and local sockets between the headless part and UI part of the app
- HeadlessService and HeadlessServiceUI: A long-running headless app that shows you how to implement IPC using QSettings or file monitoring between the headless part and UI part of the app
If you want to learn how to create a simple headless app using a step-by-step approach, see Creating a headless app.
Last modified: 2013-10-30