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

   1 # -*- coding: utf-8 -*-
   2 # Generated from the Telepathy spec
   3 """Copyright © 2005-2009 Collabora Limited
   4 Copyright © 2005-2009 Nokia Corporation
   5 Copyright © 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 ChannelInterfaceGroup(dbus.service.Interface):
  27     """\
  28       Interface for channels which have multiple members, and where the members
  29     of the channel can change during its lifetime. Your presence in the channel
  30     cannot be presumed by the channel's existence (for example, a channel you
  31     may request membership of but your request may not be granted).
  32
  33   This interface implements three lists: a list of current members
  34     (Members), and two lists of local pending
  35     and remote pending members
  36     (LocalPendingMembers and
  37     RemotePendingMembers, respectively).
  38     Contacts on the remote
  39     pending list have been invited to the channel, but the remote user has not
  40     accepted the invitation. Contacts on the local pending list have requested
  41     membership of the channel, but the local user of the framework must accept
  42     their request before they may join. A single contact should never appear on
  43     more than one of the three lists. The lists are empty when the channel is
  44     created, and the MembersChanged signal
  45     (and, if the channel's GroupFlags contains
  46     Members_Changed_Detailed, the
  47     MembersChangedDetailed signal)
  48     should be emitted when information
  49     is retrieved from the server, or changes occur.
  50
  51   If the MembersChanged or
  52     MembersChangedDetailed signal indicates
  53     that the SelfHandle has been removed from
  54     the channel, and the channel subsequently emits Closed,
  55     clients SHOULD consider the details given in the MembersChanged or
  56     MembersChangedDetailed signal to be the reason why the channel closed.
  57
  58   Addition of members to the channel may be requested by using
  59     AddMembers. If
  60     remote acknowledgement is required, use of the AddMembers method will cause
  61     users to appear on the remote pending list. If no acknowledgement is
  62     required, AddMembers will add contacts to the member list directly.  If a
  63     contact is awaiting authorisation on the local pending list, AddMembers
  64     will grant their membership request.
  65
  66   Removal of contacts from the channel may be requested by using
  67     RemoveMembers.  If a contact is awaiting
  68     authorisation on the local pending
  69     list, RemoveMembers will refuse their membership request. If a contact is
  70     on the remote pending list but has not yet accepted the invitation,
  71     RemoveMembers will rescind the request if possible.
  72
  73   It should not be presumed that the requester of a channel implementing this
  74     interface is immediately granted membership, or indeed that they are a
  75     member at all, unless they appear in the list. They may, for instance,
  76     be placed into the remote pending list until a connection has been
  77     established or the request acknowledged remotely.
  78
  79   If the local user joins a Group channel whose members or other state
  80     cannot be discovered until the user joins (e.g. many chat room
  81     implementations), the connection manager should ensure that the channel
  82     is, as far as possible, in a consistent state before adding the local
  83     contact to the members set; until this happens, the local contact should
  84     be in the remote-pending set. For instance, if the connection manager
  85     queries the server to find out the initial members list for the
  86     channel, it should leave the local contact in the remote-pending set
  87     until it has finished receiving the initial members list.
  88
  89
  90   If the protocol provides no reliable way to tell whether the complete
  91     initial members list has been received yet, the connection manager
  92     should make a best-effort attempt to wait for the full list
  93     (in the worst case, waiting for a suitable arbitrary timeout)
  94     rather than requiring user interfaces to do so on its behalf.
  95     """
  96
  97     def __init__(self):
  98         self._interfaces.add('org.freedesktop.Telepathy.Channel.Interface.Group')
  99
 100     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='aus', out_signature='')
 101     def AddMembers(self, Contacts, Message):
 102         """
 103         Invite all the given contacts into the channel, or accept requests for
 104           channel membership for contacts on the pending local list.
 105
 106         A message may be provided along with the request, which will be sent
 107         to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and
 108         CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT
 109         GroupFlags to see in which cases this
 110         message should be provided.
 111
 112         Attempting to add contacts who are already members is allowed;
 113           connection managers must silently accept this, without error.
 114
 115         """
 116         raise NotImplementedError
 117
 118     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='', out_signature='auauau')
 119     def GetAllMembers(self):
 120         """
 121         Returns arrays of all current, local and remote pending channel
 122         members.
 123
 124         """
 125         raise NotImplementedError
 126
 127     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='', out_signature='u')
 128     def GetGroupFlags(self):
 129         """
 130         Returns the value of the GroupFlags property.
 131
 132         """
 133         raise NotImplementedError
 134
 135     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='au', out_signature='au')
 136     def GetHandleOwners(self, Handles):
 137         """
 138         If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on
 139         the channel, then the handles of the group members are specific
 140         to this channel, and are not meaningful in a connection-wide
 141         context such as contact lists. This method allows you to find
 142         the owner of the handle if it can be discovered in this channel,
 143         or 0 if the owner is not available.
 144
 145         """
 146         raise NotImplementedError
 147
 148     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='', out_signature='au')
 149     def GetLocalPendingMembers(self):
 150         """
 151         Returns the To_Be_Added handle (only) for each structure in the
 152         LocalPendingMembers property.
 153
 154         """
 155         raise NotImplementedError
 156
 157     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='', out_signature='a(uuus)')
 158     def GetLocalPendingMembersWithInfo(self):
 159         """
 160         Returns the LocalPendingMembers property.
 161
 162         """
 163         raise NotImplementedError
 164
 165     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='', out_signature='au')
 166     def GetMembers(self):
 167         """
 168         Returns the Members property.
 169
 170         """
 171         raise NotImplementedError
 172
 173     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='', out_signature='au')
 174     def GetRemotePendingMembers(self):
 175         """
 176         Returns an array of handles representing contacts who have been
 177         invited to the channel and are awaiting remote approval.
 178
 179         """
 180         raise NotImplementedError
 181
 182     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='', out_signature='u')
 183     def GetSelfHandle(self):
 184         """
 185         Returns the value of the SelfHandle
 186         property.
 187
 188         """
 189         raise NotImplementedError
 190
 191     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='aus', out_signature='')
 192     def RemoveMembers(self, Contacts, Message):
 193         """
 194         Requests the removal of contacts from a channel, reject their
 195           request for channel membership on the pending local list, or
 196           rescind their invitation on the pending remote list.
 197
 198         If the SelfHandle is in a Group,
 199           it can be removed via this method, in order to leave the group
 200           gracefully. This is the recommended way to leave a chatroom, close
 201           or reject a StreamedMedia
 202           call, and so on.
 203
 204         Accordingly, connection managers SHOULD support
 205           doing this, regardless of the value of
 206           GroupFlags.
 207           If doing so fails with PermissionDenied, this is considered to a bug
 208           in the connection manager, but clients MUST recover by falling back
 209           to closing the channel with the Close
 210           method.
 211
 212         Removing any contact from the local pending list is always
 213           allowed. Removing contacts other than the
 214           SelfHandle from the channel's members
 215           is allowed if and only if Channel_Group_Flag_Can_Remove is in the
 216           GroupFlags,
 217           while removing contacts other than the
 218           SelfHandle from the remote pending list
 219           is allowed if and only if Channel_Group_Flag_Can_Rescind is in the
 220           GroupFlags.
 221
 222         A message may be provided along with the request, which will be
 223           sent to the server if supported. See the
 224           Channel_Group_Flag_Message_Remove,
 225           Channel_Group_Flag_Message_Depart,
 226           Channel_Group_Flag_Message_Reject and
 227           Channel_Group_Flag_Message_Rescind
 228           GroupFlags to see in which cases this
 229           message should be provided.
 230
 231         """
 232         raise NotImplementedError
 233
 234     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Group', in_signature='ausu', out_signature='')
 235     def RemoveMembersWithReason(self, Contacts, Message, Reason):
 236         """
 237         As RemoveMembers, but a reason code may
 238         be provided where
 239         appropriate. The reason code may be ignored if the underlying
 240         protocol is unable to represent the given reason.
 241
 242         """
 243         raise NotImplementedError
 244
 245     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Interface.Group', signature='a{uu}au')
 246     def HandleOwnersChanged(self, Added, Removed):
 247         """
 248         Emitted whenever the HandleOwners
 249         property changes.
 250
 251         """
 252         pass
 253
 254     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Interface.Group', signature='u')
 255     def SelfHandleChanged(self, Self_Handle):
 256         """
 257         Emitted whenever the SelfHandle property
 258         changes.
 259
 260         """
 261         pass
 262
 263     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Interface.Group', signature='uu')
 264     def GroupFlagsChanged(self, Added, Removed):
 265         """
 266         Emitted when the flags as returned by
 267         GetGroupFlags are changed.
 268         The user interface should be updated as appropriate.
 269
 270         """
 271         pass
 272
 273     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Interface.Group', signature='sauauauauuu')
 274     def MembersChanged(self, Message, Added, Removed, Local_Pending, Remote_Pending, Actor, Reason):
 275         """
 276         Emitted when contacts join any of the three lists (members, local
 277           pending or remote pending) or when they leave any of the three lists.
 278           There may also be a message from the server regarding this change,
 279           which may be displayed to the user if desired.
 280
 281         All channel-specific handles that are mentioned in this signal
 282           MUST be represented in the value of the
 283           HandleOwners property.
 284           In practice, this will mean that
 285           HandleOwnersChanged is
 286           emitted before emitting a MembersChanged signal in which
 287           channel-specific handles are added, but that it is emitted
 288           after emitting a MembersChanged signal in which
 289           channel-specific handles are removed.
 290
 291         """
 292         pass
 293
 294     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Interface.Group', signature='auauauaua{sv}')
 295     def MembersChangedDetailed(self, Added, Removed, Local_Pending, Remote_Pending, Details):
 296         """
 297         Emitted when contacts join any of the three lists (members, local
 298           pending or remote pending) or when they leave any of the three
 299           lists. This signal provides a superset of the information provided by
 300           MembersChanged;
 301           if the channel's GroupFlags
 302           contains Members_Changed_Detailed, then clients may listen exclusively
 303           to this signal in preference to that signal.
 304
 305         All channel-specific handles that are mentioned in this signal
 306           MUST be represented in the value of the
 307           HandleOwners property.  In practice,
 308           this will mean that
 309           HandleOwnersChanged is emitted
 310           before emitting a MembersChangedDetailed signal in which
 311           channel-specific handles are added, but that it is emitted
 312           after emitting a MembersChangedDetailed signal in which
 313           channel-specific handles are removed.
 314
 315         """
 316         pass
 317