git.maemo.org Git - theonering/blob - src/tp/_generated/Client_Approver.py

   1 # -*- coding: utf-8 -*-
   2 # Generated from the Telepathy spec
   3 """Copyright © 2008-2009 Collabora Ltd.
   4 Copyright © 2008-2009 Nokia Corporation
   5
   6     This library is free software; you can redistribute it and/or
   7       modify it under the terms of the GNU Lesser General Public
   8       License as published by the Free Software Foundation; either
   9       version 2.1 of the License, or (at your option) any later version.
  10
  11     This library is distributed in the hope that it will be useful,
  12       but WITHOUT ANY WARRANTY; without even the implied warranty of
  13       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14       Lesser General Public License for more details.
  15
  16     You should have received a copy of the GNU Lesser General Public
  17       License along with this library; if not, write to the Free Software
  18       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19       02110-1301, USA.
  20
  21 """
  22
  23 import dbus.service
  24
  25
  26 class ClientApprover(dbus.service.Object):
  27     """\
  28       Approvers are clients that notify the user that new channels have
  29         been created by a contact, and allow the user to accept or reject
  30         those channels. The new channels are represented by a ChannelDispatchOperation
  31         object, which is passed to the
  32         AddDispatchOperation method.
  33
  34
  35         For instance, Empathy's tray icon, or the answer/reject window
  36           seen when a Maemo device receives a VoIP call, should be
  37           Approvers.
  38
  39
  40       Approvers can also select which channel handler will be used for the
  41         channel, for instance by offering the user a list of possible
  42         handlers rather than just an accept/reject choice.
  43         However, the Channel Dispatcher must be able to prioritize
  44         possible handlers on its own using some reasonable heuristic,
  45         probably based on user configuration.
  46
  47       It is possible (and useful) to have an approver and
  48         a channel handler in the same process; this is particularly useful
  49         if a channel handler wants to claim responsibility for particular
  50         channels itself.
  51
  52       All approvers are notified simultaneously. For instance, in a
  53         desktop system, there might be one approver that displays a
  54         notification-area icon, one that is part of a contact list
  55         window and highlights contacts there, and one that is part
  56         of a full-screen media player.
  57
  58       Any approver can approve the handling of a channel dispatch operation
  59         with a particular channel handler by calling the HandleWith
  60         method. Approvers can also attempt to Claim
  61         channels; if this succeeds, the approver may handle the channels
  62         itself (if it is also a Handler), or close the channels in order to
  63         reject them.
  64
  65       At the D-Bus level, there is no "reject" operation: approvers wishing
  66         to reject channels SHOULD call the Claim method, then (if it succeeds)
  67         close the channels in any way they see fit.
  68
  69       The first approver to reply gets its decision acted on; any other
  70         approvers that reply at approximately the same time will get a D-Bus
  71         error, indicating that the channel has already been dealt with.
  72
  73       Approvers should usually prompt the user and ask for
  74         confirmation, rather than dispatching the channel to a handler
  75         straight away.
  76     """
  77
  78     @dbus.service.method('org.freedesktop.Telepathy.Client.Approver', in_signature='a(oa{sv})oa{sv}', out_signature='')
  79     def AddDispatchOperation(self, Channels, DispatchOperation, Properties):
  80         """
  81         Called by the channel dispatcher when a ChannelDispatchOperation
  82           in which the approver has registered an interest is created,
  83           or when the approver starts up while such channel dispatch
  84           operations already exist.
  85
  86         The channel dispatcher SHOULD call this method on all approvers
  87           at the same time. If an approver returns an error from this method,
  88           the approver is assumed to be faulty.
  89
  90         If no approvers return from this method
  91           successfully (including situations where there are no matching
  92           approvers at all), the channel dispatcher SHOULD consider this
  93           to be an error, and recover by dispatching the channel to the
  94           most preferred handler.
  95
  96
  97           Processes that aren't approvers (or don't at least ensure that there
  98           is some approver) probably shouldn't be making connections
  99           anyway, so there should always be at least one approver running.
 100
 101
 102         """
 103         raise NotImplementedError
 104