forked from sysapps/contacts-manager-api
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
478 lines (436 loc) · 20 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
<!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/43696/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">
navigator.getDataStores('contacts').then(function(stores) {
if (!stores.length)
return;
var store = stores[0];
// Create a contact.
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]
});
// Add new contact to the store.
store.insert(contact).then(function(id) {
console.log('Contact ' +
contact.name.givenNames[0] + ' ' +
contact.name.familyNames[0] + ' saved with id: ' +
id);
}, function(error) {
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://airpingu.github.io/data-store-api/index.html#datastore-interface">DataStore</a></dfn> interface
and the <dfn><a href="http://airpingu.github.io/data-store-api/index.html#idl-def-DataStoreKey">DataStoreKey</a></dfn>
type identifier are defined in [[!DATASTORE]].</p>
</section>
<!-- - - - - - - - - - - - - - Security - - - - - - - - - - - - - - - - -->
<section>
<h2>Security and privacy considerations</h2>
<p>This API must be only exposed to trusted content
</section>
<!-- Data Store integration -->
<section>
<h2>Access the contacts data stores</h2>
<p>The contacts data stores can be retrieved using the <code>getDataStores()</code> function on <code>Navigator</code>, as defined
in the Data Store API [[DATASTORE]], using <code>"contacts"</code> as label. This function returns an array of <a><code>DataStore</code></a>
objects asynchronously that can be used to get, update or insert <code>Contact</code> objects.</p>
<pre class="example highlight">
navigator.getDataStores('contacts').then(function(stores) {
if (!stores.length)
return;
var store = stores[0];
// ...
});
</pre>
</section>
<p class="issue">Which one is the system's default contacts datastore? the first one? Has a specific name?</p>
<section>
<h2>Data Store value type</h2>
<p>The values stored in contacts data stores are of type <a>Contact</a>.</p>
<!-- - - - - - - - - Contact Interface - - - - - - - - - - - - - - - - - -->
<section>
<h3><a>Contact</a> Interface</h3>
<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 DataStoreKey? id</dt>
<dd>Represents a unique identifier of the contact in the data store.
<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>
<h4>Steps</h4>
<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> <h4><a>ContactInit</a> Dictionary</h4>
<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>
<!-- - - - - - - - - ContactField Interface - - - - - - - - - - - - - - -->
<section>
<h3><a>ContactField</a> Interface</h3>
<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> <h4><a>ContactFieldInit</a> Dictionary</h4>
<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>
<h3><a>ContactTelField</a> Interface</h3>
<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> <h4><a>ContactTelFieldInit</a> Dictionary</h4>
<dl title="dictionary ContactTelFieldInit : ContactFieldInit" class="idl">
<dt>DOMString carrier</dt>
<dd>
</dl>
</section>
</section>
<!-- - - - - - - - - ContactAddress Interface - - - - - - - - - - - - - -->
<section>
<h3><a>ContactAddress</a> Interface</h3>
<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> <h4><a>ContactAddressInit</a> Dictionary</h4>
<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>
<h3>The <code>ContactGender</code> enum</h3>
<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>
<h3><a>ContactName</a> Interface</h3>
<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> <h4><a>ContactNameInit</a> Dictionary</h4>
<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>
</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>