Application Services

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.

Implementation

Service Definition

A DBus service definition file must be installed for the Service.

[D-BUS Service]
Name=org.gnome.Rhythmbox
Exec=/usr/bin/rhythmbox-service

Desktop Entry

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

Service Behaviour

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.

Rewriting...

""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.

Startup Notification

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.