Launching and Controlling Applications

The QNX Web Browser supports a Persistent Publish/Subscribe (PPS) interface that allows the main HMI process (or another privileged process) to launch and control HTML5 applications. To use this interface, the HMI creates a PPS object and then issues PPS messages to open, close, or manage applications, or to terminate the browser.

Overview

To connect the QNX Web Browser to the application launch-and-control interface, use the --qnx-application-manager-pps-object=pps_object_path command-line option. The browser will then listen for commands that the HMI sends to the PPS object specified in the pps_object_path argument. The commands can be in either native PPS format or JSON object format.

The QNX Web Browser uses the shared application process model when you specify the --qnx-application-manager-pps-object option. See “Application process models” for details.

Note: To learn how to create PPS objects, see the Persistent Publish/Subscribe Developer's Guide.

Command format

To send application launch-and-control commands to the PPS object, the HMI issues messages in either JSON object format or native PPS format. Every message contains an action command and other attributes.

Here is the message syntax in JSON format:

{
    "action":"action_command",
    "id":"app_id",
    "url":"app_location",
    "size":"WxH",
    "position":"XxY",
    "display":"display_id",
    "headless":"Boolean"
}

Here is the message syntax in PPS format:

action::action_command\nid::app_id\nurl::app_location\nsize::WxH\n
position::XxY\ndisplay::display_id\nheadless::Boolean

The action attribute is always required. It can contain one of the following commands:

Action	Description
`open`	Create a new window for the application and launch the application. When specifying this action, always include the `id` and `url` attributes. Otherwise, command_shell ignores the action.
`close`	Close the application identified by `id`.
`hide`	Hide the application identified by `id`. The `hide` action is equivalent to sending the application to the background. It minimizes CPU and memory usage, blocks touch events, and stops application rendering.
`show`	Show the application identified by `id`. The `show` action is equivalent to sending the application to the foreground. If the application was running in the background because of a `hide` action, the `show` action causes the application to resume processing.
`setbounds`	Set the size and position of the window for the application identified by `id`. This action requires the `size` and `position` attributes.
`loadurl`	Tell the application identified by `id` to load the URL specified by `url`.
`terminate`	Terminate the Browser, GPU, and Zygote processes that manage the running applications. When you specify this action, all running applications close. The action doesn't require the `id` attribute, as it applies to the Browser process, not to a specific application.

Messages can also contain the following attributes:

Attribute	Data type	Description	Used with
`id`	String	A name that identifies the application. All action commands, except `terminate`, require this attribute. The specified name appears in the `id string` property of the window created by the application. Since the shared application process model supports multiple renderer processes, the name also appears in the renderer process name when you run a “pidin a” command. (See the QNX Neutrino RTOS Utilities Reference for information on pidin.)	All actions, except `terminate`
`url`	String	The location of the application; either a web URL or a path to local content.	`open` `loadurl`
`size`	String	Set the size of the application window to the specified width and height, in pixels. The default is the size of the screen.	`open` `setbounds`
`position`	String	Set the position of the application window to the specified X and Y coordinates. The default is `0x0`.	`open` `setbounds`
`display_id`	Integer	Open the application in the specified physical display. This attribute specifies the ID of a display section defined in the graphics.conf file. It is useful for systems that support multiple HDMI displays. See the discussion on configuring Screen in the Screen Graphics Subsystem Developer's Guide for more information.	`open`
`headless`	Boolean	Run headless, without a toolbar or address bar. We recommend that you set this to `true` when using the QNX Web Browser to run applications. The default is `false`.	`open`

Security considerations

If you're running the QNX Web Browser in a production system, the browser and the system's HMI process should, for security reasons, be the only processes allowed to write to the PPS object.

Testing

You can test the application management feature by creating a PPS object and sending PPS messages to it. For instance, if you create the object under the /pps/services/qtcar/appcontrol/ directory, you could open a terminal console and issue a message like the following:

echo "action::open\nid::browser\nurl::http://www.qnx.com\nsize::1280x760" > 
    /pps/services/qtcar/appcontrol

This command launches the QNX Web Browser, sets the application ID to browser, opens a window to the QNX home page, and sets the window size to 1280x760.