forked from sysapps/contacts-manager-api
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
743 lines (682 loc) · 31.6 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
<!DOCTYPE html>
<html>
<head>
<title>Contacts Manager 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: "contacts-manager-api",
publishDate: "",
previousPublishDate: "",
previousMaturity: "",
edDraftURI: "http://www.w3.org/2012/sysapps/contacts-manager-api/",
// 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: "Christophe Dumez",
company: "Samsung Electronics, Co., Ltd",
companyURL: "http://www.samsung.com/sec" }
],
inlineCSS: true,
noIDLIn: true,
extraCSS: ["../ReSpec.js/css/respec.css"],
wg: "System Applications Working Group",
wgURI: "http://www.w3.org/2012/sysapps/",
wgPublicList: "public-sysapps",
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/58119/status",
};
</script>
</head>
<body>
<!-- - - - - - - - - - - - - - - Abstract - - - - - - - - - - - - - - - -->
<section id="abstract">
This specification defines a System Level API which offers a simple
interface to manage user's contacts stored in the system's address book. A
typical use case of the Contacts API is the implementation of an
application to manage said address book.
</section>
<!-- - - - - - - - - - - - Status of this document - - - - - - - - - - - -->
<section id="sotd">
This document defines a System Level API to manage the user's contacts
that are stored in the system's address book.
Future versions of this specification are expected to align the contact
data model with the <a href="http://www.w3.org/TR/contacts-api">Contacts
API</a> being defined by the Device APIs Working Group.
<p>If you find any issue with this specification, please
<a href="https://github.com/sysapps/contacts-manager-api/issues">file a
bug on Github</a>.
</section>
<!-- - - - - - - - - - - - - - - Introduction - - - - - - - - - - - - - -->
<section class="informative">
<h2>Introduction</h2>
<p>
The Contacts API allows to manage (create, edit, remove, etc) user's
contacts stored in the system's address book, and thus provides the
functionality needed to implement an application to manage said address
book.
<p>
An example of use is provided below:
<pre class="example highlight">
var contactName = new ContactName({
givenNames: ['John'],
familyNames: ['Doe']
});
var mobilePhone = new ContactTelField({ types: ['home'], preferred: true, value: '+34698765432' });
var contact = new Contact({
name: contactName,
phoneNumbers: [mobilePhone]
});
navigator.contacts.save(contact).then(
function(contact) { window.console.log('Contact ' +
contact.name.givenNames[0] + ' ' +
contact.name.familyNames[0] + ' saved!'); },
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 a simple event</a></dfn> are defined in [[!HTML5]].
<p>The terms <dfn><a
href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers"> event
handler</a></dfn> and <dfn><a
href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
event handler event types</a></dfn> 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 - - - - - - - - - - - - - - - - -->
<section>
<h2>Security and privacy considerations</h2>
<p>This API must be only exposed to trusted content
</section>
<section>
<h2><a>Navigator</a> Interface</h2>
<dl title="partial interface Navigator" class="idl">
<dt>readonly attribute ContactsManager contacts</dt>
<dd>
The object that exposes the contacts management functionality.
</dd>
</dl>
</section>
<!-- - - - - - - - - ContactsManager Interface - - - - - - - - - - - - - -->
<section>
<h2><a>ContactsManager</a> Interface</h2>
<p>The <a>ContactsManager</a> interface exposes the contacts management
functionality.
<dl title="interface ContactsManager : EventTarget"
class="idl">
<dt> Promise find ()</dt>
<dd>This method allows to search contacts within the address book that
match the criteria indicated in the <code>options</code> parameter.
It returns a <a><code>Promise</code></a> that will allow the caller to
be notified about the result of the operation.
<dl class='parameters'>
<dt>optional ContactFindOptions options</dt>
<dd>
Set of criteria that a contact needs to match to be included in
the outcomes of the <code>find</code>
operation.
</dd>
</dl>
</dd>
<dt> Promise clear ()</dt>
<dd>This method allows to remove all contacts in the address book.
It returns a <a><code>Promise</code></a> that will allow the caller to
be notified about the result of the operation.
</dd>
<dt> Promise save ()</dt>
<dd>This method allows to save a contact in the address book, e.g. an
existing contact after having been edited. So if a contact with the same
identifier, i.e. <code>id</code>, already exists in the address book, it
will be updated.
It returns a <a><code>Promise</code></a> that will allow the caller to
be notified about the result of the operation.
<dl class='parameters'>
<dt>Contact contact</dt>
<dd>
The <code>Contact</code> object that is requested to be saved in
the address book.
</dd>
</dl>
</dd>
<dt> Promise remove ()</dt>
<dd>This method allows to remove a contact from the address book.
It returns a <a><code>Promise</code></a> that will allow the caller to
be notified about the result of the operation.
<dl class='parameters'>
<dt>DOMString contactId</dt>
<dd>
The identifier of the <code>Contact</code> object that is
requested to be removed from the address book.
</dd>
</dl>
</dd>
<dt class="no-docs">
attribute EventHandler oncontactschange
</dt>
<dd>May be used to set an event handler to be called when contacts are
added, deleted or changed in some way.</dd>
</dl>
<p> The <dfn><code>find</code></dfn> method when invoked MUST run the
following steps:
<ol>
<li>Let <var>promise</var> be a new <a><code>Promise</code></a> object
and <var>resolver</var> its associated resolver.
<li>Return <var>promise</var> and continue the following steps
asynchronously.
<li>Make a request to the system to retrieve the contacts in the
address book matching the criteria indicated in the
<code>options</code> parameter.
<li>If there is an error invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a>
with no argument and terminate these steps.
<li>When the request has been completed:
<ol>
<li>Let <em>contacts</em> be a new array of
<a><code>Contact</code></a> objects providing the results of the
find operation.
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>contacts</em> as the <code>value</code> argument.
</ol>
</ol>
<p> The <dfn><code>clear</code></dfn> method when invoked MUST run the
following steps:
<ol>
<li>Let <var>promise</var> be a new <a><code>Promise</code></a> object
and <var>resolver</var> its associated resolver.
<li>Return <var>promise</var> and continue the following steps
asynchronously.
<li>Make a request to the system to clear all the contacts in the
address book.
<li>If there is an error invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-reject-algorithm">reject algorithm</a> with no argument and
terminate these steps.
<li>When the request has been completed invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-fulfill-algorithm">fulfill
algorithm</a> with no argument and terminate these steps.
</ol>
<p> The <dfn><code>save</code></dfn> method when invoked MUST run the
following steps:
<ol>
<li>Let <var>promise</var> be a new <a><code>Promise</code></a> object
and <var>resolver</var> its associated resolver.
<li>Return <var>promise</var> and continue the following steps
asynchronously.
<li>Make a request to the system to save in the address book the
<a><code>Contact</code></a> object passed as parameter.
<li>If there is an error invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a>
with no argument and terminate these steps.
<li>When the request has been completed:
<ol>
<li>Let <em>contact</em> be the <a><code>Contact</code></a> object
as returned by the system, and which therefore has its
<code>id</code> and <code>lastUpdated</code> parameters set, whereas
they could be null in the original <a><code>Contact</code></a>
object passed as parameter, for instance if it is a brand new
<a><code>Contact</code></a> object not yet stored in the address
book.
<li>Invoke <em>resolver</em>'s <a class="internalDFN"
href="#dfn-fulfill-algorithm">fulfill algorithm</a> with
<em>contact</em> as the <code>value</code> argument.
</ol>
</ol>
<p> The <dfn><code>remove</code></dfn> method when invoked MUST run the
following steps:
<ol>
<li>Let <var>promise</var> be a new <a><code>Promise</code></a> object
and <var>resolver</var> its associated resolver.
<li>Return <var>promise</var> and continue the following steps
asynchronously.
<li>Make a request to the system to remove the
<a><code>Contact</code></a> object identified by the
<code>contactId</code> passed as parameter from the address book.
<li>If there is an error invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-reject-algorithm">reject algorithm</a>
with no argument and terminate these steps.
<li>When the request has been completed invoke <em>resolver</em>'s <a
class="internalDFN" href="#dfn-fulfill-algorithm">fulfill
algorithm</a> with no argument and terminate these steps.
</ol>
<p> Upon a change in a contact or set thereof is performed (i.e.
contact(s) added / modified / removed) the system MUST <a>fire a simple
event</a> named <a><code>contactschange</code></a> that implements the
<a><code>ContactsChangeEvent</code></a> interface at the
<a><code>ContactsManager</code></a> object
<section>
<h2>Event handlers</h2>
<p>The following are the <a>event handlers</a> (and their corresponding
<a>event handler event types</a>) that MUST be supported as attributes
by the <a>ContactsManager</a> object:
<table class="simple">
<thead>
<tr>
<th>event handler</th>
<th>event handler event type</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong><code>oncontactschange</code></strong></td>
<td><code><dfn>contactschange</dfn></code></td>
</tr>
</tbody>
</table>
</section>
<p>The event named <a><code>contactschange</code></a> MUST implement the
<a>ContactsChangeEvent</a> interface.
</section>
<!-- - - - - - - - - ContactFindOptions Dictionary - - - - - - - - - - - -->
<section>
<h2><a>ContactFindOptions</a> Dictionary</h2>
<p>The <a>ContactFindOptions</a> dictionary represents the criteria used
to select the contacts to be returned by a <code>find</code> operation.
<dl title="dictionary ContactFindOptions"
class="idl">
<dt>DOMString value</dt>
<dd>Represents the value used for the filtering (e.g. "Tom").
<dt>FilterOperator operator</dt>
<dd>Represents the filtering operator used for the filtering.
<dt>sequence<DOMString> fields</dt>
<dd>Represents the set of fields in which the search is performed (e.g.
"givenName").
<dt>sequence<DOMString> sortBy</dt>
<dd>Represents the fields by which the results of the search are sorted
(e.g. ["givenNames", "familyNames"]). The results are sorted by the
first field, then by the following one, if present, and so on.
<dt>SortOrder sortOrder</dt>
<dd>Represents the order in which the results of the search are sorted.
<dt>unsigned long resultsLimit</dt>
<dd>Represents the maximum number of results that can be returned by the
search operation.
</dl>
<section>
<h2>Enumerations</h2>
<p>There are 2 possible filter operations:
<dl class="idl" title="enum FilterOperator">
<dt>contains</dt>
<dd>
With this operation, a contact will be returned if its filtered
field contains the given value.
</dd>
<dt>is</dt>
<dd>
With this operation, a contact will be returned if its filtered
field matches exactly the given value.
</dd>
</dl>
<p>The returned contacts can be sorted in one of the following orders:
<dl class="idl" title="enum SortOrder">
<dt>ascending</dt>
<dd>
The contacts will be sorted in ascending order.
</dd>
<dt>descending</dt>
<dd>
The contacts will be sorted in descending order.
</dd>
</dl>
</section>
<p class="issue">
It is for further study whether the level of flexibility of the filters
needs to be increased and/or additional mechanisms need to be put in
place so that applications can keep a local copy of the address book
and perform the filtering locally (e.g. startTrackingChanges() and
getNewChanges() methods)
</p>
</section>
<!-- - - - - - - - - ContactField Interface - - - - - - - - - - - - - - -->
<section>
<h2><a>ContactField</a> Interface</h2>
<p>The <a>ContactField</a> interface represents a user's attribute and the
types associated to it.
<dl title="[Constructor(optional ContactFieldInit initDict)]
interface ContactField"
class="idl">
<dt>attribute DOMString[] types</dt>
<dd>Indicates the types of this contact field (e.g. "home",
"work").</dd>
<dt>attribute boolean preferred</dt>
<dd>Indicates whether this is the preferred contact field.</dd>
<dt>attribute DOMString value</dt>
<dd>A string that contains the user's address.</dd>
</dl>
<section> <h3><a>ContactFieldInit</a> Dictionary</h3>
<dl title="dictionary ContactFieldInit" class="idl">
<dt>sequence<DOMString> types</dt>
<dd>
<dt>boolean preferred</dt>
<dd>
<dt>DOMString value</dt>
<dd>
</dl>
</section>
</section>
<!-- - - - - - - - - ContactTelField Interface - - - - - - - - - - - - - -->
<section>
<h2><a>ContactTelField</a> Interface</h2>
<p>The <a>ContactTelField</a> interface represents a telephone number as
well as metadata associated to it, namely the types (e.g. "voice", "text")
and the carrier providing service to the telephony subscription associated
to that number.
<dl title="[Constructor(optional ContactTelFieldInit initDict)]
interface ContactTelField : ContactField"
class="idl">
<dt>attribute DOMString? carrier</dt>
<dd>Indicates the carrier providing service to the telephony
subscription associated to that number</dd>
</dl>
<section> <h3><a>ContactTelFieldInit</a> Dictionary</h3>
<dl title="dictionary ContactTelFieldInit : ContactFieldInit" class="idl">
<dt>DOMString carrier</dt>
<dd>
</dl>
</section>
</section>
<!-- - - - - - - - - ContactAddress Interface - - - - - - - - - - - - - -->
<section>
<h2><a>ContactAddress</a> Interface</h2>
<p>The <a>ContactAddress</a> interface represents a user's physical
address and the types associated to it. This interface is based on <a
href="http://tools.ietf.org/html/rfc6350">vCard 4.0</a> ADR attribute.
<dl title="[Constructor(optional ContactAddressInit initDict)]
interface ContactAddress"
class="idl">
<dt>attribute DOMString[] types</dt>
<dd>Indicates the types of this contact field (e.g. "home",
"work").</dd>
<dt>attribute boolean preferred</dt>
<dd>Indicates whether this is the preferred contact field.</dd>
<dt>attribute DOMString streetAddress</dt>
<dd>A string that contains the name of the street. It maps to the third
component in vCard's ADR attribute.</dd>
<dt>attribute DOMString locality</dt>
<dd>A string that contains the name of the locality. It maps to the
forth component in vCard's ADR attribute.</dd>
<dt>attribute DOMString region</dt>
<dd>A string that contains the name of the region. It maps to the fifth
component in vCard's ADR attribute.</dd>
<dt>attribute DOMString postalCode</dt>
<dd>A string that contains the postal code. It maps to the sixth
component in vCard's ADR attribute.</dd>
<dt>attribute DOMString countryName</dt>
<dd>A string that contains the name of the country. It maps to the
seventh component in vCard's ADR attribute.</dd>
</dl>
<section> <h3><a>ContactAddressInit</a> Dictionary</h3>
<dl title="dictionary ContactAddressInit" class="idl">
<dt>sequence<DOMString> types</dt>
<dd>
<dt>boolean preferred</dt>
<dd>
<dt>DOMString streetAddress</dt>
<dd>
<dt>DOMString locality</dt>
<dd>
<dt>DOMString region</dt>
<dd>
<dt>DOMString postalCode</dt>
<dd>
<dt>DOMString countryName</dt>
<dd>
</dl>
</section>
</section>
<section>
<h2>The <code>ContactGender</code> enum</h2>
<dl title="enum ContactGender" class="idl">
<dt>male</dt>
<dd>contact is a male.</dd>
<dt>female</dt>
<dd>contact is a female.</dd>
<dt>other</dt>
<dd>contact has another gender.</dd>
<dt>none</dt>
<dd>contact does not have a gender (not applicable).</dd>
<dt>unknown</dt>
<dd>contact's gender is unknown.</dd>
</dl>
</section>
<!-- - - - - - - - - ContactName Interface - - - - - - - - - - - - - - - -->
<section>
<h2><a>ContactName</a> Interface</h2>
<p>The <a>ContactName</a> interface represents a user's naming attributes.
<dl title="[Constructor(optional ContactNameInit initDict)]
interface ContactName"
class="idl">
<dt>attribute DOMString displayName</dt>
<dd>A string representing the contact's display name. It maps to vCard's
FN attribute.
<dt>attribute DOMString[] honorificPrefixes</dt>
<dd>A string or set thereof representing the contact's honorific
prefix(es). It maps to the forth component in vCard's N attribute.
<dt>attribute DOMString[] givenNames</dt>
<dd>A string or set thereof representing the contact's given name(s). It
maps to the second component in vCard's N attribute.
<dt>attribute DOMString[] additionalNames</dt>
<dd>A string or set thereof representing any additional name of the
contact. It maps to the third component in vCard's N attribute.
<dt>attribute DOMString[] familyNames</dt>
<dd>A string or set thereof representing the contact's family name(s).
It maps to the first component in vCard's N attribute.
<dt>attribute DOMString[] honorificSuffixes</dt>
<dd>A string or set thereof representing the contact's honorific
suffix(es). It maps to the fifth component in vCard's N attribute.
<dt>attribute DOMString[] nicknames</dt>
<dd>A string or set thereof representing the contact's nick name(s). It
maps to vCard's NICKNAME attribute.
</dl>
<section> <h3><a>ContactNameInit</a> Dictionary</h3>
<dl title="dictionary ContactNameInit" class="idl">
<dt>DOMString displayName</dt>
<dd>
<dt>sequence<DOMString> honorificPrefixes</dt>
<dd>
<dt>sequence<DOMString> givenNames</dt>
<dd>
<dt>sequence<DOMString> additionalNames</dt>
<dd>
<dt>sequence<DOMString> familyNames</dt>
<dd>
<dt>sequence<DOMString> honorificSuffixes</dt>
<dd>
<dt>sequence<DOMString> nicknames</dt>
<dd>
</dl>
</section>
</section>
<!-- - - - - - - - - Contact Interface - - - - - - - - - - - - - - - - - -->
<section>
<h2><a>Contact</a> Interface</h2>
<p>The <a>Contact</a> interface represents a contact stored in the address
book. As a principle the attributes are based on <a
href="http://tools.ietf.org/html/rfc6350">vCard 4.0</a> and reuse the
literal used in that standard. Any naming deviation is mentioned in the
description of the corresponding attribute. Whereas this correspondence
facilitates the import/export from/to vCard format it should be noted that
a vCard import/export API is out of scope of this specification as parsing
and serializing can be efficiently done in JavaScript, and libraries are
readily available.
<dl title="[Constructor(optional ContactInit contactInitDict)]
interface Contact"
class="idl">
<dt>readonly attribute DOMString? id</dt>
<dd>Represents a unique identifier of the contact in the address book.
<dt>readonly attribute Date? lastUpdated</dt>
<dd>A <code>Date</code> element representing the date when the contact
was last updated.
<dt>attribute ContactName name</dt>
<dd>An object representing the different naming attributes of the
contact.
<dt>attribute ContactField[] emails</dt>
<dd>A <code>ContactField</code> element or set thereof containing the
contact's email address(es). It maps to vCard's EMAIL attribute.</dd>
<dt>attribute DOMString[] photos</dt>
<dd>A string or set thereof representing the URI of the photo(s) of the
contact. It maps to vCard's PHOTO attribute.
<dt>attribute ContactField[] urls</dt>
<dd>A <code>ContactField</code> element or set thereof containing the
user's urls (e.g. personal blog). It maps to vCard's URL attribute.</dd>
<dt>attribute DOMString[] categories</dt>
<dd>A string or set thereof representing the category or categories
associated to the contact (e.g. "family"). It maps to vCard's CATEGORIES
attribute.
<dt>attribute ContactAddress[] addresses</dt>
<dd>A <code>ContactAddress</code> element or set thereof containing the
user's physical address(es). It maps to vCard's ADR attribute</dd>
<dt>attribute ContactTelField[] phoneNumbers</dt>
<dd>A <code>ContactTelField</code> element or set thereof containing the
user's telephone numbers. It maps to vCard's TEL attribute</dd>
<dt>attribute DOMString[] organizations</dt>
<dd>A string or set thereof representing the organization(s) the contact
belongs to. It maps to vCard's ORG attribute
<dt>attribute DOMString[] jobTitles</dt>
<dd>A string or set thereof representing the contact's job title(s). It
maps to vCard's TITLE attribute
<dt>attribute Date? birthday</dt>
<dd>A <code>Date</code> element representing the contact's birth date.
It maps to vCard's BDAY attribute
<dt>attribute DOMString[] notes</dt>
<dd>A string or set thereof specifying supplemental information or a
comment that is associated with the contact. It maps to vCard's NOTE
attribute
<dt>attribute ContactField[] impp</dt>
<dd>A <code>ContactField</code> element or set thereof containing the
user's instant messaging address(es). It maps to vCard's IMPP
attribute</dd>
<dt>attribute Date? anniversary</dt>
<dd>A <code>Date</code> element representing the contact's anniversary.
It maps to vCard's ANNIVERSARY attribute</dd>
<dt>attribute ContactGender gender</dt>
<dd>A string representing the contact's gender. It maps to the first
component of vCard's GENDER attribute.
</dl>
<section>
<h3>Steps</h3>
<p> The <a>Contact</a> interface's contructor when invoked MUST run the
following steps:
<ol>
<li>Let <var>contact</var> be a new <code>Contact</code> object.
<li>Make a request to the system to generate a new unique contact
identifier.
<li>Set the <code>id</code> attribute of <var>contact</var> to the
generated contact identifier.
<li>Set the <code>lastUpdated</code> attribute of <var>contact</var> to
the Date at which the constructor was invoked.
<li>Set the other attributes of <var>contact</var> to the value of the
corresponding element in the <code>contactInitDict</code> dictionary, if
present.
</ol>
</section>
<section> <h3><a>ContactInit</a> Dictionary</h3>
<dl title="dictionary ContactInit" class="idl">
<dt>ContactName name</dt>
<dd>
<dt>sequence<ContactField> emails</dt>
<dd>
<dt>sequence<DOMString> photos</dt>
<dd>
<dt>sequence<ContactField> urls</dt>
<dd>
<dt>sequence<DOMString> categories</dt>
<dd>
<dt>sequence<ContactAddress> addresses</dt>
<dd>
<dt>sequence<ContactTelField> phoneNumbers</dt>
<dd>
<dt>sequence<DOMString> organizations</dt>
<dd>
<dt>sequence<DOMString> jobTitles</dt>
<dd>
<dt>Date birthday</dt>
<dd>
<dt>sequence<DOMString> notes</dt>
<dd>
<dt>sequence<ContactField> impp</dt>
<dd>
<dt>Date anniversary</dt>
<dd>
<dt>ContactGender gender</dt>
<dd>
</dl>
</section>
</section>
<!-- - - - - - - - - ContactsChangeEvent Interface - - - - - - - - - - - -->
<section>
<h2><a>ContactsChangeEvent</a> Interface</h2>
<p>The <a>ContactsChangeEvent</a> interface represents events related to
the set of contacts that have been simultaneously added, removed and/or
modified. Changes that are applied to the address book in batches cause a
<a>ContactsChangeEvent</a> with multiple contact references to be fired,
whereas changes applied sequentially cause a <a>ContactsChangeEvent</a>
with a single contact reference to be fired
<dl title="[Constructor(DOMString type, optional ContactsChangeEventInit
eventInitDict)]
interface ContactsChangeEvent : Event"
class="idl">
<dt>readonly attribute DOMString[] added</dt>
<dd>Indicates the identifier(s) of the <code>Contact</code> object(s)
that have been added.</dd>
<dt>readonly attribute DOMString[] modified</dt>
<dd>Indicates the identifier(s) of the <code>Contact</code> object(s)
that have been modified.</dd>
<dt>readonly attribute DOMString[] removed</dt>
<dd>Indicates the identifier(s) of the <code>Contact</code> object(s)
that have been removed.</dd>
</dl>
<section> <h3><a>ContactsChangeEventInit</a> Dictionary</h3>
<dl title="dictionary ContactsChangeEventInit : EventInit" class="idl">
<dt>sequence<DOMString> added</dt>
<dd>
<dt>sequence<DOMString> modified</dt>
<dd>
<dt>sequence<DOMString> removed</dt>
<dd>
</dl>
</section>
</section>
<!-- - - - - - - - - Acknowledgements - - - - - - - - - - - - - - - - - -->
<section>
<h2>Acknowledgements</h2>
<p>The editors would like to express their gratitude to the Mozilla B2G
Team for their technical guidance, implementation work and support, and
specially to Tantek Çelik and Gregor Wagner, the original authors of B2G
Contact API.</p>
</section>
</body>
</html>