From 7da88a448016371c26fe89c4c5d62e6e3db71f68 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 4 Nov 2013 15:45:45 +0000 Subject: [PATCH 06/12] ChannelDispatchOperation, Approver: be singular This means we can use immutable properties for the Channel. --- spec/Channel_Dispatch_Operation.xml | 132 ++++++++++++++---------------------- spec/Client_Approver.xml | 58 ++-------------- 2 files changed, 59 insertions(+), 131 deletions(-) diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml index 66b5ed4..108c990 100644 --- a/spec/Channel_Dispatch_Operation.xml +++ b/spec/Channel_Dispatch_Operation.xml @@ -26,7 +26,7 @@

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 Approver processes.

@@ -97,7 +97,7 @@ The Connection - with which the Channels are + 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 '.'. This property cannot change. @@ -110,72 +110,29 @@ The Account with which the Connection - and Channels are + and Channel is associated. This property cannot change. - - - The Channels - to be dispatched, and their properties. Change notification is via - the ChannelLost signal (channels - cannot be added to this property, only removed). + + +

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

 - + -

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 - Finished.

- -

This signal MUST NOT be emitted until all Approvers that were - invoked have returned (successfully or with an error) from - their AddDispatchOperation - method.

- - -

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 - Finished, - then download Channels (and - on error, perhaps assume that the operation has already - Finished).

- +

Properties of the Channel, + equivalent to the properties in Channel_Details. + This property cannot change.

 - - - - The Channel - that closed. - - - - - -

The name of a D-Bus error indicating why the channel closed. If - no better reason can be found, - im.telepathy.v1.Error.NotAvailable MAY - be used as a fallback; this means that this error SHOULD NOT be - given any more specific meaning.

- - - - - - A string associated with the D-Bus error. - - - + @@ -184,7 +141,7 @@ im.telepathy.v1.Client.) of the possible Handlers - 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.

@@ -212,12 +169,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.

Approvers which are also channel handlers SHOULD use Claim instead - of HandleWith to request that they can handle a channel bundle + of HandleWith to request that they can handle a channel themselves.

(FIXME: list some possible errors)

@@ -248,15 +205,15 @@ - The selected handler is temporarily unable to handle these - channels. + The selected handler is temporarily unable to handle this + channel. 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). @@ -265,7 +222,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 @@ -320,7 +277,7 @@

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.

(FIXME: list some other possible errors)

@@ -377,15 +334,15 @@ - The selected handler is temporarily unable to handle these - channels. + The selected handler is temporarily unable to handle this + channel. 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). @@ -394,7 +351,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 @@ -411,9 +368,7 @@ called on it.

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 - ChannelLost first.

+ about the channel in response to this signal.

Its object path SHOULD NOT be reused for a subsequent dispatch operation; the ChannelDispatcher MUST choose object paths @@ -433,17 +388,34 @@ method.

-

This means that Approvers can connect to the ChannelLost signal +

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 - ChannelLost and - Finished, then download Channels + state" model - first connect to Finished, then download properties (and on error, perhaps assume that the operation has already Finished).

 + + + +

If the channel dispatch operation finished because the + channel was successfully dispatched, the empty string.

+ +

Otherwise, the name of a D-Bus error indicating why the channel + closed. If no better reason can be found, + im.telepathy.v1.Error.NotAvailable MAY + be used as a fallback; this means that this error SHOULD NOT be + given any more specific meaning.

+ + + + + + A string associated with the D-Bus error. + + diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml index 03504c7..0296e02 100644 --- a/spec/Client_Approver.xml +++ b/spec/Client_Approver.xml @@ -89,8 +89,8 @@

A specification of the channels in which this approver is interested. The AddDispatchOperation - 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.

This property works in exactly the same way as the @@ -130,54 +130,6 @@ - - -

The initial value of the ChannelDispatchOperation.Channels - property, containing the Channels - to be dispatched and their properties.

- - -

This can't be signalled to the approver through the Properties - parameter of this method, because Channels is not an immutable - property.

- - -

This argument always contains all of the channels in the channel - dispatch operation, even if not all of them actually match - the ApproverChannelFilter.

- - -

This seems the least bad way to handle such a situation; - see the discussion on - bug - #21090.

- - -

The actual channels to be dispatched may reduce as channels are - closed: this is signalled by ChannelDispatchOperation.ChannelLost. -

- -

Approvers SHOULD connect to ChannelLost and ChannelDispatchOperation.Finished. - (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.

- - - - - -

The - ChannelDispatchOperation - to be processed.

- - - @@ -188,7 +140,11 @@ Account, Connection + namespace="im.telepathy.v1.ChannelDispatchOperation">Connection, + Channel, + ChannelProperties and PossibleHandlers properties.

-- 1.8.4.2