Update telepathy-spec to 0.17.21

1 files changed, 37 insertions, 156 deletions

diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml
index 6d9b24a18..ecf96f868 100644
--- a/spec/Connection_Interface_Presence.xml
+++ b/spec/Connection_Interface_Presence.xml
@@ -27,7 +27,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   <interface name="org.freedesktop.Telepathy.Connection.Interface.Presence">
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
 
-    <!-- We hope to simplify these eventually -->
     <tp:mapping name="Multiple_Status_Map">
       <tp:docstring>Mapping used in
         <tp:type>Last_Activity_And_Statuses</tp:type> and passed to
@@ -249,17 +248,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           map optional parameter names to their variant-boxed values
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Request that the user's presence be changed to the given statuses and
-        desired parameters. Changes will be reflected by
-        <tp:member-ref>PresenceUpdate</tp:member-ref>
-        signals being emitted. On certain protocols, this method may be
-        called on a newly-created connection which is still in the
-        DISCONNECTED state, and will sign on with the requested status.
-        If the requested status is not available after signing on,
-        NotAvailable will be returned and the connection will remain
-        offline, or if the protocol does not support signing on with
-        a certain status, Disconnected will be returned.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Request that the user's presence be changed to the given statuses
+          and desired parameters. Changes will be reflected by
+          <tp:member-ref>PresenceUpdate</tp:member-ref>
+          signals being emitted.</p>
+
+        <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+          is Offline, Error or Unknown MUST NOT be passed to this
+          function. Connection managers SHOULD reject these statuses.</p>
+
+        <tp:rationale>
+          <p>The same rationale as for <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref>
+            applies.</p>
+        </tp:rationale>
+
+        <p>On certain protocols, this method may be
+          called on a newly-created connection which is still in the
+          DISCONNECTED state, and will sign on with the requested status.
+          If the requested status is not available after signing on,
+          NotAvailable will be returned and the connection will remain
+          offline, or if the protocol does not support signing on with
+          a certain status, Disconnected will be returned.</p>
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -269,12 +280,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
       </tp:possible-errors>
     </method>
+
+    <tp:deprecated version="0.17.UNRELEASED">New client implementations
+      SHOULD use <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+      instead. New connection managers SHOULD implement both Presence
+      and SimplePresence.</tp:deprecated>
+
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>This interface will become deprecated in future versions. New
-        client implementations MAY use <tp:dbus-ref
-          namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
-        instead; new connection managers SHOULD implement both Presence and
-        SimplePresence.</p>
 
       <p>This interface is for services which have a concept of presence which
         can be published for yourself and monitored on your contacts.
@@ -287,28 +300,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     per connection, and a list of them can be obtained with the
     <tp:member-ref>GetStatuses</tp:member-ref> method.</p>
 
+    <p>(The SimplePresence interface which replaces this one restricts
+      presences to one status per contact, with an optional message, which is
+      in practice all that was implemented on this interface.)</p>
+
     <p>Each status has an arbitrary string identifier which should have an agreed
     meaning between the connection manager and any client which is expected to
-    make use of it. The following well-known values (in common with those in
-    Galago) should be used where possible to allow clients to identify common
-    choices:</p>
-
-    <ul>
-      <li>available (corresponding to Connection_Presence_Type_Available)</li>
-      <li>away (corresponding to Connection_Presence_Type_Away)</li>
-      <li>brb (Be Right Back) (corresponding to
-        Connection_Presence_Type_Away, but more specific)</li>
-      <li>busy (corresponding to Connection_Presence_Type_Busy)</li>
-      <li>dnd (Do Not Disturb) (corresponding to
-        Connection_Presence_Type_Busy, but more specific)</li>
-      <li>xa (Extended Away) (corresponding to
-        Connection_Presence_Type_Extended_Away)</li>
-      <li>hidden (aka Invisible) (corresponding to
-        Connection_Presence_Type_Hidden)</li>
-      <li>offline (corresponding to Connection_Presence_Type_Offline)</li>
-      <li>unknown (corresponding to Connection_Presence_Type_Unknown)</li>
-      <li>error (corresponding to Connection_Presence_Type_Error)</li>
-    </ul>
+    make use of it. The well-known values defined by the <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+      interface SHOULD be used where possible</p>
 
     <p>As well as these well-known status identifiers, every status also has a
     numerical type value chosen from
@@ -339,125 +339,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     intermittently to update any display of presence information.</p>
     </tp:docstring>
 
-    <tp:enum name="Connection_Presence_Type" type="u">
-      <tp:enumvalue suffix="Unset" value="0">
-        <tp:docstring>
-          An invalid presence type used as a null value. This value MUST NOT
-          appear in the result of <tp:member-ref>GetStatuses</tp:member-ref>,
-          or in the <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">Statuses</tp:dbus-ref>
-          property of the <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
-          interface.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Offline" value="1">
-        <tp:docstring>
-          Offline
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Available" value="2">
-        <tp:docstring>
-          Available
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Away" value="3">
-        <tp:docstring>
-          Away
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Extended_Away" value="4">
-        <tp:docstring>
-          Away for an extended time
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Hidden" value="5">
-        <tp:docstring>
-          Hidden (invisible)
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Busy" value="6">
-        <tp:added version="0.17.0"/>
-        <tp:docstring>
-          Busy, Do Not Disturb.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Unknown" value="7">
-        <tp:added version="0.17.8"/>
-        <tp:docstring>
-          Unknown, unable to determine presence for this contact, for example
-          if the protocol only allows presence of subscribed contacts.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Error" value="8">
-        <tp:added version="0.17.8"/>
-        <tp:docstring>
-          Error, an error occurred while trying to determine presence.  The
-          message, if set, is an error from the server.
-        </tp:docstring>
-      </tp:enumvalue>
-    </tp:enum>
-
-    <tp:enum name="Rich_Presence_Access_Control_Type" type="u">
-      <tp:docstring>
-        A type of access control for Rich_Presence_Access_Control.
-        For most types, the exact access control is given by an associated
-        variant.
-
-        <tp:rationale>
-          These are the access control types from XMPP publish/subscribe
-          (XEP-0060).
-        </tp:rationale>
-      </tp:docstring>
-
-      <tp:enumvalue suffix="Whitelist" value="0">
-        <tp:docstring>
-          The associated variant is a list of contacts (signature 'au',
-          Contact_Handle[]) who can see the extended presence information.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Publish_List" value="1">
-        <tp:docstring>
-          All contacts in the user's 'publish' contact list can see the
-          extended presence information. The associated variant is ignored.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Group" value="2">
-        <tp:docstring>
-          The associated variant is a handle of type Group (signature 'u',
-          Group_Handle) representing a group of contacts who can see the
-          extended presence information.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Open" value="3">
-        <tp:docstring>
-          Anyone with access to the service can see the extended presence
-          information.
-        </tp:docstring>
-      </tp:enumvalue>
-    </tp:enum>
-
-    <tp:struct name="Rich_Presence_Access_Control">
-      <tp:docstring>
-        An access control mode for extended presence items like geolocation.
-        This type isn't actually used by the core Presence interface, but
-        it's included here so it can be referenced by other specifications.
-      </tp:docstring>
-
-      <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type">
-        <tp:docstring>
-          The type of access control to apply.
-        </tp:docstring>
-      </tp:member>
-      <tp:member name="Detail" type="v">
-        <tp:docstring>
-          Any additional information required by the Type. The required
-          type and semantics are defined for each
-          Rich_Presence_Access_Control_Type.
-        </tp:docstring>
-      </tp:member>
-    </tp:struct>
-
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->