Update spec to 0.17.13

1 files changed, 123 insertions, 0 deletions

diff --git a/spec/Channel.xml b/spec/Channel.xml
index 545e84c75..f560ed8fb 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -274,6 +274,129 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:docstring>
     </method>
 
+    <property name="Requested" tp:name-for-bindings="Requested"
+      type="b" access="read">
+      <tp:added version="0.17.13">(as stable API)</tp:added>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>True if this channel was created in response to a local request,
+          such as a call to
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
+          or
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.</p>
+
+        <tp:rationale>
+          <p>The idea of this property is to distinguish between "incoming"
+            and "outgoing" channels, in a way that doesn't break down when
+            considering special cases like contact lists that are automatically
+            created on connection to the server, or chatrooms that an
+            IRC proxy/bouncer like irssi-proxy or bip was already in.</p>
+
+          <p>The reason we want to make that distinction is that UIs for
+            things that the user explicitly requested should start up
+            automatically, whereas for incoming messages and VoIP calls we
+            should first ask the user whether they want to open the messaging
+            UI or accept the call.</p>
+        </tp:rationale>
+
+        <p>If the channel was not explicitly requested (even if it was
+          created as a side-effect of a call to one of those functions,
+          e.g. because joining a Tube in a MUC context on XMPP implies
+          joining that MUC), then this property is false.</p>
+
+        <p>For compatibility with older connection managers, clients SHOULD
+          assume that this property is true if they see a channel announced
+          by the
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
+          signal with the suppress_handler parameter set to true.</p>
+
+        <tp:rationale>
+          <p>In a correct connection manager, the only way to get such a
+            channel is to request it.</p>
+        </tp:rationale>
+
+        <p>Clients MAY additionally assume that this property is false
+          if they see a channel announced by the NewChannel signal with the
+          suppress_handler parameter set to false.</p>
+
+        <tp:rationale>
+          <p>This is more controversial, since it's possible to get that
+            parameter set to false by requesting a channel. However, there's
+            no good reason to do so, and we've deprecated this practice.</p>
+
+          <p>In the particular case of the channel dispatcher, the only
+            side-effect of wrongly thinking a channel is unrequested
+            is likely to be that the user has to confirm that they want to
+            use it, so it seems fairly harmless to assume in the channel
+            dispatcher that channels with suppress_handler false are
+            indeed unrequested.</p>
+        </tp:rationale>
+      </tp:docstring>
+    </property>
+
+    <property name="InitiatorHandle" type="u" tp:type="Contact_Handle"
+      access="read" tp:name-for-bindings="Initiator_Handle">
+      <tp:added version="0.17.13">(as stable API)</tp:added>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The contact who initiated the channel. For channels requested by the
+          local user, this MUST be the value of
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref>
+          at the time the channel was created (i.e. not a channel-specific
+          handle).</p>
+
+        <tp:rationale>
+          <p>The careful wording about the self-handle is because the Renaming
+            interface can cause the return from Connection.GetSelfHandle to
+            change. It's something of a specification bug that we don't signal
+            this in the Connection interface yet.</p>
+        </tp:rationale>
+
+        <p>For channels requested by a remote user, this MUST be their handle.
+          If unavailable or not applicable, this MUST be 0 (for instance,
+          contact lists are not really initiated by anyone in particular, and
+          it's easy to imagine a protocol where chatroom invitations can be
+          anonymous).</p>
+
+        <p>For channels with the Group interface, this SHOULD be the same
+          contact who is signalled as the "Actor" causing the self-handle
+          to be placed in the local-pending set.</p>
+
+        <p>This SHOULD NOT be a channel-specific handle, if possible.</p>
+
+        <p>It does not make sense for this property to be in channel
+          requests - the initiator will always be the local user - so it
+          MUST NOT be accepted.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="InitiatorID" type="s" access="read"
+      tp:name-for-bindings="Initiator_ID">
+      <tp:added version="0.17.13">(as stable API)</tp:added>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The string that would result from inspecting the
+          <tp:member-ref>InitiatorHandle</tp:member-ref>
+          property (i.e. the initiator's identifier in the IM protocol).</p>
+
+        <tp:rationale>
+          <p>The presence of this property avoids the following race
+            condition:</p>
+
+          <ul>
+            <li>New StreamedMedia channel C is signalled with initiator
+              handle I</li>
+            <li>Client calls InspectHandles(CONTACT, [I])</li>
+            <li>Channel C closes, removing the last reference to handle I</li>
+            <li>InspectHandles(CONTACT, [I]) returns an error</li>
+            <li>Client can indicate that a call was missed, but not who
+              called!</li>
+          </ul>
+        </tp:rationale>
+
+        <p>It does not make sense for this property to be in channel
+          requests - the initiator will always be the local user - so it
+          MUST NOT be accepted.</p>
+      </tp:docstring>
+    </property>
+
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
     <p>All communication in the Telepathy framework is carried out via channel
     objects which are created and managed by connections. This interface must