35 | The Pick Contacts Intent defines a Web Intent [[!WEBINTENTS]] that enables access to a user's
36 | address book service from inside a Web application. It defines both an Intent action/type
37 | pair that selects this operation, and the format of the contacts data that is returned
38 | by services implementing this specification
39 |
40 |
41 |
42 |
43 |
44 | This document builds atop previous versions that were pure JavaScript APIs and turns them
45 | into an API built using Web Intents, while maintaining the data format which the JavaScript
46 | APIs had defined.
47 |
48 |
49 |
50 |
51 |
Introduction
52 |
53 | Every operating system and a large number of Web-based service providers have different ways of
54 | representing address book information. Most users are required to maintain a plurality of contact lists
55 | which leads to multiple copies of address book data. This in turn often leads to disjoint and inconsistent
56 | information being stored across a user's address book providers.
57 |
58 |
59 | When sharing contact data with third parties users are, more often than not, required to hand over access to
60 | their whole address book. Users are implicitly required to trust third parties with all of their data
61 | when, in reality, the user may only wish, or need, to share a subset of their address book information so
62 | that an application can fulfil its purpose. When sharing of only a subset of a user's address book is
63 | possible, it often requires the user to type the information into a form herself rather than having it
64 | extracted from one of her address book services.
65 |
66 |
67 | This specification enables a Web application to have access to a selected subset of a user's address book,
68 | obtained from arbitrary services not known to the Web application. The interactions, brokered using
69 | Web Intents [[!WEBINTENTS]] are designed in order to maximise the user's security and privacy.
70 | Address book data may be sourced from a plurality of sources — both online and local to the user's device
71 | — so long as those sources are registered as Intent services with the user agent. It defines a common
72 | format which services use to provide data to Web applications in a consistent and interoperable manner.
73 |
74 |
75 | The expectation is that data sharing happens with explicit user permission and filtering. The focus of
76 | this data sharing is on making the user aware of the data that they will share and putting them at the
77 | centre of the data sharing process; free to select both the extent to which they share their address
78 | book information and the ability to restrict which pieces of information related to which contact gets shared.
79 |
80 |
81 | A set of Security and Privacy Considerations are
82 | presented for the discretion of both implementers of Pick Contacts Intent services and recipients of contact
83 | information (i.e. Web applications).
84 |
85 |
86 | The following code illustrates how to obtain contact information from a user's address book:
87 |
88 |
89 | var intent = new Intent({ action: "http://webintents.org/pick",
90 | type: "http://w3.org/type/contact",
91 | extras: { fields: ["displayName", "emails"] }});
92 | navigator.startActivity(intent, contactsOK, contactsFail);
93 |
94 | function contactsOK (contacts) {
95 | // iterate over the array of contacts to do something useful with them
96 | }
97 | function contactsFail (err) {
98 | // display an error to the user
99 | }
100 |
101 |
102 | When the above code is run, the user would typically be prompted by her user agent to select
103 | a service able to pick a contact (there may be several such services, if she has multiple address
104 | book sources). Upon selecting a service, she will be presented with an interface enabling her
105 | to choose what contact information is returned to the Web application. Upon completing her
106 | choice, the contacts data would be returned to the Web application in the contactsOK
107 | callback.
108 |
109 |
110 |
111 |
112 |
113 | There is only one single conformance requirement placed upon the user agent
114 | product: a user agent MUST support Web Intents [[!WEBINTENTS]].
115 |
116 |
117 | The conformance criteria in this specification apply to a single product: the
118 | contact service which exposes a Web Intent service that
119 | handles Pick Contact Intents as defined in this specification.
120 |
121 |
122 | The data returned by the contact service is described in this specification using [[!WEBIDL]].
123 | When this data is provided using JavaScript, then the contact service MUST do so in a manner
124 | consistent with the ECMAScript Bindings defined in the Web IDL specification.
125 |
126 |
127 |
128 |
129 |
Security and Privacy Considerations
130 |
131 | The Intent defined in this specification can be used to find contact information from a user's address
132 | books. This discloses information related to a user's contacts such as their phone numbers, email
133 | addresses and other personally identifying information. The distribution of this information could
134 | potentially compromise the user's privacy, or the user's contacts' privacy. A conforming implementation
135 | of this specification should provide a mechanism that protects the user's privacy and this mechanism should
136 | ensure that no contact information is retrievable without the user's express permission.
137 |
138 |
139 |
Privacy considerations for implementers of the Pick Contacts Intent
140 |
141 | A contact service should not provide contact information to Web sites without the express
142 | permission of the user. Obtaining the user's express permission to access a set of contacts does
143 | not imply that the user has granted permission for the same Web site to access more contact information.
144 | A contact service should take great care to ensure that the user can clearly see which information
145 | is about to be shared, and must not share more information than has been requested by the Web application.
146 |
147 |
148 | A user agent may have prearranged trust relationships with a specific contact service
149 | that do not require such user interaction.
150 |
151 |
152 |
153 |
Privacy considerations for recipients of contact information
154 |
155 | Web sites operators that retrieve contacts information using this Intent are denoted as recipients
156 | below.
157 |
158 |
159 | Recipients should only request contact information when necessary, and only use the contact
160 | information for the task for which it was provided to them.
161 |
162 |
163 | Recipients should dispose of contact information once that task is completed, unless expressly
164 | permitted to retain it by the user. Recipients should also take measures to protect this information
165 | against unauthorised access. If contact information is stored, users should be allowed to update and
166 | delete this information.
167 |
168 |
169 | The recipient of contact information should not retransmit the contact information without the
170 | user's express permission. Care should be taken when retransmitting and use of encryption is
171 | encouraged.
172 |
173 |
174 | Recipients should clearly and conspicuously disclose the fact that they are collecting contact data,
175 | the purpose of the collection, how long the data is retained, how the data is secured, how the data is
176 | shared if it is shared, how users can access, update and delete the data, and any other choices that
177 | users have with respect to the data. This disclosure should include an explanation of any exceptions to
178 | the guidelines listed above.
179 |
180 |
181 | Note that even if a user gives permission to share their contact information this can have serious
182 | privacy implications for those parties whose contacts are shared, as they may not wish such sharing to
183 | occur. This should be considered by Web applications when requesting and using such information.
184 |
185 |
186 |
187 |
Additional implementation considerations
188 |
189 | Further to the requirements listed in the previous section, implementers of a user agents are
190 | also advised to consider the following aspects that can negatively affect the privacy of their users:
191 | in certain cases, users can inadvertently grant permission to disclose their contacts
192 | to Web sites. In other cases, the content hosted at a certain URL changes in such a way that the
193 | previously granted contact permissions no longer apply as far as the user is concerned. Or the users
194 | might simply change their minds.
195 |
196 |
197 | Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive
198 | measures are a user agent's responsibility and not prescribed by this specification. However, in
199 | designing these measures, implementers are advised to enable user awareness of information sharing, and to
200 | provide easy access to user interfaces that enable revocation of permissions that Web applications have to
201 | access this Intent.
202 |
203 |
204 |
205 |
206 |
207 |
Intent Description
208 |
209 | The action for this Intent is http://webintents.org/pick.
210 |
211 |
212 | The type for this Intent is http://w3.org/type/contact.
213 |
214 |
215 | When a contact service is matched for delivery using these action and type, it
216 | MUST respond in one of two ways:
217 |
218 |
219 |
220 | If contacts have been successfully selected for delivery, then a successful payload is returned
221 | to the client (using postResult()) matching the data format defined below.
222 |
223 |
224 | If an error of any kind takes place in the service, then an error payload is returned (using
225 | postFailure()) matching the error data format defined below. The contact service
226 | MUST NOT treat the user selecting zero contacts or cancelling the service as error conditions.
227 |
228 |
229 |
230 |
Intent Extras
231 |
232 | The Pick Contact Intent can be instantiated with an extras field that adheres to the
233 | following dictionary.
234 |
238 | The ContactIntentExtras dictionary describes the options that can be applied to contact searching.
239 |
240 |
241 |
DOMString? search
242 |
243 | A string which provides a hint to the contact service to facilitate contacts selection by the user.
244 | The exact manner in which this hint is exploited is entirely up to the contact service.
245 |
246 |
unsigned long? limit
247 |
248 | By default a contact service MAY return as many contacts as the user selects. If limit
249 | is specified, the contact service MUST NOT return more than limit contacts. The
250 | contact service SHOULD enforce this limitation in the user interface that it exposes.
251 |
252 |
DOMString[] fields
253 |
254 | An array of field names corresponding to the name of the fields in the Contact dictionary that
255 | the Web application is requesting from the contact service. The contact service MUST
256 | NOT return defined fields on the contact objects that it provides other than those present in this
257 | list. If a field name is provided that the contact service does not recognise as a field
258 | of the Contact dictionary, then it MUST ignore it.
259 |
260 |
261 |
262 |
263 |
264 |
265 |
Data Format
266 |
267 | Upon successful invocation, the contact service MUST return an array of Contact dictionaries.
268 |
272 | The Contact dictionary captures the properties of a contact object. All properties included in this
273 | interface have a corresponding definition in [[POCO-SCHEMA]], [[RFC2426]] (also known as vCard), and
274 | [[OMA-CAB]], thereby allowing the data format to be supported across implementations supporting these
275 | various contact representations.
276 |
284 | A globally unique identifier for the given Contact object.
285 |
286 |
DOMString? displayName
287 |
288 | This attribute contains the name of this Contact in a form that is suitable for display
289 | to the user.
290 |
291 |
ContactName? name
292 |
293 | This attribute represents the full name of this Contact indicated by the name components
294 | associated with the ContactName dictionary.
295 |
296 |
DOMString? nickname
297 |
298 | This attribute contains the nickname (or a casual name) for this Contact.
299 |
300 |
ContactField[]? phoneNumbers
301 |
302 | This attribute captures one or more phone numbers associated with this Contact.
303 |
304 |
ContactField[]? emails
305 |
306 | This attribute represents one or more email addresses associated with this Contact.
307 |
308 |
ContactAddress[]? addresses
309 |
310 | This attribute represents one or more physical addresses associated with this Contact.
311 |
312 |
ContactField[]? ims
313 |
314 | This attribute represents one or more instant messaging identifiers associated with this
315 | Contact.
316 |
317 |
ContactOrganization[]? organizations
318 |
319 | This attribute represents one or more organisations associated with this Contact.
320 |
321 |
Date? birthday
322 |
323 | This attribute contains birthday of this Contact. The contact service MAY
324 | set the year value to 0000 when the age of the Contact is private or the year is not
325 | available.
326 |
327 |
DOMString? note
328 |
329 | This attribute contains the personal notes (free-text) for this Contact that is managed by the
330 | user of the address book.
331 |
332 |
ContactField[]? photos
333 |
334 |
335 | This attribute represents one or more photos associated with this Contact.
336 |
337 |
338 | The photos MUST be specified in the value attribute of the ContactField object
339 | by using a URL pointing to an image resource. The data: URI scheme may be used in order
340 | to provide inline data.
341 |
342 |
343 | A contact service SHOULD NOT use this attribute to send down arbitrary photos taken by this user,
344 | but specifically profile photos of the contact suitable for display when describing the
345 | contact.
346 |
347 |
348 |
DOMString[]? categories
349 |
350 | This attribute contains one or more user-defined categories/tags/labels associated with this
351 | Contact. e.g. "family", "favourite", "cryptozoologists".
352 |
353 |
ContactField[]? urls
354 |
355 |
356 | This attribute represents one or more URLs associated with this Contact e.g. personal web page,
357 | blog.
358 |
395 | The ContactField dictionary is a reusable component that is used to capture contact fields of the
396 | Contact dictionary that have some modicum of structure.
397 |
398 |
399 |
400 |
DOMString type
401 |
402 | This attribute contains the type information for this ContactField and its content varies subject
403 | to the contact property this ContactField is representing. For example, if the ContactField
404 | is representing a phoneNumber property, the type attribute can be set to
405 | home, mobile; if the ContactField is representing the ims
406 | property, the type attribute could be set to xmpp, irc, bbm, etc.
407 |
408 |
DOMString? value
409 |
410 | This attribute contains the value for this ContactField and its content varies subject to the
411 | contact property this ContactField is representing. For example, if the ContactField is
412 | representing an email, the value attribute could be set to JoeSmith@example.com,
413 | and if the ContactField is representing a url, the value attribute can be set to
414 | http://www.example.org/joesmith, etc.
415 |
416 |
boolean pref
417 |
418 | This attribute indicates whether this instance of the ContactField is the
419 | preferred, or primary, value for the contact property this ContactField is
420 | representing in the Contact interface. By default, the value is false.
421 |
428 | The ContactAddress dictionary is a reusable component that is used to capture addresses
429 | within the Contact dictionary.
430 |
431 |
432 |
boolean pref
433 |
434 | This attribute indicates whether this instance of the ContactAddress is the preferred,
435 | or primary, value for the contact. By default, the value is false.
436 |
437 |
DOMString? type
438 |
439 | This attribute contains the type of address this object is representing (e.g. work,
440 | home, premises, etc).
441 |
442 |
DOMString? streetAddress
443 |
444 | This attribute contains the street address corresponding to this ContactAddress.
445 |
446 |
DOMString? locality
447 |
448 | This attribute contains the locality (or city) name corresponding to this ContactAddress.
449 |
450 |
DOMString? region
451 |
452 | This attribute contains the region (or state/province) name corresponding to this ContactAddress.
453 |
454 |
DOMString? postalCode
455 |
456 | This attribute contains the postal code (or zip) corresponding to this ContactAddress.
457 |
458 |
DOMString? country
459 |
460 | This attribute contains the country name corresponding to this ContactAddress.
461 |
468 | The ContactOrganization dictionary is a reusable component that is used to support contact
469 | organisations within the Contact dictionary.
470 |
471 |
472 |
boolean pref
473 |
474 | This attribute indicates whether this instance of the ContactOrganization is the preferred, or
475 | primary, value for the contact. By default, the value is false.
476 |
477 |
DOMString? type
478 |
479 | This attribute contains the type of organisation this object is representing.
480 |
481 |
DOMString? name
482 |
483 | The name of the organisation.
484 |
485 |
DOMString? department
486 |
487 | The department within which this Contact works.
488 |
489 |
DOMString? title
490 |
491 | The job title that the Contact holds inside this organisation.
492 |
498 | If the contact service encounters an error then it MUST return an error
499 | (through postFailure()) using the ContactError dictionary.
500 |
501 |
502 |
DOMString message
503 |
A message describing the error.
504 |
505 |
506 |
507 |
Extended Contact Properties and Parameters
508 |
509 | A contact service MAY extend the dictionaries described in in the Data Formats section with
510 | additional fields. If providing an extended field, a contact service MUST prefix its name
511 | with X (U+0058 LATIN CAPITAL LETTER X) or use a vendor-specific prefix.
512 |
455 | The Pick Contacts Intent defines a Web Intent [WEBINTENTS] that enables access to a user's
456 | address book service from inside a Web application. It defines both an Intent action/type
457 | pair that selects this operation, and the format of the contacts data that is returned
458 | by services implementing this specification
459 |
460 |
Status of This Document
461 |
462 |
463 |
464 |
465 | This section describes the status of this document at the time of its publication. Other
466 | documents may supersede this document. A list of current W3C publications and the latest revision
467 | of this technical report can be found in the W3C technical reports
468 | index at http://www.w3.org/TR/.
469 |
470 |
471 |
472 | This document builds atop previous versions that were pure JavaScript APIs and turns them
473 | into an API built using Web Intents, while maintaining the data format which the JavaScript
474 | APIs had defined.
475 |
476 |
477 |
478 | This document was published by the Device APIs Working Group as a Working Draft.
479 |
480 | This document is intended to become a W3C Recommendation.
481 |
482 | If you wish to make comments regarding this document, please send them to
483 | public-device-apis@w3.org
484 | (subscribe,
485 | archives).
486 |
487 |
488 | All feedback is welcome.
489 |
490 |
491 |
492 | Publication as a Working Draft does not imply endorsement by the W3C Membership.
493 | This is a draft document and may be updated, replaced or obsoleted by other documents at
494 | any time. It is inappropriate to cite this document as other than work in progress.
495 |
496 |
497 |
498 |
499 |
500 | This document was produced by a group operating under the
501 | 5 February 2004 W3C Patent Policy.
502 |
503 |
504 |
505 |
506 | W3C maintains a public list of any patent disclosures
507 |
508 | made in connection with the deliverables of the group; that page also includes instructions for
509 | disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains
510 | Essential Claim(s) must disclose the
511 | information in accordance with section
512 | 6 of the W3C Patent Policy.
513 |
514 |
515 |
527 | Every operating system and a large number of Web-based service providers have different ways of
528 | representing address book information. Most users are required to maintain a plurality of contact lists
529 | which leads to multiple copies of address book data. This in turn often leads to disjoint and inconsistent
530 | information being stored across a user's address book providers.
531 |
532 |
533 | When sharing contact data with third parties users are, more often than not, required to hand over access to
534 | their whole address book. Users are implicitly required to trust third parties with all of their data
535 | when, in reality, the user may only wish, or need, to share a subset of their address book information so
536 | that an application can fulfil its purpose. When sharing of only a subset of a user's address book is
537 | possible, it often requires the user to type the information into a form herself rather than having it
538 | extracted from one of her address book services.
539 |
540 |
541 | This specification enables a Web application to have access to a selected subset of a user's address book,
542 | obtained from arbitrary services not known to the Web application. The interactions, brokered using
543 | Web Intents [WEBINTENTS] are designed in order to maximise the user's security and privacy.
544 | Address book data may be sourced from a plurality of sources — both online and local to the user's device
545 | — so long as those sources are registered as Intent services with the user agent. It defines a common
546 | format which services use to provide data to Web applications in a consistent and interoperable manner.
547 |
548 |
549 | The expectation is that data sharing happens with explicit user permission and filtering. The focus of
550 | this data sharing is on making the user aware of the data that they will share and putting them at the
551 | centre of the data sharing process; free to select both the extent to which they share their address
552 | book information and the ability to restrict which pieces of information related to which contact gets shared.
553 |
554 |
555 | A set of Security and Privacy Considerations are
556 | presented for the discretion of both implementers of Pick Contacts Intent services and recipients of contact
557 | information (i.e. Web applications).
558 |
559 |
560 | The following code illustrates how to obtain contact information from a user's address book:
561 |
562 |
Example 1
var intent =newIntent({ action:"http://webintents.org/pick",
563 | type:"http://w3.org/type/contact",
564 | extras:{ fields:["displayName","emails"]}});
565 | navigator.startActivity(intent, contactsOK, contactsFail);
566 |
567 | function contactsOK (contacts){
568 | // iterate over the array of contacts to do something useful with them
569 | }
570 | function contactsFail (err){
571 | // display an error to the user
572 | }
573 |
574 | When the above code is run, the user would typically be prompted by her user agent to select
575 | a service able to pick a contact (there may be several such services, if she has multiple address
576 | book sources). Upon selecting a service, she will be presented with an interface enabling her
577 | to choose what contact information is returned to the Web application. Upon completing her
578 | choice, the contacts data would be returned to the Web application in the contactsOK
579 | callback.
580 |
581 |
582 |
583 |
2. Conformance
584 |
585 | As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
586 | and notes in this specification are non-normative. Everything else in this specification is
587 | normative.
588 |
589 |
590 | The key words must, must not, required, should, should not, recommended, may,
591 | and optional in this specification are to be interpreted as described in [RFC2119].
592 |
593 |
594 |
595 | There is only one single conformance requirement placed upon the user agent
596 | product: a user agentmust support Web Intents [WEBINTENTS].
597 |
598 |
599 | The conformance criteria in this specification apply to a single product: the
600 | contact service which exposes a Web Intent service that
601 | handles Pick Contact Intents as defined in this specification.
602 |
603 |
604 | The data returned by the contact service is described in this specification using [WEBIDL].
605 | When this data is provided using JavaScript, then the contact servicemust do so in a manner
606 | consistent with the ECMAScript Bindings defined in the Web IDL specification.
607 |
608 |
609 |
610 |
611 |
3. Security and Privacy Considerations
This section is non-normative.
612 |
613 | The Intent defined in this specification can be used to find contact information from a user's address
614 | books. This discloses information related to a user's contacts such as their phone numbers, email
615 | addresses and other personally identifying information. The distribution of this information could
616 | potentially compromise the user's privacy, or the user's contacts' privacy. A conforming implementation
617 | of this specification should provide a mechanism that protects the user's privacy and this mechanism should
618 | ensure that no contact information is retrievable without the user's express permission.
619 |
620 |
621 |
3.1 Privacy considerations for implementers of the Pick Contacts Intent
This section is non-normative.
622 |
623 | A contact service should not provide contact information to Web sites without the express
624 | permission of the user. Obtaining the user's express permission to access a set of contacts does
625 | not imply that the user has granted permission for the same Web site to access more contact information.
626 | A contact service should take great care to ensure that the user can clearly see which information
627 | is about to be shared, and must not share more information than has been requested by the Web application.
628 |
629 |
630 | A user agent may have prearranged trust relationships with a specific contact service
631 | that do not require such user interaction.
632 |
633 |
634 |
635 |
3.2 Privacy considerations for recipients of contact information
636 |
637 | Web sites operators that retrieve contacts information using this Intent are denoted as recipients
638 | below.
639 |
640 |
641 | Recipients should only request contact information when necessary, and only use the contact
642 | information for the task for which it was provided to them.
643 |
644 |
645 | Recipients should dispose of contact information once that task is completed, unless expressly
646 | permitted to retain it by the user. Recipients should also take measures to protect this information
647 | against unauthorised access. If contact information is stored, users should be allowed to update and
648 | delete this information.
649 |
650 |
651 | The recipient of contact information should not retransmit the contact information without the
652 | user's express permission. Care should be taken when retransmitting and use of encryption is
653 | encouraged.
654 |
655 |
656 | Recipients should clearly and conspicuously disclose the fact that they are collecting contact data,
657 | the purpose of the collection, how long the data is retained, how the data is secured, how the data is
658 | shared if it is shared, how users can access, update and delete the data, and any other choices that
659 | users have with respect to the data. This disclosure should include an explanation of any exceptions to
660 | the guidelines listed above.
661 |
662 |
663 | Note that even if a user gives permission to share their contact information this can have serious
664 | privacy implications for those parties whose contacts are shared, as they may not wish such sharing to
665 | occur. This should be considered by Web applications when requesting and using such information.
666 |
667 |
668 |
669 |
3.3 Additional implementation considerations
670 |
671 | Further to the requirements listed in the previous section, implementers of a user agents are
672 | also advised to consider the following aspects that can negatively affect the privacy of their users:
673 | in certain cases, users can inadvertently grant permission to disclose their contacts
674 | to Web sites. In other cases, the content hosted at a certain URL changes in such a way that the
675 | previously granted contact permissions no longer apply as far as the user is concerned. Or the users
676 | might simply change their minds.
677 |
678 |
679 | Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive
680 | measures are a user agent's responsibility and not prescribed by this specification. However, in
681 | designing these measures, implementers are advised to enable user awareness of information sharing, and to
682 | provide easy access to user interfaces that enable revocation of permissions that Web applications have to
683 | access this Intent.
684 |
685 |
686 |
687 |
688 |
689 |
4. Intent Description
690 |
691 | The action for this Intent is http://webintents.org/pick.
692 |
693 |
694 | The type for this Intent is http://w3.org/type/contact.
695 |
696 |
697 | When a contact service is matched for delivery using these action and type, it
698 | must respond in one of two ways:
699 |
700 |
701 |
702 | If contacts have been successfully selected for delivery, then a successful payload is returned
703 | to the client (using postResult()) matching the data format defined below.
704 |
705 |
706 | If an error of any kind takes place in the service, then an error payload is returned (using
707 | postFailure()) matching the error data format defined below. The contact service
708 | must not treat the user selecting zero contacts or cancelling the service as error conditions.
709 |
710 |
711 |
712 |
4.1 Intent Extras
713 |
714 | The Pick Contact Intent can be instantiated with an extras field that adheres to the
715 | following dictionary.
716 |
727 | An array of field names corresponding to the name of the fields in the Contact dictionary that
728 | the Web application is requesting from the contact service. The contact servicemust
730 | not return defined fields on the contact objects that it provides other than those present in this
731 | list. If a field name is provided that the contact service does not recognise as a field
732 | of the Contact dictionary, then it must ignore it.
733 |
734 | By default a contact servicemay return as many contacts as the user selects. If limit
735 | is specified, the contact servicemust not return more than limit contacts. The
736 | contact serviceshould enforce this limitation in the user interface that it exposes.
737 |
738 | A string which provides a hint to the contact service to facilitate contacts selection by the user.
739 | The exact manner in which this hint is exploited is entirely up to the contact service.
740 |
741 |
742 |
743 |
744 |
745 |
5. Data Format
746 |
747 | Upon successful invocation, the contact servicemust return an array of Contact dictionaries.
748 |
752 | The Contact dictionary captures the properties of a contact object. All properties included in this
753 | interface have a corresponding definition in [POCO-SCHEMA], [RFC2426] (also known as vCard), and
754 | [OMA-CAB], thereby allowing the data format to be supported across implementations supporting these
755 | various contact representations.
756 |
779 | This attribute contains birthday of this Contact. The contact servicemay
780 | set the year value to 0000 when the age of the Contact is private or the year is not
781 | available.
782 |
783 | This attribute contains one or more user-defined categories/tags/labels associated with this
784 | Contact. e.g. "family", "favourite", "cryptozoologists".
785 |
809 | This attribute represents one or more photos associated with this Contact.
810 |
811 |
812 | The photos must be specified in the value attribute of the ContactField object
813 | by using a URL pointing to an image resource. The data: URI scheme may be used in order
814 | to provide inline data.
815 |
816 |
Note
817 | A contact serviceshould not use this attribute to send down arbitrary photos taken by this user,
818 | but specifically profile photos of the contact suitable for display when describing the
819 | contact.
820 |
856 | The ContactField dictionary is a reusable component that is used to capture contact fields of the
857 | Contact dictionary that have some modicum of structure.
858 |
865 | This attribute indicates whether this instance of the ContactField is the
866 | preferred, or primary, value for the contact property this ContactField is
867 | representing in the Contact interface. By default, the value is false.
868 |
869 | This attribute contains the type information for this ContactField and its content varies subject
870 | to the contact property this ContactField is representing. For example, if the ContactField
871 | is representing a phoneNumber property, the type attribute can be set to
872 | home, mobile; if the ContactField is representing the ims
873 | property, the type attribute could be set to xmpp, irc, bbm, etc.
874 |
875 | This attribute contains the value for this ContactField and its content varies subject to the
876 | contact property this ContactField is representing. For example, if the ContactField is
877 | representing an email, the value attribute could be set to JoeSmith@example.com,
878 | and if the ContactField is representing a url, the value attribute can be set to
879 | http://www.example.org/joesmith, etc.
880 |
904 | This attribute indicates whether this instance of the ContactAddress is the preferred,
905 | or primary, value for the contact. By default, the value is false.
906 |
919 | The ContactOrganization dictionary is a reusable component that is used to support contact
920 | organisations within the Contact dictionary.
921 |
933 | This attribute indicates whether this instance of the ContactOrganization is the preferred, or
934 | primary, value for the contact. By default, the value is false.
935 |
954 | A contact servicemay extend the dictionaries described in in the Data Formats section with
955 | additional fields. If providing an extended field, a contact servicemust prefix its name
956 | with X (U+0058 LATIN CAPITAL LETTER X) or use a vendor-specific prefix.
957 |