This document might be useful for the D-Bus side: https://dbus.freedesktop.org/doc/dbus-api-design.html
On Mon, 18 Jun 2018 at 17:05:25 +0200, Roman Gilg wrote: > In certain high levels the compositor will ask the client through a > special D-Bus interface to restore its internal state. This interface > must be made available by the client on the address specified by the > desktop_id argument. A D-Bus "address" isn't what you think it is. I think you mean a *well-known bus name*, for example "org.gnome.Builder". Note that GNOME Builder's desktop ID is "org.gnome.Builder.desktop" but its D-Bus well-known name is "org.gnome.Builder", and any other DBusActivatable application will follow the same pattern (it's part of the Desktop Entry Specification). Be clear about which one you mean. Strictly speaking, you should also specify that this is a name on the *well-known session bus* (or "session bus" for short). I would recommend having a canonical XML description (somewhere) for the D-Bus side of this interface, similar to the one in the text of https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus > The special interface name for the D-Bus call is > zxdg_session_suspension_v1 That isn't a valid D-Bus interface name. D-Bus interface names look something like "com.example.SessionSuspension1". The equivalent of Wayland's xdg_ is org.freedesktop. If you are proposing names in that namespace you should mention them on the [email protected] list, although I think it'd be OK to say "please send feedback to the Wayland list". To call a D-Bus method, you also need an object path. There are two reasonable object paths for a singleton object related to the Desktop Entry Specification's DBusActivatable protocol: either reuse the object path corresponding to the desktop ID (for example /org/gnome/Builder), or use an object path corresponding to your interface name (for example /org/freedesktop/SessionSuspension1). If you use the object path corresponding to the desktop ID, then it will be very awkward to implement this protocol without involving the implementation of DBusActivatable (for instance GApplication/GtkApplication in GNOME), but the GApplication/GtkApplication or equivalent is probably the right place to implement this protocol anyway, so either could work. (The reason why object paths and interfaces are separate is that in a more complex design, there might be many implementations of the same interface in a process, for instance media players that provide one object per file/track/stream at different object paths, each of them implementing org.gnome.UPnP.MediaItem2. If interfaces are like abstract base classes, then object paths are like pointers.) Do you intend the D-Bus side of the protocol to be equally useful to X11 apps, or is this a Wayland-only thing? > and the method being called by the > compositor on this interface is simply called 'restore' D-Bus method names are conventionally in camel-case, so 'Restore'. When we discussed this on #gnome-hackers we were talking about doing restoration by passing the restored session ID as platform_data to the Activate method defined by https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus which would mean that for trivial/stateless apps, it would be enough to ignore it and just start up, which DBusActivatable implementations like GtkApplication will already do. Is there a reason why you've opted to define a new method instead? > compositor will issue on the next Wayland server launch the D-Bus > command: > > org.foo.bar /zxdg_session_suspension_v1 restore(1234) D-Bus has no concept of a "command". The jargon term you're looking for is a *method call*, which is one of several types of *message*. If you want a pseudocode notation, you might want something like this: a D-Bus method call to a destination given by the desktop_id, with object path /org/freedesktop/SessionSuspension1, interface org.freedesktop.SessionSuspension1, method name Restore, and the client_id as a uint32 parameter, similar to the result of this dbus-send(1) command line: dbus-send --type=method_call --destination=org.gnome.Builder \ /org/freedesktop/SessionSuspension1 \ org.freedesktop.SessionSuspension1.Restore \ uint32:1234 (Of course, compositors or session managers should normally implement this in-process instead of by running dbus-send(1).) > <arg name="desktop_id" type="string" allow-null="true" > summary="desktop file id to restore the client via d-bus"/> Does this include .desktop or not? GNOME Builder's desktop ID is "org.gnome.Builder.desktop" but its D-Bus well-known name is "org.gnome.Builder", and any other DBusActivatable application will follow the same pattern (it's part of the Desktop Entry Specification). > The quit state ends when the compositor sends the D-Bus signal to > restart the client. D-Bus method call, please. A D-Bus signal is a different jargon term (they're two different types of message, and a method call is the one you want when activating a service, because it has error-handling). _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
