path: root/spec/Channel_Interface_Messages.xml

<?xml version="1.0" ?>
<node name="/Channel_Interface_Messages"
  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
    <p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>

<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.</p>

<p>You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
USA.</p>
  </tp:license>
  <interface
    name="org.freedesktop.Telepathy.Channel.Interface.Messages">
    <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
    <tp:added version="0.17.16">(as stable API)</tp:added>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>This interface extends the Text interface to support more general
        messages, including:</p>

      <ul>
        <li>messages with attachments (like MIME multipart/mixed)</li>
        <li>groups of alternatives (like MIME multipart/alternative)</li>
        <li>delivery reports</li>
        <li>any extra types of message we need in future</li>
      </ul>

      <p>Although this specification supports formatted (rich-text)
        messages with unformatted alternatives, implementations SHOULD NOT
        attempt to send formatted messages until the Telepathy specification
        has also been extended to cover capability discovery for message
        formatting.</p>

      <tp:rationale>
        We intend to expose all rich-text messages as XHTML-IM, but on some
        protocols, formatting is an extremely limited subset of that format
        (e.g. there are protocols where foreground/background colours, font
        and size can be set, but only for entire messages).
        Until we can tell UIs what controls to offer to the user, it's
        unfriendly to offer the user controls that may have no effect.
      </tp:rationale>

      <p>This interface also replaces <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>,
        adding support for
        protocols where the message content is not echoed back to the sender on
        failure, adding support for receiving positive acknowledgements,
        and using the Messages queue for state-recovery
        (ensuring that incoming delivery reports are not lost if there is not
        currently a process handling them).</p>

      <p>If this interface is present, clients that support it SHOULD
        listen for the <tp:member-ref>MessageSent</tp:member-ref> and
        <tp:member-ref>MessageReceived</tp:member-ref> signals, and
        ignore the <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>,
        <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref>
        and <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref>
        signals on the Text interface (which are guaranteed to duplicate
        signals from this interface).</p>
    </tp:docstring>

    <property name="SupportedContentTypes" type="as" access="read"
      tp:name-for-bindings="Supported_Content_Types">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>A list of MIME types supported by this channel, with more preferred
          MIME types appearing earlier in the list. The list MAY include "*/*"
          to indicate that attachments with arbitrary MIME types can be sent.
          This list MUST NOT be empty, since all Messages implementations
          MUST accept messages containing a single "text/plain" part.</p>

        <p>Some examples of how this property interacts with the
          <tp:member-ref>MessagePartSupportFlags</tp:member-ref>:</p>

        <dl>
          <dt>A simple IM implementation: only plain text messages are
            allowed</dt>
          <dd>SupportedContentTypes = ['text/plain'],
            MessagePartSupportFlags = 0</dd>

          <dt>Formatted text with a plain text alternative is allowed (see the
            HTML interface draft)</dt>
          <dd>SupportedContentTypes = ['text/html', 'text/plain'],
            MessagePartSupportFlags = 0</dd>

          <dt>JPEG or PNG images may be sent, but without any attached
            text</dt>
          <dd>SupportedContentTypes = ['text/plain', 'image/jpeg',
            'image/png'], MessagePartSupportFlags = 0</dd>

          <dt>Unformatted text to which an optional JPEG or PNG image may be
            attached</dt>
          <dd>SupportedContentTypes = ['text/plain', 'image/jpeg',
            'image/png'], MessagePartSupportFlags = One_Attachment</dd>

          <dt>Formatted text to which arbitrarily many images may be
            attached</dt>
          <dd>SupportedContentTypes = ['text/html', 'text/plain', 'image/jpeg',
            'image/png', 'image/x-ms-bmp'], MessagePartSupportFlags =
            One_Attachment | Multiple_Attachments</dd>

          <dt>A full SIP implementation: arbitrary MIME messages are
            allowed</dt>
          <dd>SupportedContentTypes = ['*/*'], MessagePartSupportFlags =
            One_Attachment | Multiple_Attachments</dd>
        </dl>
      </tp:docstring>
    </property>

    <property name="MessagePartSupportFlags" type="u"
      tp:type="Message_Part_Support_Flags" access="read"
      tp:name-for-bindings="Message_Part_Support_Flags">
      <tp:docstring>
        Flags indicating the level of support for message parts on this
        channel.
      </tp:docstring>
    </property>

    <tp:flags name="Message_Part_Support_Flags"
      value-prefix="Message_Part_Support_Flag" type="u">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Flags indicating the level of support for message parts on this
          channel. They are designed such that setting more flags always
          implies that the channel has more capabilities.</p>

        <p>If no flags are set, this indicates that messages may contain
          a single message part whose content-type is any of the types
          from SupportedContentTypes, possibly with some alternatives.</p>

        <p>There is no flag indicating support for alternatives. This is
          because the SendMessage implementation can always accept messages
          containing alternatives, even if the underlying protocol does not,
          by deleting all alternatives except the first (most preferred)
          that is supported.</p>

        <tp:rationale>
          Each of the flags so far implies the previous flag, so we could
          have used a simple enumeration here; however, we've defined
          the message-part support indicator as a flag set for future
          expansion.
        </tp:rationale>

        <p>See <tp:member-ref>SupportedContentTypes</tp:member-ref> for some
          examples.</p>
      </tp:docstring>

      <tp:flag suffix="One_Attachment" value="1">
        <tp:docstring>
          <tp:member-ref>SendMessage</tp:member-ref> will accept messages
          containing a textual message body,
          plus a single attachment of any type listed in the
          SupportedContentTypes property. It does not make sense for this
          flag to be set if Message_Part_Support_Flag_Data_Only is not also set
          (because the connection manager can trivially provide an empty text
          part if necessary).
        </tp:docstring>
      </tp:flag>
      <tp:flag suffix="Multiple_Attachments" value="2">
        <tp:docstring>
          SendMessage will accept messages containing a textual message body,
          plus an arbitrary number of attachments of any type listed in the
          SupportedContentTypes property. It does not make sense for this
          flag to be set if Message_Part_Support_Flag_One_Attachment is not
          also set.
        </tp:docstring>
      </tp:flag>
    </tp:flags>

    <tp:mapping name="Message_Part" array-name="Message_Part_List"
      array-depth="2">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Part of a message's content. In practice, this mapping never
          appears in isolation - messages are represented by a list of
          <tp:type>Message_Part</tp:type> mappings.</p>

        <p>An example of how a rich-text message, with an embedded image, might
          look, in a Python-like syntax:</p>

          <pre>
[
  {
    'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
    'message-sender': 42,
    'message-sent': 1210067943,
    'message-received': 1210067947,
    'message-type': 0,              # = Channel_Text_Message_Type_Normal
    'pending-message-id': 437,
  },
  { 'alternative': 'main',
    'content-type': 'text/html',
    'content': 'Here is a photo of my cat:&lt;br /&gt;' +
               '&lt;img src="cid:catphoto" alt="lol!" /&gt;' +
               '&lt;br /&gt;Isn't it cute?',
  },
  { 'alternative': 'main',
    'content-type': 'text/plain',
    'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
  },
  { 'identifier': 'catphoto',
    'content-type': 'image/jpeg',
    'size': 101000,
    'needs-retrieval': True,
  },
]</pre>

        <p>An example of how a non-text message — in particular, a vCard sent
          via SMS as implemented by telepathy-ring on Nokia's Maemo 5 —
          looks:</p>

        <pre>
[
  {
    'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
    'message-sender': 42,
    'message-sent': 1210067943,
    'message-received': 1210067947,
    'message-type': 0,              # = Channel_Text_Message_Type_Normal
    'pending-message-id': 437,
  },
  { 'content-type': 'text/x-vcard',
    'content': [ 0x66, 0x69, 0x71, ...], # vCard data as an array of bytes
  },
]</pre>

        <div>
          <p>The first part of the message contains "headers" which refer
            to the entire message.</p>

          <p>It is an error for a connection manager to put keys referring
            to the message as a whole in the second or subsequent
            Message_Part, but clients MUST recover from this error by ignoring
            these keys in the second and subsequent parts.</p>

          <tp:rationale>
            <p>Instead of representing messages as aa{sv} where the first
              dictionary is special (a dictionary of headers), we could have
              used a signature like (a{sv}aa{sv}) to separate out the headers
              and the body parts.</p>

            <p>However, this would make access to the messages more awkward.
              In Python, the syntax for access to a header field would remain
              <code>message[0]['message-type']</code>, but access to a body
              field in the second body part would change from
              message[2]['content'] to message[1][1]['content']. In GLib,
              the message would change from being a
              GPtrArray(GHashTable) to being a
              GValueArray(GHashTable, GPtrArray(GHashTable)) which is rather
              inconvenient to dereference.</p>
          </tp:rationale>

          <p>Well-known keys for the message as a whole, and the corresponding
            value types, include:</p>

          <dl>
            <dt>message-token (s)</dt>
            <dd>
              <p>An opaque, globally-unique identifier for the entire message.
                This MAY be treated as if it were a MIME Message-ID, e.g. for
                the mid: and cid: URI schemes. If omitted, there is no suitable
                token; the protocol-token key SHOULD be provided if the protocol
                identifies messages in some less unique way.</p>
            </dd>

            <dt>protocol-token (s - <tp:type>Protocol_Message_Token</tp:type>)</dt>
            <dd>
              <p>An opaque token for the entire message, with whatever uniqueness
                guarantee is provided by the underlying protocol. As described
                for the Protocol_Message_Token type, this token is <em>not</em>
                guaranteed to be unique between contacts, or even within the
                scope of a Channel.</p>

              <tp:rationale>
                <p>In practice, in most protocols there is no token with the
                  uniqueness guarantees demanded for message-token; the
                  definition of message-token was inappropriate, but must now
                  be preserved for the benefit of clients that rely on it, at
                  least until Telepathy breaks backwards compatibility.</p>
              </tp:rationale>

              <p>The message-token and protocol-token SHOULD NOT both be present;
                clients requiring an identifier with the semantics of the
                protocol-token SHOULD look for the message-token first, falling
                back to the protocol-token.</p>

              <tp:rationale>
                <p>This is for compatibility with CMs older than the
                  protocol-token key.</p>
              </tp:rationale>
            </dd>

            <dt>message-sent (x - <tp:type>Unix_Timestamp64</tp:type>)</dt>
            <dd>The time the message was sent (if unavailable, the time
              it arrived at a central server MAY be used). Omitted if no
              reasonable approximation is available; SHOULD always be present
              on outgoing messages.</dd>

            <dt>message-received (x - <tp:type>Unix_Timestamp64</tp:type>)</dt>
            <dd>The time the message was received locally. SHOULD always
              be present.</dd>

            <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>)</dt>
            <dd>The contact who sent the message. If 0 or omitted, the contact
              who sent the message could not be determined.</dd>

            <dt>sender-nickname (s)</dt>
            <dd>The nickname chosen by the sender of the message, which can be
              different for each message in a conversation.</dd>

            <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>)
            </dt>
            <dd>The type of message; if omitted,
              Channel_Text_Message_Type_Normal MUST be assumed. MAY
              be omitted for normal chat messages.</dd>

            <dt>pending-message-id (u - <tp:type>Message_ID</tp:type>)</dt>
            <dd>The incoming message ID. This MUST NOT be present on outgoing
              messages. Clients SHOULD NOT store this key - it is only valid
              for as long as the message remains unacknowledged.</dd>

            <dt>interface (s - <tp:type>DBus_Interface</tp:type>)</dt>
            <dd>This message is specific to the given interface, which is
              neither Text nor Messages. It SHOULD be ignored if that
              interface is not supported. (Note that an 'interface' key
              can also appear on the second and subsequent parts, where
              it indicates that that part (only) should be ignored if
              unsupported.)</dd>

            <dt>scrollback (b)</dt>
            <dd>If present and true, the incoming message was part of a
              replay of message history (this matches the Scrollback flag in
              <tp:type>Channel_Text_Message_Flags</tp:type>). This flag
              does not make sense on outgoing messages and SHOULD NOT
              appear there.</dd>

            <dt>rescued (b)</dt>
            <dd>If present and true, the incoming message has been seen in
              a previous channel during the lifetime of the Connection,
              but had not been acknowledged when that channel closed, causing
              an identical channel (in which the message now appears) to open.
              This matches the Rescued flag in
              <tp:type>Channel_Text_Message_Flags</tp:type>; it
              does not make sense on outgoing messages, and SHOULD NOT
              appear there.</dd>
          </dl>
        </div>

        <div>
          <p>The second and subsequent parts contain the message's
            content, including plain text, formatted text and/or attached
            files.</p>

          <p>It is an error for a connection manager to put keys referring
            to the message body in the first Message_Part;
            clients MUST recover from this error by ignoring
            these keys in first part.</p>

          <p>In any group of parts with the same non-empty value for the
            "alternative" key (which represent alternative versions of the
            same content), more faithful versions of the intended message MUST
            come before less faithful versions (note that this order is the
            opposite of MIME "multipart/alternative" parts). Clients SHOULD
            display the first alternative that they understand.</p>

          <tp:rationale>
            <p>Specifying the preference order means that if the underlying
              protocol doesn't support alternatives, the CM can safely delete
              everything apart from the first supported alternative when
              sending messages.</p>

            <p>The order is the reverse of MIME because MIME's rationale for
              placing the "plainest" part first (legibility in pre-MIME UAs)
              does not apply to us, and placing the most preferred part
              first simplifies display (a client can iterate the message
              in order, display the first alternative that it understands,
              and skip displaying all subsequent parts with the same
              "alternative" key).</p>
          </tp:rationale>

          <p>Clients SHOULD present all parts that are not redundant
            alternatives in the order they appear in this array, possibly
            excluding parts that are referenced by another displayed part.
            It is implementation-specific how the parts are presented to the
            user.</p>

          <tp:rationale>
            <p>This allows CMs to assume that all parts are actually shown to
              the user, even if they are not explicitly referenced - we do
              not yet recommend formatted text, and there is no way for
              plain text to reference an attachment since it has no concept of
              markup or references. This also forces clients to do something
              sensible with messages that consist entirely of "attachments",
              with no "body" at all.</p>

            <p>For instance, when displaying the above example, a client that
              understands the HTML part should display the JPEG image once,
              between the two lines "Here is a photo of my cat:" and
              "Isn't it cute?"; it may additionally present the image in some
              way for a second time, after "Isn't it cute?", or may choose
              not to.</p>

            <p>A client that does not understand HTML, displaying the same
              message, should display the plain-text part, followed by the JPEG
              image.</p>
          </tp:rationale>

          <p>Well-known keys for the second and subsequent parts, and the
            corresponding value types, include:</p>

          <dl>
            <dt>identifier (s)</dt>
            <dd>An opaque identifier for this part.
              Parts of a message MAY reference other parts by treating
              this identifier as if it were a MIME Content-ID and using
              the cid: URI scheme.</dd>

            <dt>alternative (s)</dt>
            <dd>
              <p>If present, this part of the message is an alternative for
                all other parts with the same value for "alternative".
                Clients SHOULD only display one of them (this is expected to
                be used for XHTML messages in a future version of this
                specification).</p>

              <p>If omitted, this part is not an alternative for any other
                part.</p>

              <p>Parts of a message MAY reference the group of alternatives
                as a whole (i.e. a reference to whichever of them is chosen)
                by treating this identifier as if it were the MIME Content-ID
                of a multipart/alternative part, and using the cid: URI
                scheme.</p>
            </dd>

            <dt>content-type (s)</dt>
            <dd>
              <p>The MIME type of this part. See the documentation
                for ReceivedMessage for notes on the special status of
                "text/plain" parts.</p>

              <p>Connection managers MUST NOT signal parts without a
                'content-type' key; if a protocol provides no way to determine
                the MIME type, the connection manager is responsible for
                guessing it, but MAY fall back to "text/plain" for text and
                "application/octet-stream" for non-text.</p>

              <p>Clients MUST ignore parts without a 'content-type' key, which
                are reserved for future expansion.</p>
            </dd>

            <dt>lang (s)</dt>
            <dd>The natural language of this part, identified by a
              RFC 3066 language tag.

              <tp:rationale>
                XMPP allows alternative-selection by language as well as
                by content-type.
              </tp:rationale>
            </dd>

            <dt>size (u)</dt>
            <dd>The size in bytes (if needs-retrieval is true, this MAY be an
              estimated or approximate size). SHOULD be omitted if 'content'
              is provided.

              <tp:rationale>
                There's no point in providing the size if you're already
                providing all the content.
              </tp:rationale>
            </dd>

            <dt>thumbnail (b)</dt>
            <dd>
              <p>This part is a thumbnail. To represent an image together with
                its thumbnail in a single message, there should be one part for
                the full image followed by a part for the thumbnail (following
                the “more complete versions first” requirement), with the same
                'alternative' value. For example:</p>

              <pre>
[ ... ,
  { 'alternative': 'catphoto',
    'content-type': 'image/jpeg',
    'size': 150000,
    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
  },
  { 'alternative': 'catphoto',
    'content-type': 'image/jpeg'
    'size': 1024,
    'thumbnail': True,
    'content': [0xFF, 0xD8, ... 0xFF 0xD9],
  },
  ...
]
              </pre>
            </dd>

            <dt>needs-retrieval (b)</dt>
            <dd>If false or omitted, the connection
              manager already holds this part in memory. If present and true,
              this part will be retrieved on demand (like MIME's
              message/external-body), so clients should expect retrieval to
              take time; if this specification is later extended to provide a
              streaming version of GetPendingMessageContent, clients should
              use it for parts with this flag.</dd>

            <dt>truncated (b)</dt>
            <dd>The content available via the 'content' key or
              GetPendingMessageContent has been truncated by the server
              or connection manager (equivalent to
              Channel_Text_Message_Flag_Truncated in the Text interface).
            </dd>

            <dt>content (s or ay)</dt>
            <dd>The part's content, if it is available and
              sufficiently small to include here (implies that
              'needs-retrieval' is false or omitted). Otherwise, omitted.
              If the part is human-readable text or HTML, the value for this
              key MUST be a UTF-8 string (D-Bus signature 's').
              If the part is not text, the value MUST be a byte-array
              (D-Bus signature 'ay'). If the part is a text-based format
              that is not the main body of the message (e.g. an iCalendar
              or an attached XML document), the value SHOULD be a UTF-8 string,
              transcoding from another charset to UTF-8 if necessary, but
              MAY be a byte-array (of unspecified character set) if
              transcoding fails or the source charset is not known.</dd>

              <!-- FIXME: "sufficiently small to include" is not currently
              defined; we should add some API so clients can tell the
                CM how large a message it should emit in the signal.-->

            <dt>interface (s - <tp:type>DBus_Interface</tp:type>)</dt>
            <dd>This part is specific to the given interface, which is
              neither Text nor Messages. It SHOULD be ignored if that
              interface is not supported. (Note that an 'interface' key
              can also appear on the first part, where it indicates that the
              entire message should be ignored if unsupported.)</dd>
          </dl>

        </div>


        <div>
          <p>Delivery reports are also represented as messages, of type
            Channel_Text_Message_Type_Delivery_Report, with the
            Non_Text_Content flag in the Text interface.</p>

          <p>Whenever a message of type
            Channel_Text_Message_Type_Delivery_Report is signalled for a
            delivery error report, Channel.Type.Text.SendError SHOULD also
            be emitted; whenever Channel.Type.Text.SendError is emitted by a
            channel which supports this interface, a message of type
            Channel_Text_Message_Type_Delivery_Report MUST also be emitted.</p>

          <p>The corresponding message in the Messages interface MUST contain
            "headers" for the delivery report, as specified below, in its
            first Message_Part.</p>

          <dl>
            <dt>message-sender (u - Contact_Handle as defined above)</dt>
            <dd>MUST be the intended recipient of the original message, if
              available (zero or omitted if the intended recipient is
              unavailable or is not a contact, e.g. a chatroom), even if the
              delivery report actually came from an intermediate server.</dd>

            <dt>message-type (u - Channel_Text_Message_Type as defined
              above)</dt>
            <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd>

            <dt>delivery-status (u - Delivery_Status)</dt>
            <dd>The status of the message. All delivery reports MUST contain
              this key in the first Message_Part.</dd>

            <dt>delivery-token (s - <tp:type>Protocol_Message_Token</tp:type>)</dt>

            <dd>
              <p>An identifier for the message to which this delivery report
                refers. MUST NOT be an empty string. Omitted if not
                available.</p>

              <p>Clients may match this against the token produced by the
                SendMessage method and MessageSent signal. A status report
                with no token could match any sent message, and a sent
                message with an empty token could match any status report.
                If multiple sent messages match, clients SHOULD use some
                reasonable heuristic.</p>

              <tp:rationale>
                In an ideal world, we could unambiguously match reports
                against messages; however, deployed protocols are not ideal,
                and not all reports and messages can be matched.
              </tp:rationale>
            </dd>

            <dt>delivery-error (u - Channel_Text_Send_Error)</dt>
            <dd>
              The reason for the failure. MUST be omitted if this was a
              successful delivery; SHOULD be omitted if it would be
              Channel_Text_Send_Error_Unknown.
            </dd>

            <dt>delivery-dbus-error (s - DBus_Error_Name)</dt>
            <dd>
              The reason for the failure, specified as a (possibly
              implementation-specific) D-Bus error. MUST be omitted if this was
              a successful delivery. If set, the 'delivery-error' key SHOULD be
              set to the closest available value.
            </dd>

            <dt>delivery-error-message (s)</dt>
            <dd>
              Debugging information on why the message could not be delivered.
              MUST be omitted if this was a successful delivery; MAY always be
              omitted.
            </dd>

            <dt>delivery-echo (aa{sv} - Message_Part[])</dt>
            <dd>
              <p>The message content, as defined by the Messages interface.
                Omitted if no content is available. Content MAY have been
                truncated, message parts MAY have been removed, and message
                parts MAY have had their content removed (i.e. the message part
                metadata is present, but the 'content' key is not).</p>

              <tp:rationale>
                Some protocols, like XMPP, echo the failing message back to
                the sender. This is sometimes the only way to match it
                against the sent message, so we include it here.
              </tp:rationale>

              <p>Unlike in the Messages interface, content not visible
                in the value for this key cannot be retrieved by another
                means, so the connection manager SHOULD be more
                aggressive about including (possibly truncated) message
                content in the 'content' key.</p>

              <tp:rationale>
                The Messages interface needs to allow all content to be
                retrieved, but in this interface, the content we provide is
                merely a hint; so some is better than none, and it doesn't
                seem worth providing an API as complex as Messages'
                GetPendingMessageContent for the echoed message.
              </tp:rationale>
            </dd>

          </dl>

          <p>The second and subsequent Message_Part dictionaries, if present,
            are a human-readable report from the IM service.</p>

          <p>Clients MUST NOT attempt to send delivery reports using the
            SendMessage method in the Messages API, and connection managers
            MUST NOT allow this to be done. If support for sending delivery
            reports is later added, it will be part of this interface.</p>

          <p>Some example delivery reports in a Python-like syntax (in which
            arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2})
            follow.</p>

          <dl>
            <dt>A minimal delivery report indicating permanent failure of the
              sent message whose token was
              <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown
              reason</dt>
            <dd><pre>
[{
# header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]
</pre></dd>

            <dt>A delivery report where the failed message is echoed back to the
              sender rather than being referenced by ID, and the failure reason
              is that this protocol cannot send messages to offline contacts
              such as the contact with handle 123</dt>
            <dd><pre>
[{ # header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Temporarily_Failed,
'delivery-error': Channel_Text_Send_Error_Offline,
'delivery-echo':
    [{ # header of original message
    'message-sender': 1,
    'message-sent': 1210067943,
    },
    { # body of original message
    'content-type': 'text/plain',
    'content': 'Hello, world!',
    }]
  ],

# no body
]
</pre></dd>

            <dt>A maximally complex delivery report: the server reports a
              bilingual human-readable failure message because the user sent
              a message "Hello, world!" with token
              <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact
              with handle 123, but that handle represents a contact who does not
              actually exist</dt>
            <dd><pre>
[{ # header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Permanently_Failed,
'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
'delivery-echo':
    [{ # header of original message
    'message-sender': 1,
    'message-sent': 1210067943,
    },
    { # body of original message
    'content-type': 'text/plain',
    'content': 'Hello, world!',
    }]
  ],
},
{ # message from server (alternative in English)
'alternative': '404',
'content-type': 'text/plain',
'lang': 'en',
'content': 'I have no contact with that name',
},
{ # message from server (alternative in German)
'alternative': '404'.
'content-type': 'text/plain',
'lang': 'de',
'content', 'Ich habe keinen Kontakt mit diesem Namen',
}
]
</pre></dd>

            <dt>A minimal delivery report indicating successful delivery
              of the sent message whose token was
              <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt>
            <dd><pre>
[{
# header
'message-sender': 123,
'message-type': Channel_Text_Message_Type_Delivery_Report,
'delivery-status': Delivery_Status_Delivered,
'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
}
# no body
]
</pre></dd>

          </dl>

        </div>
      </tp:docstring>

      <tp:member name="Key" type="s">
        <tp:docstring>
          A key, which SHOULD be one of the well-known keys specified, if
          possible.
        </tp:docstring>
      </tp:member>

      <tp:member name="Value" type="v">
        <tp:docstring>
          The value corresponding to the given key, which must be of one of
          the types indicated.
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <tp:simple-type type="u" name="Message_Part_Index"
      array-name="Message_Part_Index_List">
      <tp:added version="0.17.17"/>
      <tp:docstring>
        The index of a message part within a message.
      </tp:docstring>
    </tp:simple-type>

    <tp:mapping name="Message_Part_Content_Map">
      <tp:added version="0.17.17"/>
      <tp:docstring>
        A mapping from message part indexes to their content, as returned by
        <tp:member-ref>GetPendingMessageContent</tp:member-ref>.
      </tp:docstring>

      <tp:member type="u" tp:type="Message_Part_Index" name="Part">
        <tp:docstring>
          Indexes into the array of <tp:type>Message_Part</tp:type>s that
          represents a message. The "headers" part (which is not a valid
          argument to GetPendingMessageContent) is considered to be part 0,
          so the valid part numbers start at 1 (for the second message part).
        </tp:docstring>
      </tp:member>

      <tp:member type="v" name="Content">
        <tp:docstring>
          The message part's content. The variant MUST contain either type
          's' or 'ay' (UTF-8 text string, or byte array), following the
          same rules as for the value of the 'content' key in
          the <tp:type>Message_Part</tp:type> mappings.
        </tp:docstring>
      </tp:member>
    </tp:mapping>

    <tp:simple-type type="s" name="Protocol_Message_Token">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>An opaque token used to identify messages in the underlying.
          protocol. As a special case, the empty string indicates that there
          is no particular identification for a message.</p>

        <p>CM implementations SHOULD use an identifier expected to be unique,
          such as a UUID, if possible.</p>

        <p>Some protocols can only track a limited number of messages
          in a small message-ID space (SMS messages are identified by a single
          byte), and some implementations send non-unique identifiers (some
          XMPP clients use very simple message IDs, such as an incrementing
          integer that resets to 1 at the beginning of each connection). As a
          result, clients MUST NOT assume that protocol tokens will not be
          re-used.</p>

        <p>In particular, clients SHOULD use a heuristic to assign delivery
          reports to messages, such as matching on message content or
          timestamp (if available), or assuming that the delivery report
          refers to the most recent message with that ID.</p>
      </tp:docstring>
    </tp:simple-type>

    <method name="SendMessage" tp:name-for-bindings="Send_Message">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Submit a message to the server for sending.
          If this method returns successfully, the message has been submitted
          to the server and the <tp:member-ref>MessageSent</tp:member-ref>
          signal is emitted. A corresponding
          <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>
          signal on the Text interface MUST also be emitted.</p>

        <p>This method MUST return before the MessageSent signal is
          emitted.</p>

        <tp:rationale>
          <p>This means that the process sending the message is the first
            to see the <tp:type>Protocol_Message_Token</tp:type>, and can
            relate the message to the corresponding
            <tp:member-ref>MessageSent</tp:member-ref> signal by comparing
            message tokens (if supported by the protocol).</p>
        </tp:rationale>

        <p>If this method fails, message submission to the server has failed
          and no signal on this interface (or the Text interface) is
          emitted.</p>
      </tp:docstring>

      <arg direction="in" type="aa{sv}" tp:type="Message_Part[]"
        name="Message">
        <tp:docstring>
          The message content, including any attachments or alternatives
        </tp:docstring>
      </arg>
      <arg direction="in" name="Flags" type="u"
        tp:type="Message_Sending_Flags">
        <tp:docstring>
          Flags affecting how the message is sent.
        </tp:docstring>
      </arg>

      <arg direction="out" type="s" tp:type="Protocol_Message_Token"
        name="Token">
        <tp:docstring>
          An opaque token used to match any incoming delivery or failure
          reports against this message, or an empty string if the message
          is not readily identifiable.
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring>
            The requested message is malformed and cannot be sent.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
      </tp:possible-errors>
    </method>

    <tp:flags name="Message_Sending_Flags" value-prefix="Message_Sending_Flag"
      type="u">
      <tp:docstring>
        Flags altering the way a message is sent. The "most usual" action
        should always be to have these flags unset.
      </tp:docstring>

      <tp:flag suffix="Report_Delivery" value="1">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>Provide a successful delivery report if possible, even if this is
            not the default for this protocol. Ignored if delivery reports are
            not possible on this protocol.</p>

          <tp:rationale>
            <p>In some protocols, like XMPP, it is not conventional to request
              or send positive delivery notifications.</p>
          </tp:rationale>

          <p>Delivery failure reports SHOULD always be sent, but if this flag
            is present, the connection manager MAY also try harder to obtain
            failed delivery reports or allow them to be matched to outgoing
            messages.</p>
        </tp:docstring>
      </tp:flag>
    </tp:flags>

    <signal name="MessageSent" tp:name-for-bindings="Message_Sent">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>Signals that a message has been submitted for sending. This
          MUST be emitted exactly once per emission of the <tp:dbus-ref
            namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>
          signal on the Text interface. This SHOULD be emitted as soon as
          the CM determines it's theoretically possible to send the message
          (e.g. the parameters are supported and correct).</p>

        <tp:rationale>
          <p>This signal allows a process that is not the caller of
            SendMessage to log sent messages. The double signal-emission
            provides compatibility with older clients. Clients supporting
            Messages should listen for Messages.MessageSent only (if the
            channel has the Messages interface) or Text.Sent only
            (otherwise).</p>
        </tp:rationale>
      </tp:docstring>

      <arg type="aa{sv}" tp:type="Message_Part[]" name="Content">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The message content (see <tp:type>Message_Part</tp:type> for full
            details). If the message that was passed to SendMessage has a
            formatted text part that the connection manager recognises, but no
            text/plain alternative, the CM MUST use the formatted text part to
            generate a text/plain alternative which is also included in this
            signal argument.</p>

          <p>If the connection manager can predict that the message will be
            altered during transmission, this argument SHOULD reflect what
            other contacts will receive, rather than being a copy of the
            argument to SendMessage (if the message is truncated,
            formatting or alternatives are dropped, etc., then the edited
            version SHOULD appear in this signal).</p>
        </tp:docstring>
      </arg>

      <arg name="Flags" type="u" tp:type="Message_Sending_Flags">
        <tp:docstring>
          <p>Flags affecting how the message was sent.  The flags might be a
            subset of those passed to SendMessage if the caller requested
            unsupported flags.</p>
        </tp:docstring>
      </arg>

      <arg name="Message_Token" type="s" tp:type="Protocol_Message_Token">
        <tp:docstring>
          An opaque token used to match any incoming delivery or failure
          reports against this message, or an empty string if the message
          is not readily identifiable.
        </tp:docstring>
      </arg>
    </signal>

    <property name="PendingMessages" type="aaa{sv}" access="read"
      tp:type="Message_Part[][]" tp:name-for-bindings="Pending_Messages">
      <tp:docstring>
        A list of incoming messages that have neither been acknowledged nor
        rejected. This list is a more detailed version of the one returned
        by <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Type">Text.ListPendingMessages</tp:dbus-ref>,
        and contains the same messages, uniquely identified by the same
        pending message IDs. Its items can be removed using
        <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>.
      </tp:docstring>
    </property>

    <signal name="PendingMessagesRemoved"
      tp:name-for-bindings="Pending_Messages_Removed">
      <tp:docstring>
        The messages with the given IDs have been removed from the
        <tp:member-ref>PendingMessages</tp:member-ref> list. Clients SHOULD NOT
        attempt to acknowledge those messages.

        <tp:rationale>
          This completes change notification for the PendingMessages property
          (previously, there was change notification when pending messages
          were added, but not when they were removed).
        </tp:rationale>
      </tp:docstring>

      <arg name="Message_IDs" type="au" tp:type="Message_ID[]">
        <tp:docstring>
          The messages that have been removed from the pending message list.
        </tp:docstring>
      </arg>
    </signal>

    <method name="GetPendingMessageContent"
      tp:name-for-bindings="Get_Pending_Message_Content">
      <tp:docstring>
        Retrieve the content of one or more parts of a pending message.
        Note that this function may take a considerable amount of time
        to return if the part's 'needs-retrieval' flag is true; consider
        extending the default D-Bus method call timeout. Additional API is
        likely to be added in future, to stream large message parts.
      </tp:docstring>

      <arg name="Message_ID" type="u" tp:type="Message_ID" direction="in">
        <tp:docstring>
          The ID of a pending message
        </tp:docstring>
      </arg>

      <arg name="Parts" type="au" direction="in"
        tp:type="Message_Part_Index[]">
        <tp:docstring>
          The desired entries in the array of message parts, identified by
          their position. The "headers" part (which is not a valid argument
          to this method) is considered to be part 0, so the valid part
          numbers start at 1 (for the second Message_Part).
        </tp:docstring>
      </arg>

      <arg name="Content" type="a{uv}" direction="out"
        tp:type="Message_Part_Content_Map">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          <p>The content of the requested parts. The keys in this mapping
            are positions in the array of message parts; the values are
            either of type 's' or 'ay' (UTF-8 text string, or byte array),
            following the same rules as for the value of the 'content' key in
            the <tp:type>Message_Part</tp:type> mappings.</p>

          <p>If the one of the requested part numbers was greater than zero
            but referred to a part that had no content (i.e. it had no
            'content-type' key or no 'content' key), it is simply omitted from
            this mapping; this is not considered to be an error condition.</p>
        </tp:docstring>
      </arg>

      <tp:possible-errors>
        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
          <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
            Either there is no pending message with the given message ID,
            or one of the part numbers given was 0 or too large.
          </tp:docstring>
        </tp:error>
        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
      </tp:possible-errors>
    </method>

    <signal name="MessageReceived" tp:name-for-bindings="Message_Received">
      <tp:docstring>
        Signals that a message has been received and added to the pending
        messages queue. This MUST be emitted exactly once per emission of the
        <tp:dbus-ref
          namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref>
        signal on the Text interface.

        <tp:rationale>
          The double signal-emission provides compatibility with older
          clients. Clients supporting Messages should listen for
          Messages.MessageReceived only (if the channel has the Messages
          interface) or Text.Received only (otherwise).
        </tp:rationale>
      </tp:docstring>

      <arg type="aa{sv}" tp:type="Message_Part[]" name="Message">
        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
          The message content, including any attachments or alternatives
        </tp:docstring>
      </arg>
    </signal>

    <tp:enum name="Delivery_Status" value-prefix="Delivery_Status"
      plural="Delivery_Statuses" type="u">
      <tp:docstring>
        <p>The status of a message as indicated by a delivery report.</p>

        <p>If this enum is extended in future specifications, this should
          only be to add new, non-overlapping conditions (i.e. all failures
          should still be signalled as either Temporarily_Failed
          or Permanently_Failed). If additional detail is required (e.g.
          distinguishing between the various types of permanent failure) this
          will be done using additional keys in the Message_Part.</p>
      </tp:docstring>

      <tp:enumvalue suffix="Unknown" value="0">
        <tp:docstring>
          The message's disposition is unknown.
          Clients SHOULD consider all messages to have status
          Delivery_Status_Unknown unless otherwise specified; connection
          managers SHOULD NOT signal this delivery status explicitly.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Delivered" value="1">
        <tp:docstring>
          The message has been delivered to the intended recipient.
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Temporarily_Failed" value="2">
        <tp:docstring>
          Delivery of the message has failed. Clients SHOULD notify the user,
          but MAY automatically try sending another copy of the message.

          <tp:rationale>
            Similar to errors with type="wait" in XMPP; analogous to
            4xx errors in SMTP.
          </tp:rationale>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Permanently_Failed" value="3">
        <tp:docstring>
          Delivery of the message has failed. Clients SHOULD NOT try again
          unless by specific user action. If the user does not modify the
          message or alter configuration before re-sending, this error is
          likely to happen again.

          <tp:rationale>
            Similar to errors with type="cancel", type="modify"
            or type="auth" in XMPP; analogous to 5xx errors in SMTP.
          </tp:rationale>
        </tp:docstring>
      </tp:enumvalue>

      <tp:enumvalue suffix="Accepted" value="4">
        <tp:docstring>
          An intermediate server has accepted the message but the message
          has not been yet delivered to the ultimate recipient. The
          connection manager might send a Failed report or Delivered report
          later.

          <tp:rationale>
            Similar to "202 Accepted" success code in SIP; analogous to
            251 and 252 responses in SMTP.
          </tp:rationale>
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:flags name="Delivery_Reporting_Support_Flags"
      value-prefix="Delivery_Reporting_Support_Flag" type="u">
      <tp:docstring>
        Flags indicating the level of support for delivery reporting on this
        channel. Any future flags added to this set will conform to the
        convention that the presence of an extra flag implies that
        more operations will succeed.
      </tp:docstring>

      <tp:flag suffix="Receive_Failures" value="1">
        <tp:docstring>
          Clients MAY expect to receive negative delivery reports if
          Message_Sending_Flag_Report_Delivery is specified when sending.

          <tp:rationale>
            If senders want delivery reports, they should ask for them.
            If they don't want delivery reports, they can just ignore them,
            so there's no need to have capability discovery for what will
            happen if a delivery report isn't requested.
          </tp:rationale>
        </tp:docstring>
      </tp:flag>

      <tp:flag suffix="Receive_Successes" value="2">
        <tp:docstring>
          Clients MAY expect to receive positive delivery reports if
          Message_Sending_Flag_Report_Delivery is specified when sending.

          <tp:rationale>
            Same rationale as Receive_Failures.
          </tp:rationale>
        </tp:docstring>
      </tp:flag>

    </tp:flags>

    <property name="DeliveryReportingSupport" access="read"
      tp:type="Delivery_Reporting_Support_Flags" type="u"
      tp:name-for-bindings="Delivery_Reporting_Support">
      <tp:docstring>
        A bitfield indicating features supported by this channel.
      </tp:docstring>
    </property>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->