docs/06_Component_Documentation/Application_Framework/02_Application_Startup_Dbus.md

   1 ---
   2 title: Application Startup with D-Bus
   3 ---
   4
   5 *Note: The that the D-Bus interface is in deprecation phase and for the time
   6 being only available for application & services that still rely on them. Once
   7 we migrate everything to gRPC, we will remove D-Bus IPC support. Please see
   8 [Application Startup with gRPC](02_Application_Startup.md) for the latest
   9 information*
  10
  11 # Introduction
  12
  13 At system runtime, it may be necessary for applications to start other applications
  14 on demand. Such actions can be executed in reaction to a user request, or they may
  15 be needed to perform a specific task.
  16
  17 In order to do so, running applications and services need an established way of
  18 discovering installed applications and executing those. The
  19 [Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html)
  20 defines how applications can be discovered by using `.desktop` files, but there's no
  21 simple reference implementation for this function.
  22
  23 In order to provide a language-independent interface for applications and service to
  24 use, AGL includes `applaunchd`, a user service part of the default session.
  25
  26 *Note: as mentioned [previously](01_Introduction.md), services are managed using `systemd`
  27 and are therefore not in the scope of this document.*
  28
  29 # Application launcher service
  30
  31 The purpose of `applaunchd` is to enumerate applications available on the system and
  32 provide a way for other applications to query this list and start those on demand.
  33 It is also able to notify clients of the startup and termination of applications it
  34 manages.
  35
  36 To that effect, `applaunchd` provides a D-Bus interface other applications can use
  37 in order to execute those actions.
  38
  39 *Note: `applaunchd` will only send notifications for applications it started; it isn't
  40 aware of applications started by other means (`systemd`, direct executable call...),
  41 and therefore can't send notifications for those.*
  42
  43 ## Application discovery
  44
  45 On startup, `applaunchd` inspects all `.desktop` files present under the `applications/`
  46 subfolder of any element of the `XDG_DATA_DIRS` environment variable, ignoring all entries
  47 containing either the `NoDisplay=true` or `Hidden=true` lines.
  48
  49 It then looks for the following keys:
  50 - `Terminal`
  51 - `DBusActivatable`
  52
  53 If the desktop entry file contains the `Terminal` key set to `true`, then the application
  54 is marked as a non-graphical one. As such, it won't be included in the applications list
  55 if the client requests only graphical applications.
  56
  57 If `DBusActivatable` is set to `true`, then the application is marked as D-Bus activated.
  58 Additionally, `applaunchd` will search for a corresponding D-Bus service file in case this
  59 line is missing. This is a workaround allowing D-Bus activated applications providing
  60 an incomplete desktop entry file (i.e missing the `DBusActivatable` key) to be
  61 identified as such.
  62
  63 ### Requirements for D-Bus activation
  64
  65 `applaunchd` will always start D-Bus activatable applications using D-Bus activation
  66 instead of executing the command line stated in the desktop entry file.
  67
  68 This is handled by calling the `Activate` method of the
  69 [org.freedesktop.Application](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html)
  70 interface with an empty argument.
  71
  72 As a consequence, all D-Bus activatable applications **must** implement this D-Bus
  73 interface.
  74
  75 ## Application identifiers
  76
  77 Each application is identified by a unique Application ID. Although this ID can be
  78 any valid string, it is highly recommended to use the "reverse DNS" convention in order
  79 to avoid potential name collisions and ease D-Bus integration.
  80
  81 The application ID is set in the desktop entry file itself for
  82 [graphical applications](04_Creating_a_New_Application_Dbus.md#graphical-applications):
  83 it is the value of the `StartupWMClass` field, which must be identical to the `app-id`
  84 advertised through the Wayland XDG toplevel protocol. In case this field is missing
  85 (as is usually the case for non-graphical application), the application ID will be the
  86 desktop entry file name, stripped from its `.desktop` extension.
  87
  88 ## D-Bus interface
  89
  90 The `applaunchd` D-Bus interface is named `org.automotivelinux.AppLaunch`. The object
  91 path for `applaunchd` is `/org/automotivelinux/AppLaunch`. The interface provides methods
  92 for the following actions:
  93 - retrieve the list of available applications; the client can choose to retrieve all
  94   available applications, or only those suitable for a graphical environment
  95 - request an application to be started
  96
  97 Moreover, signals are available for clients to be notified when an application has
  98 successfully started or its execution terminated.
  99
 100 ### Applications list
 101
 102 The `listApplications` method allows clients to retrieve the list of available applications.
 103 It takes one boolean argument named `graphical`:
 104 - if set to `true`, only applications suitable for graphical environments are returned
 105 - otherwise, the list contains all applications
 106
 107 This method returns an array of variants (type `av`), each element being a structure made up
 108 of 3 strings (type `(sss)`):
 109 - the application ID
 110 - the application's displayed name
 111 - the full path to the application icon file (or an empty string if no icon was specified in
 112   the application's desktop entry file)
 113
 114 ### Application startup request
 115
 116 Applications can be started by using the `start` method, passing the corresponding application
 117 ID as the only argument. This method doesn't return any data.
 118
 119 If the application is already running, `applaunchd` won't start another instance, but instead
 120 emit a `started` signal to notify clients the application is ready.
 121
 122 ### Status notifications
 123
 124 The `org.automotivelinux.AppLaunch` interface provides 2 signals clients can connect to:
 125 - `started` indicates an application has started
 126     - for D-Bus activated applications, it is emitted upon successful completion of the
 127       call to the `Activate` method of the `org.freedesktop.Application` interface
 128     - for other applications, this signal is emitted as soon as the child process has been
 129       successfully created
 130 - `terminated` is emitted when an application quits
 131
 132 Both signals have an additional argument named `appid`, containing the ID of the application
 133 affected by the event.
 134
 135 As mentioned above, the `started` signal is also emitted if `applaunchd` receives a request to
 136 start an already running application. This can be useful, for example, when switching between
 137 graphical applications:
 138 - the application switcher doesn't need to track the state of each application; instead, it can
 139   simply send a `start` request to `applaunchd` every time the user requests to switch to another
 140   application
 141 - the desktop environment then receives the `started` signal, indicating it should activate the
 142   window with the corresponding `app-id`
 143
 144 ## Testing
 145
 146 `applaunchd` can be manually tested using the `gdbus` command-line tool:
 147
 148 1. Query the application list (graphical applications only):
 149
 150 ```
 151 $ gdbus call --session --dest "org.automotivelinux.AppLaunch" \
 152                        --object-path "/org/automotivelinux/AppLaunch" \
 153                        --method "org.automotivelinux.AppLaunch.listApplications" \
 154                        true
 155 ```
 156
 157 This command will output something similar to what follows:
 158
 159 ```
 160 ([<('navigation', 'Navigation', '/usr/share/icons/hicolor/scalable/navigation.svg')>,
 161  <('settings', 'Settings', '/usr/share/icons/hicolor/scalable/settings.svg')>,
 162  <('dashboard', 'Dashboard', '/usr/share/icons/hicolor/scalable/dashboard.svg')>,
 163  <('hvac', 'HVAC', '/usr/share/icons/hicolor/scalable/hvac.svg')>,
 164  <('org.freedesktop.weston.wayland-terminal', 'Weston Terminal', '/usr/share/icons/Adwaita/scalable/apps/utilities-terminal-symbolic.svg')>],)
 165 ```
 166
 167 2. Request startup of the `org.freedesktop.weston.wayland-terminal` application:
 168
 169 ```
 170 $ gdbus call --session --dest "org.automotivelinux.AppLaunch" \
 171                        --object-path "/org/automotivelinux/AppLaunch" \
 172                        --method "org.automotivelinux.AppLaunch.start" \
 173                        "org.freedesktop.weston.wayland-terminal"
 174 ```
 175
 176 3. Monitor signals emitted by `applaunchd`:
 177
 178 ```
 179 $ gdbus monitor --session --dest "org.automotivelinux.AppLaunch"
 180 ```
 181
 182 This results in the following output when starting, then exiting, the
 183 `org.freedesktop.weston.wayland-terminal` application:
 184
 185 ```
 186 Monitoring signals from all objects owned by org.automotivelinux.AppLaunch
 187 The name org.automotivelinux.AppLaunch is owned by :1.4
 188 /org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.started ('org.freedesktop.weston.wayland-terminal',)
 189 /org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.terminated ('org.freedesktop.weston.wayland-terminal',)
 190 ```