Skip to content

GitLab

T
telepathy-spec
Commit 431a64e1 authored by Simon McVittie's avatar Simon McVittie Committed by Guillaume Desmottes
Browse files
Options

ChannelDispatchOperation, Approver: be singular 

This means we can use immutable properties for the Channel.
parent 3510bdc2
Hide whitespace changes
Inline Side-by-side
Showing with 59 additions and 131 deletions
spec/Channel_Dispatch_Operation.xml
View file @ 431a64e1
......@@ -26,7 +26,7 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A channel dispatch operation is an object in the ChannelDispatcher
representing a batch of unrequested channels being announced to
representing an unrequested channel being announced to
client
<tp:dbus-ref namespace="im.telepathy.v1.Client">Approver</tp:dbus-ref>
processes.</p>
......@@ -118,7 +118,7 @@
<tp:docstring>
The <tp:dbus-ref
namespace="im.telepathy.v1">Connection</tp:dbus-ref>
with which the <tp:member-ref>Channels</tp:member-ref> are
with which the <tp:member-ref>Channel</tp:member-ref> is
associated. The well-known bus name to use can be derived from
this object path by removing the leading '/' and replacing all
subsequent '/' by '.'. This property cannot change.
......@@ -131,72 +131,29 @@
The <tp:dbus-ref
namespace="im.telepathy.v1">Account</tp:dbus-ref>
with which the <tp:member-ref>Connection</tp:member-ref>
and <tp:member-ref>Channels</tp:member-ref> are
and <tp:member-ref>Channel</tp:member-ref> is
associated. This property cannot change.
</tp:docstring>
</property>
<property name="Channels" tp:name-for-bindings="Channels"
type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
<tp:docstring>
The <tp:dbus-ref
namespace="im.telepathy.v1">Channel</tp:dbus-ref>s
to be dispatched, and their properties. Change notification is via
the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels
cannot be added to this property, only removed).
<property name="Channel" type="o" tp:name-for-bindings="Channel"
access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The Channel object. Its well-known bus name is the same
as that of the <tp:member-ref>Connection</tp:member-ref>.
This property cannot change.</p>
</tp:docstring>
</property>
<signal name="ChannelLost" tp:name-for-bindings="Channel_Lost">
<property name="ChannelProperties" access="read" type="a{sv}"
tp:type="Qualified_Property_Value_Map"
tp:name-for-bindings="Channel_Properties">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A channel has closed before it could be claimed or handled. If
this is emitted for the last remaining channel in a channel
dispatch operation, it MUST immediately be followed by
<tp:member-ref>Finished</tp:member-ref>.</p>
<p>This signal MUST NOT be emitted until all Approvers that were
invoked have returned (successfully or with an error) from
their <tp:dbus-ref
namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref>
method.</p>
<tp:rationale>
<p>This means that Approvers can connect to the ChannelLost signal
in a race-free way. Non-approver processes that discover
a channel dispatch operation in some way (such as observers)
will have to follow the usual "connect to signals then recover
state" model - first connect to ChannelLost and
<tp:member-ref>Finished</tp:member-ref>,
then download <tp:member-ref>Channels</tp:member-ref> (and
on error, perhaps assume that the operation has already
Finished).</p>
</tp:rationale>
<p>Properties of the <tp:member-ref>Channel</tp:member-ref>,
equivalent to the properties in <tp:type>Channel_Details</tp:type>.
This property cannot change.</p>
</tp:docstring>
<arg name="Channel" type="o">
<tp:docstring>
The <tp:dbus-ref
namespace="im.telepathy.v1">Channel</tp:dbus-ref>
that closed.
</tp:docstring>
</arg>
<arg name="Error" type="s" tp:type="DBus_Error_Name">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The name of a D-Bus error indicating why the channel closed. If
no better reason can be found,
<code>im.telepathy.v1.Error.NotAvailable</code> MAY
be used as a fallback; this means that this error SHOULD NOT be
given any more specific meaning.</p>
</tp:docstring>
</arg>
<arg name="Message" type="s">
<tp:docstring>
A string associated with the D-Bus error.
</tp:docstring>
</arg>
</signal>
</property>
<property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers"
type="as" access="read" tp:type="DBus_Well_Known_Name[]">
......@@ -205,7 +162,7 @@
<code>im.telepathy.v1.Client.</code>) of the possible
<tp:dbus-ref
namespace="im.telepathy.v1.Client">Handler</tp:dbus-ref>s
for these channels. The channel dispatcher MUST place the most
for this channel. The channel dispatcher MUST place the most
preferred handlers first, according to some reasonable heuristic.
As a result, approvers SHOULD use the first handler by default.</p>
......@@ -233,12 +190,12 @@
completed and the object has already gone. If this occurs, it
indicates that another approver has asked for the bundle to be
handled by a particular handler. The approver MUST NOT attempt
to interact with the channels further in this case, unless it is
to interact with the channel further in this case, unless it is
separately invoked as the handler.</p>
<p>Approvers which are also channel handlers SHOULD use
<tp:member-ref>Claim</tp:member-ref> instead
of HandleWith to request that they can handle a channel bundle
of HandleWith to request that they can handle a channel
themselves.</p>
<p>(FIXME: list some possible errors)</p>
......@@ -269,15 +226,15 @@
</tp:error>
<tp:error name="im.telepathy.v1.Error.NotAvailable">
<tp:docstring>
The selected handler is temporarily unable to handle these
channels.
The selected handler is temporarily unable to handle this
channel.
</tp:docstring>
</tp:error>
<tp:error name="im.telepathy.v1.Error.NotImplemented">
<tp:docstring>
The selected handler is syntactically correct, but will never
be able to handle these channels (for instance because the channels
do not match its HandlerChannelFilter, or because HandleChannel
be able to handle this channel (for instance because the channel
does not match its HandlerChannelFilter, or because HandleChannel
raised NotImplemented).
</tp:docstring>
</tp:error>
......@@ -286,7 +243,7 @@
At the time that HandleWith was called, this dispatch operation was
processing an earlier call to HandleWith. The earlier call has
now succeeded, so some Handler nominated by another approver is
now responsible for the channels. In this situation, the second
now responsible for the channel. In this situation, the second
call to HandleWith MUST NOT return until the first one has
returned successfully or unsuccessfully, and if the first call
to HandleChannel fails, the channel dispatcher SHOULD try to obey
......@@ -341,7 +298,7 @@
<p>This method may fail because the dispatch operation has already
been completed. Again, see HandleWith for more details. The approver
MUST NOT attempt to interact with the channels further in this
MUST NOT attempt to interact with the channel further in this
case.</p>
<p>(FIXME: list some other possible errors)</p>
......@@ -398,15 +355,15 @@
</tp:error>
<tp:error name="im.telepathy.v1.Error.NotAvailable">
<tp:docstring>
The selected handler is temporarily unable to handle these
channels.
The selected handler is temporarily unable to handle this
channel.
</tp:docstring>
</tp:error>
<tp:error name="im.telepathy.v1.Error.NotImplemented">
<tp:docstring>
The selected handler is syntactically correct, but will never
be able to handle these channels (for instance because the channels
do not match its HandlerChannelFilter, or because HandleChannel
be able to handle these channels (for instance because the channel
does not match its HandlerChannelFilter, or because HandleChannel
raised NotImplemented).
</tp:docstring>
</tp:error>
......@@ -415,7 +372,7 @@
At the time that HandleWith was called, this dispatch operation was
processing an earlier call to HandleWith. The earlier call has
now succeeded, so some Handler nominated by another approver is
now responsible for the channels. In this situation, the second
now responsible for the channel. In this situation, the second
call to HandleWith MUST NOT return until the first one has
returned successfully or unsuccessfully, and if the first call
to HandleChannel fails, the channel dispatcher SHOULD try to obey
......@@ -432,9 +389,7 @@
called on it.</p>
<p>Approvers that have a user interface SHOULD stop notifying the user
about the channels in response to this signal; they MAY assume that
on errors, they would have received
<tp:member-ref>ChannelLost</tp:member-ref> first.</p>
about the channel in response to this signal.</p>
<p>Its object path SHOULD NOT be reused for a subsequent dispatch
operation; the ChannelDispatcher MUST choose object paths
......@@ -454,17 +409,34 @@
method.</p>
<tp:rationale>
<p>This means that Approvers can connect to the ChannelLost signal
<p>This means that Approvers can connect to the Finished signal
in a race-free way. Non-approver processes that discover
a channel dispatch operation in some way (such as observers)
will have to follow the usual "connect to signals then recover
state" model - first connect to
<tp:member-ref>ChannelLost</tp:member-ref> and
Finished, then download <tp:member-ref>Channels</tp:member-ref>
state" model - first connect to Finished, then download properties
(and on error, perhaps assume that the operation has already
Finished).</p>
</tp:rationale>
</tp:docstring>
<arg name="Error" type="s" tp:type="DBus_Error_Name">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>If the channel dispatch operation finished because the
channel was successfully dispatched, the empty string.</p>
<p>Otherwise, the name of a D-Bus error indicating why the channel
closed. If no better reason can be found,
<code>im.telepathy.v1.Error.NotAvailable</code> MAY
be used as a fallback; this means that this error SHOULD NOT be
given any more specific meaning.</p>
</tp:docstring>
</arg>
<arg name="Message" type="s">
<tp:docstring>
A string associated with the D-Bus error.
</tp:docstring>
</arg>
</signal>
</interface>
......
spec/Client_Approver.xml
View file @ 431a64e1
......@@ -89,8 +89,8 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A specification of the channels in which this approver is
interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref>
method should be called by the channel dispatcher whenever at least
one of the channels in a channel dispatch operation matches this
method should be called by the channel dispatcher whenever
the channel in a channel dispatch operation matches this
description.</p>
<p>This property works in exactly the same way as the
......@@ -130,54 +130,6 @@
</tp:rationale>
</tp:docstring>
<arg name="Channels" direction="in"
type="a(oa{sv})" tp:type="Channel_Details[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The initial value of the <tp:dbus-ref
namespace="im.telepathy.v1">ChannelDispatchOperation.Channels</tp:dbus-ref>
property, containing the <tp:dbus-ref
namespace="im.telepathy.v1">Channel</tp:dbus-ref>s
to be dispatched and their properties.</p>
<tp:rationale>
<p>This can't be signalled to the approver through the Properties
parameter of this method, because Channels is not an immutable
property.</p>
</tp:rationale>
<p>This argument always contains all of the channels in the channel
dispatch operation, even if not all of them actually match
the <tp:member-ref>ApproverChannelFilter</tp:member-ref>.</p>
<tp:rationale>
<p>This seems the least bad way to handle such a situation;
see the discussion on
<a href="http://bugs.freedesktop.org/show_bug.cgi?id=21090">bug
#21090</a>.</p>
</tp:rationale>
<p>The actual channels to be dispatched may reduce as channels are
closed: this is signalled by <tp:dbus-ref
namespace="im.telepathy.v1">ChannelDispatchOperation.ChannelLost</tp:dbus-ref>.
</p>
<p>Approvers SHOULD connect to ChannelLost and <tp:dbus-ref
namespace="im.telepathy.v1">ChannelDispatchOperation.Finished</tp:dbus-ref>.
(if desired) before returning from AddDispatchOperation, since
those signals are guaranteed not to be emitted until after all
AddDispatchOperation calls have returned (with success or failure)
or timed out.</p>
</tp:docstring>
</arg>
<arg name="DispatchOperation" type="o" direction="in">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The
<tp:dbus-ref namespace="im.telepathy.v1">ChannelDispatchOperation</tp:dbus-ref>
to be processed.</p>
</tp:docstring>
</arg>
<arg name="Properties" type="a{sv}"
tp:type="Qualified_Property_Value_Map" direction="in">
<tp:docstring>
......@@ -188,7 +140,11 @@
<tp:dbus-ref
namespace="im.telepathy.v1.ChannelDispatchOperation">Account</tp:dbus-ref>,
<tp:dbus-ref
namespace="im.telepathy.v1.ChannelDispatchOperation">Connection</tp:dbus-ref>
namespace="im.telepathy.v1.ChannelDispatchOperation">Connection</tp:dbus-ref>,
<tp:dbus-ref
namespace="im.telepathy.v1.ChannelDispatchOperation">Channel</tp:dbus-ref>,
<tp:dbus-ref
namespace="im.telepathy.v1.ChannelDispatchOperation">ChannelProperties</tp:dbus-ref>
and <tp:dbus-ref
namespace="im.telepathy.v1.ChannelDispatchOperation">PossibleHandlers</tp:dbus-ref>
properties.</p>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment