From 8065095d01be756e072581e0d0f7e0d03046a8ce Mon Sep 17 00:00:00 2001
From: Ryan Lortie <desrt@desrt.ca>
Date: Mon, 29 Apr 2013 17:17:42 -0700
Subject: [PATCH] desktop-entry: add DBusActivatable

Add a DBusActivatable key along with the recommendation that desktop
files be named like "org.example.FooViewer.desktop".
---
 desktop-entry/desktop-entry-spec.xml | 101 ++++++++++++++++++++++++++++++++---
 1 file changed, 93 insertions(+), 8 deletions(-)

diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
index 7d99d0a..ce270c5 100644
--- a/desktop-entry/desktop-entry-spec.xml
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -52,6 +52,15 @@
 	  </address>
 	</affiliation>
       </author>
+      <author>
+        <firstname>Ryan</firstname>
+        <surname>Lortie</surname>
+        <affiliation>
+          <address>
+            <email>desrt@desrt.ca</email>
+          </address>
+        </affiliation>
+      </author>
     </authorgroup>
   </articleinfo>
 
@@ -79,6 +88,10 @@
       fall back to recognition via "magic detection".
     </para>
     <para>
+      For applications, the part of the name of the desktop file (before the <filename>.desktop</filename>)
+      should follow the "reverse DNS" convention, e.g. <literal>org.example.FooViewer.desktop</literal>.
+    </para>
+    <para>
       Desktop entry files are encoded in UTF-8. A file is interpreted as a
       series of lines that are separated by linefeed characters. Case is
       significant everywhere in the file.
@@ -467,6 +480,20 @@
 	    <entry>NO</entry>
             <entry>1-3</entry>
 	  </row>
+          <row>
+            <entry id="key-dbusactivatable"><varname>DBusActivatable</varname></entry>
+            <entry>
+              A boolean value specifying if D-Bus activation is supported for this application.  If this key is
+              missing, the default value is <literal>false</literal>.  If the value is <literal>true</literal>
+              then implementations should ignore the <varname>Exec</varname> key and send a D-Bus message to
+              launch the application.  See <link linkend="dbus">D-Bus Activation</link> for more information on
+              how this works.  Applications should still include Exec= lines in their desktop files for
+              compatibility with implementations that do not understand the DBusActivatable key.
+            </entry>
+            <entry>boolean</entry>
+            <entry>NO</entry>
+            <entry></entry>
+          </row>
 	  <row>
 	    <entry id="key-tryexec"><varname>TryExec</varname></entry>
 	    <entry>
@@ -483,12 +510,15 @@
 	  <row>
 	    <entry id="key-exec"><varname>Exec</varname></entry>
 	    <entry>
-           Program to execute, possibly with arguments. See the <link
-           linkend="exec-variables"><varname>Exec</varname> key</link> for
-           details on how this key works.
+              Program to execute, possibly with arguments. See the
+              <link linkend="exec-variables"><varname>Exec</varname> key</link> for details on how this key
+              works.  The <varname>Exec</varname> key is required if <varname>DBusActivatable</varname> is not
+              set to <literal>true</literal>.  Even if <varname>DBusActivatable</varname> is
+              <literal>true</literal>, <varname>Exec</varname> should be specified for compatibility with
+              implementations that do not understand <varname>DBusActivatable</varname>.
 	    </entry>
 	    <entry>string</entry>
-	    <entry>YES</entry>
+	    <entry>NO</entry>
             <entry>1</entry>
 	  </row>
 	  <row>
@@ -798,6 +828,57 @@
       %U field codes may only be used as an argument on their own.
     </para>
   </sect1>
+  <sect1 id="dbus">
+    <title>D-Bus Activation</title>
+    <para>
+      Applications that support being launched by D-Bus must implement the following interface (given in D-Bus
+      introspection XML format):
+    </para>
+    <programlisting>
+<![CDATA[  <interface name='org.freedesktop.Application'>
+    <method name='Activate'>
+      <arg type='a{sv}' name='platform_data' direction='in'/>
+    </method>
+    <method name='Open'>
+      <arg type='as' name='uris' direction='in'/>
+      <arg type='a{sv}' name='platform_data' direction='in'/>
+    </method>
+    <method name='ActivateAction'>
+      <arg type='s' name='action_name' direction='in'/>
+      <arg type='av' name='parameter' direction='in'/>
+      <arg type='a{sv}' name='platform_data' direction='in'/>
+    </method>
+  </interface>]]>
+    </programlisting>
+    <para>
+      The application must name its desktop file in accordance with the naming recommendations in the
+      introduction section (e.g. the filename must be like <literal>org.example.FooViewer.desktop</literal>).
+      The application must have a D-Bus service activatable at the well-known name that is equal to the desktop
+      file name with the <filename>.desktop</filename> portion removed (for our example,
+      <literal>org.example.FooViewer</literal>).  The above interface must be implemented at an object path
+      determined as follows: starting with the well-known D-Bus name of the application, change all dots to
+      slashes and prefix a slash.  For our example, this is <literal>/org/example/FooViewer</literal>.
+    </para>
+    <para>
+      The <literal>Activate</literal> method is called when the application is started without files to open.
+    </para>
+    <para>
+      The <literal>Open</literal> method is called when the application is started with files.  The array of
+      strings is an array of URIs, in UTF-8.
+    </para>
+    <para>
+      The <literal>ActivateAction</literal> method is called when <link linkend="extra-actions">Desktop
+      Actions</link> are activated.  The <literal>action-name</literal> parameter is the name of the action.
+    </para>
+    <para>
+      All methods take a <literal>platform-data</literal> argument that is used in a similar way to how
+      environment variables might be used.  Currently, only one field is defined by the specification:
+      <varname>desktop-startup-id</varname>.  This should be a string of the same value as would be stored in
+      the <varname>DESKTOP_STARTUP_ID</varname> environment variable, as specified by the <ulink
+      url="http://www.freedesktop.org/Standards/startup-notification-spec">Startup Notification Protocol
+      Specification</ulink>.
+    </para>
+  </sect1>
   <sect1 id="mime-types">
     <title>Registering MIME Types</title>
     <para>
@@ -963,12 +1044,16 @@ application/x-bar=bar.desktop;</programlisting>
             <row>
               <entry id="key-action-group-exec"><varname>Exec</varname></entry>
               <entry>
-                Program to execute for this action, possibly with arguments.
-                See the <link linkend="exec-variables"><varname>Exec</varname>
-                key</link> for details on how this key works.
+                Program to execute for this action, possibly with arguments.  See the
+                <link linkend="exec-variables"><varname>Exec</varname> key</link> for details on how this key
+                works.  The <varname>Exec</varname> key is required if <varname>DBusActivatable</varname> is not
+                set to <literal>true</literal> in the main desktop entry group.  Even if
+                <varname>DBusActivatable</varname> is <literal>true</literal>, <varname>Exec</varname> should be
+                specified for compatibility with implementations that do not understand
+                <varname>DBusActivatable</varname>.
               </entry>
               <entry>string</entry>
-              <entry>YES</entry>
+              <entry>NO</entry>
             </row>
           </tbody>
         </tgroup>
-- 
1.8.3.1