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

   1 # -*- coding: utf-8 -*-
   2 # Generated from the Telepathy spec
   3 """ Copyright (C) 2005, 2006, 2008 Collabora Limited
   4  Copyright (C) 2005, 2006, 2008 Nokia Corporation
   5  Copyright (C) 2006 INdT
   6
   7     This library is free software; you can redistribute it and/or
   8 modify it under the terms of the GNU Lesser General Public
   9 License as published by the Free Software Foundation; either
  10 version 2.1 of the License, or (at your option) any later version.
  11
  12 This library is distributed in the hope that it will be useful,
  13 but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 Lesser General Public License for more details.
  16
  17 You should have received a copy of the GNU Lesser General Public
  18 License along with this library; if not, write to the Free Software
  19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20
  21 """
  22
  23 import dbus.service
  24
  25
  26 class ConnectionInterfaceContactCapabilities(dbus.service.Interface):
  27     """\
  28       Contact capabilities describe the channel classes which may be
  29         created with a given contact in advance of attempting to create a
  30         channel. Each capability represents a commitment by the
  31         connection manager that it will ordinarily be able to create a channel
  32         with a contact when given a request with the properties defined by the
  33         channel class.
  34
  35       Capabilities pertain to particular contact handles, and represent
  36         activities such as having a text chat, a voice call with the user or a
  37         stream tube of a defined type.
  38
  39       This interface also enables user interfaces to notify the connection
  40         manager what capabilities to advertise for the user to other contacts.
  41         This is done by using the
  42         UpdateCapabilities method.
  43
  44
  45         XMPP is a major user of this interface: XMPP contacts will not,
  46           in general, be callable using VoIP unless they advertise suitable
  47           Jingle capabilities.
  48
  49         Many other protocols also have some concept of capability flags,
  50           which this interface exposes in a protocol-independent way.
  51
  52     """
  53
  54     def __init__(self):
  55         self._interfaces.add('org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities')
  56
  57     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities', in_signature='a(saa{sv}as)', out_signature='')
  58     def UpdateCapabilities(self, Handler_Capabilities):
  59         """
  60         Alter the connection's advertised capabilities to include
  61           the intersection of the given clients' capabilities with what the
  62           connection manager is able to implement.
  63
  64         On connections managed by the ChannelDispatcher, processes other
  65           than the ChannelDispatcher SHOULD NOT call this method, and the
  66           ChannelDispatcher SHOULD use this method to advertise the
  67           capabilities of all the registered Client.Handler
  68           implementations.On connections not managed by the ChannelDispatcher,
  69           clients MAY use this method directly, to indicate the channels they
  70           will handle and the extra capabilities they have.
  71
  72         Upon a successful invocation of this method, the connection manager
  73           will only emit the
  74           ContactCapabilitiesChanged signal
  75           for the user's SelfHandle
  76           if, in the underlying protocol, the new capabilities are distinct
  77           from the previous state.
  78
  79
  80           The connection manager will essentially intersect the provided
  81             capabilities and the channel classes it implements. Therefore,
  82             certain properties which are never fixed for a channel class
  83             (such as the target handle, or the Parameters property of a tube
  84             channel) will almost certainly not be advertised.
  85
  86
  87         This method MAY be called on a newly-created connection while it
  88           is still in the DISCONNECTED state, to request that when the
  89           connection connects, it will do so with the appropriate
  90           capabilities. Doing so MUST NOT fail.
  91
  92         """
  93         raise NotImplementedError
  94
  95     @dbus.service.method('org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities', in_signature='au', out_signature='a{ua(a{sv}as)}')
  96     def GetContactCapabilities(self, handles):
  97         """
  98         Returns an array of enhanced capabilities for the given contact handles.
  99
 100         """
 101         raise NotImplementedError
 102
 103     @dbus.service.signal('org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities', signature='a{ua(a{sv}as)}')
 104     def ContactCapabilitiesChanged(self, caps):
 105         """
 106         Announce that there has been a change of capabilities on the
 107           given handles. A single signal can be emitted for several
 108         contacts.
 109
 110
 111           The underlying protocol can get several contacts' capabilities at
 112             the same time.
 113
 114
 115
 116         """
 117         pass
 118