[Telepathy-commits] [telepathy-salut/master] Update Requests spec draft to that from 0.17.9
Will Thompson
will.thompson at collabora.co.uk
Thu Oct 23 07:30:34 PDT 2008
---
extensions/Connection_Interface_Requests.xml | 90 +++++++++++++------------
1 files changed, 47 insertions(+), 43 deletions(-)
diff --git a/extensions/Connection_Interface_Requests.xml b/extensions/Connection_Interface_Requests.xml
index b2ac381..ea1eeeb 100644
--- a/extensions/Connection_Interface_Requests.xml
+++ b/extensions/Connection_Interface_Requests.xml
@@ -24,7 +24,7 @@
<interface name="org.freedesktop.Telepathy.Connection.Interface.Requests.DRAFT"
tp:causes-havoc="experimental">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
- <tp:added version="0.17.UNRELEASED"/>
+ <tp:added version="0.17.9"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An enhanced version of the Telepathy connection interface, which can
@@ -78,10 +78,12 @@
<p>Each dictionary MUST contain the keys
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>,
- <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>
- and <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>.
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>,
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>
+ and
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref>.
</p>
- <!-- FIXME: maybe also TargetID, Requested, InitiatorHandle,
+ <!-- FIXME: maybe also Requested, InitiatorHandle,
InitiatorID once they leave the FUTURE pseudo-interface -->
<tp:rationale>
@@ -144,7 +146,7 @@
<arg name="Channel" direction="out" type="o">
<tp:docstring>
- The Channel object, which SHOULD already have been signalled with
+ The Channel object, which MUST already have been signalled with
<tp:member-ref>NewChannels</tp:member-ref> by the time this method
returns.
</tp:docstring>
@@ -220,7 +222,9 @@
<arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
<tp:docstring>
The channels and their details. All channels that are signalled
- together like this MUST have the same Bundle property, which may
+ together like this MUST have the same
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
+ property, which may
either refer to an existing bundle, or establish a new bundle.
</tp:docstring>
</arg>
@@ -317,57 +321,57 @@
<tp:member name="Fixed_Properties" type="a{sv}"
tp:type="Channel_Class">
- <tp:docstring>
- The property values that identify this requestable channel class.
- These properties MUST be included in requests for a channel of this
- class, and MUST take these values.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The property values that identify this requestable channel class.
+ These properties MUST be included in requests for a channel of this
+ class, and MUST take these values.</p>
+
+ <p>Clients that do not understand the semantics of all the
+ Fixed_Properties MUST NOT request channels of this class, since
+ they would be unable to avoid making an incorrect request.</p>
+
+ <p>This implies that connection managers wishing to make channels
+ available to old or minimal clients SHOULD have a channel class
+ with the minimum number of Fixed_Properties, and MAY additionally
+ have channel classes with extra Fixed_Properties.</p>
</tp:docstring>
</tp:member>
- <tp:member name="Required_Properties" type="as"
+ <tp:member name="Allowed_Properties" type="as"
tp:type="DBus_Qualified_Member[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Properties that MUST be set when requesting a channel of this
+ <p>Properties that MAY be set when requesting a channel of this
channel type and handle type.</p>
- <p>Properties MAY have additional requirement semantics not
- represented in this array. For instance, if TargetHandleType
- takes a value that is not Handle_Type_None, one or the other of
- TargetHandle and TargetID is required. In this case,
- TargetHandle and TargetID would both be listed as optional:
- clients are expected to understand the documented relationship
- between the properties.</p>
+ <p>This array MUST NOT include properties that are in the
+ Fixed_Properties mapping.</p>
- <p>Clients that do not understand the semantics of all the
- Fixed_Properties, and all the properties in this list, MUST NOT
- request channels of this class (unless they are intended as
- debugging/development tools to be operated only by users who
- understand the Telepathy D-Bus API).</p>
- </tp:docstring>
- </tp:member>
+ <p>Properties in this array may either be required or optional,
+ according to their documented semantics.</p>
- <tp:member name="Optional_Properties" type="as"
- tp:type="DBus_Qualified_Member[]">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Properties that MAY be set when requesting a
- channel of this channel type and handle type.</p>
-
- <p>Properties mentioned in Fixed_Properties or Required_Properties
- SHOULD NOT appear in this array.</p>
-
- <p>If this array contains the Channel.Bundle property, then this
- class of channel can be combined with other channels with that
- property in a request, or added to an existing bundle. If not,
- this signifies that the connection manager is unable to mark
- channels of this class as part of a bundle - this means that
- to the remote contact they are likely to be indistinguishable
- from channels requested separately.</p>
+ <tp:rationale>
+ <p>For instance, if
+ TargetHandleType takes a value that is not Handle_Type_None,
+ one or the other of TargetHandle and TargetID is required.
+ Clients are expected to understand the documented relationship
+ between the properties, so we do not have separate arrays
+ of required and optional properties.</p>
+ </tp:rationale>
+
+ <p>If this array contains the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
+ property, then this class of channel can be combined with other
+ channels with that property in a request, or added to an existing
+ bundle. If not, this signifies that the connection manager is
+ unable to mark channels of this class as part of a bundle - this
+ means that to the remote contact they are likely to be
+ indistinguishable from channels requested separately.</p>
</tp:docstring>
</tp:member>
</tp:struct>
<property name="RequestableChannelClasses" access="read"
- type="a(a{sv}asas)" tp:type="Requestable_Channel_Class[]">
+ type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The classes of channel that are expected to be available on this
connection, i.e. those for which
--
1.5.6.5
More information about the Telepathy-commits
mailing list