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.

(as a stable interface)

Approvers are clients that notify the user that new channels have been created by a contact, and allow the user to accept or reject those channels. The new channels are represented by a ChannelDispatchOperation object, which is passed to the AddDispatchOperation method.

For instance, Empathy's tray icon, or the answer/reject window seen when a Maemo device receives a VoIP call, should be Approvers.

Approvers can also select which channel handler will be used for the channel, for instance by offering the user a list of possible handlers rather than just an accept/reject choice. However, the Channel Dispatcher must be able to prioritize possible handlers on its own using some reasonable heuristic, probably based on user configuration.

It is possible (and useful) to have an approver and a channel handler in the same process; this is particularly useful if a channel handler wants to claim responsibility for particular channels itself.

All approvers are notified simultaneously. For instance, in a desktop system, there might be one approver that displays a notification-area icon, one that is part of a contact list window and highlights contacts there, and one that is part of a full-screen media player.

Any approver can approve the handling of a channel dispatch operation with a particular channel handler by calling the HandleWith method. Approvers can also attempt to Claim channels; if this succeeds, the approver may handle the channels itself (if it is also a Handler), or close the channels in order to reject them.

At the D-Bus level, there is no "reject" operation: approvers wishing to reject channels SHOULD call the Claim method, then (if it succeeds) close the channels in any way they see fit.

The first approver to reply gets its decision acted on; any other approvers that reply at approximately the same time will get a D-Bus error, indicating that the channel has already been dealt with.

Approvers should usually prompt the user and ask for confirmation, rather than dispatching the channel to a handler straight away.

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

This property works in exactly the same way as the Client.Observer.ObserverChannelFilter property. In particular, it cannot change while the approver 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 ApproverChannelFilter instead of ObserverChannelFilter.

Called by the channel dispatcher when a ChannelDispatchOperation in which the approver has registered an interest is created, or when the approver starts up while such channel dispatch operations already exist.

The channel dispatcher SHOULD call this method on all approvers at the same time. If an approver returns an error from this method, the approver is assumed to be faulty.

If no approvers return from this method successfully (including situations where there are no matching approvers at all), the channel dispatcher SHOULD consider this to be an error, and recover by dispatching the channel to the most preferred handler.

Processes that aren't approvers (or don't at least ensure that there is some approver) probably shouldn't be making connections anyway, so there should always be at least one approver running.

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.

Properties of the channel dispatch operation. The keys MUST be fully qualified D-Bus property names. This MUST NOT include properties that could change, SHOULD include as many properties as possible given that constraint, and MUST include at least the Account, Connection and PossibleHandlers properties.