forked from sysapps/messaging
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
2329 lines (2105 loc) · 101 KB
/
index.html
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
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>Messaging API</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<script src='https://www.w3.org/Tools/respec/respec-w3c-common'
class='remove'></script>
<script class="remove">
var respecConfig = {
specStatus: "ED",
shortName: "messaging",
publishDate: "",
previousPublishDate: "",
previousMaturity: "",
edDraftURI: "http://www.w3.org/2012/sysapps/messaging/",
// lcEnd: "",
crEnd: "",
editors: [
{ name: "Eduardo Fullea", company: "Telefonica",
companyURL: "http://www.tid.es/" },
{ name: "Jose M. Cantera", company: "Telefonica",
companyURL: "http://www.tid.es/" },
{ name: "Zoltan Kis", company: "Intel",
companyURL: "http://www.intel.com/" }
],
inlineCSS: true,
noIDLIn: true,
noIDLSorting: true,
wg: "System Applications Working Group",
wgURI: "http://www.w3.org/2012/sysapps/",
wgPublicList: "public-sysapps",
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
otherLinks: [{
key: "Repository",
data: [{
value: "We are on Github.",
href: "https://github.com/sysapps/messaging"
}, {
value: "File a bug.",
href: "https://github.com/sysapps/messaging/issues"
}, {
value: "Commit history.",
href: "https://github.com/sysapps/messaging/commits/gh-pages"
}
]
}
]
};
</script>
</head>
<!-----------------------------------------------------------------------------
Style guide to contributors:
============================
- this document uses ReSpec, see
http://dev.w3.org/2009/dap/ReSpec.js/documentation.html
- use 80 characters wide lines, whenever possible (except long links)
- keep sections 2 empty lines apart
- put comments in front of sections, for better readability with syntax coloring
editors
- use indentation with care: it may improve readability, but at the expense of
line lenght
- when descriptions of attributes is short, use the <dd> elements even when
the text also contains conformance statements (e.g. MUST, SHOULD, MAY).
No use repeating the same information in a separate paragraph.
------------------------------------------------------------------------------>
<body>
<!-- - - - - - - - - - - - - - - Abstract - - - - - - - - - - - - - - - - - -->
<section id="abstract">
This specification defines a System Level API which offers a simple interface
to get access to mobile messaging services. A typical use case of the
Messaging API is the implementation of a messaging client application that
allows the user to send SMS and MMS messages as well as to access and manage
the received SMS and MMS messages.
</section>
<!-- - - - - - - - - - - - - - - Status of this document - - - - - - - - - - -->
<section id="sotd">
</section>
<!-- - - - - - - - - - - - - - - Introduction - - - - - - - - - - - - - - - -->
<section class="informative">
<h2>Introduction</h2>
<p>
The Messaging API provides operations to get access to the primitives
offered by mobile messaging services (send, receive) as well as those that
allow to manage a mobile messaging client inbox (delete, store, mark as
read)
<p>
An example of use is provided below:
<pre class="example highlight">
navigator.messaging.sms.send ( '+1234567890', 'How are you?').done(
function(message) { window.console.log('Message with identifier ' +
message.messageID + ' sent at ' + message.timestamp); },
function(error) { window.console.error('Error: ' + error); } )
</pre>
</section>
<!-- - - - - - - - - - - - - - - Conformance - - - - - - - - - - - - - - - - -->
<section id="conformance">
<p>This specification defines conformance criteria that apply to a single
product: the <dfn>user agent</dfn> that implements the interfaces that it
contains.
<p>Implementations that use ECMAScript to implement the APIs defined in this
specification MUST implement them in a manner consistent with the ECMAScript
Bindings defined in the Web IDL specification [[!WEBIDL]], as this
specification uses that specification and terminology.
</section>
<!-- - - - - - - - - - - - - - - Terminology - - - - - - - - - - - - - - - -->
<section>
<h2>Terminology</h2> <p>The <code><a
href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">
EventHandler</a></code> interface represents a callback used for event
handlers as defined in [[!HTML5]].
<p>The concepts <dfn><a
href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task"> queue a
task</a></dfn> and <dfn><a
href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
fire an event</a></dfn> are defined in [[!HTML5]].
<p>The terms <a
href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers"><dfn
id="dfn-eventhandler">event handler</dfn></a> and <a
href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
<dfn id="dfn-eventtypes"> event handler event types</dfn></a> are defined in
[[!HTML5]].
<p>The <dfn><a href="http://dom.spec.whatwg.org/#promise">Promise</a></dfn>
interface, the concepts of a <a href=
"http://dom.spec.whatwg.org/#concept-resolver"><dfn>resolver</dfn></a>, a <dfn
id="dfn-fulfill-algorithm"><a
href="http://dom.spec.whatwg.org/#concept-resolver-fulfill"> resolver's
fulfill algorithm</a></dfn> and a <dfn id="dfn-reject-algorithm"><a
href="http://dom.spec.whatwg.org/#concept-resolver-reject"> resolver's reject
algorithm</a></dfn> are defined in [[DOM4]].</p>
</section>
<!-- - - - - - - - - - - - - - - Security and privacy - - - - - - - - - - - -->
<section>
<h2>Security and privacy considerations</h2>
<p>This API must be only exposed to trusted content
</section>
<!-- - - - - - - - - - - - - Extended interface Navigator - - - - - - - - - -->
<section>
<h2><a>Navigator</a> Interface</h2>
<dl title="partial interface Navigator" class="idl">
<dt>readonly attribute Messaging messaging</dt>
<dd>
The object that exposes the interface to mobile messaging services.
</dd>
</dl>
</section>
<!-- - - - - - - - - - - - - Interface MessagingManager - - - - - - - - - - -->
<section>
<h2><a>MessagingManager</a> Interface</h2>
<p>The <a>MessagingManager</a> interface
represents the initial entry point for getting access to the mobile messaging
services, i.e. SMS and MMS.
<dl title="interface MessagingManager" class="idl">
<dt>readonly attribute SmsManager sms</dt> <dd>Provides access to the
SMS service's specific functionality.</dd>
<dt>readonly attribute MmsManager mms</dt> <dd>Provides access to the
MMS service's specific functionality.</dd>
<dt> Promise findMessages ()</dt> <dd>This method makes a request
to retrieve the messages matching the filter described by the
<code>filter</code> parameter and according to the filtering options
described in the <code>options</code>. It returns a new
<code>Promise</code> that will be used to notify the caller about
the result of the operation, which is a MessagingCursor to access the set of
messages.
<dl class='parameters'>
<dt>MessagingFilter filter</dt> <dd>
Filter that identifies the set of messages that are requested to
be retrieved
</dd> <dt>FilterOptions options</dt> <dd>
Indicates the filtering options (i.e. sorting criteria, sorting
order, limit of results).
</dd>
</dl>
</dd>
<dt> Promise findConversations ()</dt> <dd>This method makes a
request to retrieve the list of conversations in which the messages can be
grouped using the criteria defined by the <code>groupBy</code> parameter.
Only those messages matching the filter described in the <code>filter</code>
parameter SHALL be included in the resulting conversations, what can be
useful for instance to filter just a specific type of messages (e.g. SMS) or
to implement message search in a conversational messaging client. It returns
a new <code>Promise</code> that will be used to notify the caller
about the result of the operation, which is a MessagingCursor to access the
set of conversations.
<dl class='parameters'>
<dt>DOMString groupBy</dt> <dd>
Indicates the criteria used to define the conversations. It may have
the values 'participants' if a conversation is to be defined as the
set of messages exchanged among the same set of parties, and 'subject'
if a conversation is to be defined as the set of messages with the
same subject.
</dd> <dt>MessagingFilter filter</dt> <dd>
Filter that identifies the set of messages that are requested to be
included in the resulting conversations.
</dd> <dt>FilterOptions options</dt> <dd>
Indicates the filtering options (i.e. sorting criteria, sorting order,
limit of results) to be aplied when filtering the messages to be
included in each of the resulting conversations.
</dd>
</dl>
</dd>
<dt> Promise getMessage ()</dt> <dd>This method makes a request to
retrieve the message identified by the <code>messageID</code> parameter.
It returns a new <code>Promise</code> object which allows the
caller to be notified about the result of the operation.
<dl class='parameters'>
<dt>DOMString messageID</dt> <dd>
Identifier of the message that is requested to be retrieved
</dd>
</dl>
</dd>
<dt> Promise deleteMessage ()</dt> <dd>This method requests the
deletion of the message with identifier equal to the <code>messageID</code>
parameter. A new <code>Promise</code> is returned in order to
notify the request result (success or error) to the caller.
<dl class='parameters'>
<dt>DOMString messageID</dt> <dd>
Identifier of the message that is requested to be deleted
</dd>
</dl>
</dd>
<dt> Promise deleteConversation ()</dt> <dd>This method requests
the deletion of all the messages in the conversation with identifier equal
to the <code>conversationID</code> parameter. A new <code>Promise</code> is
returned in order to notify the request result (success or error) to the
caller.
<dl class='parameters'>
<dt>DOMString conversationID</dt> <dd>
Identifier of the conversation whose messages are requested to
be deleted
</dd>
</dl>
</dd>
<dt> Promise markMessageRead ()</dt> <dd>This method requests to
mark as read or unread the message with identifier equal to the
<code>messageID</code> parameter. The method returns a new
<code>Promise</code> that will allow the caller to be notified
about the result (success, error) of the operation.
<dl class='parameters'>
<dt>DOMString messageID</dt> <dd>
Identifier of the message that is requested to be marked as
read or unread
</dd>
<dt>boolean value</dt>
<dd>
Indicates whether the message is to be marked as read ('true') or
unread ('false')
</dd>
<dt>optional boolean sendReadReport = false</dt>
<dd>
Indicates that, in case a Read Report was requested, it is to be sent
('true') or not ('false', which is the default)
</dd>
</dl>
</dd>
<dt> Promise markConversationRead ()</dt> <dd>This method requests to mark
as read or unread all the messages in the conversation with identifier equal
to the <code>conversationID</code> parameter. The method returns a new
<code>Promise</code> that will allow the caller to be notified about the
result (success, error) of the operation.
<dl class='parameters'>
<dt>DOMString conversationID</dt> <dd>
Identifier of the conversation whose messages are requested to be
marked as read or unread
</dd>
<dt>boolean value</dt>
<dd>
Indicates whether the messages in the conversation are to be marked as
read ('true') or unread ('false')
</dd>
<dt>optional boolean sendReadReport = false</dt>
<dd>
Indicates that, in case a Read Report was requested for any MMS
message in the conversation, a Read Report is to be sent ('true') or
not ('false', which is the default)
</dd>
</dl>
</dd>
</dl>
<section>
<h3>Steps</h3>
<p> The <dfn><code>findMessages</code></dfn>
method when invoked MUST run the following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Make a request to the system to get the message(s) matching the filter
included in the <code>filter</code> parameter and according to the
filtering options described in the <code>options</code> parameter.
<li>If an <var>error</var> occurs invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a> with
<em>error</em> as the <code>value</code> argument.
<li>When the request has been successfully completed:
<ol>
<li>Let <var>messagingCursor</var> be a new <code>MessagingCursor</code>
object providing access to the results of the retrieval, i.e. the set of
<code>SmsMessage</code> and/or <code>MmsMessage</code> elements.
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>messagingCursor</em> as the <code>value</code> argument.
</ol>
</ol>
<p> The <dfn><code>findConversations</code></dfn> method when invoked MUST
run the following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Make a request to the system to get the set of conversations in which
the messages can be grouped, according to the set of participants or the
subject as indicated in the <code>groupBy</code> parameter, and filtering
the messages included in those conversations according to the filter
included in the <code>filter</code> parameter and the filtering options
described in the <code>options</code> parameter.
<li>If an <var>error</var> occurs invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a> with
<em>error</em> as the <code>value</code> argument.
<li>When the request has been successfully completed:
<ol>
<li>Let <var>messagingCursor</var> be a new <code>MessagingCursor</code>
object providing access to the results of the retrieval, i.e. the set of
<code>Conversation</code> elements.
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>messagingCursor</em> as the <code>value</code> argument.
</ol>
</ol>
<p> The <dfn><code>getMessage</code></dfn> method when invoked MUST run
the following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Make a request to the system to get the message with identifier equal
to the <code>messageID</code> parameter passed in the request.
<li>If an <var>error</var> occurs invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a> with
<em>error</em> as the <code>value</code> argument.
<li>When the request has been successfully completed:
<ol>
<li>Let <var>message</var> be the <code>SmsMessage</code> or
<code>MmsMessage</code> whose identifier matches the
<code>messageID</code> parameter.
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>message</em> as the <code>value</code> argument.
</ol>
</ol>
<p> The <dfn><code>deleteMessage</code></dfn> method when invoked MUST run the
following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Make a request to the system to delete the message with identifier
equal to the <code>messageID</code> parameter passed in the request.
<li>If an <var>error</var> occurs invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a> with
<em>error</em> as the <code>value</code> argument.
<li>When the request has been successfully completed:
<ol>
<li>Let <var>messageID</var> be the <code>messageID</code> parameter
passed in the request
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>messageID</em> as the <code>value</code> argument.
</ol>
</ol>
<p> The <dfn><code>deleteConversation</code></dfn> method when invoked MUST
run the following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Make a request to the system to delete the messages in the conversation
with identifier equal to the <code>conversationID</code> parameter passed
in the request.
<li>If an <var>error</var> occurs invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a> with
<em>error</em> as the <code>value</code> argument.
<li>When the request has been successfully completed:
<ol>
<li>Let <var>conversationID</var> be the <code>conversationID</code>
parameter passed in the request
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>conversationID</em> as the <code>value</code> argument.
</ol>
</ol>
<p> The <dfn><code>markMessageRead</code></dfn> method when invoked MUST run
the following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Make a request to the system to mark as read/unread (depending on the
<code>value</code> parameter being respectively 'true' or 'false') the
message with identifier equal to the <code>messageID</code> parameter
passed in the request, and to send a Read Report if
<code>sendReadReport</code> is set to 'true'.
<li>If an <var>error</var> occurs invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a> with
<em>error</em> as the <code>value</code> argument.
<li>When the request has been successfully completed:
<ol>
<li>Let <var>messageID</var> be the <code>messageID</code> parameter
passed in the request
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>messageID</em> as the <code>value</code> argument.
</ol>
</ol>
<p> The <dfn><code>markConversationRead</code></dfn> method when invoked
MUST run the following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Make a request to the system to mark as read/unread (depending on the
<code>value</code> parameter being respectively 'true' or 'false') the
messages in the conversation with identifier equal to the
<code>conversationID</code> parameter passed in the request, and in case
<code>sendReadReport</code> is set to 'true', to send a Read Report for
each of the MMS messages for which it was requested.
<li>If an <var>error</var> occurs invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a> with
<em>error</em> as the <code>value</code> argument.
<li>When the request has been successfully completed:
<ol>
<li>Let <var>conversationID</var> be the <code>conversationID</code>
parameter passed in the request
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>conversationID</em> as the <code>value</code> argument.
</ol>
</ol>
<div class='note'>
It is FFS whether the methods deleteMessage() and markMessageRead() should
also accept an array of message identifiers as input parameter.
</div>
</section>
</section>
<!-- - - - - - - - - - - - Interface SmsManager - - - - - - - - - - - - - - -->
<section>
<h2><a>SmsManager</a> Interface</h2>
<p>The <a>SmsManager</a> interface represents the SMS messaging service
manager.
<dl title="interface SmsManager : EventTarget"
class="idl">
<dt>readonly attribute MessageType type</dt> <dd>MUST return the type of the
messaging service manager. It can have the following values: 'sms' or
'mms'.</dd>
<dt>readonly attribute DOMString[] serviceIDs</dt> <dd>MUST return the
identifier of the different services for this type of messaging service
(e.g. 'sms_sim1').</dd>
<dt> Promise segmentInfo ()</dt>
<dd>This method issues a request to get information on the number of
concatenated SMS segments needed to send the text in the <code>text</code>
parameter, the number of characters available per segment and the maximum
number of available characters in the last segment.
A <code>Promise</code> object will be returned in order to notify
the result of the request.
<dl class='parameters'>
<dt>DOMString text</dt>
<dd>
Text intended to be sent as an SMS, whose segmentation
information is checked by this method.
</dd>
<dt>optional DOMString serviceID</dt>
<dd>
Identifier of the service through which the message is would be sent.
</dd>
</dl>
</dd>
<dt> Promise send ()</dt>
<dd>This method issues a request to the messaging system to send an SMS
message with the text of the <code>text</code> parameter to the destination
number indicated in the <code>to</code> parameter.
A <code>Promise</code> object will be returned in order to notify
the result of the request.
<dl class='parameters'>
<dt>DOMString to</dt>
<dd>
Destination number for the SMS message.
</dd>
<dt>DOMString text</dt>
<dd>
Content of the SMS message to be sent.
</dd>
<dt>optional DOMString serviceID</dt>
<dd>
Identifier of the service through which the message is requested to
be sent.
</dd>
</dl>
</dd>
<dt>Promise clear ()</dt>
<dd>This method makes a request to delete all the messages associated to the
messaging service passed as parameter.
<dl class='parameters'>
<dt>DOMString serviceID</dt>
<dd>
Identifies the messaging service all whose messages are requested to
be deleted.
</dd>
</dl>
</dd>
<dt class="no-docs">
attribute EventHandler onreceived
</dt>
<dd>Handles the <code>received</code> event of type <a>MessagingEvent</a>,
fired when a new message is received on this messaging service manager.</dd>
<dt class="no-docs">
attribute EventHandler onsent
</dt>
<dd>Handles the <code>sent</code> event of type <a>MessagingEvent</a>, fired
when a new message is sent using this messaging service manager.</dd>
<dt class="no-docs">
attribute EventHandler ondeliverysuccess
</dt>
<dd>Handles the <code>deliverysuccess</code> event of type
<a>DeliveryReportEvent</a>, fired when a new succesful delivery
report is received on this messaging service manager.</dd>
<dt class="no-docs">
attribute EventHandler ondeliveryerror
</dt>
<dd>Handles the <code>deliveryerror</code> event of type
<a>DeliveryReportEvent</a>, fired when a new failure delivery
report is received on this messaging service manager.</dd>
<dt class="no-docs">
attribute EventHandler onserviceadded
</dt>
<dd>Handles the <code>serviceadded</code> event of type
<a>ServiceChangeEvent</a>, fired whenever a new messaging service is enabled
on this messaging service manager.</dd>
<dt class="no-docs">
attribute EventHandler onserviceremoved
</dt>
<dd>Handles the <code>serviceremoved</code> event of type
<a>ServiceChangeEvent</a>, fired when an existing messaging service is
disabled on this messaging service manager.</dd>
</dl>
<section>
<h3>Steps</h3>
<p> The <code>send</code> method when invoked MUST run the following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Let <var>smsMessage</var> be a new instance of <code>SmsMessage</code>:
<ol>
<li>Generate a identifier for this message that is globally unique within
the implementation, i.e. there cannot be any other message with the same
identifier.
<li>Set the <code>messageID</code> of <em>smsMessage</em> to the
generated identifier.
<li>Set the <code>type</code> of <em>smsMessage</em> to 'sms'.
<li>Set the <code>serviceID</code> of <em>smsMessage</em> to the
identifier of the service used to send the message, i.e. the one passed in
the <code>serviceID</code> parameter, if provided, or otherwise to the
first item in the <code>serviceIDs</code> attribute of the
<code>SmsManager</code>.
<li>Set the <code>from</code> of <em>smsMessage</em> to the number of the
mobile subscription used to send this SMS message.
<li>Set the <code>read</code> of <em>smsMessage</em> to 'true'.
<li>Set the <code>to</code> of <em>smsMessage</em> to the value of the
<code>to</code> parameter.
<li>Set the <code>body</code> of <em>smsMessage</em> to the value of the
<code>text</code> parameter.
<li>Set the <code>messageClass</code> of <em>smsMessage</em> to 'class1'.
<li>Set the <code>state</code> of <em>smsMessage</em> to 'sending'.
<li>Set the <code>deliveryStatus</code> of <em>smsMessage</em> to
'pending' if a delivery report has been requested or to 'not-applicable'
otherwise.
<li>Make a request to the system to send an SMS message with text passed
in the <code>text</code> parameter to the number of the recipient
indicated in the <code>to</code> parameter, using the proper service as
described above.
<li><a>Queue a task</a> to monitor SMS submission process.
</ol>
<li>If an <var>error</var> occurs run these substeps and terminate these
steps
<ol>
<li>If a delivery report had been requested set the
<code>deliveryStatus</code> of <em>smsMessage</em> to 'error'.
<li>invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-reject-algorithm">reject algorithm</a> with <em>error</em> as
the <code>value</code> argument.
</ol>
<li>When the request has been successfully completed:
<ol>
<li>Set the <code>state</code> of <em>smsMessage</em> to 'sent'.
<li>Set the <code>timestamp</code> of <em>smsMessage</em> to the
device's date when the SMS message was sent, i.e. when the SMS-SUBMIT
Protocol Data Unit was sent.
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>smsMessage</em> as the <code>value</code> argument.
<li><a>Queue a task</a> to <a>fire an event</a> named <a
class="internalDFN" href="#dfn-sms-sent-event"><code>sent</code></a> with
the <code>message</code> attribute set to <em>smsMessage</em>.
</ol>
</ol>
<p> The <dfn><code>segmentInfo</code></dfn> method when invoked MUST run the
following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Let <var>smsSegmentInfo</var> be a new instance of
<code>SmsSegmentInfo</code>.
<li>Make a request to the system to calculate the segmentation information
related to the sending as SMS the text passed in the <code>text</code>
parameter, using the service with identifier equal to the one passed in the
<code>serviceID</code> parameter, if provided, or otherwise to the first
item in the <code>serviceIDs</code> attribute of the
<code>SmsManager</code>.
<li><a>Queue a task</a> to monitor the calculation process.
<li>If an <var>error</var> occurs run these substeps and terminate these
steps
<ol>
<li>invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-reject-algorithm">reject algorithm</a> with <em>error</em> as
the <code>value</code> argument.
</ol>
<li>When the request has been successfully completed:
<ol>
<li>Set the <code>segments</code> of <em>smsSegmentInfo</em> to the
number of concatenated SMS segments needed to send the provided text.
<li>Set the <code>charsPerSegment</code> of <em>smsSegmentInfo</em> to
the number of characters available per SMS segment. This number depends
on the encoding to be used to send the SMS message, which in turn
depends on the language / special characters included in the text.
<li>Set the <code>charsAvailableInLastSegment</code> of
<em>smsSegmentInfo</em> to the maximum number of available characters in
the last segment that would be needed to send the input string. This
provides useful information to the user on the number of characters that
can type without requiring an additional SMS segment to send the text.
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>smsSegmentInfo</em> as the <code>value</code> argument.
</ol>
</ol>
<p>Note that the application that has invoked the <code>segmentInfo</code>
method SHOULD NOT split the text in a set of strings that fit each into a
single SMS segment and send each of them by an independent call to the
<code>sendSMS</code> method as it would result in different independent SMS
messages being sent, but SHOULD instead send the full message in a single
<code>sendSMS</code> request. However having information on the number of SMS
segments may be required by the application in order to inform the user (e.g.
in case the length of the text impacts on the price charged for sending the
message).
<p>Upon a new SMS message being received, the <a>user agent</a> MUST:
<ol>
<li>Let <var>smsMessage</var> be a new instance of <code>SmsMessage</code>.
<li>Generate a identifier for this message that is globally unique within
the implementation, i.e. there cannot be any other message with the same
identifier.
<li>Set the <code>messageID</code> of <em>smsMessage</em> to the
generated identifier.
<li>Set the <code>type</code> of <em>smsMessage</em> to 'sms'.
<li>Set the <code>serviceID</code> of <em>smsMessage</em> to the
identifier of the service at which the message has been received.
<li>Set the <code>from</code> of <em>smsMessage</em> to the
sender of the SMS message, i.e. the value of the TP Originating Address
(TP-OA) field of the SMS message [[!GSM-SMS]].
<li>Set the <code>timestamp</code> of <em>smsMessage</em> to the
timestamp of the SMS message, i.e. the value of the
TP-Service-Centre-Time-Stamp (TP-SCTS) parameter received in the SMS
DELIVER Protocol Data Unit [[!GSM-SMS]].
<li>Set the <code>read</code> of <em>smsMessage</em> to 'false'.
<li>Set the <code>to</code> of <em>smsMessage</em> to the recipient of the
SMS message, i.e. the value of the TP Destination Address (TP-DA) field of
the SMS message [[!GSM-SMS]].
<li>Set the <code>messageClass</code> of <em>smsMessage</em> to the
message class indicated in the TP-Data-Coding-Scheme (TP-DCS) field of the
SMS message [[!GSM-SMS]].
<li>Set the <code>body</code> element to the text of the received SMS
message, i.e. the value of the SM element contained within the TP User
Data (TP-UD) field of the SMS message [[!GSM-SMS]].
<li>Set the <code>state</code> of <em>smsMessage</em> to
'received'.
<li>Set the <code>deliveryStatus</code> of <em>smsMessage</em> to
'not-applicable'.
<li><a>Queue a task</a> to <a>fire an event</a> named <code><a
class="internalDFN" href="#dfn-sms-received-event">received</a></code>
with the <code>message</code> attribute set to <em>smsMessage</em>.
<li><a>Queue a task</a> to fire a system message named
<code>received</code> of type <code><a>ReceivedMessage</a></code> with the
<code>message</code> attribute set to <em>smsMessage</em>.
</ol>
<p>Upon a delivery report of a previously sent SMS message being received, the
<a>user agent</a> MUST
<ol>
<li>Let <var>smsMessage</var> be the instance of <code>SmsMessage</code>
to which this delivery report is related.
<li>Set the <code>deliveryStatus</code> parameter of <em>smsMessage</em>
to 'success' or 'error' depending on the reported
result.
<li>Set the <code>deliveryTimestamp</code> of <em>smsMessage</em>
to the delivery time of the SMS message, i.e. the TP-Discharge-Time (TP
DT) parameter included in the SMS-STATUS-REPORT Protocol Data Unit
[[!GSM-SMS]].
<li><a>Queue a task</a> to <a>fire an event</a> named <a
class="internalDFN"
href="#dfn-sms-deliverysuccess-event">deliverysuccess</a> or <a
class="internalDFN" href="#dfn-sms-deliveryerror-event">deliveryerror</a>
respectively if the delivery was successfull or not, with
<ol>
<li>the <code>messageID</code> attribute set to the
<code>messageID</code> attribute of <em>smsMessage</em>,
<li>the <code>serviceID</code> attribute set to the
<code>serviceID</code> attribute of <em>smsMessage</em>,
<li>the first item in the <code>recipients</code> attribute set to the
<code>to</code> attribute of <em>smsMessage</em>, and
<li>the first item in the <code>deliveryTimestamps</code> attribute set
to delivery time of such message.
</ol>
<li><a>Queue a task</a> to fire a system message of type
<code><a>DeliveryReport</a></code>named <code>deliverysuccess</code> or
<a>deliveryerror</a> respectively if the delivery was successfull or
not, with
<ol>
<li>the <code>messageID</code> attribute set to the
<code>messageID</code> attribute of <em>smsMessage</em>,
<li>the <code>serviceID</code> attribute set to the
<code>serviceID</code> attribute of <em>smsMessage</em>, and
<li>the first item in the <code>recipients</code> attribute set to the
<code>to</code> attribute of <em>smsMessage</em>.
<li>the first item in the <code>deliveryTimestamps</code> attribute set
to delivery time of such message.
</ol>
</ol>
<p> The <code>clear</code> method when invoked MUST run the following steps:
<ol>
<li>Let <var>promise</var> be a new <code>Promise</code> object and
<var>resolver</var> its associated <code>resolver</code>
<li>Return <var>promise</var> to the caller.
<li>Make a request to the system to delete all the messages associated to
the messaging service with identifier equal to the <code>serviceID</code>
parameter.
<li>If an <var>error</var> occurs invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a> with
<em>error</em> as the <code>value</code> argument.
<li>When the request has been successfully completed:
<ol>
<li>Let <var>serviceID</var> be the <code>serviceID</code> parameter
passed in the request
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>serviceID</em> as the <code>value</code> argument.
</ol>
</ol>
</section>
<section>
<h2>Event handlers</h2>
<p>The following are the <a class="internalDFN"
href="#dfn-eventhandler">event handlers</a> (and their corresponding <a
class="internalDFN" href="#dfn-eventtypes">event types</a>) that MUST be
supported as attributes by the <a>SmsManager</a> object.
<table class="simple">
<thead>
<tr>
<th>event handler</th>
<th>event name</th>
<th>event type</th>
<th>short description</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong><code>onreceived</code></strong></td>
<td><code><dfn id="dfn-sms-received-event">received</dfn></code></td>
<td><a><code>MessagingEvent</code></a></td>
<td>handles received messages</td>
</tr>
<tr>
<td><strong><code>onsent</code></strong></td>
<td><code><dfn id="dfn-sms-sent-event">sent</dfn></code></td>
<td><a><code>MessagingEvent</code></a></td>
<td>handles sent messages</td>
</tr>
<tr>
<td><strong><code>ondeliverysuccess</code></strong></td>
<td><code><dfn
id="dfn-sms-deliverysuccess-event">deliverysuccess</dfn></code></td>
<td><a><code>DeliveryReportEvent</code></a></td>
<td>handles successful delivery reports</td>
</tr>
<tr>
<td><strong><code>ondeliveryerror</code></strong></td>
<td><code><dfn
id="dfn-sms-deliveryerror-event">deliveryerror</dfn></code></td>
<td><a><code>DeliveryReportEvent</code></a></td>
<td>handles failure delivery reports</td>
</tr>
<tr>
<td><strong><code>onserviceadded</code></strong></td>
<td><code><dfn
id="dfn-sms-serviceadded-event">serviceadded</dfn></code></td>
<td><a><code>ServiceChangeEvent</code></a></td>
<td>handle new messaging services</td>
</td>
</tr>
<tr>
<td><strong><code>onserviceremoved</code></strong></td>
<td><code><dfn
id="dfn-sms-serviceremoved-event">serviceremoved</dfn></code></td>
<td><a><code>ServiceChangeEvent</code></a></td>
<td>handle disabled messaging services</td>
</td>
</tr>
</tbody>
</table>
</section>
</section>
<!-- - - - - - - - - - - - Interface SmsSegmentInfo - - - - - - - - - - - - -->
<section>
<h2><a>SmsSegmentInfo</a> Dictionary</h2>
<p>The <a>SmsSegmentInfo</a> dictionary contains information about the
segmentation of a given text to be sent as SMS.
<dl title="dictionary SmsSegmentInfo"
class="idl">
<dt>long segments</dt>
<dd>MUST return the total number of SMS segments needed to send the input
string, taking into account the encoding to be used to send such message as
well as the overhead associated to concatenated SMS messages.</dd>
<dt>long charsPerSegment</dt>
<dd>MUST return the number of characters available per SMS segment as per
the encoding to be used to send the SMS message. In case the variable length
encoding, the value of this element MUST be calculated asumming the minimum
length for all the characters.</dd>
<dt>long charsAvailableInLastSegment</dt>
<dd>MUST return the maximum number of available characters in the last
segment needed to send the input string. In case the variable length
encoding, the value of this element MUST be calculated asumming the minimum
length for all the remaining characters.</dd>
</dl>
</section>
<!-- - - - - - - - - - - - Interface MmsManager - - - - - - - - - - - - - - -->
<section>
<h2><a>MmsManager</a> Interface</h2>
<p>The <a>MmsManager</a> interface represents the MMS messaging service
manager.
<dl title="interface MmsManager : EventTarget"
class="idl">
<dt>readonly attribute MessageType type</dt> <dd>MUST return the type of the
messaging service manager. It can have the following values: 'sms' or
'mms'.</dd>
<dt>readonly attribute DOMString[] serviceIDs</dt> <dd>MUST return the
identifier of the different services for this type of messaging service
(e.g. 'sms_sim1').</dd>
<dt>FetchMode getFetchMode ()</dt>
<dd>This method requests to retrieve the fetch mode associated to a specific
service (the one identified by the <code>serviceID</code> parameter, if
provided, or the first item in the <code>serviceIDs</code> attribute of
the <code>MmsManager</code> otherwise).
<dl class='parameters'>
<dt>optional DOMString serviceID</dt>
<dd>
Identifier of the service whose fetch mode is queried.
</dd>
</dl>
</dd>
<dt>void setFetchMode ()</dt>
<dd>This method issues a request to the messaging system to set the MMS
message fetch mode for the service identified by the <code>serviceID</code>
parameter, if provided, or for all services otherwise, to the mode indicated
in the <code>fetchMode</code> parameter.
<dl class='parameters'>
<dt>FetchMode fetchMode</dt>
<dd>
Fetch mode that is requested to be set for a specific service.
</dd>
<dt>optional DOMString serviceID</dt>
<dd>
Identifier of the service whose fetch mode is requested to be set.
</dd>
</dl>
</dd>
<dt> Promise send ()</dt>
<dd>This method issues a request to the messaging system to send an MMS
message with the content and recipients included in the
<code>mmsContent</code> parameter.
A <code>Promise</code> object will be returned in order to notify the result
of the request.
<dl class='parameters'>
<dt>MmsContent mmsContent</dt>
<dd>
Content and recipients of the MMS message to be sent.
</dd>
<dt>optional MmsSendParameters sendParameters</dt>
<dd>
Set of parameters related to the submission of the message (e.g.
request of delivery/read report or not).
</dd>
</dl>
</dd>
<dt> Promise fetch ()</dt>
<dd>This method requests to fetch an MMS message with identifier equal to
the indicated in the <code>messageID</code> parameter from the URL indicated
in the MMS notification. The method returns a new <code>Promise</code> that
will allow the caller to be notified about the result (success, error) of
the
operation.
<dl class='parameters'>
<dt>DOMString messageID</dt>
<dd>
Identifier of the MMS message that is requested to be download.
</dd>
</dl>
</dd>
<dt>Promise clear ()</dt>
<dd>This method makes a request to delete all the messages associated to the
messaging service passed as parameter.
<dl class='parameters'>
<dt>DOMString serviceID</dt>
<dd>
Identifies the messaging service all whose messages are requested to
be deleted.
</dd>
</dl>