Home · All Classes · All Namespaces · Modules · Functions · Files
Public Member Functions

Tp::MessagePart Struct Reference
[Mapping types]

#include <TelepathyQt4/Types>

List of all members.

Public Member Functions

Detailed Description

Mapping type generated from the specification. Convertible with QMap<QString, QDBusVariant>, but needed to have a discrete type in the Qt4 type system.

Part of a message's content. In practice, this mapping never appears in isolation: incoming messages are represented by a list of <tp:type>Message_Part</tp:type> mappings in the <tp:member-ref>MessageReceived</tp:member-ref> signal, and outgoing messages are passed to <tp:member-ref>SendMessage</tp:member-ref> as a list of these mappings.

The first part of the message contains "headers", which refer to the entire message. The second and subsequent parts contain the message's content, including plain text, formatted text and/or attached files. Well-known keys for the header and body parts are defined by the <tp:type>Message_Header_Key</tp:type> and <tp:type>Message_Body_Key</tp:type> types, respectively. 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, or keys intended for body parts in the first Message_Part; clients MUST recover from this error by ignoring these mis-placed keys.

<tp:rationale>

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.

However, this would make access to the messages more awkward. In Python, the syntax for access to a header field would remain message[0]['message-type'], 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. </tp:rationale>

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.

<tp:rationale>

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.

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). </tp:rationale>

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.

<tp:rationale>

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.

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.

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

Example messages

A rich-text message, with an embedded image, might be represented as:

 [
   {
     '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:<br />' +
                '<img src="cid:catphoto" alt="lol!" />' +
                '<br />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,
   },
 ]

telepathy-ring, Nokia's GSM connection manager, represents vCards sent via SMS as:

 [
   {
     '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
   },
 ]

Delivery reports

Delivery reports are also represented as messages with the message-type header mapping to <tp:type>Channel_Text_Message_Type</tp:type> Delivery_Report. Delivery reports SHOULD contain the message-sender header, mapping to the intended recipient of the original message, if possible; other headers specific to delivery reports are defined by the <tp:type>Delivery_Report_Header_Key</tp:type> type. The second and subsequent parts, if present, are a human-readable report from the IM service.
For backwards- and forwards-compatibility, whenever a delivery error report is signalled—that is, with delivery-status mapping to <tp:type>Delivery_Status</tp:type> Temporarily_Failed or Permanently_Failed—<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> SHOULD also be emitted; whenever <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> is emitted, a delivery report MUST also be signalled. Delivery report messages on this interface MUST be represented in emissions of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> as messages with the Non_Text_Content <tp:type>Channel_Text_Message_Flags</tp:type>; clients which understand this interface SHOULD ignore the SendError signal in favour of listening for delivery reports, as mentioned in the introduction.
The result of attempting to send delivery reports using <tp:member-ref>SendMessage</tp:member-ref> is currently undefined.

Example delivery reports

A minimal delivery report indicating permanent failure of the sent message whose token was b9a991bd-8845-4d7f-a704-215186f43bb4 for an unknown reason 
 [{
 # 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
 ]

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 
 [{ # 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
 ]

A maximally complex delivery report: the server reports a bilingual human-readable failure message because the user sent a message "Hello, world!" with token b9a991bd-8845-4d7f-a704-215186f43bb4 to a contact with handle 123, but that handle represents a contact who does not actually exist 
 [{ # 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',
 }
 ]

A minimal delivery report indicating successful delivery of the sent message whose token was b9a991bd-8845-4d7f-a704-215186f43bb4 
 [{
 # 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
 ]

Constructor & Destructor Documentation

Tp::MessagePart::MessagePart (  )  [inline]
Tp::MessagePart::MessagePart ( const QMap< QString, QDBusVariant > &  a  )  [inline]

Member Function Documentation

MessagePart& Tp::MessagePart::operator= ( const QMap< QString, QDBusVariant > &  a  )  [inline]

Copyright © 2008-2010 Collabora Ltd. and Nokia Corporation
Telepathy-Qt4 0.4.4