[Telepathy-commits] [telepathy-glib/master] Update Requests spec plus EnsureChannel to that from a spec branch
Will Thompson
will.thompson at collabora.co.uk
Wed Sep 24 03:56:08 PDT 2008
(rather than using a placeholder spec for EnsureChannel)
---
spec/Connection_Interface_Requests.xml | 170 ++++++++++++++++++--------------
1 files changed, 96 insertions(+), 74 deletions(-)
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index a969976..c409dca 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -201,11 +201,11 @@
time</li>
<li>a channel matching the request has already been requested
(by a previous call to CreateChannel,
+ <tp:member-ref>EnsureChannel</tp:member-ref>,
<tp:dbus-ref
namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
- or some future channel-requesting method)
- and the protocol requires that only one such channel can exist
- at a time</li>
+ or similar) and the protocol requires that only one such
+ channel can exist at a time</li>
</ul>
</tp:docstring>
</tp:error>
@@ -215,85 +215,51 @@
</tp:possible-errors>
</method>
- <signal name="NewChannels" tp:name-for-bindings="New_Channels">
- <tp:added version="0.17.11">(as stable API)</tp:added>
-
+ <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>New channels have been created. The connection manager SHOULD emit
- a single signal for any group of closely related channels that are
- created at the same time, so that the channel dispatcher can try to
- dispatch them to a handler as a unit.</p>
-
- <p>In particular, if additional channels are created as a side-effect
- of a call to <tp:member-ref>CreateChannel</tp:member-ref>,
- these channels SHOULD appear in the same NewChannels signal as
- the channel that satisfies the request.</p>
+ <p>Request that channels are ensured to exist.</p>
<tp:rationale>
- <p>Joining a MUC Tube in XMPP requires joining the corresponding
- MUC (chatroom), so a Text channel can be created as a
- side-effect.</p>
+ <p>The connection manager is in the best position to determine which
+ existing channels could satisfy which requests.</p>
</tp:rationale>
- </tp:docstring>
- <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
- <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>
- </signal>
-
- <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
- <tp:added version="0.17.UNRELEASED"/>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Request a channel with certain properties; whether or not the
- channel existed before this method call, it should exist when it
- returns.</p>
</tp:docstring>
<arg direction="in" name="Request" type="a{sv}"
tp:type="Qualified_Property_Value_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A dictionary containing desirable properties. Some properties
- are defined such that only an exact match makes sense, and
- connection managers MUST NOT satisfy a request with a channel
- where that property does not match; some properties are defined
- such that the connection manager MAY treat the request as merely
- a hint, and make a best-effort attempt to satisfy it. This is
- documented separately for each property.</p>
-
- <p>If this dictionary contains a property whose semantics
- are not known to the connection manager, this method MUST fail
- without side-effects (in particular it must not create a new
- channel).</p>
-
- <tp:rationale>
- <p>This is necessary if we want to be able to invent properties
- in future that, when used in a request, are hard requirements
- rather than just hints. A connection manager that did not know
- the semantics of those properties could incorrectly return a
- new channel that did not satisfy the requirements.</p>
- </tp:rationale>
-
- <p>The connection manager MUST NOT respond successfully,
- and SHOULD NOT create a new channel or cause any other
- side-effects, unless it can create a new channel or return an
- existing channel that satisfies the client's requirements.</p>
+ <p>A dictionary containing desirable properties, with the same
+ semantics as the corresponding parameter to
+ <tp:member-ref>CreateChannel</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
- <p>Properties that will be set by this argument need not have write
- access on the returned channel - indeed, it is
- expected that most will be read-only.</p>
+ <arg name="Yours" direction="out" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If false, the caller of EnsureChannel MUST assume that some
+ other process is handling this channel; if true, the caller of
+ EnsureChannel SHOULD handle it themselves or delegate it to another
+ client.</p>
+
+ <p>If the creation of a channel makes several calls to EnsureChannel
+ (and no other requests) successful, exactly one of those calls MUST
+ return a true value for this argument.</p>
+
+ <p>If the creation of a channel makes other requests successful,
+ the value returned for this argument MUST be such that exactly
+ one of the clients making requests ends up responsible for the
+ channel. In particular, if CreateChannel returns a channel
+ <em>C</em>, any EnsureChannel calls that also return <em>C</em>
+ MUST return a false value for this argument.</p>
</tp:docstring>
</arg>
<arg name="Channel" direction="out" type="o">
<tp:docstring>
- The Channel object.
+ 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>
</arg>
@@ -308,16 +274,72 @@
</tp:docstring>
</arg>
- <arg name="Yours" direction="out" type="b">
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The channel request was one that can never succeed,
+ such as requesting an unsupported channel type, or requesting
+ a channel type which this connection manager does not support with
+ the given target handle type.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+ <tp:docstring>
+ An invalid handle was requested as the value of a property whose
+ value is a handle (like
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>),
+ or a syntactically invalid identifier was requested as the value
+ of a property whose value is the string corresponding to a handle
+ (like TargetID).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The requested channel cannot be created, but in
+ principle, a similar request might succeed in future. For instance,
+ this might be because the requested contact is using a client
+ that lacks a particular feature.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="NewChannels" tp:name-for-bindings="New_Channels">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>New channels have been created. The connection manager SHOULD emit
+ a single signal for any group of closely related channels that are
+ created at the same time, so that the channel dispatcher can try to
+ dispatch them to a handler as a unit.</p>
+
+ <p>In particular, if additional channels are created as a side-effect
+ of a call to <tp:member-ref>CreateChannel</tp:member-ref>,
+ these channels SHOULD appear in the same NewChannels signal as
+ the channel that satisfies the request.</p>
+
+ <tp:rationale>
+ <p>Joining a MUC Tube in XMPP requires joining the corresponding
+ MUC (chatroom), so a Text channel can be created as a
+ side-effect.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
<tp:docstring>
- True if the channel was created afresh to satisfy the caller's
- request, and hence the caller should take responsibility for it as if
- it had called CreateChannel. This parameter MUST NOT be True for
- more than one call of EnsureChannel per channel, and MUST NOT be True
- if the channel is also returned to a caller of CreateChannel.
+ The channels and their details. All channels that are signalled
+ 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>
- </method>
+ </signal>
<property name="Channels" tp:name-for-bindings="Channels"
type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
@@ -349,7 +371,7 @@
</arg>
</signal>
- <tp:mapping name="Channel_Class">
+ <tp:mapping name="Channel_Class" array-name="Channel_Class_List">
<tp:added version="0.17.11">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Mapping representing a class of channels that can be requested
--
1.5.6.5
More information about the Telepathy-commits
mailing list