git.maemo.org Git - theonering/blob - src/tp/_generated/Channel_Type_Text.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 ChannelTypeText(dbus.service.Interface):
  27     """\
  28       A channel type for sending and receiving messages in plain text,
  29         with no formatting. In future specifications, channels for sending
  30         and receiving messages that can be reduced to plain text (i.e.
  31         formatted text) should also have this type.
  32
  33       When a message is received, an identifier is assigned and a
  34         Received signal emitted, and the message
  35         placed in a pending queue which can be inspected with
  36         ListPendingMessages. A client which has
  37         handled the message by showing it to the user (or equivalent) should
  38         acknowledge the receipt using the
  39         AcknowledgePendingMessages method,
  40         and the message will then be removed from the pending queue. Numeric
  41         identifiers for received messages may be reused over the lifetime of
  42         the channel.
  43
  44       Each message has an associated 'type' value, which should be one
  45         of the values allowed by
  46         Channel_Text_Message_Type.
  47
  48       Each message also has a flags value, which is a bitwise OR of the
  49         flags given in Channel_Text_Message_Flags.
  50
  51       Sending messages can be requested using the
  52         Send method, which will return
  53         successfully and emit the Sent signal
  54         when the message has been delivered to the server, or return an error
  55         with no signal emission if there is a failure. If a message is sent but
  56         delivery of the message later fails, this is indicated with the
  57         SendError signal.
  58
  59       On protocols where additional contacts cannot be invited into
  60         a one-to-one chat, or where a one-to-one chat is just a series of
  61         individual personal messages rather than being represented by some
  62         object on the server (i.e. most protocols), one-to-one chats should be
  63         represented by a Text channel with Handle_Type
  64         CONTACT.
  65
  66       Named chat rooms whose identity can be saved and used again later
  67         (IRC channels, Jabber MUCs) are expected to be represented by Text
  68         channels with Handle_Type ROOM and the Group
  69         interface; they should usually also have the Properties interface.
  70
  71       Unnamed, transient chat rooms defined only by their members (e.g. on
  72         MSN) are expected to be represented by Text channels with handle type
  73         0, handle 0, the Group
  74         interface, and optionally the Properties interface.
  75
  76       On protocols where a conversation with a user is actually just
  77         a nameless chat room starting with exactly two members, to which
  78         more members can be invited, calling
  79         RequestChannel
  80         with type Text
  81         and handle type CONTACT should continue to succeed, but may return
  82         a channel with handle type 0, handle 0, the group interface,
  83         and the local and remote contacts in its members.
  84
  85       If a channel of type Text is closed while it has pending messages,
  86         the connection manager MUST allow this, but SHOULD open a new,
  87         identical channel to deliver those messages, signalling it as a new
  88         channel with the
  89         NewChannel
  90         signal (with the suppress_handler parameter set to FALSE).
  91
  92       If messages were sent on the old channel but the
  93         Sentsignal has not yet been emitted
  94         for those messages, the new channel SHOULD emit Sent for those
  95         messages when appropriate - it behaves like a continuation of the
  96         old channel.
  97
  98
  99         In effect, this turns this situation, in which a client
 100           is likely to lose messages:
 101
 102
 103           UI window is closed
 104           message arrives
 105           text channel emits Received
 106           UI calls Close on text channel before it has seen the
 107             Received signal
 108           text channel emits Closed and closes
 109
 110
 111         into something nearly equivalent to this situation, which is
 112           fine:
 113
 114
 115           UI window is closed
 116           UI calls Close on text channel
 117           text channel emits Closed and closes
 118           message arrives
 119           new text channel is created, connection emits NewChannel
 120           (the same or a different) UI handles it
 121
 122
 123         suppress_handler must be set to FALSE so the replacement channel
 124           will be handled by something.
 125
 126
 127       As a result, Text channels SHOULD implement Channel.Interface.Destroyable.
 128
 129
 130         This "respawning" behaviour becomes problematic if there is no
 131           suitable handler for Text channels, or if a particular message
 132           repeatedly crashes the Text channel handler; a channel dispatcher
 133           can't just Close() the channel in these situations, because
 134           it will come back.
 135
 136         In these situations, the channel dispatcher needs a last-resort
 137           way to destroy the channel and stop it respawning. It could either
 138           acknowledge the messages itself, or use the Destroyable interface;
 139           the Destroyable interface has the advantage that it's not
 140           channel-type-dependent, so the channel dispatcher only has to
 141           understand one extra interface, however many channel types
 142           eventually need a distinction between Close and Destroy.
 143
 144
 145     """
 146
 147     @dbus.service.method('org.freedesktop.Telepathy.Channel.Type.Text', in_signature='au', out_signature='')
 148     def AcknowledgePendingMessages(self, IDs):
 149         """
 150         Inform the channel that you have handled messages by displaying them to
 151         the user (or equivalent), so they can be removed from the pending queue.
 152
 153         """
 154         raise NotImplementedError
 155
 156     @dbus.service.method('org.freedesktop.Telepathy.Channel.Type.Text', in_signature='', out_signature='au')
 157     def GetMessageTypes(self):
 158         """
 159         Return an array indicating which types of message may be sent on this
 160         channel.
 161
 162         """
 163         raise NotImplementedError
 164
 165     @dbus.service.method('org.freedesktop.Telepathy.Channel.Type.Text', in_signature='b', out_signature='a(uuuuus)')
 166     def ListPendingMessages(self, Clear):
 167         """
 168         List the messages currently in the pending queue, and optionally
 169         remove then all.
 170
 171         """
 172         raise NotImplementedError
 173
 174     @dbus.service.method('org.freedesktop.Telepathy.Channel.Type.Text', in_signature='us', out_signature='')
 175     def Send(self, Type, Text):
 176         """
 177         Request that a message be sent on this channel. When the message has
 178           been submitted for delivery, this method will return and the
 179           Sent signal will be emitted. If the
 180           message cannot be submitted for delivery, the method returns an error
 181           and no signal is emitted.
 182
 183         This method SHOULD return before the Sent signal is
 184           emitted.
 185
 186
 187           When a Text channel implements the Messages
 188             interface, that "SHOULD" becomes a "MUST".
 189
 190
 191         """
 192         raise NotImplementedError
 193
 194     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Type.Text', signature='')
 195     def LostMessage(self):
 196         """
 197         This signal is emitted to indicate that an incoming message was
 198         not able to be stored and forwarded by the connection manager
 199         due to lack of memory.
 200
 201         """
 202         pass
 203
 204     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Type.Text', signature='uuuuus')
 205     def Received(self, ID, Timestamp, Sender, Type, Flags, Text):
 206         """
 207         Signals that a message with the given id, timestamp, sender, type
 208         and text has been received on this channel. Applications that catch
 209         this signal and reliably inform the user of the message should
 210         acknowledge that they have dealt with the message with the
 211         AcknowledgePendingMessages method.
 212
 213         """
 214         pass
 215
 216     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Type.Text', signature='uuus')
 217     def SendError(self, Error, Timestamp, Type, Text):
 218         """
 219         Signals that an outgoing message has failed to send. The error
 220           will be one of the values from ChannelTextSendError.
 221
 222         This signal should only be emitted for messages for which
 223           Sent has already been emitted and
 224           Send has already returned success.
 225
 226         """
 227         pass
 228
 229     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Type.Text', signature='uus')
 230     def Sent(self, Timestamp, Type, Text):
 231         """
 232         Signals that a message has been submitted for sending.
 233
 234         """
 235         pass
 236