git.maemo.org Git - theonering/blob - src/tp/_generated/Client.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 Client(dbus.service.Object):
  27     """\
  28       Telepathy clients use connection managers, the channel dispatcher
  29         and optionally the account manager to provide useful
  30         functionality.
  31
  32       User interface processes are the obvious example of Telepathy
  33         clients, but they can provide other functionality, such as
  34         address-book synchronization.
  35
  36       Every running or activatable process with a well-known
  37         name of the form org.freedesktop.Telepathy.Client.clientname
  38         should be probed by the channel dispatcher to discover its
  39         capabilities. Each client is either an observer, an
  40         approver, a channel handler, or some combination
  41         of these.
  42
  43
  44         Activatable services (those with a D-Bus .service
  45           file) must be supported so that we can run clients
  46           in response to channel creation.
  47
  48         Non-activatable services (those that do not register a D-Bus
  49           .service file for their well-known name, but do
  50           request it at runtime) must be supported so that we can have
  51           programs that process channels, but only if they are already
  52           running - for instance, a full-screen media centre
  53           application might do this.
  54
  55
  56       The client name, clientname, MUST be a non-empty string of
  57         ASCII digits, letters, dots and/or underscores, starting with a
  58         letter, and without sets of two consecutive dots or a dot
  59         followed by a digit. For non-activatable services, it MAY contain a
  60         part that is generated per instance at runtime.
  61
  62
  63         If each of a client Foo's instances should be able to manipulate
  64           channels separately, the instance with unique name
  65           :1.25 might request a well-known name like
  66           org.freedesktop.Telepathy.Client.Foo._1._25.
  67
  68         (Note that well-known bus-name components may not start with a
  69           digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)
  70
  71
  72       Each Client MUST export an object whose object path may be
  73         determined by replacing '.' with '/' in the well-known name and
  74         prepending '/'. This object represents its API as a Telepathy
  75         client; the channel dispatcher will call its methods and read
  76         its properties when appropriate.
  77
  78       As an optimization, activatable clients SHOULD install a file
  79         $XDG_DATA_DIRS/telepathy/clients/clientname.client
  80         containing a cached version of its immutable properties,
  81         so that for most clients, the channel dispatcher can
  82         just read a file to discover capabilities, instead of
  83         having to service-activate the client immediately in order to fetch
  84         its read-only properties. However, the D-Bus API is canonical, and
  85         the channel dispatcher MUST support clients without such a file.
  86
  87       Non-activatable clients MAY install a .client file,
  88         but there's not much point in them doing so.
  89
  90       The .client files MUST contain UTF-8 text with the same syntax
  91         as
  92         Desktop
  93           Entry files (although the allowed groups, keys and values differ).
  94         Every .client file MUST contain a group whose name is
  95         the name of this interface.
  96
  97       The groups, keys and values in the .client file are
  98         defined by individual interfaces. Each interface that can usefully
  99         cache information in the .client file SHOULD correspond
 100         to a group with the same name.
 101     """