This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
A channel dispatch operation is an object in the ChannelDispatcher
representing a batch of unrequested channels being announced to
client
These objects can result from new incoming channels or channels which are automatically created for some reason, but cannot result from outgoing requests for channels.
More specifically, whenever the
(If some channels in a NewChannels signal are in different bundles, this is an error. The channel dispatcher SHOULD recover by treating the NewChannels signal as if it had been several NewChannels signals each containing one channel.)
First, the channel dispatcher SHOULD construct a list of all the
If no handler at all can handle a channel, the channel dispatcher
SHOULD terminate that channel instead of creating a channel dispatcher
for it. It is RECOMMENDED that the channel dispatcher closes
the channels using
ContactList channels are strange. We hope to replace them with something better, such as an interface on the Connection, in a future version of this specification.
When listing channel handlers, priority SHOULD be given to channel handlers that are already handling channels from the same bundle.
If a handler with = True
could handle all of the channels in the dispatch
operation, then the channel dispatcher SHOULD call
Some channel types can be picked up "quietly" by an existing
channel handler. If a
Otherwise, the channel dispatcher SHOULD send the channel dispatch
operation to all relevant approvers (in parallel) and wait for an
approver to claim the channels or request that they are handled.
See
Finally, if the approver requested it, the channel dispatcher SHOULD send the channels to a handler.
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
This signal MUST NOT be emitted until all Approvers that were
invoked have returned (successfully or with an error) from
their
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
The name of a D-Bus error indicating why the channel closed. If
no better reason can be found,
org.freedesktop.Telepathy.Error.NotAvailable
MAY
be used as a fallback; this means that this error SHOULD NOT be
given any more specific meaning.
The well known bus names (starting with
org.freedesktop.Telepathy.Client.
) of the possible
The heuristic used to prioritize handlers SHOULD give a higher priority to handlers that are already running.
If, for instance, Empathy and Kopete have similar functionality, and Empathy is running, we should prefer to send channels to it rather than launching Kopete via service activation.
Called by an approver to accept a channel bundle and request that the given handler be used to handle it.
If successful, this method will cause the ChannelDispatchOperation
object to disappear, emitting
However, this method may fail because the dispatch has already been 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 separately invoked as the handler.
Approvers which are also channel handlers SHOULD use
(FIXME: list some possible errors)
If the channel handler raises an error from
The well-known bus name (starting with
org.freedesktop.Telepathy.Client.
) of the channel
handler that should handle the channel, or the empty string
if the client has no preferred channel handler.
org.freedesktop.Telepathy.Client.
".
Called by an approver to claim channels for handling
internally. If this method is called successfully, the process
calling this method becomes the handler for the channel, but
does not have the
Clients that call Claim on channels but do not immediately
close them SHOULD implement the Handler interface and its
Approvers wishing to reject channels MUST call this method to
claim ownership of them, and MUST NOT call
The channel dispatcher can't know how best to close arbitrary
channel types, so it leaves it up to the approver to do so.
For instance, for Text channels it is necessary
to acknowledge any messages that have already been displayed to
the user first - ideally, the approver would display and then
acknowledge the messages - or to call
Similarly, an Approver for StreamedMedia channels can close the channel with a reason (e.g. "busy") if desired. The channel dispatcher, which is designed to have no specific knowledge of particular channel types, can't do that.
If successful, this method will cause the ChannelDispatchOperation
object to disappear, emitting
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 case.
(FIXME: list some other possible errors)
A variant of
The well-known bus name (starting with
org.freedesktop.Telepathy.Client.
) of the channel
handler that should handle the channel, or the empty string
if the client has no preferred channel handler.
The time at which user action occurred.
org.freedesktop.Telepathy.Client.
".
Emitted when this dispatch operation finishes. The dispatch operation is no longer present and further methods must not be 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
Its object path SHOULD NOT be reused for a subsequent dispatch operation; the ChannelDispatcher MUST choose object paths in a way that avoids immediate re-use.
Otherwise, clients might accidentally call
This signal MUST NOT be emitted until all Approvers that were
invoked have returned (successfully or with an error) from
their
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