/pps/services/launcher/control

Publishers: Launcher service; Homescreen
Subscribers: Launcher service; Homescreen

Note: This object is a server object, designed to process requests from individual clients and deliver the results to the clients that issued the requests. For more information, see the "Server objects" subsection.

Overview

The launcher service (Application Launcher) provides this control object so clients can issue commands to start and stop applications based on their IDs. In the QNX Apps and Media image, the Homescreen uses this object to launch applications. If you write your own window manager, it can use this object.

Message/response format

Commands sent to the /pps/services/launcher/control object have the following form:

msg::command_string\ndat::application_ID[,display_parameters]\nid::ID_number

Here, command_string contains the name of the command and application_ID contains the name of the app when it's loaded. The app names are found in the /apps directory. The display_parameters string is used only with the start command for launching applications; details on this command and other supported commands are given in "Commands". The ID_number can be a number or any other identifier meaningful to the client.

Responses always reflect the command_string and ID_number that were sent in the command message:

res::command_string\ndat::process_ID,process_name\nid::ID_number

The launcher service stores the process ID (PID) and name in the dat attribute. The PID must be saved by the client so it can later refer to the same application. For instance, when the user selects to stop the app in the HMI, the client must pass the PID in the stop command.

Because this is a server object, to observe its status, you must force the shell to keep the file descriptor open. In the following example, we use the exec command to do this, then direct the response messages to stderr. To start apps through PPS in the QNX Apps and Media image, you must slay the HMI and issue commands to the launcher control object. In this case, we start an application called Peaks And Valleys. The service writes the PID of the new process into the dat attribute in its response. You can use this PID to pause or stop the app.

# slay -13 homescreen
# exec 3<> /pps/services/launcher/control
# echo "msg::start\ndat::PeaksAndValleys.testDev_sAndValleys6bb91d91,
        ORIENTATION=0,WIDTH=900,HEIGHT=480\nid::1234" >&3
# cat <&3
@control
res::start
id::1234
dat::1589296,dev_mode
# echo "msg::stop\ndat::1589296\nid::1234" >&3; cat <&3
@control
res::stop
id::1234

Commands

The control object accepts these commands:

start: Launches an application based on the application ID.
stop: Stops an application from running.
freeze: Pauses an application. The application appears frozen on the screen.
thaw: Unpauses an application.

The format for these commands is as follows:

msg::	dat::	id::
start	ID of the application to launch, followed by a list of display parameters. The ID string is based on the app's directory name found in /apps. For the display parameters, you can list the orientation, height, and width of the app display area. Individual parameters are separated by commas and each one is specified by listing its name, followed by an equal sign (`=`) and the value. You can set these parameters: ORIENTATION — 0 for landscape mode, 1 for portrait mode WIDTH — Width of the app display area, in pixels HEIGHT — Height of the app display area, in pixels Note: We strongly recommend setting the WIDTH and HEIGHT parameters. Although the launcher service still launches the app (using the full screen to display it) if these parameters are not provided, the full-screen display might not be optimal for viewing the app. In the reference Apps and Media images, the Homescreen application sets these parameters in the start command, which it sends when the user launches an app in the HMI.	Number (or any other identifier meaningful to the clients involved)
stop	PID of the application to close. This must be the PID returned in the dat attribute of the start response.	Number (or any other identifier meaningful to the clients involved)
freeze	PID of the application to pause.	Number (or any other identifier meaningful to the clients involved)
thaw	PID of the paused application to resume running.	Number (or any other identifier meaningful to the clients involved)

Examples

To launch the Settings application, write the following to the /pps/services/launcher/control object:

echo "msg::start\ndat::Settings.testRel_Settings___595d2043,
        ORIENTATION=0,WIDTH=900,HEIGHT=480\nid::1"
        > /pps/services/launcher/control

The service then writes this type of response (containing the PID) to the object:

res::start\ndat::2015282\nid::1

You must pass the PID in the stop command to close this application:

echo "msg::stop\ndat::2015282\nid::1" > /pps/services/launcher/control

If you don't specify the PID, Application Launcher stops all active applications when you issue the following stop command:

echo "msg::stop\ndat::\nid::" > /pps/services/launcher/control

Note: In the default QNX Apps and Media image, only one application can be active at a time. If you modify the HMI to allow for multiple applications to be active at the same time but want to affect only one application, you must specify the PID when sending the stop, freeze, or thaw command.