git.maemo.org Git - theonering/blob - src/tp/_generated/Channel_Dispatcher.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 02110-1301,
  19       USA.
  20
  21 """
  22
  23 import dbus.service
  24
  25
  26 class ChannelDispatcher(dbus.service.Object):
  27     """\
  28       The channel dispatcher is responsible for responding to new
  29         channels and launching client processes to handle them. It also
  30         provides functionality for client processes to request that new
  31         channels are created.
  32
  33       If a channel dispatcher is running, it is responsible for dispatching
  34         new channels on all
  35         Connections
  36         created by the
  37         AccountManager.
  38         Connections not created by the AccountManager are outside the scope
  39         of the channel dispatcher.
  40
  41
  42         Connections created by standalone Telepathy clients
  43           that do not intend to interact with the channel dispatcher
  44           should be ignored - otherwise, the channel dispatcher would try
  45           to launch handlers for channels that the standalone client
  46           was already handling internally.
  47
  48
  49       The current channel dispatcher is defined to be the process that
  50         owns the well-known bus name
  51         org.freedesktop.Telepathy.ChannelDispatcher on
  52         the session bus. This process MUST export an object with this
  53         interface at the object path
  54         /org/freedesktop/Telepathy/ChannelDispatcher.
  55
  56       Until a mechanism exists for making a reasonable automatic choice
  57         of ChannelDispatcher implementation, implementations SHOULD NOT
  58         register as an activatable service for the ChannelDispatcher's
  59         well-known bus name. Instead, it is RECOMMENDED that some component
  60         of the user's session will select and activate a particular
  61         implementation, and that other Telepathy-enabled programs
  62         can detect whether channel request/dispatch functionality is available
  63         by checking whether the ChannelDispatcher's well-known name is in use
  64         at runtime.
  65
  66       There are three categories of client process defined by this
  67         specification:
  68
  69
  70         Observer
  71         Observers monitor the creation of new channels. This
  72             functionality can be used for things like message logging.
  73             All observers are notified simultaneously.
  74
  75         Approver
  76
  77           Approvers notify the user that new channels have been created,
  78             and also select which channel handler will be used for the channel,
  79             either by asking the user or by choosing the most appropriate
  80             channel handler.
  81
  82
  83         Handler
  84
  85           Each new channel or set of channels is passed to exactly one
  86             handler as its final destination. A typical channel handler is a
  87             user interface process handling channels of a particular type.
  88
  89
  90     """
  91
  92     @dbus.service.method('org.freedesktop.Telepathy.ChannelDispatcher', in_signature='oa{sv}xs', out_signature='o')
  93     def CreateChannel(self, Account, Requested_Properties, User_Action_Time, Preferred_Handler):
  94         """
  95         Start a request to create a channel. This initially just creates a
  96           ChannelRequest
  97           object, which can be used to continue the request and track its
  98           success or failure.
  99
 100
 101           The request can take a long time - in the worst case, the
 102             channel dispatcher has to ask the account manager to put the
 103             account online, the account manager has to ask the operating
 104             system to obtain an Internet connection, and the operating
 105             system has to ask the user whether to activate an Internet
 106             connection using an on-demand mechanism like dialup.
 107
 108           This means that using a single D-Bus method call and response
 109             to represent the whole request will tend to lead to that call
 110             timing out, which is not the behaviour we want.
 111
 112
 113         If this method is called for an Account that is disabled, invalid
 114           or otherwise unusable, no error is signalled until
 115           ChannelRequest.Proceed
 116           is called, at which point
 117           ChannelRequest.Failed
 118           is emitted with an appropriate error.
 119
 120
 121           This means there's only one code path for errors, apart from
 122             InvalidArgument for "that request makes no sense".
 123
 124           It also means that the request will proceed if the account is
 125             enabled after calling CreateChannel, but before calling
 126             Proceed.
 127
 128
 129         """
 130         raise NotImplementedError
 131
 132     @dbus.service.method('org.freedesktop.Telepathy.ChannelDispatcher', in_signature='oa{sv}xs', out_signature='o')
 133     def EnsureChannel(self, Account, Requested_Properties, User_Action_Time, Preferred_Handler):
 134         """
 135         Start a request to ensure that a channel exists, creating it if
 136           necessary.  This initially just creates a ChannelRequest
 137           object, which can be used to continue the request and track its
 138           success or failure.
 139
 140         If this method is called for an Account that is disabled, invalid
 141           or otherwise unusable, no error is signalled until
 142           ChannelRequest.Proceed
 143           is called, at which point
 144           ChannelRequest.Failed
 145           is emitted with an appropriate error.
 146
 147
 148           The rationale is as for CreateChannel.
 149
 150
 151         """
 152         raise NotImplementedError
 153