One of the channel dispatcher's functions is to offer incoming channels to Approver clients for approval.
An approver should generally ask the user whether they want to participate in the requested communication channels (join the chat or chatroom, answer the call, accept the file transfer, or whatever is appropriate). A collection of channels offered in this way is represented by a ChannelDispatchOperation object.
If the user wishes to accept the communication channels, the approver should call
tp_cli_channel_dispatch_operation_call_handle_with to indicate the user's or approver's preferred handler for the channels (the
empty string indicates no particular preference, and will cause any suitable handler to be used).
If the user wishes to reject the communication channels, or if the user accepts the channels and the approver will handle them itself,
the approver should call tp_cli_channel_dispatch_operation_call_claim. If this method succeeds, the approver immediately has
control over the channels as their primary handler, and may do anything with them (in particular, it may close them in whatever way seems
most appropriate).
There are various situations in which the channel dispatch operation will be closed, causing the invalidated signal to be emitted. If this happens, the approver should stop prompting the user.
Because all approvers are launched simultaneously, the user might respond to another approver; if this happens, the
invalidated signal will be emitted with the domain TP_DBUS_ERRORS
and the error code OBJECT_REMOVED.
If a channel closes, the channel_lost signal is
emitted. If all channels close, there is nothing more to dispatch, so the
invalidated signal will be emitted with the domain TP_DBUS_ERRORS and the error code
OBJECT_REMOVED.
If the channel dispatcher crashes or exits, the invalidated signal will
be emitted with the domain TP_DBUS_ERRORS and the error code
NAME_OWNER_LOST. In a high-quality implementation, the
dispatcher should be restarted, at which point it will create new channel dispatch operations for any undispatched channels, and the
approver will be notified again.
Creating a ChannelDispatchOperation directly is deprecated: it should only be created via a BaseClient.
Since 0.16, ChannelDispatchOperation always has a non-%NULL factory, which will be propagated to the Account, Connection and Channel.