2 title: Application Startup
7 At system runtime, it may be necessary for applications to start other
8 applications on demand. Such actions can be executed in reaction to a user
9 request, or they may be needed to perform a specific task.
11 In order to do so, running applications and services need an established way of
12 discovering installed applications and executing those.
14 In order to provide a language-independent interface for applications and
15 service to use, AGL includes `applaunchd`, a system service.
17 # Application launcher service
19 The purpose of `applaunchd` is to enumerate applications available on the
20 system and provide a way for other applications to query this list and start
21 those on demand. It is also able to notify clients of the startup and
22 termination of applications it manages.
24 To that effect, `applaunchd` provides a gRPC interface which other applications
25 can use in order to execute those actions.
27 *Note: `applaunchd` will only send notifications for applications it started;
28 it isn't aware of applications started by other means (`systemd`, direct
29 executable call...), and therefore can't send notifications for those.*
31 ## Application discovery
33 Applications are enumerated from systemd's list of available units based on the
34 pattern `agl-app*@*.service`, and are started and controled using their systemd
35 unit. Please note `applaunchd` allows only one instance of a given
38 ## Application identifiers
40 Each application is identified by a unique Application ID. Although this ID can
41 be any valid string, it is highly recommended to use the "reverse DNS"
42 convention in order to avoid potential name collisions.
46 The interface provides methods for the following actions:
48 - retrieve the list of available applications
49 - request an application to be started
50 - subscribe to status events
52 Moreover, with the gRPC the client subscribes to a status signal to be notified
53 when an application has successfully started or its execution terminated.
55 The gRPC protobuf file provides a Request and Response arguments to RPC methods
56 even though in some cases these might be empty in order to allow forward
57 compatibility in case additional fields are required.
58 It is a good standard practice to follow up with these recommendation when
59 developing a new protobuf specification.
63 The `ListApplications` method allows clients to retrieve the list of available
66 The `ListRequest` is an empty message, while `ListResponse` contains the following:
75 message ListResponse {
76 repeated AppInfo apps = 1;
80 ### Application startup request
82 Applications can be started by using the `StartApplication` method, passing the
83 `StartRequest` message, defined as:
86 message StartRequest {
91 In reply, the following `StartResponse` will be returned:
94 message StartResponse {
100 The "message" string of `StartResponse` message will contain an error message
101 in case we couldn't start the application for whatever reason, or if the "id"
102 isn't a known application ID. The "status" string would be boolean set to
103 boolean `TRUE` otherwise.
105 If the application is already running, `applaunchd` won't start another
106 instance, but instead reply with a `AppStatus` message setting the `status`
109 ### Status notifications
111 The gRPC interface provides clients with a subscription model to receive
112 status events. Client should subscribe to `GetStatusEvents` method to receive
115 The `StatusRequest` is empty, while the `StatusResponse` is defined as
124 message LauncherStatus {
127 message StatusResponse {
130 LauncherStatus launcher = 2;
135 As mentioned above, the `status` string is set to "started" and is also emitted
136 if `applaunchd` receives a request to start an already running application.
137 This can be useful, for example, when switching between graphical applications:
139 - the application switcher doesn't need to track the state of each application;
140 instead, it can simply send a `StartApplication` request to `applaunchd`
141 every time the user requests to switch to another application
142 - the shell client then receives the `StatusResponse` with the message `status`
143 string set to "started" indicating it that it should activate the window with
144 the corresponding `id` string