summaryrefslogtreecommitdiff
path: root/spec/Connection_Interface_Mail_Notification1.xml
blob: b8ef504e8290aeb5c889c5466f5c257c94311acd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
<?xml version="1.0" ?>
<node name="/Connection_Interface_Mail_Notification1"
  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="im.telepathy1.Connection.Interface.MailNotification1">
    <tp:requires interface="im.telepathy1.Connection"/>
    <tp:added version="0.21.3">(as stable API)</tp:added>

    <tp:client-interest>
      <tp:docstring>
        A client MUST notify interest in this feature before it will be
        enabled.
      </tp:docstring>
    </tp:client-interest>

    <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="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="im.telepathy1.Error.Disconnected"/>
        <tp:error name="im.telepathy1.Error.NetworkError"/>
        <tp:error name="im.telepathy1.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="im.telepathy1.Error.Disconnected"/>
        <tp:error name="im.telepathy1.Error.NetworkError"/>
        <tp:error name="im.telepathy1.Error.NotImplemented"/>
        <tp:error name="im.telepathy1.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 by passing the
        name of this interface to the <tp:dbus-ref
          namespace="im.telepathy1"
          >Connection.AddClientInterest</tp:dbus-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:dbus-ref namespace="im.telepathy1"
          >Connection.RemoveClientInterest</tp:dbus-ref> to allow the CM to
        release resources.</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: -->