[Telepathy-commits] [telepathy-spec/master] Client: remove HandledChannelClasses in favour of putting it in the Observer etc. namespace. Explain .client files and client discovery

[Simon McVittie]

20080624145645-53eee-f62d75203e66d23051d433be50d84335aa76f793.gz
---
 spec/Client.xml |   63 +++++++++++++++++++++++++++++++++++++-----------------
 1 files changed, 43 insertions(+), 20 deletions(-)

diff --git a/spec/Client.xml b/spec/Client.xml
index 72a5df4..5be5ced 100644
--- a/spec/Client.xml
+++ b/spec/Client.xml
@@ -21,6 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
   </tp:license>
   <interface name="org.freedesktop.Telepathy.Client.DRAFT"
     tp:causes-havoc="experimental">
+
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>Telepathy clients use connection managers, the channel dispatcher
         and optionally the account manager to provide useful
@@ -31,33 +32,55 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         address-book synchronization.</p>
 
       <p>Every running or activatable process with a well-known
-        name of the form org.freedesktop.Telepathy.Client.something should be
-        probed by the channel dispatcher to discover its capabilities. Each
-        client is either an <em>observer</em>, an <em>approver</em>, a
-        <em>channel handler</em>, or some combination of these.</p>
+        name of the form org.freedesktop.Telepathy.Client.<em>clientname</em>
+        should be probed by the channel dispatcher to discover its
+        capabilities. Each client is either an <em>observer</em>, an
+        <em>approver</em>, a <em>channel handler</em>, or some combination
+        of these.</p>
+
+      <p>The client name, <em>clientname</em>, MUST be a non-empty string of
+        ASCII digits, letters and/or underscores, starting with a letter.</p>
+
+      <p>Each Client MUST export an object whose object path may be
+        determined by replacing '.' with '/' in the well-known name and
+        prepending '/'. This object represents its API as a Telepathy
+        client; the channel dispatcher will call its methods and read
+        its properties when appropriate.</p>
+
+      <p>As an optimization, clients MAY install a file
+        <a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">$XDG_DATA_DIRS</a>/telepathy/clients/<em>clientname</em>.client
+        containing a cached version of its immutable properties,
+        so that for most clients, the channel dispatcher can
+        just read a file to discover capabilities, instead of
+        having to service-activate the client immediately in order to fetch
+        its read-only properties. However, the D-Bus API is canonical, and
+        the channel dispatcher MUST support clients without such a file.</p>
+
+      <p>The .client files MUST contain UTF-8 text with the same syntax
+        as
+        <a href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
+          Entry files</a> (although the allowed groups, keys and values differ).
+        Every .client file MUST contain a group whose name is the name
+        of this interface.</p>
 
-      <p>As an optimization, we intend to introduce a .client file (similar to
-        .manager files) so that for most clients, the channel dispatcher can
-        just read a file instead of service-activating the client straight
-        away.</p>
+      <p>The groups, keys and values in the .client file are defined by
+        individual interfaces.</p>
     </tp:docstring>
 
     <property name="Interfaces" type="as" access="read"
       tp:type="DBus_Interface[]">
-      <tp:docstring>
-        A list of the extra interfaces provided by this client.
-        This SHOULD include at least one of Client.Approver,
-        Client.Observer or Client.ChannelHandler.
-      </tp:docstring>
-    </property>
-
-    <property name="HandledChannelClasses" access="read" type="a(su)">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      </tp:docstring>
+        <p>A list of the extra interfaces provided by this client.
+          This SHOULD include at least one of ...Client.Approver,
+          ...Client.Observer or ...Client.ChannelHandler.</p>
 
-      <!-- FIXME: invent and document a tp:type when it's clearer what we
-      need. This is conjectured to be an array of (channel type, handle type)
-      for now, hence a(su) -->
+        <p>In the .client file, this is represented by key "interfaces"
+          in the group named after this interface. The value of the key
+          is a list of interface names each followed by a semicolon (so
+          it always ends with a semicolon unless it is empty), i.e. a key
+          of type "strings" as described in the Desktop Entry
+          specification.</p>
+      </tp:docstring>
     </property>
 
   </interface>
-- 
1.5.6.5