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

   1 # -*- coding: utf-8 -*-
   2 # Generated from the Telepathy spec
   3 """ Copyright (C) 2005, 2006 Collabora Limited
   4  Copyright (C) 2005, 2006 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 ChannelTypeContactList(dbus.service.Interface):
  27     """\
  28       A channel type for representing a list of people on the server which is
  29     not used for communication. This is intended for use with the interface
  30     Channel.Interface.Group
  31     for managing buddy lists and privacy lists
  32     on the server. This channel type has no methods because all of the
  33     functionality it represents is available via the group interface.
  34
  35     There are currently two types of contact list:
  36     HANDLE_TYPE_LIST is a "magic" server-defined list, and
  37     HANDLE_TYPE_GROUP is a user-defined contact group.
  38
  39     For server-defined lists like the subscribe list, singleton instances
  40     of this channel type should be created by the connection manager at
  41     connection time if the list exists on the server, or may be requested
  42     by using the appropriate handle.  These handles can be obtained using
  43     RequestHandles
  44     with a Handle_Type of HANDLE_TYPE_LIST and one of the
  45     following identifiers:
  46
  47
  48       subscribe - the group of contacts for whom you receive presence
  49       publish - the group of contacts who may receive your presence
  50       hide - a group of contacts who are on the publish list but are temporarily disallowed from receiving your presence
  51       allow - a group of contacts who may send you messages
  52       deny - a group of contacts who may not send you messages
  53       stored - on protocols where the user's contacts are stored, this
  54       contact list contains all stored contacts regardless of subscription
  55       status.
  56
  57
  58     A contact can be in several server-defined lists. All lists are optional
  59     to implement. If RequestHandles
  60     or RequestChannel
  61     for a particular contact list raises an error, this indicates that the
  62     connection manager makes no particular statement about the list's contents;
  63     clients MUST NOT consider this to be fatal.
  64
  65     If a client wants to list all of a user's contacts, it is appropriate to
  66     use the union of the subscribe, publish and stored lists, including the
  67     local and remote pending members.
  68
  69     For example in XMPP, contacts who have the subscription type "none",
  70     "from", "to" and "both" can be respectively in the lists:
  71
  72
  73       "none": stored
  74       "from": stored and publish
  75       "to": stored and subscribe
  76       "both": stored, publish and subscribe
  77
  78
  79     These contact list channels may not be closed.
  80
  81     For user-defined contact groups, instances of this channel type should
  82     be created by the connection manager at connection time for each group
  83     that exists on the server. New, empty groups can be created by calling
  84     RequestHandles
  85     with a Handle_Type of HANDLE_TYPE_GROUP and with the
  86     name set to the human-readable UTF-8 name of the group.
  87
  88     User-defined groups may be deleted by calling Close on the
  89     channel, but only if
  90     the group is already empty. Closing a channel to a non-empty group is
  91     not allowed; its members must be set to the empty set first.
  92
  93     On some protocols (e.g. XMPP) empty groups are not represented on the
  94     server, so disconnecting from the server and reconnecting might cause
  95     empty groups to vanish.
  96     """