Commit 9c9d773e authored by Simon McVittie's avatar Simon McVittie Committed by Guillaume Desmottes

ObserveChannel: be singular

parent b9dfcdad
......@@ -325,7 +325,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
after the channel has been announced with <tp:dbus-ref
namespace='imt1.Connection'>NewChannel</tp:dbus-ref>),
provided to clients in the
<tp:dbus-ref namespace='imt1.Client.Observer'>ObserveChannels</tp:dbus-ref>,
<tp:dbus-ref namespace='imt1.Client.Observer'>ObserveChannel</tp:dbus-ref>,
<tp:dbus-ref namespace='imt1.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and
<tp:dbus-ref namespace='imt1.Client.Handler'>HandleChannel</tp:dbus-ref>
methods to permit immediate identification of the channel. This interface
......
......@@ -64,11 +64,11 @@
to the Observer.</p>
</tp:rationale>
<p>Whenever a collection of new channels is signalled, the channel
<p>Whenever a new channel is signalled, the channel
dispatcher will notify all running or activatable observers whose
<tp:member-ref>ObserverChannelFilter</tp:member-ref> property
(possibly as cached in the .client file) indicates that they are
interested in some of the channels.</p>
interested in that channel.</p>
<p>Observers are activated for all channels in which they have
registered an interest - incoming, outgoing or automatically created -
......@@ -82,7 +82,7 @@
instance, a Text logger needs to wait until pending messages have been
downloaded), the channel dispatcher must wait (up to some timeout) for
all observers to return from
<tp:member-ref>ObserveChannels</tp:member-ref> before letting anything
<tp:member-ref>ObserveChannel</tp:member-ref> before letting anything
destructive happen. Destructive things (e.g. acknowledging messages)
are defined to be done by handlers, therefore HandleWith and Claim
aren't allowed to succeed until all observers are ready.</p>
......@@ -93,13 +93,13 @@
be implemented as observers by following these steps:</p>
<ol>
<li><tp:member-ref>ObserveChannels</tp:member-ref>() is called
<li><tp:member-ref>ObserveChannel</tp:member-ref>() is called
on the observer.</li>
<li>The observer calls <tp:dbus-ref
namespace="imt1.ChannelDispatchOperation">Claim</tp:dbus-ref>()
on the CDO.</li>
<li>The observer then returns from
<tp:member-ref>ObserveChannels</tp:member-ref>().</li>
<tp:member-ref>ObserveChannel</tp:member-ref>().</li>
<li><tp:dbus-ref
namespace="imt1.ChannelDispatchOperation">Claim</tp:dbus-ref>
will return successfully if the channels were successfully
......@@ -109,7 +109,7 @@
<p>Non-interactive approvers implemented as observers SHOULD
also set <tp:member-ref>DelayApprovers</tp:member-ref> to TRUE
so that other Approvers are not called on until all observers
return from <tp:member-ref>ObserveChannels</tp:member-ref>.
return from <tp:member-ref>ObserveChannel</tp:member-ref>.
This gives non-interactive approvers a chance to claim the
channels before Approvers are called.</p>
</tp:docstring>
......@@ -119,7 +119,7 @@
type="aa{sv}" access="read" tp:type="Channel_Class[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A specification of the channels in which this observer is
interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method
interested. The <tp:member-ref>ObserveChannel</tp:member-ref> method
should be called by the channel dispatcher whenever the new
channel in a <tp:dbus-ref
namespace="im.telepathy.v1.Connection">NewChannel</tp:dbus-ref>
......@@ -215,14 +215,14 @@ im.telepathy.v1.Channel.Requested b=true
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>If true, upon the startup of this observer, <tp:dbus-ref
namespace="im.telepathy.v1.Client.Observer">ObserveChannels</tp:dbus-ref>
namespace="im.telepathy.v1.Client.Observer">ObserveChannel</tp:dbus-ref>
will be called for every already existing channel matching
its <tp:dbus-ref
namespace="im.telepathy.v1.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p>
<p>When an activatable client having this property disappears from the
bus and there are channels matching its ObserverChannelFilter,
ObserveChannels will be called immediately to reactivate it
ObserveChannel will be called immediately to reactivate it
again. Such clients should specify this property in their
<tt>.client</tt> file as follows:</p>
......@@ -245,13 +245,13 @@ Recover=true
currently active at the time that it starts up.</p>
</tp:rationale>
<p>When the ObserveChannels method is called due to observer recovery,
<p>When the ObserveChannel method is called due to observer recovery,
the <var>Observer_Info</var> dictionary will contain one extra item
mapping the key <code>"recovering"</code> to <code>True</code>.</p>
</tp:docstring>
</property>
<method name="ObserveChannels" tp:name-for-bindings="Observe_Channels">
<method name="ObserveChannel" tp:name-for-bindings="Observe_Channel">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Called by the channel dispatcher when a channel in which the
observer has registered an interest are announced in a <tp:dbus-ref
......@@ -265,7 +265,7 @@ Recover=true
<tp:rationale>
<p>The channel dispatcher must wait for observers to start up,
to avoid the following race: text channel logger (observer) gets
ObserveChannels, text channel handler gets
ObserveChannel, text channel handler gets
<tp:dbus-ref
namespace="im.telepathy.v1.Client.Handler">HandleChannel</tp:dbus-ref>
channel handler starts up faster and acknowledges messages,
......@@ -288,7 +288,7 @@ Recover=true
<tp:docstring>
The
<tp:dbus-ref namespace="im.telepathy.v1">Account</tp:dbus-ref>
with which the channels are associated. The
with which the channel is associated. The
well-known bus name to use is that of the
<tp:dbus-ref namespace="im.telepathy.v1">AccountManager</tp:dbus-ref>.
</tp:docstring>
......@@ -298,20 +298,25 @@ Recover=true
<tp:docstring>
The
<tp:dbus-ref namespace="im.telepathy.v1">Connection</tp:dbus-ref>
with which the channels are associated. The
with which the channel 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 '.'.
</tp:docstring>
</arg>
<arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]"
direction="in">
<tp:docstring>
The <tp:dbus-ref
namespace="im.telepathy.v1">Channel</tp:dbus-ref>s
and their properties. Their well-known bus names are all the same as
that of the Connection.
<arg name="Channel" direction="in" type="o">
<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 Connection.</p>
</tp:docstring>
</arg>
<arg name="Channel_Properties" direction="in" type="a{sv}"
tp:type="Qualified_Property_Value_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Properties of the channel, equivalent to
the properties in <tp:type>Channel_Details</tp:type>.</p>
</tp:docstring>
</arg>
......@@ -319,8 +324,8 @@ Recover=true
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The path to the <tp:dbus-ref
namespace="im.telepathy.v1">ChannelDispatchOperation</tp:dbus-ref>
for these channels, or the special value '/' if there is no
ChannelDispatchOperation (because the channels were requested, not
for this channel, or the special value '/' if there is no
ChannelDispatchOperation (because the channel was requested, not
incoming).</p>
<p>If the Observer calls <tp:dbus-ref
......@@ -329,12 +334,12 @@ Recover=true
namespace="im.telepathy.v1.ChannelDispatchOperation">HandleWith</tp:dbus-ref>
on the dispatch operation, it MUST be careful to avoid deadlock,
since these methods cannot return until the Observer has returned
from <tp:member-ref>ObserveChannels</tp:member-ref>.</p>
from <tp:member-ref>ObserveChannel</tp:member-ref>.</p>
<tp:rationale>
<p>This allows an Observer to <tp:dbus-ref
namespace="im.telepathy.v1.ChannelDispatchOperation">Claim</tp:dbus-ref>
a set of channels without having to match up calls to this method
a channel without having to match up calls to this method
with calls to <tp:dbus-ref
namespace="im.telepathy.v1.Client.Approver">AddDispatchOperation</tp:dbus-ref>.</p>
</tp:rationale>
......@@ -345,7 +350,7 @@ Recover=true
<tp:docstring>
The <tp:dbus-ref
namespace="im.telepathy.v1">ChannelRequest</tp:dbus-ref>s
satisfied by these channels.
satisfied by this channel.
<tp:rationale>
If the same process is an Observer and a Handler, it can be useful
......@@ -358,12 +363,12 @@ Recover=true
<arg name="Observer_Info" type="a{sv}" direction="in">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Additional information about these channels. Currently defined
<p>Additional information about this channel. Currently defined
keys are:</p>
<dl>
<dt><code>recovering</code> - b</dt>
<dd><code>True</code> if ObserveChannels was called for an existing
<dd><code>True</code> if ObserveChannel was called for an existing
channel (due to the <tp:member-ref>Recover</tp:member-ref>
property being <code>True</code>); <code>False</code> or omitted
otherwise.
......@@ -396,7 +401,7 @@ Recover=true
<tp:added version="0.21.11"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>If true, the channel dispatcher will wait for
<tp:member-ref>ObserveChannels</tp:member-ref> to return
<tp:member-ref>ObserveChannel</tp:member-ref> to return
before calling <tp:dbus-ref
namespace="imt1.Client">Approver.AddDispatchOperation</tp:dbus-ref>
on appropriate Approvers.</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