Upgrade to spec 0.17.16 and generate code for Messages

1 files changed, 94 insertions, 24 deletions

diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
index 76b85f3be..6bd0f36ef 100644
--- a/spec/Connection_Interface_Avatars.xml
+++ b/spec/Connection_Interface_Avatars.xml
@@ -21,11 +21,60 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   <interface name="org.freedesktop.Telepathy.Connection.Interface.Avatars">
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
 
+    <tp:simple-type name="Avatar_Token" type="s">
+      <tp:changed version="0.17.16">strengthened uniqueness requirements
+        so (CM name, protocol, token) is unique; previously only
+        (our Account, remote contact identifier, token) was required to be
+        unique</tp:changed>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>An opaque token chosen by the connection manager, representing
+          a particular avatar.</p>
+
+        <tp:rationale>
+          <p>Because avatars can be relatively large images, most protocols
+            provide a way to detect whether an old avatar is still valid,
+            or whether an avatar has changed, without pushing the actual
+            avatar data to all clients.</p>
+        </tp:rationale>
+
+        <p>The connection manager MUST choose these tokens in a way that
+          makes it highly unlikely that two different avatars with the same
+          connection manager and protocol will have the same token.</p>
+
+        <tp:rationale>
+          <p>This means that clients MAY use the triple
+            (<tp:type>Connection_Manager_Name</tp:type>,
+            <tp:type>Protocol</tp:type>, avatar token) as a key for
+            their avatar cache. For instance, an avatar for a
+            telepathy-gabble Jabber contact might be stored in a file
+            .../gabble/jabber/4e199b4a1c40b497a95fcd1cd896351733849949.png.</p>
+        </tp:rationale>
+
+        <p>For instance, some protocols (like XMPP) identify avatars by a
+          hash of the avatar data; in this case, the hash can be used as the
+          avatar token.</p>
+
+        <p>Some protocols identify avatars by the timestamp of the last
+          change to the avatar; in these protocols it would be necessary for
+          the connection manager to encode both the timestamp and the
+          contact's identifier into the avatar token in order to ensure
+          uniqueness.</p>
+
+        <p>This token SHOULD be kept short and reasonably suitable for use
+          in a filename, but MAY contain any UTF-8 character (so clients using
+          avatar tokens in filenames MUST be prepared to escape characters
+          that are not valid in filenames). Connection managers for protocols
+          where tokens would otherwise become inconveniently large or contain
+          many unsuitable characters SHOULD hash the identifying data to
+          generate the token.</p>
+      </tp:docstring>
+    </tp:simple-type>
+
     <tp:mapping name="Avatar_Token_Map">
       <tp:docstring>A dictionary whose keys are contact handles and whose
         values are avatar tokens.</tp:docstring>
       <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
-      <tp:member type="s" name="Token"/>
+      <tp:member type="s" tp:type="Avatar_Token" name="Token"/>
     </tp:mapping>
 
     <signal name="AvatarUpdated" tp:name-for-bindings="Avatar_Updated">
@@ -34,7 +83,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           An integer handle for the contact whose avatar has changed
         </tp:docstring>
       </arg>
-      <arg name="New_Avatar_Token" type="s">
+      <arg name="New_Avatar_Token" tp:type="Avatar_Token" type="s">
         <tp:docstring>
           Unique token for their new avatar
         </tp:docstring>
@@ -43,16 +92,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         Emitted when the avatar for a contact has been updated, or first
         discovered on this connection. If the token differs from the token
         associated with the client's cached avatar for this contact, the new
-        avatar should be requested with RequestAvatars.
+        avatar should be requested with
+        <tp:member-ref>RequestAvatars</tp:member-ref>.
       </tp:docstring>
     </signal>
+
     <signal name="AvatarRetrieved" tp:name-for-bindings="Avatar_Retrieved">
       <arg name="Contact" type="u" tp:type="Contact_Handle">
         <tp:docstring>
           The contact whose avatar has been retrieved
         </tp:docstring>
       </arg>
-      <arg name="Token" type="s">
+      <arg name="Token" tp:type="Avatar_Token" type="s">
         <tp:docstring>
           The token corresponding to the avatar
         </tp:docstring>
@@ -72,6 +123,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         Emitted when the avatar for a contact has been retrieved.
       </tp:docstring>
     </signal>
+
     <method name="GetAvatarRequirements"
       tp:name-for-bindings="Get_Avatar_Requirements">
       <arg direction="out" type="as">
@@ -114,13 +166,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
       </tp:possible-errors>
     </method>
+
     <method name="GetAvatarTokens" tp:name-for-bindings="Get_Avatar_Tokens">
       <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="as">
+      <arg direction="out" type="as" name="Tokens" tp:type="Avatar_Token[]">
         <tp:docstring>
           An array of avatar tokens or empty strings (if no avatar is set) in the
           same order as the given array of contact handles
@@ -130,7 +183,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         Get the unique tokens for all of the given contacts' avatars.
 
         Using this method in new Telepathy clients is deprecated; use
-        GetKnownAvatarTokens instead.
+        <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> instead.
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -140,6 +193,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
       </tp:possible-errors>
     </method>
+
     <method name="GetKnownAvatarTokens"
       tp:name-for-bindings="Get_Known_Avatar_Tokens">
       <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
@@ -147,7 +201,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         An array of handles representing contacts
         </tp:docstring>
       </arg>
-      <arg direction="out" type="a{us}" tp:type="Avatar_Token_Map">
+      <arg direction="out" type="a{us}" name="Tokens" tp:type="Avatar_Token_Map">
         <tp:docstring>
           A dictionary of handles mapped to avatar tokens, containing only
           the known avatar tokens.
@@ -172,6 +226,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
       </tp:possible-errors>
     </method>
+
     <method name="RequestAvatar" tp:name-for-bindings="Request_Avatar">
       <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
         <tp:docstring>
@@ -205,6 +260,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:error>
       </tp:possible-errors>
     </method>
+
     <method name="RequestAvatars" tp:name-for-bindings="Request_Avatars">
       <arg direction="in" name="Contacts" type="au"
         tp:type="Contact_Handle[]">
@@ -213,17 +269,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </arg>
       <tp:docstring>
-        Request avatars for a number of contacts. The AvatarRetrieved signal
-        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.
+        Request avatars for a number of contacts. The
+        <tp:member-ref>AvatarRetrieved</tp:member-ref> signal 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" tp:name-for-bindings="Set_Avatar">
       <arg direction="in" name="Avatar" type="ay">
         <tp:docstring>
@@ -235,14 +292,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           A string representing the image MIME type
         </tp:docstring>
       </arg>
-      <arg direction="out" type="s">
+      <arg direction="out" type="s" name="Token" tp:type="Avatar_Token">
         <tp:docstring>
           The string token of the new avatar
         </tp:docstring>
       </arg>
       <tp:docstring>
         Set a new avatar image for this connection. The avatar image must
-        respect the requirements obtained by GetAvatarRequirements.
+        respect the requirements obtained by
+        <tp:member-ref>GetAvatarRequirements</tp:member-ref>.
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -252,6 +310,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
       </tp:possible-errors>
     </method>
+
     <method name="ClearAvatar" tp:name-for-bindings="Clear_Avatar">
       <tp:added version="0.15.0" />
       <tp:docstring>
@@ -262,32 +321,42 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
       </tp:possible-errors>
     </method>
+
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>An interface for requesting avatars for contacts on a given connection,
     receiving notification when avatars are changed, and publishing your own
     avatar.</p>
 
-    <p>Avatars are identified by a unique (per contact) token which represents a
-    hash or timestamp (depending on the protocol) of the contacts' avatar data.
+    <p>Avatars are identified by a string, the <tp:type>Avatar_Token</tp:type>,
+    which represents a particular avatar. Tokens MUST be chosen by the
+    connection manager in such a way that the triple
+    (<tp:type>Connection_Manager_Name</tp:type>, <tp:type>Protocol</tp:type>,
+    <tp:type>Avatar_Token</tp:type>) uniquely identifies an avatar.
     An empty token means that an avatar has not been set for this contact, and
     a changed token implies the contact's avatar has changed, but the strings
     should otherwise be considered opaque by clients.</p>
 
-    <p>A client should use GetKnownAvatarTokens to request the tokens for the
+    <p>A client should use <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>
+    to request the tokens for the
     avatars of all the contacts it is interested in when it connects. The
-    avatars can then be requested using RequestAvatars for the contacts.
-    Clients should bind to the AvatarChanged signal and request a new copy of
+    avatars can then be requested using
+    <tp:member-ref>RequestAvatars</tp:member-ref> for the contacts.  Clients
+    should bind to the <tp:member-ref>AvatarUpdated</tp:member-ref> signal and
+    request a new copy of
     the avatar when a contacts' avatar token changes. Clients should cache the
     token and data of each contact's avatar between connections, to avoid
     repeatedly retrieving the same avatar.</p>
 
-    <p>To publish an avatar, a client should use SetAvatar to provide an image
-    which meets the requirements returned by the GetAvatarRequirements
+    <p>To publish an avatar, a client should use
+    <tp:member-ref>SetAvatar</tp:member-ref> to provide an image which meets
+    the requirements returned by the
+    <tp:member-ref>GetAvatarRequirements</tp:member-ref>
     function. On some protocols the avatar is stored on the server, so setting
     the avatar is persistent, but on others it is transferred via a peer to
     peer mechanism, so needs to be set every connection. Hence, on every
     connection, clients should inspect the avatar token of the connection's
-    self handle using GetKnownAvatarTokens; if the self handle is not in the
+    self handle using <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>; if
+    the self handle is not in the
     returned map, the client should re-set the avatar. If the self handle's
     avatar token is known, but the avatar has been changed locally since the
     last connection, the client should upload the new avatar; if the avatar has
@@ -295,8 +364,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     server if its token differs from the that of the local avatar.</p>
 
     <p>To remove the published avatar on protocols which have persistent avatars,
-    a client should use the ClearAvatar method. This method can safely be used
-    even if there is no avatar for this connection.</p>
+    a client should use the <tp:member-ref>ClearAvatar</tp:member-ref> method.
+    This method can safely be used even if there is no avatar for this
+    connection.</p>
     </tp:docstring>
   </interface>
 </node>