git.maemo.org Git - theonering/blob - src/tp/_generated/Client_Observer.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 ClientObserver(dbus.service.Object):
  27     """\
  28       Observers monitor the creation of new channels. This
  29         functionality can be used for things like message logging.
  30         All observers are notified simultaneously.
  31
  32       Observers SHOULD NOT modify the state of a channel except
  33         via user interaction.
  34
  35
  36         We want Observer UIs for file transfer channels (a progress
  37           bar for the transfer) to be able to have a Cancel button.
  38
  39
  40       Observers MUST NOT carry out actions that exactly one process
  41         must take responsibility for (e.g. acknowledging Text
  42         messages, or carrying out the actual transfer in a file transfer
  43         channel).
  44
  45
  46         Since arbitrarily many observers can be activated for
  47           each channel, it would not make sense for observers to do things
  48           that can only be done by one process (acknowledging
  49           Text
  50           messages, carrying out streaming for
  51           StreamedMedia
  52           channels, doing the actual data transfer for file transfers,
  53           setting up the out-of-band connection for Tubes). The
  54           Handler
  55           is responsible for such tasks.
  56
  57         Handlers MAY, of course, delegate responsibility for these
  58           tasks to other processes (including those run as observers),
  59           but this MUST be done explicitly via a request from the Handler
  60           to the Observer.
  61
  62
  63       Whenever a collection of new channels is signalled, the channel
  64         dispatcher will notify all running or activatable observers whose
  65         ObserverChannelFilter property
  66         (possibly as cached in the .client file) indicates that they are
  67         interested in some of the channels.
  68
  69       Observers are activated for all channels in which they have
  70         registered an interest - incoming, outgoing or automatically created -
  71         although of course the ObserverChannelFilter property can be set
  72         to filter on the
  73         Requested
  74         property.
  75
  76       Because it might take time for an observer to become ready (for
  77         instance, a Text logger needs to wait until pending messages have been
  78         downloaded), the channel dispatcher must wait (up to some timeout) for
  79         all observers to return from
  80         ObserveChannels before letting anything
  81         destructive happen. Destructive things (e.g. acknowledging messages)
  82         are defined to be done by handlers, therefore HandleWith and Claim
  83         aren't allowed to succeed until all observers are ready.
  84     """
  85
  86     @dbus.service.method('org.freedesktop.Telepathy.Client.Observer', in_signature='ooa(oa{sv})oaoa{sv}', out_signature='')
  87     def ObserveChannels(self, Account, Connection, Channels, Dispatch_Operation, Requests_Satisfied, Observer_Info):
  88         """
  89         Called by the channel dispatcher when channels in which the
  90           observer has registered an interest are announced in a NewChannels
  91           signal.
  92
  93         If the same NewChannels signal announces some channels that match
  94           the filter, and some that do not, then only a subset of the channels
  95           (those that do match the filter) are passed to this method.
  96
  97         If the channel dispatcher will split up the channels from a single
  98           NewChannels signal and dispatch them separately (for instance
  99           because no installed Handler can handle all of them), it will call
 100           ObserveChannels several times.
 101
 102         The observer MUST NOT return from this method call until it is ready
 103           for a handler for the channel to run (which may change the channel's
 104           state).
 105
 106
 107           The channel dispatcher must wait for observers to start up,
 108             to avoid the following race: text channel logger (observer) gets
 109             ObserveChannels, text channel handler gets
 110             HandleChannels
 111             channel handler starts up faster and acknowledges messages,
 112             logger never sees those messages.
 113
 114
 115         The channel dispatcher SHOULD NOT change its behaviour based on
 116           whether this method succeeds or fails: there are no defined D-Bus
 117           errors for this method, and if it fails, this only indicates that
 118           an Observer is somehow broken.
 119
 120
 121           The expected error response in the channel dispatcher is to
 122             log a warning, and otherwise continue as though this method
 123             had succeeded.
 124
 125
 126         """
 127         raise NotImplementedError
 128