git.maemo.org Git - theonering/blob - src/tp/_generated/Channel_Dispatch_Operation.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,
  19       MA 02110-1301, USA.
  20
  21 """
  22
  23 import dbus.service
  24
  25
  26 class ChannelDispatchOperation(dbus.service.Object):
  27     """\
  28       A channel dispatch operation is an object in the ChannelDispatcher
  29         representing a batch of unrequested channels being announced to
  30         client
  31         Approver
  32         processes.
  33
  34       These objects can result from new incoming channels or channels
  35         which are automatically created for some reason, but cannot result
  36         from outgoing requests for channels.
  37
  38       More specifically, whenever the
  39         Connection.Interface.Requests.NewChannels
  40         signal contains channels whose
  41         Requested
  42         property is false, or whenever the
  43         Connection.NewChannel
  44         signal contains a channel with suppress_handler false,
  45         one or more ChannelDispatchOperation objects are created for those
  46         channels.
  47
  48       (If some channels in a NewChannels signal are in different bundles,
  49         this is an error. The channel dispatcher SHOULD recover by treating
  50         the NewChannels signal as if it had been several NewChannels signals
  51         each containing one channel.)
  52
  53       First, the channel dispatcher SHOULD construct a list of all the
  54         Handlers
  55         that could handle all the channels (based on their HandlerChannelFilter
  56         property), ordered by
  57         priority in some implementation-dependent way. If there are handlers
  58         which could handle all the channels, one channel dispatch operation
  59         SHOULD be created for all the channels. If there are not, one channel
  60         dispatch operation SHOULD be created for each channel, each with
  61         a list of channel handlers that could handle that channel.
  62
  63       If no handler at all can handle a channel, the channel dispatcher
  64         SHOULD terminate that channel instead of creating a channel dispatcher
  65         for it. It is RECOMMENDED that the channel dispatcher closes
  66         the channels using Channel.Interface.Destroyable.Destroy
  67         if supported, or Channel.Close
  68         otherwise. As a special case, the channel dispatcher SHOULD NOT close
  69         ContactList
  70         channels, and if Close fails, the channel dispatcher SHOULD ignore
  71         that channel.
  72
  73
  74         ContactList channels are strange. We hope to replace them with
  75           something better, such as an interface on the Connection, in a
  76           future version of this specification.
  77
  78
  79       When listing channel handlers, priority SHOULD be given to
  80         channel handlers that are already handling channels from the same
  81         bundle.
  82
  83       If a handler with BypassApproval
  84         = True could handle all of the channels in the dispatch
  85         operation, then the channel dispatcher SHOULD call HandleChannels
  86         on that handler, and (assuming the call succeeds) emit
  87         Finished and stop processing those
  88         channels without involving any approvers.
  89
  90
  91         Some channel types can be picked up "quietly" by an existing
  92           channel handler. If a Text
  93           channel is added to an existing bundle containing a StreamedMedia
  94           channel, there shouldn't be
  95           any approvers, flashing icons or notification bubbles, if the
  96           the UI for the StreamedMedia channel can just add a text box
  97           and display the message.
  98
  99
 100       Otherwise, the channel dispatcher SHOULD send the channel dispatch
 101         operation to all relevant approvers (in parallel) and wait for an
 102         approver to claim the channels or request that they are handled.
 103         See
 104         AddDispatchOperation
 105         for more details on this.
 106
 107       Finally, if the approver requested it, the channel dispatcher SHOULD
 108         send the channels to a handler.
 109     """
 110
 111     @dbus.service.method('org.freedesktop.Telepathy.ChannelDispatchOperation', in_signature='s', out_signature='')
 112     def HandleWith(self, Handler):
 113         """
 114         Called by an approver to accept a channel bundle and request that
 115           the given handler be used to handle it.
 116
 117         If successful, this method will cause the ChannelDispatchOperation
 118           object to disappear, emitting
 119           Finished.
 120
 121         However, this method may fail because the dispatch has already been
 122           completed and the object has already gone. If this occurs, it
 123           indicates that another approver has asked for the bundle to be
 124           handled by a particular handler. The approver MUST NOT attempt
 125           to interact with the channels further in this case, unless it is
 126           separately invoked as the handler.
 127
 128         Approvers which are also channel handlers SHOULD use
 129           Claim instead
 130           of HandleWith to request that they can handle a channel bundle
 131           themselves.
 132
 133         (FIXME: list some possible errors)
 134
 135         If the channel handler raises an error from HandleChannels,
 136           this method
 137           MAY respond by raising that same error, even if it is not
 138           specifically documented here.
 139
 140         """
 141         raise NotImplementedError
 142
 143     @dbus.service.method('org.freedesktop.Telepathy.ChannelDispatchOperation', in_signature='', out_signature='')
 144     def Claim(self):
 145         """
 146         Called by an approver to claim channels for handling
 147           internally. If this method is called successfully, the process
 148           calling this method becomes the handler for the channel, but
 149           does not have the HandleChannels
 150           method called on it.
 151
 152         Clients that call Claim on channels but do not immediately
 153           close them SHOULD implement the Handler interface and its
 154           HandledChannels
 155           property.
 156
 157         Approvers wishing to reject channels MUST call this method to
 158           claim ownership of them, and MUST NOT call
 159           Close
 160           on the channels unless/until this method returns successfully.
 161
 162
 163           The channel dispatcher can't know how best to close arbitrary
 164             channel types, so it leaves it up to the approver to do so.
 165             For instance, for Text channels it is necessary
 166             to acknowledge any messages that have already been displayed to
 167             the user first - ideally, the approver would display and then
 168             acknowledge the messages - or to call Channel.Interface.Destroyable.Destroy
 169             if the destructive behaviour of that method is desired.
 170
 171           Similarly, an Approver for StreamedMedia channels can close the
 172             channel with a reason (e.g. "busy") if desired. The channel
 173             dispatcher, which is designed to have no specific knowledge
 174             of particular channel types, can't do that.
 175
 176
 177         If successful, this method will cause the ChannelDispatchOperation
 178           object to disappear, emitting
 179           Finished, in the same way as for
 180           HandleWith.
 181
 182         This method may fail because the dispatch operation has already
 183           been completed. Again, see HandleWith for more details. The approver
 184           MUST NOT attempt to interact with the channels further in this
 185           case.
 186
 187         (FIXME: list some other possible errors)
 188
 189         """
 190         raise NotImplementedError
 191
 192     @dbus.service.signal('org.freedesktop.Telepathy.ChannelDispatchOperation', signature='oss')
 193     def ChannelLost(self, Channel, Error, Message):
 194         """
 195         A channel has closed before it could be claimed or handled. If
 196           this is emitted for the last remaining channel in a channel
 197           dispatch operation, it MUST immediately be followed by
 198           Finished.
 199
 200         This signal MUST NOT be emitted until all Approvers that were
 201           invoked have returned (successfully or with an error) from
 202           their AddDispatchOperation
 203           method.
 204
 205
 206           This means that Approvers can connect to the ChannelLost signal
 207             in a race-free way. Non-approver processes that discover
 208             a channel dispatch operation in some way (such as observers)
 209             will have to follow the usual "connect to signals then recover
 210             state" model - first connect to ChannelLost and
 211             Finished,
 212             then download Channels (and
 213             on error, perhaps assume that the operation has already
 214             Finished).
 215
 216
 217         """
 218         pass
 219
 220     @dbus.service.signal('org.freedesktop.Telepathy.ChannelDispatchOperation', signature='')
 221     def Finished(self):
 222         """
 223         Emitted when this dispatch operation finishes. The dispatch
 224           operation is no longer present and further methods must not be
 225           called on it.
 226
 227         Approvers that have a user interface SHOULD stop notifying the user
 228           about the channels in response to this signal; they MAY assume that
 229           on errors, they would have received
 230           ChannelLost first.
 231
 232         Its object path SHOULD NOT be reused for a subsequent dispatch
 233           operation; the ChannelDispatcher MUST choose object paths
 234           in a way that avoids immediate re-use.
 235
 236
 237           Otherwise, clients might accidentally call
 238             HandleWith or
 239             Claim on a new dispatch operation
 240             instead of the one they intended to handle.
 241
 242
 243         This signal MUST NOT be emitted until all Approvers that were
 244           invoked have returned (successfully or with an error) from
 245           their AddDispatchOperation
 246           method.
 247
 248
 249           This means that Approvers can connect to the ChannelLost signal
 250             in a race-free way. Non-approver processes that discover
 251             a channel dispatch operation in some way (such as observers)
 252             will have to follow the usual "connect to signals then recover
 253             state" model - first connect to
 254             ChannelLost and
 255             Finished, then download Channels
 256             (and on error, perhaps assume that the operation has already
 257             Finished).
 258
 259
 260         """
 261         pass
 262