X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2F06_Component_Documentation%2FApplication_Framework%2F02_Application_Startup_Dbus.md;fp=docs%2F06_Component_Documentation%2FApplication_Framework%2F02_Application_Startup_Dbus.md;h=0000000000000000000000000000000000000000;hb=04ae05c69a1ee2934b139b179d15ba112ff18ab6;hp=f951e0ed4b4dcc4fa0cc4b589c528965210e2927;hpb=ecccce4b62c048272dd48378cc05d7165746b83e;p=AGL%2Fdocumentation.git diff --git a/docs/06_Component_Documentation/Application_Framework/02_Application_Startup_Dbus.md b/docs/06_Component_Documentation/Application_Framework/02_Application_Startup_Dbus.md deleted file mode 100644 index f951e0e..0000000 --- a/docs/06_Component_Documentation/Application_Framework/02_Application_Startup_Dbus.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Application Startup with D-Bus ---- - -*Note: The that the D-Bus interface is in deprecation phase and for the time -being only available for application & services that still rely on them. Once -we migrate everything to gRPC, we will remove D-Bus IPC support. Please see -[Application Startup with gRPC](02_Application_Startup.md) for the latest -information* - -# Introduction - -At system runtime, it may be necessary for applications to start other applications -on demand. Such actions can be executed in reaction to a user request, or they may -be needed to perform a specific task. - -In order to do so, running applications and services need an established way of -discovering installed applications and executing those. The -[Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) -defines how applications can be discovered by using `.desktop` files, but there's no -simple reference implementation for this function. - -In order to provide a language-independent interface for applications and service to -use, AGL includes `applaunchd`, a user service part of the default session. - -*Note: as mentioned [previously](01_Introduction.md), services are managed using `systemd` -and are therefore not in the scope of this document.* - -# Application launcher service - -The purpose of `applaunchd` is to enumerate applications available on the system and -provide a way for other applications to query this list and start those on demand. -It is also able to notify clients of the startup and termination of applications it -manages. - -To that effect, `applaunchd` provides a D-Bus interface other applications can use -in order to execute those actions. - -*Note: `applaunchd` will only send notifications for applications it started; it isn't -aware of applications started by other means (`systemd`, direct executable call...), -and therefore can't send notifications for those.* - -## Application discovery - -On startup, `applaunchd` inspects all `.desktop` files present under the `applications/` -subfolder of any element of the `XDG_DATA_DIRS` environment variable, ignoring all entries -containing either the `NoDisplay=true` or `Hidden=true` lines. - -It then looks for the following keys: -- `Terminal` -- `DBusActivatable` - -If the desktop entry file contains the `Terminal` key set to `true`, then the application -is marked as a non-graphical one. As such, it won't be included in the applications list -if the client requests only graphical applications. - -If `DBusActivatable` is set to `true`, then the application is marked as D-Bus activated. -Additionally, `applaunchd` will search for a corresponding D-Bus service file in case this -line is missing. This is a workaround allowing D-Bus activated applications providing -an incomplete desktop entry file (i.e missing the `DBusActivatable` key) to be -identified as such. - -### Requirements for D-Bus activation - -`applaunchd` will always start D-Bus activatable applications using D-Bus activation -instead of executing the command line stated in the desktop entry file. - -This is handled by calling the `Activate` method of the -[org.freedesktop.Application](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html) -interface with an empty argument. - -As a consequence, all D-Bus activatable applications **must** implement this D-Bus -interface. - -## Application identifiers - -Each application is identified by a unique Application ID. Although this ID can be -any valid string, it is highly recommended to use the "reverse DNS" convention in order -to avoid potential name collisions and ease D-Bus integration. - -The application ID is set in the desktop entry file itself for -[graphical applications](04_Creating_a_New_Application_Dbus.md#graphical-applications): -it is the value of the `StartupWMClass` field, which must be identical to the `app-id` -advertised through the Wayland XDG toplevel protocol. In case this field is missing -(as is usually the case for non-graphical application), the application ID will be the -desktop entry file name, stripped from its `.desktop` extension. - -## D-Bus interface - -The `applaunchd` D-Bus interface is named `org.automotivelinux.AppLaunch`. The object -path for `applaunchd` is `/org/automotivelinux/AppLaunch`. The interface provides methods -for the following actions: -- retrieve the list of available applications; the client can choose to retrieve all - available applications, or only those suitable for a graphical environment -- request an application to be started - -Moreover, signals are available for clients to be notified when an application has -successfully started or its execution terminated. - -### Applications list - -The `listApplications` method allows clients to retrieve the list of available applications. -It takes one boolean argument named `graphical`: -- if set to `true`, only applications suitable for graphical environments are returned -- otherwise, the list contains all applications - -This method returns an array of variants (type `av`), each element being a structure made up -of 3 strings (type `(sss)`): -- the application ID -- the application's displayed name -- the full path to the application icon file (or an empty string if no icon was specified in - the application's desktop entry file) - -### Application startup request - -Applications can be started by using the `start` method, passing the corresponding application -ID as the only argument. This method doesn't return any data. - -If the application is already running, `applaunchd` won't start another instance, but instead -emit a `started` signal to notify clients the application is ready. - -### Status notifications - -The `org.automotivelinux.AppLaunch` interface provides 2 signals clients can connect to: -- `started` indicates an application has started - - for D-Bus activated applications, it is emitted upon successful completion of the - call to the `Activate` method of the `org.freedesktop.Application` interface - - for other applications, this signal is emitted as soon as the child process has been - successfully created -- `terminated` is emitted when an application quits - -Both signals have an additional argument named `appid`, containing the ID of the application -affected by the event. - -As mentioned above, the `started` signal is also emitted if `applaunchd` receives a request to -start an already running application. This can be useful, for example, when switching between -graphical applications: -- the application switcher doesn't need to track the state of each application; instead, it can - simply send a `start` request to `applaunchd` every time the user requests to switch to another - application -- the desktop environment then receives the `started` signal, indicating it should activate the - window with the corresponding `app-id` - -## Testing - -`applaunchd` can be manually tested using the `gdbus` command-line tool: - -1. Query the application list (graphical applications only): - -``` -$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ - --object-path "/org/automotivelinux/AppLaunch" \ - --method "org.automotivelinux.AppLaunch.listApplications" \ - true -``` - -This command will output something similar to what follows: - -``` -([<('navigation', 'Navigation', '/usr/share/icons/hicolor/scalable/navigation.svg')>, - <('settings', 'Settings', '/usr/share/icons/hicolor/scalable/settings.svg')>, - <('dashboard', 'Dashboard', '/usr/share/icons/hicolor/scalable/dashboard.svg')>, - <('hvac', 'HVAC', '/usr/share/icons/hicolor/scalable/hvac.svg')>, - <('org.freedesktop.weston.wayland-terminal', 'Weston Terminal', '/usr/share/icons/Adwaita/scalable/apps/utilities-terminal-symbolic.svg')>],) -``` - -2. Request startup of the `org.freedesktop.weston.wayland-terminal` application: - -``` -$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ - --object-path "/org/automotivelinux/AppLaunch" \ - --method "org.automotivelinux.AppLaunch.start" \ - "org.freedesktop.weston.wayland-terminal" -``` - -3. Monitor signals emitted by `applaunchd`: - -``` -$ gdbus monitor --session --dest "org.automotivelinux.AppLaunch" -``` - -This results in the following output when starting, then exiting, the -`org.freedesktop.weston.wayland-terminal` application: - -``` -Monitoring signals from all objects owned by org.automotivelinux.AppLaunch -The name org.automotivelinux.AppLaunch is owned by :1.4 -/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.started ('org.freedesktop.weston.wayland-terminal',) -/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.terminated ('org.freedesktop.weston.wayland-terminal',) -```