From 371fc326449174d4ecd012bb27432cbcddad3517 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 4 Nov 2013 15:35:49 +0000 Subject: [PATCH 05/12] HandleChannel: be singular --- spec/Channel.xml | 2 +- spec/Channel_Dispatch_Operation.xml | 16 ++++++------- spec/Channel_Dispatcher.xml | 8 +++---- spec/Channel_Request.xml | 4 ++-- spec/Client_Handler.xml | 48 +++++++++++++++++++++---------------- spec/Client_Interface_Requests.xml | 2 +- spec/Client_Observer.xml | 4 ++-- 7 files changed, 45 insertions(+), 39 deletions(-) diff --git a/spec/Channel.xml b/spec/Channel.xml index 0646f29..c5f219f 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -327,7 +327,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.ObserveChannel, AddDispatchOperation and - HandleChannels + HandleChannel methods to permit immediate identification of the channel. This interface contains immutable properties common to all channels. In brief:

diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml index 26deb7d..66b5ed4 100644 --- a/spec/Channel_Dispatch_Operation.xml +++ b/spec/Channel_Dispatch_Operation.xml @@ -55,7 +55,7 @@ namespace="im.telepathy.v1.Client.Handler">BypassApproval = True could handle the channel in the dispatch operation, then the channel dispatcher SHOULD call HandleChannels + namespace="im.telepathy.v1.Client.Handler">HandleChannel on that handler, and (assuming the call succeeds) emit Finished and stop processing that channel without involving any approvers.

@@ -223,7 +223,7 @@

(FIXME: list some possible errors)

If the channel handler raises an error from HandleChannels, + namespace="im.telepathy.v1.Client.Handler">HandleChannel, this method MAY respond by raising that same error, even if it is not specifically documented here.

@@ -256,7 +256,7 @@ 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 HandleChannels + do not match its HandlerChannelFilter, or because HandleChannel raised NotImplemented). @@ -268,7 +268,7 @@ now responsible for the channels. 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 HandleChannels fails, the channel dispatcher SHOULD try to obey + to HandleChannel fails, the channel dispatcher SHOULD try to obey the choice of Handler made by the second call to HandleWith. @@ -281,7 +281,7 @@ internally. If this method is called successfully, the process calling this method becomes the handler for the channel, but does not have the HandleChannels + namespace="im.telepathy.v1.Client.Handler">HandleChannel method called on it.

Clients that call Claim on channels but do not immediately @@ -348,7 +348,7 @@

A variant of HandleWith allowing the approver to pass an user action time. This timestamp will be passed to the Handler when HandleChannels + namespace="im.telepathy.v1.Client.Handler">HandleChannel is called.

@@ -385,7 +385,7 @@ 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 HandleChannels + do not match its HandlerChannelFilter, or because HandleChannel raised NotImplemented). @@ -397,7 +397,7 @@ now responsible for the channels. 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 HandleChannels fails, the channel dispatcher SHOULD try to obey + to HandleChannel fails, the channel dispatcher SHOULD try to obey the choice of Handler made by the second call to HandleWith. diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml index b8f5f87..3d7d52b 100644 --- a/spec/Channel_Dispatcher.xml +++ b/spec/Channel_Dispatcher.xml @@ -174,7 +174,7 @@ namespace="im.telepathy.v1.ChannelRequest">UserActionTime property will be set to this value, and it will eventually be passed as the User_Action_Time parameter of HandleChannels.

+ namespace="im.telepathy.v1.Client.Handler">HandleChannel.

@@ -200,7 +200,7 @@

This is partly so the channel dispatcher can call HandleChannels + namespace="im.telepathy.v1.Client.Handler">HandleChannel on it, and partly so the channel dispatcher can recover state if it crashes and is restarted.

@@ -429,7 +429,7 @@ This method now returns Delegated and Not_Delegated instead of nothing. - HandleChannels + HandleChannel is now called once per Channel in Channels. @@ -440,7 +440,7 @@

For each Channel in Channels, if another Handler can be found, - HandleChannels + HandleChannel will be called on it until a Handler accepts it.

diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index b36b0a6..2b98284 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -272,13 +272,13 @@ The Handler should check each ChannelRequest of the Requests_Satisfied parameter of - HandleChannels + HandleChannel for the hint. The first request containing the hint SHOULD be used and all further hints SHOULD be ignored. This covers the very unlikely case where - HandleChannels + HandleChannel satisfies two separate requests which have different PreferredHandlers. diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index 7ea0b52..46b9aee 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -162,11 +162,11 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true - + -

Called by the channel dispatcher when this client should handle these - channels, or when this client should present channels that it is already - handling to the user (e.g. bring them into the foreground).

+

Called by the channel dispatcher when this client should handle this + channel, or when this client should present a channel that it is already + handling to the user (e.g. bring it into the foreground).

Clients are expected to know what channels they're already handling, @@ -178,20 +178,19 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true

This method can raise any D-Bus error. If it does, the handler is assumed to have failed or crashed, and the channel dispatcher MUST recover in an implementation-specific way; it MAY - attempt to dispatch the channels to another handler, or close the - channels.

+ attempt to dispatch the channel to another handler, or close the + channel.

-

If closing the channels, it is RECOMMENDED that the channel - dispatcher attempts to close the channels using - If closing the channel, it is RECOMMENDED that the channel + dispatcher attempts to use Channel.Close, but resorts to calling Channel.Interface.Destroyable1.Destroy (if available) or ignoring the channel (if not) if the same handler - repeatedly fails to handle channels.

+ repeatedly fails to handle a channel.

-

After HandleChannels returns successfully, the client process is +

After HandleChannel returns successfully, the client process is considered to be responsible for the channel until it its unique name disappears from the bus.

@@ -207,7 +206,7 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=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. @@ -215,28 +214,35 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true - The Connection with which the channels are associated. The + The Connection 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 immutable properties. Their well-known - bus name is 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.

 -

The requests satisfied by these channels.

+

The requests satisfied by this channel.

If the handler implements Requests, this tells it - that these channels match previous AddRequest calls that it may have received.

@@ -259,7 +265,7 @@ im.telepathy.v1.Channel.Interface.MediaSignalling/video/h264=true -

Additional information about these channels. Currently defined +

Additional information about this channel. Currently defined keys are:

diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml index f515aba..c96a29b 100644 --- a/spec/Client_Interface_Requests.xml +++ b/spec/Client_Interface_Requests.xml @@ -54,7 +54,7 @@

If the request succeeds and is given to the expected Handler, the Requests_Satisfied parameter to HandleChannels + namespace="im.telepathy.v1.Client.Handler">HandleChannel can be used to match the channel to a previous AddRequest call.

diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml index b899742..4511bfd 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -267,7 +267,7 @@ Recover=true to avoid the following race: text channel logger (observer) gets ObserveChannel, text channel handler gets HandleChannels + namespace="im.telepathy.v1.Client.Handler">HandleChannel channel handler starts up faster and acknowledges messages, logger never sees those messages.

 @@ -356,7 +356,7 @@ Recover=true If the same process is an Observer and a Handler, it can be useful to be given this information as soon as possible (it will also be passed to Handler.HandleChannels). + namespace="im.telepathy.v1.Client">Handler.HandleChannel). -- 1.8.4.2