Methods
| Subscribe | () | → | nothing | |
| Unsubscribe | () | → | nothing | |
| RequestInboxURL | () | → | (sua(ss)): URL | |
| RequestMailURL | (s: ID, v: URL_Data) | → | (sua(ss)): URL |
Signals
| MailsReceived | (aa{sv}: Mails) | |
| UnreadMailsChanged | (u: Count, aa{sv}: Mails_Added, as: Mails_Removed) |
Properties
| MailNotificationFlags | u (Mail_Notification_Flags) | Read only | |
| UnreadMailCount | u | Read only | |
| UnreadMails | aa{sv} (Mail_List) | Read only | |
| MailAddress | s | Read only |
Types
| HTTP_Method | Enum | u | |
| Mail_Notification_Flags | Flags | u | |
| Mapping | a{sv} | ||
| HTTP_Post_Data | Struct | (ss) | |
| Mail_Address | Struct | (ss) | |
| Mail_URL | Struct | (sua(ss)) |
Description
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 using the Subscribe 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 Unsubscribe to release resources in the CM.
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.
Methods
Subscribe () → nothing
This method subscribes a client to the notification interface. This MUST be called by clients before using this interface.
The Connection tracks a subscription count (like a refcount) for each unique bus name that has called Subscribe(). When a client calls Unsubscribe(), it releases one "reference". If a client exits (or crashes), the Connection releases all "references" held on its behalf.
The reference count imposed on the subscription simplifies implementation of client running in the same process (e.g. plug-ins): two plug-ins interested in mail notification can call Subscribe and Unsubscribe independently without interfering with each other.
This method exists to reduce memory and network overhead when there is no active subscription. An example of a protocol that benefits from this method is the Google XMPP Mail Notification extension: in this protocol, the CM receives a notification that something has changed, but to get more information, the CM must request this information. Knowing that nobody is currently interested in this information, the CM can avoid generating useless network traffic. Similarly, the CM may free the list of unread messages to reduce memory overhead.
Possible Errors
- Disconnected
- Not Implemented
Unsubscribe () → nothing
Possible Errors
- Not Available
- Not Implemented
RequestInboxURL () → (sua(ss)): URL
Returns
- URL — (sua(ss)) (Mail_URL)
Possible Errors
- Disconnected
- Network Error
- Not Implemented
RequestMailURL (s: ID, v: URL_Data) → (sua(ss)): URL
Parameters
Returns
- URL — (sua(ss)) (Mail_URL)
Possible Errors
- Disconnected
- Network Error
- Not Implemented
- Invalid Argument
Signals
MailsReceived (aa{sv}: Mails)
Parameters
UnreadMailsChanged (u: Count, aa{sv}: Mails_Added, as: Mails_Removed)
Parameters
- Count — u
- Mails_Added — aa{sv} (Mail_List)
- Mails_Removed — as
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.
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.
Properties
MailNotificationFlags — u (Mail_Notification_Flags)
UnreadMailCount — u
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.
UnreadMails — aa{sv} (Mail_List)
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.
MailAddress — s
Types
HTTP_Method — u
- Get (0)
- Post (1)
Mail_Notification_Flags — u
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.
- Supports_Unread_Mail_Count (1)
- Supports_Unread_Mails (2)
- Emits_Mails_Received (4)
- Supports_Request_Inbox_URL (8)
- Supports_Request_Mail_URL (16)
- Thread_Based (32)
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.
Mail — a{sv}
- Key — s
- 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.
- Value — v
A key providing information about the mail or thread. Well-known keys are as follows:
HTTP_Post_Data — (ss)
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=<&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"><</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.
- Key — s
- Value — s
Mail_Address — (ss)
- Name — s
- Address — s
Mail_URL — (sua(ss))
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.
- URL — s
- Method — u (HTTP_Method)
- Post_Data — a(ss) (HTTP_Post_Data_List)