path: root/spec/Connection_Interface_Mail_Notification.xml

<?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 xmlns="http://www.w3.org/1999/xhtml">
        <p>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.</p>
        <tp:rationale>
	  <p>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 <tp:type>Mail</tp:type> entirely.)</p>
        </tp:rationale>
      </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>

        <p>Note that this count MAY be bigger than the number of items in
          <tp:member-ref>UnreadMails</tp:member-ref>. See
          <tp:member-ref>UnreadMails</tp:member-ref> for more details.</p>
      </tp:docstring>
    </property>

    <property name="UnreadMails" type="aa{sv}" tp:type="Mail[]"
      tp:name-for-bindings="Unread_Mails" access="read">
      <tp:docstring>
        <p>An 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.</p>
        <p>The array size MAY be shorter than
          <tp:member-ref>UnreadMailCount</tp:member-ref>.</p>
        <tp:rationale>
          <p>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
            <tp:member-ref>UnreadMailCount</tp:member-ref> be bigger or equal
            to the size of this array.</p>
          </tp:rationale>
      </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: -->