From 4f734282a18a1e29b095b2c04220214af9d5bd46 Mon Sep 17 00:00:00 2001
From: Ryan Lortie <desrt@desrt.ca>
Date: Mon, 6 Jan 2014 00:29:30 -0500
Subject: desktop entry spec: Add support for Implements=

https://bugs.freedesktop.org/show_bug.cgi?id=73317
---
 desktop-entry/desktop-entry-spec.xml | 60 ++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

(limited to 'desktop-entry')

diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
index d3879f2..0bdb83a 100644
--- a/desktop-entry/desktop-entry-spec.xml
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -601,6 +601,17 @@
 	    <entry>NO</entry>
             <entry>1</entry>
 	  </row>
+          <row>
+            <entry id="key-implements"><varname>Implements</varname></entry>
+            <entry>
+              A list of interfaces that this application implements.  By default, a desktop file implements no
+              interfaces.  See <link linkend="interfaces">Interfaces</link> for more information on how this
+              works.
+            </entry>
+            <entry>string(s)</entry>
+            <entry>NO</entry>
+            <entry></entry>
+          </row>
           <row>
             <entry id="key-keywords"><varname>Keywords</varname></entry>
             <entry>
@@ -908,6 +919,55 @@
       Specification</ulink>.
     </para>
   </sect1>
+  <sect1 id="interfaces">
+    <title>Interfaces</title>
+    <para>
+      The <varname>Implements</varname> key can be used to declare one or more interfaces that a desktop file
+      implements.
+    </para>
+    <para>
+      Each interface name must follow the rules used for D-Bus interface names, but other than that, they have
+      no particular meaning.  For instance, listing an interface here does not necessarily mean that this
+      application implements that D-Bus interface or even that such a D-Bus interface exists.  It is entirely up
+      to the entity who defined a particular interface to define what it means to implement it.
+    </para>
+    <para>
+      Although it is entirely up to the designer of the interface to decide what a given interface name means,
+      here are some recommended "best practices":
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          interfaces should require that application is DBusActivatable, including the requirement that the
+          application's desktop file is named using the D-Bus "reverse DNS" convention
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          the interface name should correspond to a D-Bus interface that the application exports on the same
+          object path as it exports the org.freedesktop.Application interface
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          if the interface wishes to allow for details about the implementation, it should do so by specifying
+          that implementers add a group in their desktop file with the same name as the interface (eg:
+          "[org.freedesktop.ImageAcquire]")
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      Recommendations notwithstanding, interfaces could specify almost any imaginable requirement including such
+      (ridiculous) things as "when launched via the Exec line, the application is expected to present a window
+      with the _FOO_IDENTIFIER property set, at which point an X client message will be sent to that window".
+      Another example is "all implementations of this interface are expected to be marked NoDisplay and, on
+      launch, will present no windows and will delete all of the user's files without confirmation".
+    </para>
+    <para>
+      Interface definers should take care to keep issues of backward and forward compatibility in mind when
+      designing their interfaces.
+    </para>
+  </sect1>
   <sect1 id="mime-types">
     <title>Registering MIME Types</title>
     <para>
-- 
cgit v1.2.3-70-g09d2