From 35d9efe1fa71985f7368a3e66ba6a265fb1a4d9d Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Wed, 22 Apr 2009 12:34:28 +0100 Subject: Update to telepathy-spec 0.17.23 (add Terminated error) --- spec/Client_Handler.xml | 168 ++++++++++++++++++++---------------------------- 1 file changed, 71 insertions(+), 97 deletions(-) (limited to 'spec/Client_Handler.xml') diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index 3d75f0b8c..da4870158 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -20,21 +20,36 @@ 02110-1301, USA.

- + (as a draft) - + -

Channel handlers are the eventual handler for a channel or a - channel bundle; a typical channel handler is a user interface - process handling channels of a particular type.

+

Handlers are the user interface for a channel. They turn an abstract + Telepathy channel into something the user wants to see, like a text + message stream or an audio and/or video call.

+ +

For its entire lifetime, each channel on a connection known to the + channel dispatcher is either being processed by the channel dispatcher, + or being handled by precisely one Handler.

+ +

Because each channel is only handled by one Handler, handlers may + perform actions that only make sense to do once, such as acknowledging + Text + messages, doing the actual streaming for StreamedMedia + channels with the MediaSignalling + interface, or transferring the file in FileTransfer + channels.

When a new incoming channel (one with Requested = FALSE) is offered to - Approver.DRAFTs + Approvers by the channel dispatcher, it also offers the Approvers a list of all the running or activatable handlers whose HandlerChannelFilter property @@ -60,8 +75,11 @@ or for suitable channels that must be handled separately.

This property works in exactly the same way as the - Client.Observer.DRAFT.ObserverChannelFilter - property. In the .client file, it is represented in the + Client.Observer.ObserverChannelFilter + property. In particular, it cannot change while the handler process + continues to own the corresponding Client bus name.

+ +

In the .client file, it is represented in the same way as ObserverChannelFilter, but the group has the same name as this interface and the keys start with HandlerChannelFilter instead of ObserverChannelFilter.

@@ -105,13 +123,14 @@ paths.

-

This method can raise any D-Bus error. If it does, or if the - handler loses its bus name before all the channels have closed, the +

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.

+ dispatcher MUST recover in an implementation-specific way; it MAY + attempt to dispatch the channels to another handler, or close the + channels.

-

It is RECOMMENDED that the channel dispatcher attempts to - close the channels using +

If closing the channels, it is RECOMMENDED that the channel + dispatcher attempts to close the channels using Channel.Close, but resorts to calling @@ -119,6 +138,17 @@ namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy (if available) or ignoring the channel (if not) if the same handler repeatedly fails to handle channels.

+ +

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

+ + +

If a process has multiple Client bus names - some temporary and + some long-lived - and drops one of the temporary bus names in order + to reduce the set of channels that it will handle, any channels + that it is already handling should remain unaffected.

+ @@ -149,12 +179,17 @@ - - The requests satisfied by these channels. + +

The requests satisfied by these channels.

- There can be more than one, if they were EnsureChannel - requests. +

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

+ +

There can be more than one, if they were EnsureChannel + requests.

 @@ -168,95 +203,23 @@ - - - - - -

Called by the ChannelDispatcher to indicate that channels have been - requested, and that if the request is successful, they will be - handled by this Handler.

- - -

This allows the UI to start preparing to handle the channels - in advance (e.g. render a window with an "in progress" message), - improving perceived responsiveness.

- - -

(FIXME: how do we know the returned channels will be handled by - this handler? Do we just assume that they'll match the - HandlerChannelFilter iff the request does?)

- - - - - The ChannelRequest.DRAFT - object, which MUST have been returned by CreateChannel - or EnsureChannel - before this method is called. - - - See those methods for the rationale of this ordering. - - - - - - -

Some of the properties of the ChannelRequest. To avoid race - conditions, this dictionary MUST NOT include properties whose - values could subsequently change. It SHOULD include as many - properties as possible, given that constraint.

- -

In particular, the properties Requests - and UserActionTime - MUST be included.

- - - - - - -

Called by the ChannelDispatcher to indicate that a request - previously passed to AddRequest - has failed and should be disregarded.

- - - - - The request that failed. - - - - + -

The name of the D-Bus error with which the request failed.

+

Additional information about these channels. No keys are + currently defined.

-

If this is org.freedesktop.Telepathy.Error.NotYours, - this indicates that the request succeeded, but all the resulting - channels were given to some other handler.

+

If keys are defined for this dictionary, all will be optional; + handlers MAY safely ignore any entry in this dictionary.

 - - - Any message supplied with the D-Bus error. - - + -

A list of the channels that this Handler is currently handling. -

+

A list of the channels that this process is currently handling.

There is no change notification.

@@ -272,6 +235,17 @@ the user is that unhandled channels that they have already approved might be sent back to Approvers.

+ +

The value of this property SHOULD be the same for all Client + instances that share a unique bus name, and SHOULD include all + channels that are being handled, even if they were conceptually + handled by a different Client instance.

+ + +

Otherwise, when a process released a temporary Client name, + channels that it handled because of that Client name would no + longer be state-recoverable.

+ -- cgit v1.2.3