Copyright (C) 2007 Collabora Limited

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.

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 Library General Public License for more details.

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.

 (as stable API) A client MUST notify interest in this feature before it will be enabled. This Connection provides the number of unread e-mails (or e-mail threads) in the main folder of your e-mail account, as the UnreadMailCount property. The connection manager will update this value by emitting the UnreadMailsChanged signal. This Connection provides a detailed list of unread e-mails, as the UnreadMails property. If this flag is set, Supports_Unread_Mail_Count MUST be set, and Emits_Mails_Received MUST NOT be set. The Connection will update the list by emitting the UnreadMailsChanged signals. This Connection emits the MailsReceived signal, which provides details about newly arrived e-mails but does not maintain their read/unread status afterwards. This flag MUST NOT be combined with Supports_Unread_Mails. This Connection can provide a URL (with optional POST data) to open the the inbox of the e-mail account in a web-based client, via the RequestInboxURL method.

This Connection can provide a URL (with optional POST data) to open a specific mail in a web-based client, via the RequestMailURL method. This feature is not useful unless either Emits_Mails_Received or Supports_Unread_Mails is set.

If this flag is not set, clients SHOULD fall back to using RequestInboxURL if available.

Each Mail represents a thread of e-mails, which MAY have more than one sender.

Google Talk notifies users about new mail in terms of unread threads, rather than unread e-mails.

Flags representing capabilities provided by a connection manager. Those values can be used as bitfield. Some flags depend on, or conflict with, each other.

Connections SHOULD implement as many of these features as the underlying protocol allows, preferring to implement Supports_Unread_Mails instead of Emits_Mails_Received if both are possible.

 Use the GET method when opening the URL. Use the POST method when opening the URL. Refer to HTTP_Post_Data for more details. The HTTP Method with which to request a URL.

A pair (key, value) representing POST data compatible with the application/x-www-form-urlencoded MIME type. The strings MUST be valid UTF-8 strings, and the characters used in the key MUST obey the requirements of the HTML CDATA type. The value MUST NOT be encoded with HTML entities.

For example, if the POST data should contain a key "less-than" with value "<", and a key "percent" with value "%", this should be represented as two HTTP_Post_Data structures, ("less-than", "<") and ("percent", "%"), resulting in a POST request whose request body is "less-than=&lt;&percent=%25". If a client passes this to a browser by writing it into an HTML form, it could do so by representing it as:

        <input type="hidden" name="less-than">&lt;</input>
        <input type="hidden" name="percent">%</input>

This data can be used to generate a HTML file that will automatically load the URL with appropriate POST data, in which case the client MUST convert any characters that are special within HTML into HTML entities. Alternatively, it can be used in an API that will instruct the browser how to load the URL (like the Netscape Plug-in API), in which case the client MUST escape characters that are reserved in URLs, if appropriate for that API.

An array of pairs is used instead of a map from keys to values, because it's valid to repeat keys in both HTML and x-www-form-urlencoded data.

 The key, corresponding to a HTML control name The value

A pair (name, address) representing an e-mail address, such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). At least one of name and address MUST be provided. A missing element will be represented by the empty string.

The CM should provide as much information as possible, but not all protocols provide both the displayed name and the address. (If a protocol doesn't provide either, it should omit the appropriate field from the Mail entirely.)

 The displayed name corresponding to the e-mail address The actual e-mail address

A structure containing the required information to open a web-based e-mail UI, without needing re-authentication (if possible).

Because the URL and POST data frequently contain short-lived credential tokens, a new URL should be requested (by calling one of the methods that returns a Mail_URL) for each visit to the web-based UI, and the URL should be visited soon after it is returned.

 The URL to which to send a request. The HTTP method of the request. An array of name-value pairs containing the POST data to use when opening the URL. This MUST be an empty array if the Method is not POST. An extensible map representing a mail, or (on protocols where Thread_Based appears in MailNotificationFlags) a thread of mails. All keys are optional where not otherwise stated; however, at least one of "senders" and "subject" must be included.

A key providing information about the mail or thread. Well-known keys are as follows:

id — s

A unique ID for this e-mail. CMs with Supports_Unread_Mails set in MailNotificationFlags MUST provide this key in each Mail.

If provided, the ID SHOULD be unique to a Mail at least until that mail is removed with the UnreadMailsChanged signal (in protocols with Supports_Unread_Emails), or unique for the duration of a session (otherwise).

In protocols with Supports_Unread_Mails, this key is used to indicate which mail was removed. In protocols without that feature, it's impossible to tell when a mail has been removed (and hence how long the identifier will remain valid for use with RequestMailURL).
url-data — any type
An opaque identifier (typically a string or list of strings) provided to the Connection when calling RequestMailURL, containing information used by the Connection to build the URL.
senders — a(ss) (Mail_Address)
An array of sender display name and e-mail address pairs. Note that only e-mails represented as a thread can have multiple senders.
to-addresses — a(ss) (Mail_Address)
An array of display name and e-mail address pairs representing the recipients.
cc-addresses — a(ss) (Mail_Address)
An array of display name and e-mail address pairs representing the carbon-copy recipients.
sent-timestamp — x (Unix_Timestamp64)
A UNIX timestamp indicating when the message was sent, or for a thread, when the most recent message was sent.
received-timestamp — x (Unix_Timestamp64)
A UNIX timestamp indicating when the message was received, or for a thread, when the most recent message was received.
has-attachments — b
If true, this mail has attachments.
subject — s
The subject of the message. This MUST be encoded in UTF-8.
content-type — s

The MIME type of the message content. Two types are currently supported: "text/plain" for plain text, and "text/html" for a HTML document. If omitted, "text/plain" MUST be assumed. Regardless of MIME type, the content MUST be valid UTF-8 (which may require that the Connection transcodes it from a legacy encoding).

All strings on D-Bus must be UTF-8.
truncated — b
If true, the content is only a partial message; if false or omitted, the content is the entire message.
content — s
The body of the message, possibly truncated, encoded as appropriate for "content-type".
folder — s
The name of the folder containing this e-mails. If omitted, the inbox SHOULD be assumed.
The value, of whatever type is appropriate for the key. Integer representing the bitwise-OR of supported features for e-mails notification on this server. This property MUST NOT change after the Connection becomes CONNECTED. This property indicates the behavior and availability of the other properties and signals within this interface. A connection manager that cannot at least set one of the flags in the Mail_Notification_Flags SHOULD NOT provide this interface.

The number of unread messages in the Inbox. Change notification is via UnreadMailsChanged.

This property is only useful if Supports_Unread_Mail_Count is set in the MailNotificationFlags; otherwise, it MUST be zero.

If Thread_Based appears in the MailNotificationFlags, this property counts the number of threads, not the number of mails.

Note that this count MAY be bigger than the number of items in UnreadMails. See UnreadMails for more details.

An array of unread Mails. Change notification is via UnreadMailsChanged. This property is only useful if Supports_Unread_Mails is set in MailNotificationFlags; otherwise, it MUST be an empty list.

The array size MAY be shorter than UnreadMailCount.

Some servers may limits the amount of detailed e-mails sent. This can significantly reduce the network traffic for large inbox. For this reason, it is normal that UnreadMailCount be bigger or equal to the size of this array.

 A string representing the e-mail address of the account. The CMs MUST provide this information. In close integration of MailNotification with other e-mail services, the e-mail address can be used has a unique identifier for the account. Possible integration could be between Telepathy and Evolution where the e-mail address is the common information in both interfaces.

An array of Mails. Those e-mail MUST NOT have the "id" key.

On connections that emit this signal, it's impossible to tell when a mail has been removed, and hence when "id" has become invalid.

 Emitted when new e-mails messages arrive to the inbox associated with this connection. This signal is used for protocols that are not able to maintain the UnreadMails list, but do provide real-time notification about newly arrived e-mails. It MUST NOT be emitted unless Emits_Mails_Received is set in MailNotificationFlags. Number of unread messages in the inbox (the new value of UnreadMailCount).

A list of Mail that are being added or updated in UnreadMails.

Mails may be updated when the URL information (URL and POST data) have changed, or senders were added or removed from an e-mail thread.

If the Supports_Unread_Mails flag is not set, this list MUST be empty, even if Count has increased.

 A list of e-mail IDs that are being removed from UnreadMails. If the Supports_Unread_Mails flag is not set, this list MUST be empty, even if Count has decreased.

Emitted when UnreadMails or UnreadMailCount have changed. It MUST NOT be emited if Supports_Unread_Mail_Count flag is not set in MailNotificationFlags.

Mails_Added and Mails_Removed MUST be empty if the Supports_Unread_Mails flag is not set.

 A struture containing a URL and optional additional data to open a webmail client, without re-authentication if possible. This method creates and returns a URL and an optional POST data that allow opening the Inbox folder of a webmail account. This URL MAY contain tokens with a short lifetime, so clients SHOULD request a new URL for each visit to the webmail interface. This method is implemented only if the Supports_Request_Inbox_URL flag is set in MailNotificationFlags. We are not using properties here because the tokens are unsuitable for sharing between clients, and network round-trips may be required to obtain the information that leads to authentication free webmail access. The mail's id as found in the Mail structure, or the empty string if no id key was provided. Whatever url-data was found in the Mail structure, or the boolean value False (D-Bus type 'b') if no url-data was provided in the Mail. A struture that contains a URL and optional additional data to open a webmail client, without re-authentication if possible. This method creates and returns a URL and optional POST data that allow opening a specific mail in a webmail interface. This method is implemented only if Supports_Request_Mail_URL flag is set in MailNotificationFlags. See RequestInboxURL for design rationale.

An interface to support receiving notifications about a e-mail account associated with this connection.

In protocols where this is possible, this interface also allows the connection manager to provide the necessary information for clients to open a web-based mail client without having to re-authenticate.

To use this interface, a client MUST first subscribe by passing the name of this interface to the Connection.AddClientInterest method. The subscription mechanic aims at reducing network traffic and memory footprint in the situation where nobody is currently interesting in provided information. When done with this interface, clients SHOULD call Connection.RemoveClientInterest to allow the CM to release resources.

Protocols have various different levels of Mail Notification support. To describe the level of support, the interface provides a property called MailNotificationFlags. Not all combinations are valid; protocols can be divided into four categories as follows.

Connections to the most capable protocols, such as Google's XMPP Mail Notification extension, have the Supports_Unread_Mails flag (this implies that they must also have Supports_Unread_Mail_Count, but not Emits_Mails_Received). On these connections, clients requiring change notification MUST monitor the UnreadMailsChanged signal, and either recover the initial state from the UnreadMails property (if they require details other than the number of mails) or the UnreadMailCount property (if they are only interested in the number of unread mails). The MailsReceived signal is never emitted on these connections, so clients that will display a short-term notification for each new mail MUST do so in response to emission of the UnreadMailsChanged signal.

The most common situation, seen in protocols like MSN and Yahoo, is that the number of unread mails is provided and kept up-to-date, and a separate notification is emitted with some details of each new mail. This is a combination of the following two features, and clients SHOULD implement one or both as appropriate for their requirements.

On protocols that have the Emits_Mails_Received flag (which implies that they do not have Supports_Unread_Mails), the CM does not keep track of any mails; it simply emits a notification whenever new mail arrives. Those events may be used for short term display (like a notification popup) to inform the user. No protocol is known to support only this feature, but it is useful for integration with libraries that that do not implement tracking of the number of mails. Clients requiring these notifications MUST monitor the MailsReceived signal on any connections with this flag.

On protocols that have the Supports_Unread_Mail_Count flag but not the Supports_Unread_Mails flag, clients cannot display complete details of unread email, but can display an up-to-date count of the number of unread mails. To do this, they must monitor the UnreadMailsChanged signal, and retrieve the initial state from the UnreadMailCount property.

Orthogonal features described by the MailNotificationFlags property include the RequestSomethingURL methods, which are used to obtain URLs allowing clients to open a webmail client. Connections SHOULD support as many of these methods as possible.