update spec to fit 0.15.5

20070926140503-7fe3f-1586e78fb9152a9b8ed8bc95070ed1b0638e2827.gz

9 files changed, 148 insertions, 33 deletions

diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
index 0e18241..7da8c77 100644
--- a/spec/Channel_Interface_Group.xml
+++ b/spec/Channel_Interface_Group.xml
@@ -373,6 +373,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
             requested handle.
         </tp:docstring>
       </tp:enumvalue>
+      <tp:enumvalue suffix="Separated" value="11">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>If members are removed with this reason code, the change is
+            because the group has split into unconnected parts which can only
+            communicate within themselves (e.g. netsplits on IRC use this
+            reason code).
+          </p>
+          <p>
+            If members are added with this reason code, the change is because
+            unconnected parts of the group have rejoined. If this channel
+            carries messages (e.g. Text or Tubes channels) applications must
+            assume that the contacts being added are likely to have missed some
+            messages as a result of the separation, and that the contacts
+            in the group are likely to have missed some messages from the
+            contacts being added.
+          </p>
+          <p>Note that from the added contacts' perspective, they have been
+            in the group all along, and the contacts we indicate to be in
+            the group (including the local user) have just rejoined
+            the group with reason Separated. Application protocols in Tubes
+            should be prepared to cope with this situation.
+          </p>
+        </tp:docstring>
+      </tp:enumvalue>
     </tp:enum>
     <signal name="MembersChanged">
       <arg name="message" type="s">
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 3a59de0..3e3f174 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -20,6 +20,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   </tp:license>
   <interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+    <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
     <method name="GetSessionHandlers">
       <arg direction="out" type="a(os)"/>
       <tp:docstring>
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index 8cfe071..7339439 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -20,6 +20,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   </tp:license>
   <interface name="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+    <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/>
     <tp:enum name="Media_Stream_Type" type="u">
       <tp:enumvalue suffix="Audio" value="0">
         <tp:docstring>An audio stream</tp:docstring>
@@ -283,7 +284,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     signals to indicate when streams have been added, removed and changed
     status.</p>
 
-    <p>In general this should always be used in conjunction with the IceSignalling
+      <p>Channels of this type are expected to provide the Group interface
+        and be "anonymous" (have no associated handle). To make a media call
+        to a contact, clients should request a new, empty streamed media
+        channel, then call AddMembers to add the contact to the channel.
+        The local user should be in the group's members, while the contact
+        should be in "remote pending" until the call is accepted, then
+        move to the group's members.</p>
+
+      <p>Similarly, incoming calls should be signalled as having handle type 0
+        and handle 0. The remote contact should be in the group's members,
+        with the local user in the "local pending" members; to accept the
+        call, AddMembers can be used to move the local user to the
+        group's members.</p>
+
+    <p>In general this should be used in conjunction with the MediaSignalling
     interface to exchange connection candidates and codec choices with
     whichever component is responsible for the streams. However, in certain
     applications where no candidate exchange is necessary (eg the streams are
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 9cb0376..db016a2 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -318,7 +318,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     </tp:property>
     <tp:property name="subject-contact" type="u" tp:type="Contact_Handle">
       <tp:docstring>
-      A contact handle representing who last modified the subject.
+      A contact handle representing who last modified the subject, or 0
+      if it isn't known.
       </tp:docstring>
     </tp:property>
     <tp:property name="subject-timestamp" type="u" tp:type="Timestamp">
@@ -347,6 +348,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <p>Sending messages can be requested using the Send method, which will return
       and cause the Sent signal to be emitted when the message has been delivered
       to the server, or SendError if there is a failure.</p>
+
+      <p>On protocols where additional contacts cannot be invited into
+        a one-to-one chat, or where a one-to-one chat is just a series of
+        individual personal messages rather than being represented by some
+        object on the server (i.e. most protocols), one-to-one chats should be
+        represented by a Text channel with handle type CONTACT.</p>
+
+      <p>Named chat rooms whose identity can be saved and used again later
+        (IRC channels, Jabber MUCs) are expected to be represented by Text
+        channels with handle type ROOM and the Group interface; they should
+        usually also have the Properties interface.</p>
+
+      <p>Unnamed, transient chat rooms defined only by their members (e.g. on
+        MSN) are expected to be represented by Text channels with handle type
+        0, handle 0, the Group interface, and optionally the Properties
+        interface.</p>
+
+      <p>On protocols where a conversation with a user is actually just
+        a nameless chat room starting with exactly two members, to which
+        more members can be invited, calling RequestChannel with type Text
+        and handle type CONTACT should continue to succeed, but may return
+        a channel with handle type 0, handle 0, the group interface,
+        and the local and remote contacts in its members.</p>
     </tp:docstring>
   </interface>
 </node>
diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index b66ae98..8591b6b 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -622,7 +622,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           The ID of the tube
         </tp:docstring>
       </arg>
-      <arg name="handle" type="u" tp:type="Contact_Handle">
+      <arg name="handle" type="u" tp_type="Contact_Handle">
         <tp:docstring>
           The handle of the participant who opened the new connection
         </tp:docstring>
diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
index bf36793..9997464 100644
--- a/spec/Connection_Interface_Avatars.xml
+++ b/spec/Connection_Interface_Avatars.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Connection_Interface_Avatars" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
-  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+  <tp:copyright>Copyright (C) 2005-2007 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
     <p>This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -82,17 +82,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </arg>
       <arg direction="out" type="q">
         <tp:docstring>
-          The maximum image width in pixels
+          The maximum image width in pixels, or 0 if there is no limit
         </tp:docstring>
       </arg>
       <arg direction="out" type="q">
         <tp:docstring>
-          The maximum image height in pixels
+          The maximum image height in pixels, or 0 if there is no limit
         </tp:docstring>
       </arg>
       <arg direction="out" type="u">
         <tp:docstring>
-          The maximum image size in bytes
+          The maximum image size in bytes, or 0 if there is no limit
         </tp:docstring>
       </arg>
       <tp:docstring>
@@ -118,6 +118,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </arg>
       <tp:docstring>
+        Get the unique tokens for all of the given contacts' avatars.
+
+        Using this method in new Telepathy clients is deprecated; use
+        GetKnownAvatarTokens instead.
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+      </tp:possible-errors>
+    </method>
+    <method name="GetKnownAvatarTokens">
+      <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
+        <tp:docstring>
+        An array of handles representing contacts
+        </tp:docstring>
+      </arg>
+      <arg direction="out" type="a{us}">
+        <tp:docstring>
+          A dictionary of handles mapped to avatar tokens, containing only
+          the known avatar tokens.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
         Get the unique tokens for the given contacts' avatars. These tokens
         can be persisted across connections, and should be used by the client
         to check whether the avatars have been updated. A empty token means
@@ -149,14 +175,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </arg>
       <tp:docstring>
-        Request the avatar for a given contact.
+        Request the avatar for a given contact. Using this method in new
+        Telepathy clients is deprecated; use RequestAvatars instead.
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
         <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            The contact does not currently have an avatar.
+          </tp:docstring>
+        </tp:error>
       </tp:possible-errors>
     </method>
     <method name="RequestAvatars">
@@ -168,9 +199,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </arg>
       <tp:docstring>
         Request avatars for a number of contacts. The AvatarRetrieved signal
-        is emitted for each avatar retrieved. If retrieving an avatar fails,
-        the AvatarRetrieved signal is not emitted.
+        is emitted for each avatar retrieved. If the handles are valid but
+        retrieving an avatar fails (for any reason, including the contact not
+        having an avatar) the AvatarRetrieved signal is not emitted for that
+        contact.
       </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+      </tp:possible-errors>
     </method>
     <method name="SetAvatar">
       <arg direction="in" name="avatar" type="ay">
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index c25f27b..815ec69 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -86,6 +86,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           <li>icq - ICQ</li>
           <li>irc - Internet Relay Chat</li>
           <li>jabber - Jabber (XMPP)</li>
+          <li>local-xmpp - Link-local XMPP (XEP-0174, Bonjour, Salut)</li>
           <li>msn - MSN Messenger</li>
           <li>napster - Napster</li>
           <li>silc - SILC</li>
diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml
index 7b6cc07..63b8e9b 100644
--- a/spec/Properties_Interface.xml
+++ b/spec/Properties_Interface.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" ?>
 <node name="/Properties_Interface" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright (C) 2005-2007 Collabora Limited </tp:copyright>
   <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
   <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
@@ -21,16 +21,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   <interface name="org.freedesktop.Telepathy.Properties">
     <method name="GetProperties">
       <tp:docstring>
-        Returns a dictionary of variants containing the current values of the
-        given properties.
+        Returns an array of (identifier, value) pairs containing the current
+        values of the given properties.
       </tp:docstring>
       <arg direction="in" name="properties" type="au">
         <tp:docstring>An array of property identifiers</tp:docstring>
       </arg>
       <arg direction="out" type="a(uv)">
-        <tp:docstring>An array of structs containing:
-          - integer identifiers
-          - variant boxed values
+        <!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>An array of structs containing:</p>
+          <ul>
+            <li>integer identifiers</li>
+            <li>variant boxed values</li>
+          </ul>
         </tp:docstring>
       </arg>
       <tp:possible-errors>
@@ -52,6 +56,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         Returns a dictionary of the properties available on this channel.
       </tp:docstring>
       <arg direction="out" type="a(ussu)">
+        <!-- XXX: if we're ever breaking API compatibility, make this
+        a{u(ssu)} ? -->
         <tp:docstring>
           An array of structs containing:
           <ul>
@@ -68,13 +74,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         Emitted when the value of readable properties has changed.
       </tp:docstring>
       <arg name="properties" type="a(uv)">
-      <tp:docstring>
-        An array of structs containing:
-        <ul>
-          <li>integer identifiers</li>
-          <li>variant boxed values</li>
-        </ul>
-      </tp:docstring>
+        <!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>An array of structs containing:</p>
+          <ul>
+            <li>integer identifiers</li>
+            <li>variant boxed values</li>
+          </ul>
+          <p>The array should contain only properties whose values have
+            actually changed.</p>
+        </tp:docstring>
       </arg>
     </signal>
     <signal name="PropertyFlagsChanged">
@@ -82,21 +91,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         Emitted when the flags of some room properties have changed.
       </tp:docstring>
       <arg name="properties" type="a(uu)">
-        <tp:docstring>
-          An array of structs containing:
+        <!-- XXX: if we're ever breaking API compatibility, make this a{uu} -->
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>An array of structs containing:</p>
           <ul>
             <li>integer identifiers</li>
             <li>a bitwise OR of the current flags</li>
           </ul>
+          <p>The array should contain only properties whose flags have actually
+            changed.</p>
         </tp:docstring>
       </arg>
     </signal>
     <method name="SetProperties">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Takes a dictionary of variants containing desired values to set the given
-        properties. In the case of any errors, no properties will be changed.
-        When the changes have been acknowledged by the server, the
-        PropertiesChanged signal will be emitted.</p>
+        <p>Takes an array of (identifier, value) pairs containing desired
+          values to set the given properties. In the case of any errors, no
+          properties will be changed. When the changes have been acknowledged
+          by the server, the PropertiesChanged signal will be emitted.</p>
 
         <p>All properties given must have the PROPERTY_FLAG_WRITE flag, or
         PermissionDenied will be returned. If any variants are of the wrong
@@ -105,6 +117,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:docstring>
 
       <arg direction="in" name="properties" type="a(uv)">
+        <!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
       <tp:docstring>
         A dictionary mapping integer identifiers to boxed values
       </tp:docstring>
diff --git a/spec/all.xml b/spec/all.xml
index cd57495..bbddd8d 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.15.4</tp:version>
+<tp:version>0.15.5</tp:version>
 
 <tp:copyright>Copyright (C) 2005, 2006, 2007 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright (C) 2005, 2006, 2007 Nokia Corporation</tp:copyright>