From 592dc2fe3045501bb23a6b2c5c141d8a0f4eeeb8 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 4 Nov 2013 15:28:24 +0000 Subject: [PATCH 04/12] ObserveChannel: be singular --- spec/Channel.xml | 2 +- spec/Client_Observer.xml | 63 ++++++++++++++++++++++++++---------------------- 2 files changed, 35 insertions(+), 30 deletions(-) diff --git a/spec/Channel.xml b/spec/Channel.xml index f93043d..0646f29 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -325,7 +325,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.NewChannel), provided to clients in the - ObserveChannels, + ObserveChannel, AddDispatchOperation and HandleChannels methods to permit immediate identification of the channel. This interface diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index a21078f..b899742 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -64,11 +64,11 @@ to the Observer.

-

Whenever a collection of new channels is signalled, the channel +

Whenever a new channel is signalled, the channel dispatcher will notify all running or activatable observers whose ObserverChannelFilter property (possibly as cached in the .client file) indicates that they are - interested in some of the channels.

+ interested in that channel.

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 - ObserveChannels before letting anything + ObserveChannel 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.

@@ -93,13 +93,13 @@ be implemented as observers by following these steps:

    -
  1. ObserveChannels() is called +
  2. ObserveChannel() is called on the observer.
  3. The observer calls Claim() on the CDO.
  4. The observer then returns from - ObserveChannels().
    5. + ObserveChannel().
  5. Claim will return successfully if the channels were successfully @@ -109,7 +109,7 @@

    Non-interactive approvers implemented as observers SHOULD also set DelayApprovers to TRUE so that other Approvers are not called on until all observers - return from ObserveChannels. + return from ObserveChannel. This gives non-interactive approvers a chance to claim the channels before Approvers are called.

    @@ -119,7 +119,7 @@ type="aa{sv}" access="read" tp:type="Channel_Class[]">

    A specification of the channels in which this observer is - interested. The ObserveChannels method + interested. The ObserveChannel method should be called by the channel dispatcher whenever the new channel in a NewChannel @@ -215,14 +215,14 @@ im.telepathy.v1.Channel.Requested b=true

    If true, upon the startup of this observer, ObserveChannels + namespace="im.telepathy.v1.Client.Observer">ObserveChannel will be called for every already existing channel matching its ObserverChannelFilter

    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 .client file as follows:

    @@ -245,13 +245,13 @@ Recover=true currently active at the time that it starts up.

    -

    When the ObserveChannels method is called due to observer recovery, +

    When the ObserveChannel method is called due to observer recovery, the Observer_Info dictionary will contain one extra item mapping the key "recovering" to True.

     - +

    Called by the channel dispatcher when a channel in which the observer has registered an interest are announced in a

    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 HandleChannels channel handler starts up faster and acknowledges messages, @@ -288,7 +288,7 @@ Recover=true The Account - with which the channels are associated. The + with which the channel is associated. The well-known bus name to use is that of the AccountManager. @@ -298,20 +298,25 @@ Recover=true The Connection - 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 '.'. - - - The Channels - and their properties. Their well-known bus names are all the same as - that of the Connection. + + +

    The Channel object. Its well-known bus name is the same + as that of the Connection.

    +     + + + + +

    Properties of the channel, equivalent to + the properties in Channel_Details.

         @@ -319,8 +324,8 @@ Recover=true

    The path to the ChannelDispatchOperation - 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).

    If the Observer calls HandleWith on the dispatch operation, it MUST be careful to avoid deadlock, since these methods cannot return until the Observer has returned - from ObserveChannels.

    + from ObserveChannel.

    This allows an Observer to Claim - 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 AddDispatchOperation.

     @@ -345,7 +350,7 @@ Recover=true The ChannelRequests - satisfied by these channels. + satisfied by this channel. If the same process is an Observer and a Handler, it can be useful @@ -358,12 +363,12 @@ Recover=true -

    Additional information about these channels. Currently defined +

    Additional information about this channel. Currently defined keys are:

    recovering - b
    -
    True if ObserveChannels was called for an existing +
    True if ObserveChannel was called for an existing channel (due to the Recover property being True); False or omitted otherwise. @@ -396,7 +401,7 @@ Recover=true

    If true, the channel dispatcher will wait for - ObserveChannels to return + ObserveChannel to return before calling Approver.AddDispatchOperation on appropriate Approvers.

    -- 1.8.4.2