git.maemo.org Git - theonering/blob - src/tp/_generated/Channel_Interface_Messages.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 02110-1301,
  19 USA.
  20
  21 """
  22
  23 import dbus.service
  24
  25
  26 class ChannelInterfaceMessages(dbus.service.Interface):
  27     """\
  28       This interface extends the Text interface to support more general
  29         messages, including:
  30
  31
  32         messages with attachments (like MIME multipart/mixed)
  33         groups of alternatives (like MIME multipart/alternative)
  34         delivery reports
  35         any extra types of message we need in future
  36
  37
  38       Although this specification supports formatted (rich-text)
  39         messages with unformatted alternatives, implementations SHOULD NOT
  40         attempt to send formatted messages until the Telepathy specification
  41         has also been extended to cover capability discovery for message
  42         formatting.
  43
  44
  45         We intend to expose all rich-text messages as XHTML-IM, but on some
  46         protocols, formatting is an extremely limited subset of that format
  47         (e.g. there are protocols where foreground/background colours, font
  48         and size can be set, but only for entire messages).
  49         Until we can tell UIs what controls to offer to the user, it's
  50         unfriendly to offer the user controls that may have no effect.
  51
  52
  53       This interface also replaces Text.SendError,
  54         adding support for
  55         protocols where the message content is not echoed back to the sender on
  56         failure, adding support for receiving positive acknowledgements,
  57         and using the Messages queue for state-recovery
  58         (ensuring that incoming delivery reports are not lost if there is not
  59         currently a process handling them).
  60
  61       If this interface is present, clients that support it SHOULD
  62         listen for the MessageSent and
  63         MessageReceived signals, and
  64         ignore the Sent,
  65         SendError
  66         and Received
  67         signals on the Text interface (which are guaranteed to duplicate
  68         signals from this interface).
  69     """
  70
  71     def __init__(self):
  72         self._interfaces.add('org.freedesktop.Telepathy.Channel.Interface.Messages')
  73
  74     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Messages', in_signature='aa{sv}u', out_signature='s')
  75     def SendMessage(self, Message, Flags):
  76         """
  77         Submit a message to the server for sending.
  78           If this method returns successfully, the message has been submitted
  79           to the server and the MessageSent
  80           signal is emitted. A corresponding
  81           Sent
  82           signal on the Text interface MUST also be emitted.
  83
  84         This method MUST return before the MessageSent signal is
  85           emitted.
  86
  87
  88           This means that the process sending the message is the first
  89             to see the Sent_Message_Token, and can
  90             relate the message to the corresponding
  91             MessageSent signal by comparing
  92             message tokens (if supported by the protocol).
  93
  94
  95         If this method fails, message submission to the server has failed
  96           and no signal on this interface (or the Text interface) is
  97           emitted.
  98
  99         """
 100         raise NotImplementedError
 101
 102     @dbus.service.method('org.freedesktop.Telepathy.Channel.Interface.Messages', in_signature='uau', out_signature='a{uv}')
 103     def GetPendingMessageContent(self, Message_ID, Parts):
 104         """
 105         Retrieve the content of one or more parts of a pending message.
 106         Note that this function may take a considerable amount of time
 107         to return if the part's 'needs-retrieval' flag is true; consider
 108         extending the default D-Bus method call timeout. Additional API is
 109         likely to be added in future, to stream large message parts.
 110
 111         """
 112         raise NotImplementedError
 113
 114     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Interface.Messages', signature='aa{sv}us')
 115     def MessageSent(self, Content, Flags, Message_Token):
 116         """
 117         Signals that a message has been submitted for sending. This
 118           MUST be emitted exactly once per emission of the Sent
 119           signal on the
 120           Text interface.
 121
 122
 123           This signal allows a process that is not the caller of
 124             SendMessage to log sent messages. The double signal-emission
 125             provides compatibility with older clients. Clients supporting
 126             Messages should listen for Messages.MessageSent only (if the
 127             channel has the Messages interface) or Text.Sent only
 128             (otherwise).
 129
 130
 131         """
 132         pass
 133
 134     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Interface.Messages', signature='au')
 135     def PendingMessagesRemoved(self, Message_IDs):
 136         """
 137         The messages with the given IDs have been removed from the
 138         PendingMessages list. Clients SHOULD NOT
 139         attempt to acknowledge those messages.
 140
 141
 142           This completes change notification for the PendingMessages property
 143           (previously, there was change notification when pending messages
 144           were added, but not when they were removed).
 145
 146
 147         """
 148         pass
 149
 150     @dbus.service.signal('org.freedesktop.Telepathy.Channel.Interface.Messages', signature='aa{sv}')
 151     def MessageReceived(self, Message):
 152         """
 153         Signals that a message has been received and added to the pending
 154         messages queue. This MUST be emitted exactly once per emission of the
 155         Received
 156         signal on the Text interface.
 157
 158
 159           The double signal-emission provides compatibility with older
 160           clients. Clients supporting Messages should listen for
 161           Messages.MessageReceived only (if the channel has the Messages
 162           interface) or Text.Received only (otherwise).
 163
 164
 165         """
 166         pass
 167