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

   1 # -*- coding: utf-8 -*-
   2 # Generated from the Telepathy spec
   3 """Copyright (C) 2005-2008 Collabora Limited
   4 Copyright (C) 2005-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 ConnectionManager(dbus.service.Object):
  27     """\
  28     A D-Bus service which allows connections to be created. The manager
  29       processes are intended to be started by D-Bus service activation.
  30
  31     For service discovery, each Telepathy connection manager must have
  32       a connection manager name (see
  33       Connection_Manager_Name for syntax).
  34
  35     The connection manager must then provide a well-known bus name of
  36       org.freedesktop.Telepathy.ConnectionManager.cmname
  37       where cmname is its connection manager name. If it makes sense
  38       to start the connection manager using D-Bus service activation, it
  39       must register that well-known name for service activation by installing
  40       a .service file.
  41
  42     Clients can list the running connection managers by calling the
  43       ListNames method on the D-Bus daemon's org.freedesktop.DBus interface
  44       and looking for names matching the above pattern; they can list the
  45       activatable connection managers by calling ListActivatableNames, and
  46       they should usually combine the two lists to get a complete list of
  47       running or activatable connection managers.
  48
  49     When the connection manager is running, it must have an object
  50       implementing the ConnectionManager interface at the object path
  51       /org/freedesktop/Telepathy/ConnectionManager/cmname.
  52
  53
  54     Connection managers' capabilities can be determined dynamically by
  55       calling their ListProtocols method, then
  56       for each protocol of interest, calling
  57       GetParameters to discover the required and
  58       optional parameters.
  59       However, since it is inefficient to activate all possible connection
  60       managers on the system just to find out what they can do, there
  61       is a standard mechanism to store static information about CMs in
  62       ".manager files".
  63
  64     To look up a connection manager's supported protocols, clients
  65       should search the data directories specified by
  66       the
  67         freedesktop.org XDG Base Directory Specification ($XDG_DATA_HOME,
  68       defaulting to $HOME/.local/share if unset, followed by
  69       colon-separated paths from $XDG_DATA_DIRS, defaulting to
  70       /usr/local/share:/usr/share if unset) for the first file named
  71       telepathy/managers/cmname.manager that can be
  72       read without error. This file has the same syntax as a
  73       freedesktop.org Desktop Entry file.
  74
  75     Clients must still support connection managers for which no
  76       .manager file can be found, which they can do by activating
  77       the connection manager and calling its methods; the
  78       .manager file is merely an optimization. Connection managers
  79       whose list of protocols can change at any time (for instance, via
  80       a plugin architecture) should not install a .manager
  81       file.
  82
  83     For each protocol name proto that would be returned by
  84       ListProtocols, the .manager file contains a group
  85       headed [Protocol proto]. For each parameter
  86       p that would be returned by GetParameters(proto), the
  87       .manager file contains a key param-p with a value
  88       consisting of a D-Bus signature (a single complete type), optionally
  89       followed by a space and a space-separated list of flags. The supported
  90       flags are:
  91
  92
  93       required, corresponding to
  94         Conn_Mgr_Param_Flag_Required
  95       register, corresponding
  96         to Conn_Mgr_Param_Flag_Register
  97       secret, corresponding
  98         to Conn_Mgr_Param_Flag_Secret
  99       dbus-property, corresponding
 100         to Conn_Mgr_Param_Flag_DBus_Property
 101
 102
 103     The group may also contain a key default-p
 104       whose value is a string form of the default value for the parameter.
 105       If this key exists, it sets the default, and also sets the flag
 106       Conn_Mgr_Param_Flag_Has_Default. The default value is formatted
 107       according to the D-Bus signature as follows:
 108
 109
 110       s (string)
 111         The UTF-8 string, with the standard backslash escape
 112           sequences supported by the Desktop Entry Specification
 113           (the "localestring" type from the Desktop Entry Specification)
 114       o (object path)
 115         The object path as an ASCII string
 116       b (boolean)
 117         "true" (case-insensitively) or "1" means True, "false"
 118           (case-insensitively) or "0" means False
 119       y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)
 120         ASCII decimal integer
 121       n, i, x (16-, 32-, 64-bit signed integer)
 122         ASCII decimal integer, optionally prefixed with "-"
 123       d (double-precision floating point)
 124         ASCII decimal number
 125       as (array of string)
 126         A sequence of UTF-8 strings each followed by a semicolon, with
 127           any semicolons they contain escaped with a backslash
 128           (the "localestrings" type from the Desktop Entry Specification)
 129
 130
 131     Currently, no other D-Bus signatures are allowed to have default values,
 132       but clients parsing the .manager file MUST ignore defaults
 133       that they cannot parse, and treat them as if the
 134       default-p key was not present at all.
 135
 136     It is not required that a connection manager be able to support multiple
 137     protocols, or even multiple connections. When a connection is made, a
 138     service name where the connection object can be found is returned. A
 139     manager which can only make one connection may then remove itself from its
 140     well-known bus name, causing a new connection manager to be activated when
 141     somebody attempts to make a new connection.
 142     """
 143
 144     @dbus.service.method('org.freedesktop.Telepathy.ConnectionManager', in_signature='s', out_signature='a(susv)')
 145     def GetParameters(self, Protocol):
 146         """
 147         Get a list of the parameters which must or may be provided to the
 148         RequestConnection method when connecting
 149         to the given protocol,
 150         or registering (the boolean "register" parameter is available,
 151         and set to true).
 152
 153         """
 154         raise NotImplementedError
 155
 156     @dbus.service.method('org.freedesktop.Telepathy.ConnectionManager', in_signature='', out_signature='as')
 157     def ListProtocols(self):
 158         """
 159         Get a list of protocol identifiers that are implemented by this
 160         connection manager.
 161
 162         """
 163         raise NotImplementedError
 164
 165     @dbus.service.method('org.freedesktop.Telepathy.ConnectionManager', in_signature='sa{sv}', out_signature='so')
 166     def RequestConnection(self, Protocol, Parameters):
 167         """
 168         Request a
 169           Connection
 170           object representing a given account on a given
 171           protocol with the given parameters. The method returns the bus name
 172           and the object path where the new Connection object can be found,
 173           which should have the status of Connection_Status_Disconnected, to
 174           allow signal handlers to be attached before connecting is started
 175           with the
 176           Connect
 177           method.
 178
 179         The parameters which must and may be provided in the parameters
 180         dictionary can be discovered with the
 181         GetParameters method. These
 182         parameters, their types, and their default values may be cached
 183         in files so that all available connection managers do not need to be
 184         started to discover which protocols are available.
 185
 186         To request values for these parameters from the user, a client must
 187         have prior knowledge of the meaning of the parameter names, so the
 188         following well-known names and types should be used where appropriate:
 189
 190
 191           account (s)
 192           The identifier for the user's account on the server
 193
 194           server (s)
 195           A fully qualified domain name or numeric IPv4 or IPv6 address.
 196             Using the fully-qualified domain name form is recommended whenever
 197             possible. If this parameter is specified and the account for that
 198             protocol also specifies a server, this parameter should override
 199             that in the user id.
 200
 201           port (q)
 202           A TCP or UDP port number. If this parameter is specified and the
 203             account for that protocol also specifies a port, this parameter
 204             should override that in the account.
 205
 206           password (s)
 207           A password associated with the account.
 208
 209           require-encryption (b)
 210           Require encryption for this connection. A connection should fail
 211             to connect if require-encryption is set and an encrypted connection
 212             is not possible.
 213
 214           register (b)
 215           This account should be created on the server if it does not
 216             already exist.
 217
 218           ident (s)
 219           The local username to report to the server if necessary, such as
 220             in IRC.
 221
 222           fullname (s)
 223           The user's full name if the service requires this when
 224             authenticating or registering.
 225
 226           stun-server (s)
 227           The IP address or FQDN of a STUN server to use for NAT traversal,
 228             without any ":port" suffix.
 229
 230           stun-port (q)
 231           The UDP port number on the stun-server to use for STUN. Only
 232             significant if the stun-server is also supplied.
 233
 234           keepalive-interval (u)
 235           The time in seconds between pings sent to the server to ensure
 236             that the connection is still alive, or 0 to disable such
 237             pings.
 238
 239
 240         Every successful RequestConnection call will cause the emission of a
 241         NewConnection signal for the same newly
 242         created connection. The
 243         requester can use the returned object path and service name
 244         independently of the emission of that signal. In that case this signal
 245         emission is most useful for, e.g. other processes that are monitoring
 246         the creation of new connections.
 247
 248         """
 249         raise NotImplementedError
 250
 251     @dbus.service.signal('org.freedesktop.Telepathy.ConnectionManager', signature='sos')
 252     def NewConnection(self, Bus_Name, Object_Path, Protocol):
 253         """
 254         Emitted when a new Connection object
 255         is created.
 256
 257         """
 258         pass
 259