Update spec to 0.19.1 (no API changes)

Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>

1 files changed, 653 insertions, 0 deletions

diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml
new file mode 100644
index 000000000..35678c2f9
--- /dev/null
+++ b/spec/Connection_Interface_Mail_Notification.xml
@@ -0,0 +1,653 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Mail_Notification"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+  >
+  <tp:copyright> Copyright (C) 2007 Collabora Limited </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
+Library 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.Connection.Interface.MailNotification.DRAFT"
+    tp:causes-havoc="experimental">
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+    <tp:added version="0.19.1">(as draft 1)</tp:added>
+
+    <tp:flags name="Mail_Notification_Flags" value-prefix="Mail_Notification_Flag" type="u" >
+      <tp:flag suffix="Supports_Unread_Mail_Count" value="1">
+        <tp:docstring>
+          This Connection provides the number of unread e-mails (or e-mail
+          threads) in the main folder of your e-mail account, as the
+          <tp:member-ref>UnreadMailCount</tp:member-ref> property. The
+          connection manager will update this value by emitting the
+          <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Supports_Unread_Mails" value="2">
+        <tp:docstring>
+          This Connection provides a detailed list of unread e-mails, as the
+          <tp:member-ref>UnreadMails</tp:member-ref> property. If this flag
+          is set, <tt>Supports_Unread_Mail_Count</tt> MUST be set, and
+          <tt>Emits_Mails_Received</tt> MUST NOT be set.
+          The Connection will update the list by emitting the
+          <tp:member-ref>UnreadMailsChanged</tp:member-ref> signals.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Emits_Mails_Received" value="4">
+        <tp:docstring>
+          This Connection emits the <tp:member-ref>MailsReceived</tp:member-ref>
+          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 <tt>Supports_Unread_Mails</tt>.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Supports_Request_Inbox_URL" value="8">
+        <tp:docstring>
+          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 <tp:member-ref>RequestInboxURL</tp:member-ref> method.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Supports_Request_Mail_URL" value="16">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>This Connection can provide a URL (with optional POST data) to open
+            a specific mail in a web-based client, via the
+            <tp:member-ref>RequestMailURL</tp:member-ref> method. This feature
+            is not useful unless either Emits_Mails_Received or
+            Supports_Unread_Mails is set.</p>
+
+          <p>If this flag is not set, clients SHOULD fall back to using
+            <tp:member-ref>RequestInboxURL</tp:member-ref> if available.</p>
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="Thread_Based" value="32">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Each <tp:type>Mail</tp:type> represents a thread of e-mails, which
+            MAY have more than one sender.</p>
+
+          <tp:rationale>
+            <p>Google Talk notifies users about new mail in terms of unread
+              threads, rather than unread e-mails.</p>
+          </tp:rationale>
+        </tp:docstring>
+      </tp:flag>
+
+      <tp:docstring>
+        <p>Flags representing capabilities provided by a connection manager.
+          Those values can be used as bitfield. Some flags depend on, or
+          conflict with, each other.</p>
+
+        <p>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.</p>
+      </tp:docstring>
+    </tp:flags>
+
+    <tp:enum name="HTTP_Method" type="u">
+      <tp:enumvalue suffix="Get" value="0">
+        <tp:docstring>
+          Use the GET method when opening the URL.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Post" value="1">
+        <tp:docstring>
+          Use the POST method when opening the URL. Refer to
+          <tp:type>HTTP_Post_Data</tp:type> for more details.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:docstring>
+        The HTTP Method with which to request a URL.
+      </tp:docstring>
+    </tp:enum>
+
+    <tp:struct name="HTTP_Post_Data" array-name="HTTP_Post_Data_List">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>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
+        <a href="http://www.w3.org/TR/html401/types.html#type-cdata">
+          HTML CDATA type</a>. The value MUST NOT be
+        encoded with HTML entities.</p>
+
+        <p>For example, if the POST data should contain a key "less-than" with value
+        "&lt;", and a key "percent" with value "%", this should be represented as
+        two HTTP_Post_Data structures, ("less-than", "&lt;") and ("percent", "%"),
+        resulting in a POST request whose request body is "less-than=&amp;lt;&amp;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:</p>
+
+        <pre>
+        &lt;input type="hidden" name="less-than"&gt;&amp;lt;&lt;/input&gt;
+        &lt;input type="hidden" name="percent"&gt;%&lt;/input&gt;
+        </pre>
+
+        <tp:rationale>
+          <p>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
+            <a href="http://www.ietf.org/rfc/rfc1738.txt">characters that are
+              reserved in URLs</a>, if appropriate for that API.</p>
+
+          <p>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.</p>
+        </tp:rationale>
+      </tp:docstring>
+      <tp:member type="s" name="Key">
+        <tp:docstring>The key, corresponding to a HTML control
+          name</tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Value">
+        <tp:docstring>The value</tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:struct name="Mail_Address" array-name="Mail_Address_List">
+      <tp:docstring>
+        A pair (name, address) representing an e-mail address,
+        such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk").
+      </tp:docstring>
+      <tp:member type="s" name="Name">
+        <tp:docstring>The displayed name corresponding to the e-mail
+          address</tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Address">
+        <tp:docstring>The actual e-mail address</tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:struct name="Mail_URL">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A structure containing the required information to open a web-based
+          e-mail UI, without needing re-authentication (if possible).</p>
+
+        <p>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.</p>
+      </tp:docstring>
+      <tp:member type="s" name="URL">
+        <tp:docstring>
+          The URL to which to send a request.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="u" name="Method" tp:type="HTTP_Method">
+        <tp:docstring>
+          The HTTP method of the request.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="a(ss)" name="Post_Data" tp:type="HTTP_Post_Data[]">
+        <tp:docstring>
+          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.
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:mapping name="Mail" array-name="Mail_List">
+      <tp:docstring>
+        An extensible map representing a mail, or (on protocols where
+        <tt>Thread_Based</tt> appears in
+        <tp:member-ref>MailNotificationFlags</tp:member-ref>) a thread of
+        mails. All keys are optional where not otherwise stated; however, at
+        least one of "senders" and "subject" must be included.
+      </tp:docstring>
+
+      <tp:member type="s" name="Key">
+        <tp:docstring>
+          <p>A key providing information about the mail or thread. Well-known
+            keys are as follows:</p>
+
+        <dl>
+          <dt>id &#8212; s</dt>
+          <dd>
+            <p>A unique ID for this e-mail. CMs with
+              <tt>Supports_Unread_Mails</tt> set in
+              <tp:member-ref>MailNotificationFlags</tp:member-ref> MUST provide
+              this key in each <tp:type>Mail</tp:type>.</p>
+
+            <p>If provided, the ID SHOULD be unique to a Mail at least until
+              that mail is removed with the
+              <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal
+              (in protocols with <tt>Supports_Unread_Emails</tt>), or
+              unique for the duration of a session (otherwise).</p>
+
+            <tp:rationale>
+              <p>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 <tp:member-ref>RequestMailURL</tp:member-ref>).</p>
+            </tp:rationale>
+          </dd>
+
+          <dt>url-data &#8212; any type</dt>
+          <dd>An opaque identifier (typically a string or list of strings)
+            provided to the Connection when calling
+            <tp:member-ref>RequestMailURL</tp:member-ref>,
+            containing information used by the Connection to build the URL.
+          </dd>
+
+          <dt>senders &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</dt>
+          <dd>
+            An array of sender display name and e-mail address pairs. Note that
+            only e-mails represented as a thread can have multiple senders.
+          </dd>
+
+          <dt>to-addresses &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</dt>
+          <dd>
+            An array of display name and e-mail address pairs representing
+            the recipients.
+          </dd>
+
+          <dt>cc-addresses &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</dt>
+          <dd>
+            An array of display name and e-mail address pairs representing
+            the carbon-copy recipients.
+          </dd>
+
+          <dt>sent-timestamp &#8212; x (<tp:type>Unix_Timestamp64</tp:type>)</dt>
+          <dd>A UNIX timestamp indicating when the message was sent, or for
+            a thread, when the most recent message was sent.
+          </dd>
+
+          <dt>received-timestamp &#8212; x (<tp:type>Unix_Timestamp64</tp:type>)</dt>
+          <dd>A UNIX timestamp indicating when the message was received, or for
+            a thread, when the most recent message was received.
+          </dd>
+
+          <dt>has-attachments &#8212; b</dt>
+          <dd>If true, this mail has attachments.</dd>
+
+          <dt>subject &#8212; s</dt>
+          <dd>
+            The subject of the message. This MUST be encoded in UTF-8.
+          </dd>
+
+          <dt>content-type &#8212; s</dt>
+          <dd>
+            <p>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).</p>
+
+            <tp:rationale>
+              <p>All strings on D-Bus must be UTF-8.</p>
+            </tp:rationale>
+          </dd>
+
+          <dt>truncated &#8212; b</dt>
+          <dd>
+            If true, the content is only a partial message; if false or
+            omitted, the content is the entire message.
+          </dd>
+
+          <dt>content &#8212; s</dt>
+          <dd>
+            The body of the message, possibly truncated, encoded as appropriate
+            for "content-type".
+          </dd>
+
+          <dt>folder &#8212; s</dt>
+          <dd>
+            The name of the folder containing this e-mails.
+            If omitted, the inbox SHOULD be assumed.
+          </dd>
+        </dl>
+        </tp:docstring>
+      </tp:member>
+
+      <tp:member name="Value" type="v">
+        <tp:docstring>The value, of whatever type is appropriate for the
+          key.</tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <property name="MailNotificationFlags" type="u" access="read"
+      tp:type="Mail_Notification_Flags"
+      tp:name-for-bindings="Mail_Notification_Flags">
+      <tp:docstring>
+        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.
+
+        <tp:rationale>
+          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 <tp:type>Mail_Notification_Flags</tp:type>
+          SHOULD NOT provide this interface.
+        </tp:rationale>
+      </tp:docstring>
+    </property>
+
+    <property name="UnreadMailCount" type="u" access="read"
+      tp:name-for-bindings="Unread_Mail_Count">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The number of unread messages in the Inbox. Change notification is
+          via <tp:member-ref>UnreadMailsChanged</tp:member-ref>.</p>
+
+        <p>This property is only useful if <tt>Supports_Unread_Mail_Count</tt>
+          is set in the <tp:member-ref>MailNotificationFlags</tp:member-ref>;
+          otherwise, it MUST be zero.</p>
+
+        <p>If <tt>Thread_Based</tt> appears in the
+          <tp:member-ref>MailNotificationFlags</tp:member-ref>, this property
+          counts the number of threads, not the number of mails.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="UnreadMails" type="aa{sv}" tp:type="Mail[]"
+      tp:name-for-bindings="Unread_Mails" access="read">
+      <tp:docstring>
+        A array of unread <tp:type>Mail</tp:type>s. Change notification is via
+        <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property is
+        only useful if <tt>Supports_Unread_Mails</tt> is set in
+        <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it MUST be
+        an empty list.
+      </tp:docstring>
+    </property>
+
+    <property name="MailAddress" type="s"
+      tp:name-for-bindings="Mail_Address" access="read">
+      <tp:docstring>
+        A string representing the e-mail address of the account. The CMs MUST
+        provide this information.
+        <tp:rationale>
+          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.
+        </tp:rationale>
+      </tp:docstring>
+    </property>
+
+    <signal name="MailsReceived" tp:name-for-bindings="Mails_Received">
+      <arg name="Mails" type="aa{sv}" tp:type="Mail[]">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>An array of <tp:type>Mail</tp:type>s. Those e-mail MUST NOT have
+            the "id" key.</p>
+
+          <tp:rationale>
+            <p>On connections that emit this signal, it's impossible to tell
+              when a mail has been removed, and hence when "id" has become
+              invalid.</p>
+          </tp:rationale>
+        </tp:docstring>
+      </arg>
+
+      <tp:docstring>
+        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 <tp:member-ref>UnreadMails</tp:member-ref> list, but
+        do provide real-time notification about newly arrived e-mails. It MUST
+        NOT be emitted unless <tt>Emits_Mails_Received</tt> is set in
+        <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+      </tp:docstring>
+    </signal>
+
+    <signal name="UnreadMailsChanged"
+      tp:name-for-bindings="Unread_Mails_Changed">
+      <arg name="Count" type="u">
+        <tp:docstring>
+          Number of unread messages in the inbox (the new value of
+          <tp:member-ref>UnreadMailCount</tp:member-ref>).
+        </tp:docstring>
+      </arg>
+      <arg name="Mails_Added" type="aa{sv}" tp:type="Mail[]">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A list of <tp:type>Mail</tp:type> that are being added or updated
+            in <tp:member-ref>UnreadMails</tp:member-ref>.</p>
+
+          <tp:rationale>
+            <p>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.</p>
+          </tp:rationale>
+
+          <p>If the <tt>Supports_Unread_Mails</tt> flag is not set, this list
+            MUST be empty, even if Count has increased.</p>
+        </tp:docstring>
+      </arg>
+      <arg name="Mails_Removed" type="as">
+        <tp:docstring>
+          A list of e-mail IDs that are being removed from
+          <tp:member-ref>UnreadMails</tp:member-ref>.
+          If the <tt>Supports_Unread_Mails</tt> flag is not set, this list
+          MUST be empty, even if Count has decreased.
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when <tp:member-ref>UnreadMails</tp:member-ref> or
+          <tp:member-ref>UnreadMailCount</tp:member-ref> have changed. It MUST
+          NOT be emited if <tt>Supports_Unread_Mail_Count</tt> flag is not set
+          in <tp:member-ref>MailNotificationFlags</tp:member-ref>.</p>
+
+        <p><tt>Mails_Added</tt> and
+          <tt>Mails_Removed</tt> MUST be empty if the
+          <tt>Supports_Unread_Mails</tt> flag is not set.</p>
+      </tp:docstring>
+    </signal>
+
+    <method name="Subscribe"
+        tp:name-for-bindings="Subscribe">
+      <tp:docstring>
+        <p>This method subscribes a client to the notification interface. This
+          MUST be called by clients before using this interface.</p>
+
+        <p>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.</p>
+
+        <tp:rationale>
+          <p>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.</p>
+
+          <p>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.</p>
+        </tp:rationale>
+
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+      </tp:possible-errors>
+    </method>
+
+    <method name="Unsubscribe"
+        tp:name-for-bindings="Unsubscribe">
+      <tp:docstring>
+        This method unsubscribes a client from the notification interface.
+        This SHOULD be called by each client that has successfully called
+        Subscribe when it no longer needs the mail notification interface.
+
+        <tp:rationale>
+          See <tp:member-ref>Subscribe</tp:member-ref> for rationale.
+        </tp:rationale>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            Raised if the client calling this method has no references to
+            release.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+      </tp:possible-errors>
+    </method>
+
+    <method name="RequestInboxURL"
+      tp:name-for-bindings="Request_Inbox_URL">
+      <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" >
+        <tp:docstring>
+          A struture containing a URL and optional additional data to open a
+          webmail client, without re-authentication if possible.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        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 <tt>Supports_Request_Inbox_URL</tt> flag is set in
+        <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+
+        <tp:rationale>
+          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.
+        </tp:rationale>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+      </tp:possible-errors>
+    </method>
+
+    <method name="RequestMailURL"
+      tp:name-for-bindings="Request_Mail_URL">
+      <arg direction="in" name="ID" type="s">
+        <tp:docstring>
+          The mail's <tt>id</tt> as found in the <tp:type>Mail</tp:type>
+          structure, or the empty string if no <tt>id</tt> key was provided.
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="URL_Data" type="v">
+        <tp:docstring>
+          Whatever <tt>url-data</tt> was found in the <tp:type>Mail</tp:type>
+          structure, or the boolean value False (D-Bus type 'b') if no
+          <tt>url-data</tt> was provided in the Mail.
+        </tp:docstring>
+      </arg>
+      <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" >
+        <tp:docstring>
+          A struture that contains a URL and optional additional data to open a
+          webmail client, without re-authentication if possible.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        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 <tt>Supports_Request_Mail_URL</tt> flag
+        is set in <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+        <tp:rationale>
+          See <tp:member-ref>RequestInboxURL</tp:member-ref> for design
+          rationale.
+        </tp:rationale>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+      </tp:possible-errors>
+    </method>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>An interface to support receiving notifications about a e-mail
+        account associated with this connection.</p>
+
+      <p>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.</p>
+
+      <p>To use this interface, a client MUST first subscribe using the
+        <tp:member-ref>Subscribe</tp:member-ref> 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
+        <tp:member-ref>Unsubscribe</tp:member-ref> to release resources in
+        the CM.</p>
+
+      <p>Protocols have various different levels of Mail Notification support.
+        To describe the level of support, the interface provides a property
+        called <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+        Not all combinations are valid; protocols can be divided into four
+        categories as follows.</p>
+
+      <p>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
+        <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and
+        either recover the initial state from the
+        <tp:member-ref>UnreadMails</tp:member-ref> property (if they require
+        details other than the number of mails) or the
+        <tp:member-ref>UnreadMailCount</tp:member-ref> property (if they
+        are only interested in the number of unread mails). The
+        <tp:member-ref>MailsReceived</tp:member-ref> 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 <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal.</p>
+
+      <p>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.</p>
+
+      <p>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
+        <tp:member-ref>MailsReceived</tp:member-ref> signal on any connections
+        with this flag.</p>
+
+      <p>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
+        <em>number</em> of unread mails. To do this, they must monitor the
+        <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and
+        retrieve the initial state from the
+        <tp:member-ref>UnreadMailCount</tp:member-ref> property.</p>
+
+      <p>
+        Orthogonal features described by the
+        <tp:member-ref>MailNotificationFlags</tp:member-ref> 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.</p>
+    </tp:docstring>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
+