An "Application" is a set of tools that a user might use to accomplish some task.
An "Application Service" is a process that provides a set of "Applications" to the user.
Two examples of Applications are Epiphany Web Bookmarks and Epiphany Web Browser. These Applications are provided by the Epiphany Application Service.
A few more examples of Applications are Evolution Mail, Evolution Calendar, Evolution Tasks, etc. All of these Applications are provided by the Evolution Application Service.
In most cases, however, a Service only provides one Application.
A DBus service definition file must be installed for the Service.
[D-BUS Service] Name=org.gnome.Rhythmbox Exec=/usr/bin/rhythmbox-service
X-GNOME-Application-Service=org.gnome.Rhythmbox X-GNOME-Application-Path=/org/gnome/Rhythmbox X-GNOME-Application-FileHandler-FileActions=Play;Queue;Import [X-GNOME-Application-FileHandler-FileAction Play] Name=Play in Rhythmbox Description=Play immediately in Rhythmbox MimeType=audio/ogg;etc. MultipleFiles=false [X-GNOME-Application-FileHandler-FileAction Queue] Name=Queue Up in Rhythmbox Description=Add to the Rhythmbox playback queue MimeType=audio/ogg;etc. MultipleFiles=true [X-GNOME-Application-FileHandler-FileAction Import] Name=Import to Rhythmbox Description=Import to a Rhythmbox Library MimeType=audio/ogg;etc. MultipleFiles=true
The Service registers the chosen bus name on startup and creates objects that correspond to Applications. These objects implement the org.gnome.Application interface.
The org.gnome.Application interface includes two methods: Launch and InvokeFileAction.
Launch is used for generically launching the application, typically from a launcher or from the CLI.
The way an application handles a Launch is dependent on the type of application being launched. For example, GNOME Terminal will spawn a new terminal (either a window or a tab, based on the application configuration). In contrast, Rhythmbox will simply present its window when asked to Launch.
InvokeFileAction is used for acting on a file, which is generally represented by a URI. Two arguments are passed to this function: an "action name" and a string URI. The action names are registered in the Desktop Entry corresponding to the Application.
""THE FOLLOWING INFORMATION IS OUTDATED, IT IS JUST HERE BECAUSE I HAVEN'T FINISHED THIS PAGE!""
Example Python source code: my-singleton-app .* This script requires head version of the D-Bus Python bindings in order for the service bus name request to honour the "queue" argument. It will work without it, but if you launch it twice, the second instance will block until the first quits. One can open a URI with an application by using these methods directly with D-Bus, or by invoking:
dbus-send \ --dest=com.weej.alex.MySingletonApp \ --type=method_call \ /com/weej/alex/MySingletonApp/Application \ org.gnome.Application.OpenURI string:'file:///some/path/to/resource'
I have hacked up a prototype launch script in Python to make it (slightly) simpler to invoke OpenURI, and also demonstrate how to do it from other D-Bus-using applications: gnome-app-launch
gnome-app-launch \ com.weej.alex.MySingletonApp \ /com/weej/alex/MySingletonApp/Application \ file:///some/path/to/resource
Of course, if you need to run your application from a console for whatever reason (debugging, etc.), you can simply close/kill the service if it is already running, and run it without D-Bus service activation.
For the sake of preserving sanity on the CLI, you could move the service binary to -service and keep the old name for a simple dbus file-open call. For example "gedit-service" for the service executable (which can be started either with D-Bus Service Activation or otherwise), and keep "gedit uri://whatever/whatever" for opening files. In such a case, behaviour is consistent in that "gedit" always returns instantly, though "gedit-service" persists.
This can probably be achieved by simply waiting for the DBus method call to return. At which point, the application should have finished starting up.