[Telepathy-commits] [telepathy-gabble/master] Add Requests interface in extensions/, and update Channel.FUTURE to the -requestotron branch
Simon McVittie
simon.mcvittie at collabora.co.uk
Tue Aug 19 10:53:54 PDT 2008
20080722161535-53eee-8225109792ca1d908ccfbee42d5446ff32eb9d32.gz
---
extensions/Channel_Future.xml | 98 +++++++++++++++++++++++++++++++++++++---
extensions/all.xml | 5 ++
2 files changed, 95 insertions(+), 8 deletions(-)
diff --git a/extensions/Channel_Future.xml b/extensions/Channel_Future.xml
index 09d116f..75aa8e1 100644
--- a/extensions/Channel_Future.xml
+++ b/extensions/Channel_Future.xml
@@ -42,17 +42,97 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:rationale>
</tp:docstring>
+ <property name="Requested" type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if this channel was created in response to 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.DRAFT.RequestChannels</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, but was created as a
+ side-effect of a call to one of those functions (e.g. joining a
+ Tube in a MUC context on XMPP implies joining that MUC), this
+ property is still true.</p>
+
+ <p>Otherwise, 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="TargetID" type="s" access="read">
<tp:added version="0.17.7">(in Channel.FUTURE
pseudo-interface)</tp:added>
- <tp:docstring>
- The string that would result from inspecting the TargetHandle
- property (i.e. the identifier in the IM protocol of the contact,
- room, etc. with which this channel communicates).
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The string that would result from inspecting the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ property (i.e. the identifier in the IM protocol of the contact,
+ room, etc. with which this channel communicates), or the empty
+ string if the TargetHandle is 0.</p>
<tp:rationale>
See InitiatorID; the rationale is the same.
</tp:rationale>
+
+ <p>If this is present in a channel request,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ MUST NOT be Handle_Type_None, and TargetHandle MUST NOT be
+ present. The request MUST fail with error InvalidHandle, without
+ side-effects, if the requested TargetID would not be accepted by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.</p>
+
+ <p>The returned channel must be related to the handle corresponding
+ to the given identifier, in the same way as if TargetHandle
+ had been part of the request instead.</p>
+
+ <tp:rationale>
+ <p>Requesting channels with a string identifier saves a round-trip
+ (the call to RequestHandles). It also allows the channel
+ dispatcher to accept a channel request for an account that is not
+ yet connected (and thus has no valid handles), bring the account
+ online, and pass on the same parameters to the new connection's
+ RequestChannels method.</p>
+ </tp:rationale>
</tp:docstring>
</property>
@@ -85,8 +165,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>This SHOULD NOT be a channel-specific handle, if possible.</p>
- <p>It does not make sense for this property to be passed to the
- RequestChannels method on Channel.Interface.Requests.</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>
@@ -112,8 +193,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</ul>
</tp:rationale>
- <p>It does not make sense for this property to be passed to the
- RequestChannels method on Channel.Interface.Requests.</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>
diff --git a/extensions/all.xml b/extensions/all.xml
index 4404e07..f4eab7f 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -23,12 +23,17 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
</tp:license>
<xi:include href="Channel_Future.xml"/>
+<xi:include href="Connection_Interface_Requests.xml"/>
<xi:include href="OLPC_Buddy_Info.xml"/>
<xi:include href="OLPC_Activity_Properties.xml"/>
<tp:generic-types>
<tp:external-type name="Contact_Handle" type="u"
from="Telepathy specification"/>
+ <tp:external-type name="DBus_Qualified_Member" type="s"
+ from="Telepathy specification"/>
+ <tp:external-type name="Qualified_Property_Value_Map" type="a{sv}"
+ from="Telepathy specification"/>
</tp:generic-types>
</tp:spec>
--
1.5.6.3
More information about the Telepathy-commits
mailing list