# HG changeset patch # User Dominique Hazaël-Massieux # Date 1306316703 -7200 # Node ID 518970294839db2d1a8f27ffa8960a536c2bfd54 # Parent 6917065f74dbf432382864f58862c522bb04773e updated list of test suite diff -r 52acb4877e86 -r 518970294839 .hgignore --- a/.hgignore Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,4 +0,0 @@ -# use glob syntax. -syntax: glob - -.DS_Store diff -r 52acb4877e86 -r 518970294839 battery/CR.html --- a/battery/CR.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,724 +0,0 @@ - - - - Battery Status API - - - - -

W3C

Battery Status API

W3C Candidate Recommendation 08 May 2012

This Version:
http://www.w3.org/TR/2012/CR-battery-status-20120508/
Latest Published Version:
http://www.w3.org/TR/battery-status/
Latest Editor's Draft:
http://dvcs.w3.org/hg/dap/raw-file/tip/battery/Overview.html
Previous version:
http://www.w3.org/TR/2011/WD-battery-status-20111129/
Editors:
Anssi Kostiainen, Nokia
Mounir Lamouri, Mozilla

-

Abstract

- This specification defines an API that provides information about the - battery status of the hosting device. -

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

-

- The functionality described in this specification was initially - specified as part of the - System Information - API but has been extracted in order to be more readily available, - more straightforward to implement, and in order to produce a - specification that could be implemented on its own merits without - interference with other, often unrelated, features. -

-

This document was published by the Device APIs Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation on 01 July 2012. All feedback is welcome.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

- - - -
-

1. Introduction

This section is non-normative. -

- The Battery Status API specification defines a means for web - developers to programmatically determine the battery status of the - hosting device. Without knowing the battery status of a device, a web - developer must design the web application with an assumption of - sufficient battery level for the task at hand. This means the battery - of a device may exhaust faster than desired because web developers are - unable to make decisions based on the battery status. Given knowledge - of the battery status, web developers are able to craft web content and - applications which are power-efficient, thereby leading to improved - user experience. -

-

- The Battery Status API can be used to defer or scale back work when - the device is not charging in or is low on battery. An archetype of an - advanced web application, a web-based email client, may check the - server for new email every few seconds if the device is charging, - but do so less frequently if the device is not charging or is low on - battery. Another example is a web-based word processor which could - monitor the battery level and save changes before the battery runs - out to prevent data loss. -

-

- The following example shows how a web-based email client could check - for new emails every ten seconds without knowledge of the battery - status: -

-
<!DOCTYPE html>
<html>
<head>
 
<title>Email Client</title>
 
<script>
   
var mail = {
      INTERVAL_DEFAULT
: 1000 * 10,
      interval
: null,
      timer
: 0,

      check
: function () {
        console
.log('Checking the server for new emails using an interval of ' +
                   
(mail.interval / 1000) + ' seconds.');
     
},
     
      setTimer
: function (interval) {
       
if (interval === mail.interval) { return; }
       
if (mail.timer !== 0) { clearTimeout(mail.timer); }
       
if (interval) { mail.timer = setInterval(function () { mail.check(); }, interval); }
        mail
.interval = interval;
     
}
   
};

    window
.addEventListener('load', function () {
      mail
.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
   
}, false);
 
</script>
</head>
<body></body>
</html>
-

- The script will always check for emails every ten seconds, even if the - battery level is critically low and the device is not charging. - This is an example of poor resource management. -

-

- Using the BatteryManager interface, the web application is, for - example, able to throttle checking for emails if the device is low on - battery, stop checking for emails if the battery is critically low and - resume normal operation when the battery is charging: -

-
<!DOCTYPE html>
<html>
<head>
 
<title>Battery-aware Email Client</title>
 
<script>
   
var mail = {
      INTERVAL_BATTERY_LOW
: 1000 * 60 * 10,
      INTERVAL_DEFAULT
: 1000 * 10,
      interval
: null,
      timer
: 0,
     
      check
: function () {
        console
.log('Checking the server for new emails using an interval of ' +
                   
(mail.interval / 1000) + ' seconds.');
     
},
     
      setTimer
: function (interval) {
       
if (interval === mail.interval) { return; }
       
if (mail.timer !== 0) { clearTimeout(mail.timer); }
       
if (interval) { mail.timer = setInterval(function () { mail.check(); }, interval); }
        mail
.interval = interval;
     
}
   
};
   
    window
.addEventListener('load', function () {
      mail
.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
   
}, false);
   
   
var battery = navigator.battery;
   
    battery
.addEventListener('dischargingtimechange', function () {
     
if (battery.dischargingTime < 60 * 30 || battery.level < 0.1) {
        mail
.setTimer(mail.INTERVAL_BATTERY_LOW);
        console
.log('30 minutes remaining or level below 10%, checking the server less frequently.');
     
} else if (battery.dischargingTime < 60 * 10 || battery.level < 0.05) {
        mail
.setTimer(null);
        console
.log('10 minutes remaining or level below 5%, stop checking the server.');
     
}
   
}, false);
   
    battery
.addEventListener('chargingchange', function () {
     
if (battery.charging) {
        mail
.setTimer(mail.INTERVAL_DEFAULT);
        console
.log('Battery is charging, checking the server normally.');
     
}
   
}, false);
 
</script>
</head>
<body></body>
</html>
-
- -

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

-

- This specification defines conformance criteria that apply to a single - product: the user agent that implements the - interfaces that it contains. -

-

- 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. -

-
-
-

3. Terminology

-

- The - Function interface represents a function in the scripting - language being used as defined in [HTML5]. -

-

- The concepts - queue a task and - - fires a simple event are defined in [HTML5]. -

-

- The terms - event handlers and - - event handler event types are defined in [HTML5]. -

-
-
-

4. Security and privacy considerations

-

- The API defined in this specification is used to determine the battery - status of the hosting device. The information disclosed has minimal - impact on privacy or fingerprinting, and therefore is exposed without - permission grants. For example, authors cannot directly know if there - is a battery or not in the hosting device. -

-
- - -
-

6. BatteryManager Interface

-
[NoInterfaceObject]
-interface BatteryManager : EventTarget {
-    readonly attribute boolean   charging;
-    readonly attribute double    chargingTime;
-    readonly attribute double    dischargingTime;
-    readonly attribute double    level;
-    [TreatNonCallableAsNull]
-             attribute Function? onchargingchange;
-    [TreatNonCallableAsNull]
-             attribute Function? onchargingtimechange;
-    [TreatNonCallableAsNull]
-             attribute Function? ondischargingtimechange;
-    [TreatNonCallableAsNull]
-             attribute Function? onlevelchange;
-};
-

6.1 Attributes

charging of type boolean, readonly
- Represents if the system's battery is charging. -
No exceptions.
chargingTime of type double, readonly
- Represents the time remaining in seconds until the system's battery - is fully charged. -
No exceptions.
dischargingTime of type double, readonly
- Represents the time remaining in seconds until the system's battery - is completely discharged and the system is about to be suspended. -
No exceptions.
level of type double, readonly
- Represents the current battery level scaled from 0 to 1.0. -
No exceptions.
-

- When a BatteryManager object is created, - charging must be set to true, chargingTime - to 0, level to 1.0 and dischargingTime to - the value positive Infinity, if the implementation is unable to report - the battery's charging state, charging time, level or remaining time - respectively. -

-

- The charging attribute must be set to false if the battery - is discharging, and set to true, if the battery is charging, the - implementation is unable to report the state, or there is no battery - attached to the system, or otherwise. When the battery charging state - is updated, the user agent must queue a task which sets - the charging attribute's value and fires a simple - event named chargingchange at the - BatteryManager object. -

-

- The chargingTime attribute must be set to 0, if the - battery is full or there is no battery attached to the system, and to - the value positive Infinity if the battery is discharging, the - implementation is unable to report the remaining charging time, or - otherwise. When the battery charging time is updated, the user - agent must queue a task which sets the - chargingTime attribute's value and fires a simple - event named chargingtimechange at the - BatteryManager object. -

-

- The dischargingTime attribute must be set to the value - positive Infinity, if the battery is charging, the implementation is - unable to report the remaining discharging time, there is no battery - attached to the system, or otherwise. When the battery discharging time - is updated, the user agent must queue a task which sets - the dischargingTime attribute's value and fires a - simple event named dischargingtimechange at the - BatteryManager object. -

-

- The level attribute must be set to 0 if the system's - battery is depleted and the system is about to be suspended, and to - 1.0 if the battery is full, the implementation is unable to report the - battery's level, or there is no battery attached to the system. When - the battery level is updated, the user agent must queue a - task which sets the level attribute's value and - fires a simple event named levelchange at - the BatteryManager object. -

-
- The definition of how often the chargingtimechange, - dischargingtimechange, and levelchange - events are fired is left to the implementation. -
-
-

6.2 Event handlers

-

- The following are the event handlers (and their corresponding - event handler event types) that must be supported as - attributes by the BatteryManager object: -

- - - - - - - - - - - - - - - - - - - - - - - - - -
event handlerevent handler event type
onchargingchangechargingchange
onchargingtimechangechargingtimechange
ondischargingtimechangedischargingtimechange
onlevelchangelevelchange
-
-
- -
-

7. Examples

This section is non-normative. -

- This trivial example writes the battery level to the console each time - the level changes: -

-
-
navigator.battery.onlevelchange = function () {
  console
.log(navigator.battery.level);
};
-
-

- Alternatively, the same using the addEventListener() - method: -

-
-
navigator.battery.addEventListener('levelchange', function () {
  console
.log(navigator.battery.level);
}, false);
-
-

- The following example updates the indicators to show the charging - state, level and time remaining in minutes: -

-
-
<!DOCTYPE html>
<html>
<head>
 
<title>Battery Status API Example</title>
 
<script>
   
var battery = navigator.battery;
   
    battery
.onchargingchange = function () {
      document
.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging';
   
};

    battery
.onlevelchange = function () {
      document
.querySelector('#level').textContent = battery.level;
   
};

    battery
.ondischargingtimechange = function () {
      document
.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60;
   
};
 
</script>
</head>
<body>
 
<div id="charging">(charging state unknown)</div>
 
<div id="level">(battery level unknown)</div>
 
<div id="dischargingTime">(discharging time unknown)</div>
</body>
</html>
-
-
-
-

A. Acknowledgements

-

- The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and - the Mozilla WebAPI team in general for their invaluable feedback - based on prototype implementations. Many thanks to the people behind - the System Information API and Device Orientation Event specification - for the initial inspiration. Also thanks to the nice folks bringing us - the Page Visibility specification, which motivated the editor of this - specification to write the introduction chapter discussing some - real-world high value use cases that apply equally to this - specification. Special thanks to all the participants of the Device - APIs Working Group and others who have sent in substantial feedback - and comments, and made the Web a better place for everyone by - doing so. -

-
- - -

B. References

B.1 Normative references

[HTML5]
Ian Hickson, David Hyatt. - - HTML 5. - 4 March 2010. - W3C Working Draft. - - URL: http://www.w3.org/TR/2010/WD-html5-20100304/
[RFC2119]
S. Bradner. - - Key words for use in RFCs to Indicate Requirement Levels. - March 1997. - Internet RFC 2119. - (Work in progress.) - URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. - - Web IDL. - 19 December 2008. - W3C Working Draft. - - URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219
\ No newline at end of file diff -r 52acb4877e86 -r 518970294839 battery/Overview.html --- a/battery/Overview.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,440 +0,0 @@ - - - - Battery Status API - - - - - -
- This specification defines an API that provides information about the - battery status of the hosting device. -
- -
-

- The functionality described in this specification was initially - specified as part of the - System Information - API but has been extracted in order to be more readily available, - more straightforward to implement, and in order to produce a - specification that could be implemented on its own merits without - interference with other, often unrelated, features. -

-
- -
-

Introduction

-

- The Battery Status API specification defines a means for web - developers to programmatically determine the battery status of the - hosting device. Without knowing the battery status of a device, a web - developer must design the web application with an assumption of - sufficient battery level for the task at hand. This means the battery - of a device may exhaust faster than desired because web developers are - unable to make decisions based on the battery status. Given knowledge - of the battery status, web developers are able to craft web content and - applications which are power-efficient, thereby leading to improved - user experience. -

-

- The Battery Status API can be used to defer or scale back work when - the device is not charging in or is low on battery. An archetype of an - advanced web application, a web-based email client, may check the - server for new email every few seconds if the device is charging, - but do so less frequently if the device is not charging or is low on - battery. Another example is a web-based word processor which could - monitor the battery level and save changes before the battery runs - out to prevent data loss. -

-

- The following example shows how a web-based email client could check - for new emails every ten seconds without knowledge of the battery - status: -

-
-        <!DOCTYPE html>
-        <html>
-        <head>
-          <title>Email Client</title>
-          <script>
-            var mail = {
-              INTERVAL_DEFAULT: 1000 * 10,
-              interval: null,
-              timer: 0,
-
-              check: function () {
-                console.log('Checking the server for new emails using an interval of ' + 
-                            (mail.interval / 1000) + ' seconds.');
-              },
-              
-              setTimer: function (interval) {
-                if (interval === mail.interval) { return; }
-                if (mail.timer !== 0) { clearTimeout(mail.timer); }
-                if (interval) { mail.timer = setInterval(function () { mail.check(); }, interval); }
-                mail.interval = interval;
-              }
-            };
-
-            window.addEventListener('load', function () {
-              mail.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
-            }, false);
-          </script>
-        </head>
-        <body></body>
-        </html>
-
-      
-

- The script will always check for emails every ten seconds, even if the - battery level is critically low and the device is not charging. - This is an example of poor resource management. -

-

- Using the BatteryManager interface, the web application is, for - example, able to throttle checking for emails if the device is low on - battery, stop checking for emails if the battery is critically low and - resume normal operation when the battery is charging: -

-
-        <!DOCTYPE html>
-        <html>
-        <head>
-          <title>Battery-aware Email Client</title>
-          <script>
-            var mail = {
-              INTERVAL_BATTERY_LOW: 1000 * 60 * 10,
-              INTERVAL_DEFAULT: 1000 * 10,
-              interval: null,
-              timer: 0,
-              
-              check: function () {
-                console.log('Checking the server for new emails using an interval of ' + 
-                            (mail.interval / 1000) + ' seconds.');
-              },
-              
-              setTimer: function (interval) {
-                if (interval === mail.interval) { return; }
-                if (mail.timer !== 0) { clearTimeout(mail.timer); }
-                if (interval) { mail.timer = setInterval(function () { mail.check(); }, interval); }
-                mail.interval = interval;
-              }
-            };
-            
-            window.addEventListener('load', function () {
-              mail.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
-            }, false);
-            
-            var battery = navigator.battery;
-            
-            battery.addEventListener('dischargingtimechange', function () {
-              if (battery.dischargingTime < 60 * 30 || battery.level < 0.1) {
-                mail.setTimer(mail.INTERVAL_BATTERY_LOW);
-                console.log('30 minutes remaining or level below 10%, checking the server less frequently.');
-              } else if (battery.dischargingTime < 60 * 10 || battery.level < 0.05) {
-                mail.setTimer(null);
-                console.log('10 minutes remaining or level below 5%, stop checking the server.');
-              }
-            }, false);
-            
-            battery.addEventListener('chargingchange', function () {
-              if (battery.charging) {
-                mail.setTimer(mail.INTERVAL_DEFAULT);
-                console.log('Battery is charging, checking the server normally.');
-              }
-            }, false);
-          </script>
-        </head>
-        <body></body>
-        </html>
-      
-
- -
-

- This specification defines conformance criteria that apply to a single - product: the user agent that implements the - interfaces that it contains. -

-

- 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. -

-
-
-

Terminology

-

- The - EventHandler interface represents a callback used for event - handlers as defined in [[!HTML5]]. -

-

- The concepts - queue a task and - - fires a simple event are defined in [[!HTML5]]. -

-

- The terms - event handlers and - - event handler event types are defined in [[!HTML5]]. -

-
-
-

Security and privacy considerations

-

- The API defined in this specification is used to determine the battery - status of the hosting device. The information disclosed has minimal - impact on privacy or fingerprinting, and therefore is exposed without - permission grants. For example, authors cannot directly know if there - is a battery or not in the hosting device. -

-
-
-

NavigatorBattery Interface

-

- The NavigatorBattery interface is exposed on the - Navigator object. -

-
-
-
readonly attribute BatteryManager battery
-
- The object that exposes the battery status information. -
-
-
- -
-

BatteryManager Interface

-
-
readonly attribute boolean charging
-
- Represents if the system's battery is charging. -
-
readonly attribute unrestricted double chargingTime
-
- Represents the time remaining in seconds until the system's battery - is fully charged. -
-
readonly attribute unrestricted double dischargingTime
-
- Represents the time remaining in seconds until the system's battery - is completely discharged and the system is about to be suspended. -
-
readonly attribute double level
-
- Represents the current battery level scaled from 0 to 1.0. -
-
- attribute EventHandler onchargingchange -
-
-
-
- attribute EventHandler onchargingtimechange -
-
-
-
- attribute EventHandler ondischargingtimechange -
-
-
-
- attribute EventHandler onlevelchange -
-
-
-
-

- When a BatteryManager object is created, - charging MUST be set to true, chargingTime - to 0, level to 1.0 and dischargingTime to - the value positive Infinity, if the implementation is unable to report - the battery's charging state, charging time, level or remaining time - respectively. -

-

- The charging attribute MUST be set to false if the battery - is discharging, and set to true, if the battery is charging, the - implementation is unable to report the state, or there is no battery - attached to the system, or otherwise. When the battery charging state - is updated, the user agent MUST queue a task which sets - the charging attribute's value and fires a simple - event named chargingchange at the - BatteryManager object. -

-

- The chargingTime attribute MUST be set to 0, if the - battery is full or there is no battery attached to the system, and to - the value positive Infinity if the battery is discharging, the - implementation is unable to report the remaining charging time, or - otherwise. When the battery charging time is updated, the user - agent MUST queue a task which sets the - chargingTime attribute's value and fires a simple - event named chargingtimechange at the - BatteryManager object. -

-

- The dischargingTime attribute MUST be set to the value - positive Infinity, if the battery is charging, the implementation is - unable to report the remaining discharging time, there is no battery - attached to the system, or otherwise. When the battery discharging time - is updated, the user agent MUST queue a task which sets - the dischargingTime attribute's value and fires a - simple event named dischargingtimechange at the - BatteryManager object. -

-

- The level attribute MUST be set to 0 if the system's - battery is depleted and the system is about to be suspended, and to - 1.0 if the battery is full, the implementation is unable to report the - battery's level, or there is no battery attached to the system. When - the battery level is updated, the user agent MUST queue a - task which sets the level attribute's value and - fires a simple event named levelchange at - the BatteryManager object. -

-
- The definition of how often the chargingtimechange, - dischargingtimechange, and levelchange - events are fired is left to the implementation. -
-
-

Event handlers

-

- The following are the event handlers (and their corresponding - event handler event types) that MUST be supported as - attributes by the BatteryManager object: -

- - - - - - - - - - - - - - - - - - - - - - - - - -
event handlerevent handler event type
onchargingchangechargingchange
onchargingtimechangechargingtimechange
ondischargingtimechangedischargingtimechange
onlevelchangelevelchange
-
-
- -
-

Examples

-

- This trivial example writes the battery level to the console each time - the level changes: -

-
-        navigator.battery.onlevelchange = function () {
-          console.log(navigator.battery.level);
-        };
-      
-

- Alternatively, the same using the addEventListener() - method: -

-
-      navigator.battery.addEventListener('levelchange', function () {
-        console.log(navigator.battery.level);
-      }, false);
-      
-

- The following example updates the indicators to show the charging - state, level and time remaining in minutes: -

-
-        <!DOCTYPE html>
-        <html>
-        <head>
-          <title>Battery Status API Example</title>
-          <script>
-            var battery = navigator.battery;
-            
-            battery.onchargingchange = function () {
-              document.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging';
-            };
-
-            battery.onlevelchange = function () {
-              document.querySelector('#level').textContent = battery.level;
-            };
-
-            battery.ondischargingtimechange = function () {
-              document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60;
-            };
-          </script>
-        </head>
-        <body>
-          <div id="charging">(charging state unknown)</div>
-          <div id="level">(battery level unknown)</div>
-          <div id="dischargingTime">(discharging time unknown)</div>
-        </body>
-        </html>
-      
-
-
-

Acknowledgements

-

- The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and - the Mozilla WebAPI team in general for their invaluable feedback - based on prototype implementations. Many thanks to the people behind - the System Information API and Device Orientation Event specification - for the initial inspiration. Also thanks to the nice folks bringing us - the Page Visibility specification, which motivated the editor of this - specification to write the introduction chapter discussing some - real-world high value use cases that apply equally to this - specification. Special thanks to all the participants of the Device - APIs Working Group and others who have sent in substantial feedback - and comments, and made the Web a better place for everyone by - doing so. -

-
- - diff -r 52acb4877e86 -r 518970294839 battery/index.html --- a/battery/index.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,10 +0,0 @@ - - - - Battery Status API - - - Moved to - http://dvcs.w3.org/hg/dap/raw-file/tip/battery/Overview.html - - diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/TODO.txt --- a/battery/tests/submissions/anssik/TODO.txt Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,4 +0,0 @@ ----+ TODO - - * proper {level | chargingtime | dischargingtime}change tests - * validate tests on a real device and tweak timeouts for async tests \ No newline at end of file diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/battery-charging.html --- a/battery/tests/submissions/anssik/battery-charging.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,58 +0,0 @@ - - - - Battery Status API Test Suite - - - - - - -

Description

-

- This test validates that all of the navigator.battery attributes exist and are set to correct values, when the battery is charging. -

-

Preconditions

-
    -
  1. - The device is plugged in to the charger before this test is run. -
  2. -
  3. - The battery must neither be empty or full, nor reach empty or full capacity during the test. -
  4. -
-
- - - diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/battery-created.html --- a/battery/tests/submissions/anssik/battery-created.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,46 +0,0 @@ - - - - Battery Status API Test Suite - - - - -

Description

-

- - This test is only useful on devices that expose the BatteryManager interface, - but lack a backend implementation. - -

-

- This test validates that all of the navigator.battery attributes exist and are set to their default values. -

-

Preconditions

-
    -
  1. - The implementation is unable to report the battery's charging state, - charging time, level or remaining time respectively. -
  2. -
  3. - The device is unplugged from the charger before this test case is run. -
  4. -
-
- - - diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/battery-discharging.html --- a/battery/tests/submissions/anssik/battery-discharging.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,74 +0,0 @@ - - - - Battery Status API Test Suite - - - - - - -

Description

-

- This test validates that all of the navigator.battery attributes exist and are set to correct values, when the battery is discharging. -

-

Preconditions

-
    -
  1. - The device is unplugged from the charger before this test is run. -
  2. -
  3. - The battery must neither be empty or full, nor reach empty or full capacity during the test. -
  4. -
-

- The highest prime number discovered so far is: -

-
- - - diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/battery-full.html --- a/battery/tests/submissions/anssik/battery-full.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,46 +0,0 @@ - - - - Battery Status API Test Suite - - - - - -

Description

-

- This test validates that all of the navigator.battery attributes exist and are set to correct values, when the battery is full. -

-

Preconditions

-
    -
  1. - The device is plugged in to the charger before this test is run. -
  2. -
  3. - The battery is full. -
  4. -
-
- - - diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/battery-interface-idlharness.html --- a/battery/tests/submissions/anssik/battery-interface-idlharness.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,59 +0,0 @@ - - - - Battery Status API Test Suite - - - - - - - -

Description

-

- This test validates the BatteryManager interface IDL. -

-

- This test uses idlharness.js, and - is an alternative to the battery-interface.html - test. -

-
-

- - Distributed under both the - - W3C Test Suite License and the - - W3C 3-clause BSD License. To contribute to a W3C Test Suite, see the - policies and contribution - forms. - -

- - - - diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/battery-interface.html --- a/battery/tests/submissions/anssik/battery-interface.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,28 +0,0 @@ - - - - Battery Status API Test Suite - - - - - -

Description

-

- This test validates the BatteryManager interface IDL. -

- -
-

- - Distributed under both the - - W3C Test Suite License and the - - W3C 3-clause BSD License. To contribute to a W3C Test Suite, see the - policies and contribution - forms. - -

- - \ No newline at end of file diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/battery-interface.js --- a/battery/tests/submissions/anssik/battery-interface.js Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,393 +0,0 @@ -/** -* W3C 3-clause BSD License -* Redistribution and use in source and binary forms, with or without -* modification, are permitted provided that the following conditions are -* met: -* o Redistributions of works must retain the original copyright notice, -* this list of conditions and the following disclaimer. -* -* o Redistributions in binary form must reproduce the original copyright -* notice, this list of conditions and the following disclaimer in the -* documentation and/or other materials provided with the distribution. -* -* o Neither the name of the W3C nor the names of its contributors may be -* used to endorse or promote products derived from this work without -* specific prior written permission. -* -* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS -* IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE -* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -* POSSIBILITY OF SUCH DAMAGE. -**/ - -(function() { - - /** - * - * Navigator implements NavigatorBattery; - * - * [NoInterfaceObject] - * interface NavigatorBattery { - * readonly attribute BatteryManager battery; - * }; - * - */ - - test(function() { - assert_idl_attribute(navigator, 'battery', 'navigator must have battery attribute'); - }, 'battery is present on navigator'); - - test(function() { - assert_readonly(navigator, 'battery', 'battery must be readonly') - }, 'battery is readonly'); - - /** - * - * [NoInterfaceObject] - * interface BatteryManager : EventTarget { - * readonly attribute boolean charging; - * readonly attribute unrestricted double chargingTime; - * readonly attribute unrestricted double dischargingTime; - * readonly attribute double level; - * attribute EventHandler onchargingchange; - * attribute EventHandler onchargingtimechange; - * attribute EventHandler ondischargingtimechange; - * attribute EventHandler onlevelchange; - * }; - * - */ - - // interface BatteryManager : EventTarget { - - test(function() { - assert_true(navigator.battery instanceof EventTarget); - }, 'battery inherits from EventTarget'); - - // readonly attribute boolean charging; - - test(function() { - assert_idl_attribute(navigator.battery, 'charging', 'battery must have charging attribute'); - }, 'charging attribute exists'); - - test(function() { - assert_readonly(navigator.battery, 'charging', 'charging must be readonly') - }, 'charging attribute is readonly'); - - // readonly attribute unrestricted double chargingTime; - - test(function() { - assert_idl_attribute(navigator.battery, 'chargingTime', 'battery must have chargingTime attribute'); - }, 'chargingTime attribute exists'); - - test(function() { - assert_readonly(navigator.battery, 'chargingTime', 'chargingTime must be readonly') - }, 'chargingTime attribute is readonly'); - - // readonly attribute unrestricted double dischargingTime; - - test(function() { - assert_idl_attribute(navigator.battery, 'dischargingTime', 'battery must have dischargingTime attribute'); - }, 'dischargingTime attribute exists'); - - test(function() { - assert_readonly(navigator.battery, 'dischargingTime', 'dischargingTime must be readonly') - }, 'dischargingTime attribute is readonly'); - - // readonly attribute double level; - - test(function() { - assert_idl_attribute(navigator.battery, 'level', 'battery must have level attribute'); - }, 'level attribute exists'); - - test(function() { - assert_readonly(navigator.battery, 'level', 'level must be readonly') - }, 'level attribute is readonly'); - - // attribute EventHandler onchargingchange; - - test(function() { - assert_idl_attribute(navigator.battery, 'onchargingchange', 'battery must have onchargingchange attribute'); - }, 'onchargingchange attribute exists'); - - test(function() { - assert_equals(navigator.battery.onchargingchange, null, 'onchargingchange must be null') - }, 'onchargingchange is null'); - - test(function() { - var desc = 'onchargingchange did not accept callable object', - func = function() {}, - desc = 'Expected to find onchargingchange attribute on battery object'; - assert_idl_attribute(navigator.battery, 'onchargingchange', desc); - window.onchargingchange = func; - assert_equals(window.onchargingchange, func, desc); - }, 'onchargingchange is set to function'); - - test(function() { - var desc = 'onchargingchange did not treat noncallable as null'; - navigator.battery.onchargingchange = function() {}; - navigator.battery.onchargingchange = {}; - assert_equals(navigator.battery.onchargingchange, null, desc); - }, 'onchargingchange: treat object as null'); - - test(function() { - var desc = 'onchargingchange did not treat noncallable as null'; - navigator.battery.onchargingchange = function() {}; - navigator.battery.onchargingchange = { - call: 'test' - }; - assert_equals(navigator.battery.onchargingchange, null, desc); - }, 'onchargingchange: treat object with non-callable call property as null'); - - test(function() { - var desc = 'onchargingchange did not treat noncallable (string) as null'; - navigator.battery.onchargingchange = function() {}; - navigator.battery.onchargingchange = 'string'; - assert_equals(navigator.battery.onchargingchange, null, desc); - }, 'onchargingchange: treat string as null'); - - test(function() { - var desc = 'onchargingchange did not treat noncallable (number) as null'; - navigator.battery.onchargingchange = function() {}; - navigator.battery.onchargingchange = 123; - assert_equals(navigator.battery.onchargingchange, null, desc); - }, 'onchargingchange: treat number as null'); - - test(function() { - var desc = 'onchargingchange did not treat noncallable (undefined) as null'; - navigator.battery.onchargingchange = function() {}; - navigator.battery.onchargingchange = undefined; - assert_equals(navigator.battery.onchargingchange, null, desc); - }, 'onchargingchange: treat undefined as null'); - - test(function() { - var desc = 'onchargingchange did not treat noncallable (array) as null'; - navigator.battery.onchargingchange = function() {}; - navigator.battery.onchargingchange = []; - assert_equals(navigator.battery.onchargingchange, null, desc); - }, 'onchargingchange: treat array as null'); - - test(function() { - var desc = 'onchargingchange did not treat noncallable host object as null'; - navigator.battery.onchargingchange = function() {}; - navigator.battery.onchargingchange = Node; - assert_equals(navigator.battery.onchargingchange, null, desc); - }, 'onchargingchange: treat non-callable host object as null'); - - // attribute EventHandler onchargingtimechange; - - test(function() { - assert_idl_attribute(navigator.battery, 'onchargingtimechange', 'battery must have onchargingtimechange attribute'); - }, 'onchargingtimechange attribute exists'); - - test(function() { - assert_equals(navigator.battery.onchargingtimechange, null, 'onchargingtimechange must be null') - }, 'onchargingtimechange is null'); - - test(function() { - var desc = 'onchargingtimechange did not accept callable object', - func = function() {}, - desc = 'Expected to find onchargingtimechange attribute on battery object'; - assert_idl_attribute(navigator.battery, 'onchargingtimechange', desc); - window.onchargingtimechange = func; - assert_equals(window.onchargingtimechange, func, desc); - }, 'onchargingtimechange is set to function'); - - test(function() { - var desc = 'onchargingtimechange did not treat noncallable as null'; - navigator.battery.onchargingtimechange = function() {}; - navigator.battery.onchargingtimechange = {}; - assert_equals(navigator.battery.onchargingtimechange, null, desc); - }, 'onchargingtimechange: treat object as null'); - - test(function() { - var desc = 'onchargingtimechange did not treat noncallable as null'; - navigator.battery.onchargingtimechange = function() {}; - navigator.battery.onchargingtimechange = { - call: 'test' - }; - assert_equals(navigator.battery.onchargingtimechange, null, desc); - }, 'onchargingtimechange: treat object with non-callable call property as null'); - - test(function() { - var desc = 'onchargingtimechange did not treat noncallable (string) as null'; - navigator.battery.onchargingtimechange = function() {}; - navigator.battery.onchargingtimechange = 'string'; - assert_equals(navigator.battery.onchargingtimechange, null, desc); - }, 'onchargingtimechange: treat string as null'); - - test(function() { - var desc = 'onchargingtimechange did not treat noncallable (number) as null'; - navigator.battery.onchargingtimechange = function() {}; - navigator.battery.onchargingtimechange = 123; - assert_equals(navigator.battery.onchargingtimechange, null, desc); - }, 'onchargingtimechange: treat number as null'); - - test(function() { - var desc = 'onchargingtimechange did not treat noncallable (undefined) as null'; - navigator.battery.onchargingtimechange = function() {}; - navigator.battery.onchargingtimechange = undefined; - assert_equals(navigator.battery.onchargingtimechange, null, desc); - }, 'onchargingtimechange: treat undefined as null'); - - test(function() { - var desc = 'onchargingtimechange did not treat noncallable (array) as null'; - navigator.battery.onchargingtimechange = function() {}; - navigator.battery.onchargingtimechange = []; - assert_equals(navigator.battery.onchargingtimechange, null, desc); - }, 'onchargingtimechange: treat array as null'); - - test(function() { - var desc = 'onchargingtimechange did not treat noncallable host object as null'; - navigator.battery.onchargingtimechange = function() {}; - navigator.battery.onchargingtimechange = Node; - assert_equals(navigator.battery.onchargingtimechange, null, desc); - }, 'onchargingtimechange: treat non-callable host object as null'); - - // attribute EventHandler ondischargingtimechange; - - test(function() { - assert_idl_attribute(navigator.battery, 'ondischargingtimechange', 'battery must have ondischargingtimechange attribute'); - }, 'ondischargingtimechange attribute exists'); - - test(function() { - assert_equals(navigator.battery.ondischargingtimechange, null, 'ondischargingtimechange must be null') - }, 'ondischargingtimechange is null'); - - test(function() { - var desc = 'ondischargingtimechange did not accept callable object', - func = function() {}, - desc = 'Expected to find ondischargingtimechange attribute on battery object'; - assert_idl_attribute(navigator.battery, 'ondischargingtimechange', desc); - window.ondischargingtimechange = func; - assert_equals(window.ondischargingtimechange, func, desc); - }, 'ondischargingtimechange is set to function'); - - test(function() { - var desc = 'ondischargingtimechange did not treat noncallable as null'; - navigator.battery.ondischargingtimechange = function() {}; - navigator.battery.ondischargingtimechange = {}; - assert_equals(navigator.battery.ondischargingtimechange, null, desc); - }, 'ondischargingtimechange: treat object as null'); - - test(function() { - var desc = 'ondischargingtimechange did not treat noncallable as null'; - navigator.battery.ondischargingtimechange = function() {}; - navigator.battery.ondischargingtimechange = { - call: 'test' - }; - assert_equals(navigator.battery.ondischargingtimechange, null, desc); - }, 'ondischargingtimechange: treat object with non-callable call property as null'); - - test(function() { - var desc = 'ondischargingtimechange did not treat noncallable (string) as null'; - navigator.battery.ondischargingtimechange = function() {}; - navigator.battery.ondischargingtimechange = 'string'; - assert_equals(navigator.battery.ondischargingtimechange, null, desc); - }, 'ondischargingtimechange: treat string as null'); - - test(function() { - var desc = 'ondischargingtimechange did not treat noncallable (number) as null'; - navigator.battery.ondischargingtimechange = function() {}; - navigator.battery.ondischargingtimechange = 123; - assert_equals(navigator.battery.ondischargingtimechange, null, desc); - }, 'ondischargingtimechange: treat number as null'); - - test(function() { - var desc = 'ondischargingtimechange did not treat noncallable (undefined) as null'; - navigator.battery.ondischargingtimechange = function() {}; - navigator.battery.ondischargingtimechange = undefined; - assert_equals(navigator.battery.ondischargingtimechange, null, desc); - }, 'ondischargingtimechange: treat undefined as null'); - - test(function() { - var desc = 'ondischargingtimechange did not treat noncallable (array) as null'; - navigator.battery.ondischargingtimechange = function() {}; - navigator.battery.ondischargingtimechange = []; - assert_equals(navigator.battery.ondischargingtimechange, null, desc); - }, 'ondischargingtimechange: treat array as null'); - - test(function() { - var desc = 'ondischargingtimechange did not treat noncallable host object as null'; - navigator.battery.ondischargingtimechange = function() {}; - navigator.battery.ondischargingtimechange = Node; - assert_equals(navigator.battery.ondischargingtimechange, null, desc); - }, 'ondischargingtimechange: treat non-callable host object as null'); - - // attribute EventHandler onlevelchange; - - test(function() { - assert_idl_attribute(navigator.battery, 'onlevelchange', 'battery must have onlevelchange attribute'); - }, 'onlevelchange attribute exists'); - - test(function() { - assert_equals(navigator.battery.onlevelchange, null, 'onlevelchange must be null') - }, 'onlevelchange is null'); - - test(function() { - var desc = 'onlevelchange did not accept callable object', - func = function() {}, - desc = 'Expected to find onlevelchange attribute on battery object'; - assert_idl_attribute(navigator.battery, 'onlevelchange', desc); - window.onlevelchange = func; - assert_equals(window.onlevelchange, func, desc); - }, 'onlevelchange is set to function'); - - test(function() { - var desc = 'onlevelchange did not treat noncallable as null'; - navigator.battery.onlevelchange = function() {}; - navigator.battery.onlevelchange = {}; - assert_equals(navigator.battery.onlevelchange, null, desc); - }, 'onlevelchange: treat object as null'); - - test(function() { - var desc = 'onlevelchange did not treat noncallable as null'; - navigator.battery.onlevelchange = function() {}; - navigator.battery.onlevelchange = { - call: 'test' - }; - assert_equals(navigator.battery.onlevelchange, null, desc); - }, 'onlevelchange: treat object with non-callable call property as null'); - - test(function() { - var desc = 'onlevelchange did not treat noncallable (string) as null'; - navigator.battery.onlevelchange = function() {}; - navigator.battery.onlevelchange = 'string'; - assert_equals(navigator.battery.onlevelchange, null, desc); - }, 'onlevelchange: treat string as null'); - - test(function() { - var desc = 'onlevelchange did not treat noncallable (number) as null'; - navigator.battery.onlevelchange = function() {}; - navigator.battery.onlevelchange = 123; - assert_equals(navigator.battery.onlevelchange, null, desc); - }, 'onlevelchange: treat number as null'); - - test(function() { - var desc = 'onlevelchange did not treat noncallable (undefined) as null'; - navigator.battery.onlevelchange = function() {}; - navigator.battery.onlevelchange = undefined; - assert_equals(navigator.battery.onlevelchange, null, desc); - }, 'onlevelchange: treat undefined as null'); - - test(function() { - var desc = 'onlevelchange did not treat noncallable (array) as null'; - navigator.battery.onlevelchange = function() {}; - navigator.battery.onlevelchange = []; - assert_equals(navigator.battery.onlevelchange, null, desc); - }, 'onlevelchange: treat array as null'); - - test(function() { - var desc = 'onlevelchange did not treat noncallable host object as null'; - navigator.battery.onlevelchange = function() {}; - navigator.battery.onlevelchange = Node; - assert_equals(navigator.battery.onlevelchange, null, desc); - }, 'onlevelchange: treat non-callable host object as null'); - -})(); \ No newline at end of file diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/battery-plugged-in.html --- a/battery/tests/submissions/anssik/battery-plugged-in.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,78 +0,0 @@ - - - - Battery Status API Test Suite - - - - - - - -

Description

-

- This test validates that all of the navigator.battery attributes exist and are set to correct values, with corresponding events fired, when the charger is plugged in. -

-

Preconditions

-
    -
  1. - The device is unplugged from the charger before this test is run. -
  2. -
  3. - The battery must not be full or reach full capacity during the time the test is run. -
  4. -
-
- Plug in the charger and wait for all the tests to complete. -
-
- - - diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/battery-unplugged.html --- a/battery/tests/submissions/anssik/battery-unplugged.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,94 +0,0 @@ - - - - Battery Status API Test Suite - - - - - - - -

Description

-

- This test validates that all of the navigator.battery attributes exist and are set to correct values, with corresponding events fired, when the charger is unplugged. -

-

Preconditions

-
    -
  1. - The device is plugged in to the charger before this test is run. -
  2. -
  3. - The battery must not be full or reach full capacity during the time the test is run. -
  4. -
-

- The highest prime number discovered so far is: -

-
- Unplug the charger and wait for all the tests to complete. -
-
- - - diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/countdown.js --- a/battery/tests/submissions/anssik/countdown.js Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ -function countdown(prop) { - var seconds = !isNaN(parseInt(prop.timeout, 10)) ? (prop.timeout / 1000) : 0, - body = document.getElementsByTagName('body')[0], - div = document.createElement('div'), - timer, remaining_time, min, sec; - - add_completion_callback(function () { - clearInterval(timer); - body.removeChild(div); - }); - - div.innerHTML = 'This test will timeout in ...'; - body.appendChild(div); - - remaining_time = document.querySelector('#remaining_time'); - - timer = setInterval(function() { - function zeroPad(n) { - return (n < 10) ? '0' + n : n; - } - - if (seconds / 60 >= 1) { - min = Math.floor(seconds / 60); - sec = seconds % 60; - } else { - min = 0; - sec = seconds; - } - - if (seconds === 0) { - div.innerHTML = 'Timeout exceeded. Increase the timeout and re-run.'; - clearInterval(timer); - } - - remaining_time.textContent = zeroPad(min) + ':' + zeroPad(sec); - seconds--; - }, 1000); -} diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/manifest.txt --- a/battery/tests/submissions/anssik/manifest.txt Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,7 +0,0 @@ -battery-interface.html Battery Status API Test Suite -battery-charging.html Battery Status API Test Suite -battery-created.html Battery Status API Test Suite -battery-discharging.html Battery Status API Test Suite -battery-full.html Battery Status API Test Suite -battery-plugged-in.html Battery Status API Test Suite -battery-unplugged.html Battery Status API Test Suite diff -r 52acb4877e86 -r 518970294839 battery/tests/submissions/anssik/prime.js --- a/battery/tests/submissions/anssik/prime.js Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,35 +0,0 @@ -// adapted from http://html5demos.com/worker - -var running = false; - -onmessage = function (event) { - // doesn't matter what the message is, just toggle the worker - if (running == false) { - running = true; - run(1); - } else { - running = false; - } -}; - -function run(n) { - // split the task into 20k chunks - var limit = n + 20000; - search: while (running && n < limit) { - n += 1; - for (var i = 2; i <= Math.sqrt(n); i += 1) { - if (n % i == 0) { - continue search; - } - } - // found a prime! - postMessage(n); - } - if (n === limit) { - // wait for the UI thread to update itself - setTimeout(function(start_time) { - // resume prime computation at n - run(n); - }, 150); - } -} \ No newline at end of file diff -r 52acb4877e86 -r 518970294839 contacts/BlobWriter.html --- a/contacts/BlobWriter.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,231 +0,0 @@ - - - - - Contact Blob Writer - - - - - - - - -
-

- The Contact Blob Writer provides an interface for developers to create contact objects from Javascript. -

-

- Contact objects can then be saved to the user's current device via the APIs and mechanisms defined in [[!FILE-API]] and shown - in this specification. -

-

- This specification is built on top of an accompanying specification [[CONTACTS-API]] that enables read access to a user's - unified address book. -

-
-
-

- This document represents the early consensus of the group on the scope and features of the proposed Contact Blob Writer specification. - Issues and editors note in the document highlight some of the points on which the group is still working and would particularly like - to get feedback. -

-
-
-

- This specification defines conformance criteria that apply to a single product: the user agent that implements the - interfaces that it contains. -

-

- 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. -

-
-
-

- Introduction -

- -

- This specification provides a method for creating objects consisting of standard contact card information such as names, addresses and phone numbers so that - these objects may be efficiently stored and saved on a user's device. -

-

- The interfaces and API defined in this specification have been built on top of [[!FILE-API]]. Contact Blobs can be presented, downloaded - and stored on the user's device by creating a Blob URI [[!FILE-API]] from a created Contact Blob object. - This Blob URI may be presented to the user or invoked wherever URLs can be used within the web platform. -

-

- The API is designed so that implementors of this specification are not required to implement a handler for valid Contact Blob Types. - The valid Contact Blob Types contained herein have been chosen for their ability to integrate with existing and legacy - address book systems while still allowing user agents to handle the given media types as required. -

-
-
-

Security and Privacy Considerations

-

- This specification builds upon the security and privacy protections provided by the [[HTML5]] and [[!FILE-API]] specifications; - in particular, it is expected that any action to download the Contact information that has been created would require a - specific user interaction on an HTML element that is entirely controlled by the user agent. -

-
-
-

- Contact Blob API -

- -
-

- Example -

-

- The following example illustrates how to create a Contact Blob, create a Blob URI and then a mechanism for saving the Contact object on the host device: -

-
-<a id="contactcard">Save our business card</a>
-
-<script type="text/javascript"> 
-  // Define/Get some contact properties:
-  var contact = {
-    displayName: 'Robert',
-    emails: [
-      {
-        value: 'bob@foo.com'
-      }
-    ]
-    // ...
-  };
-
-  // Create a new Contact Blob:
-  var contactBlob = navigator.service.contacts.createContactBlob(contact);
-  
-  // Create a Blob URI object:
-  // @see http://www.w3.org/TR/file-upload/#dfn-createObjectURL
-  var contactURL = createObjectURL(contactBlob);
-  
-  // e.g. Assign contact URI to anchor element for user-initiated download: 
-  document.getElementById('contactcard').href = contactURL;
-</script>
-
-
- -
-

ContactBlobWriter interface

- -

- The ContactBlobWriter interface allows users to create a Contact Blob. -

- -

- The ContactBlobWriter interface is exposed on the Contacts object as defined in [[!CONTACTS-API]]. -

-
-   -
-
-
- Blob createContactBlob() -
-
- Returns a Contact Blob containing the attributes provided and processed according to the rules for converting a Contact object to a Contact Blob. -
-
- Contact attributes -
-
- Contact [[!CONTACTS-API]] properties to assign to the resulting Contact Blob object. -
-
-
-
-
-
-
-

Contact Blobs

- -

- A Contact Blob is a Blob object [[!FILE-API]] with a type attribute that - matches one of the given valid Contact Blob Types. -

- -

- A valid Contact Blob Type MUST be one of the following media types: -

- - - -

- ... -

- -

- Define fragment identifiers [[!FILE-API]] for this media type(?) -

- -

- ... -

- -
-
-

Converting a Contact object to a Contact Blob

- -

- The rules for converting a Contact object to a Contact Blob are defined as follows: -

- -

- To be written. -

- -

- Include mappings of Contact object attributes to Contact Blob attributes. -

- -

- Include the special rule for assigning the Contact.id (if provided) to the X-ABUID attribute of the resulting Contact Blob. -

- -
- - \ No newline at end of file diff -r 52acb4877e86 -r 518970294839 contacts/FPWD.html --- a/contacts/FPWD.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1344 +0,0 @@ - - - - - - The Contacts API - - - - - -

W3C

The Contacts API

W3C Working Draft 21 January 2010

This Version:
http://www.w3.org/TR/2010/WD-contacts-api-20100121/
Latest Published Version:
http://www.w3.org/TR/contacts-api/
Latest Editor's Draft:
http://dev.w3.org/2009/dap/contacts/
Editor:
Richard Tibbett, France Telecom

-

Abstract

-

This specification defines an API that provides access to a user's unified address book.

-

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

-

- This document represents the early consensus of the group on the scope and features of the - proposed Contacts API. Issues and editors note in the document highlight some of the points - on which the group is still working and would particularly like to get feedback. -

-

This document was published by the Device APIs and Policy Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

- -

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

-

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

- -

- This specification defines conformance criteria that apply to a single product: the - - user agent - - that implements the interfaces that it contains. -

-
-
-

2. Introduction

This section is non-normative.

-

- The Contacts API defines a high-level interface to provide access to the user's unified contact information, such as names, - addresses and other contact information. -

-

- The API itself is agnostic of any underlying address book sources and data formats. -

-
-

2.1 Usage Examples

-

- The following code extracts illustrate how to search, add, remove and update contact information in a given address book: -

-
-

- Searching for matching contacts. -

-
function successContactFindCallback(contacts) {
-    // do something with resulting contact objects
-    // for (var i in contacts) alert(contacts[i].name);
-    // ...
-}
-
-function generalErrorCB(error) {
-    // do something with resulting errors
-    // alert(error.code);
-    // ...
-}
-
-// Perform an address book search
-navigator.service.contacts.find( {name: 'Bob'},
-                                successContactFindCallback, 
-                                generalErrorCB );
-
-
-

- Creating a new contact. -

-
// previous example follow-on...
-
-// Create new contact	
-var myContact = navigator.service.contacts.create({name: 'Mr. Robert Smith Jr'});
-
-// Add additional contact attributes as required...
-// myContact.nicknames.push('bobby');
-
-
-

- Adding a new contact. -

-
// previous example follow-on...
-
-function successContactCallback(contact) {
-    // do something with resulting contact object
-    // alert(contact.name);
-    // ...
-}
-
-// Add new contact
-myContact.save(successContactCallback, generalErrorCB);
-
- -
-

- Editing an existing contact. -

-
// previous example follow-on...
-
-// e.g. add a new phone number
-myContact.phones.push({types: ['home'], value: '+440000000002'});
-
-// Update existing contact
-myContact.save(successContactCallback, generalErrorCB);
-
- -
-

- Removing an existing contact. -

-
// previous example follow-on...
-
-// Remove existing contact
-myContact.remove(successContactCallback, generalErrorCB);
-
- - -
- -
-
-

3. Security and Privacy Considerations

- -

- This section is under development. - -

This section has been inspired (verbatim where necessary) from the Geolocation WG latest public working draft specification. - -

There are a number of reasons for this approach: - -

1. The programmatic styles of the Contacts API and Geolocation API are very similar and because they both have the the same implied user experience within - the same implied User Agent the general security and privacy considerations of both APIs should remain common. - -

2. The ability to align the security and privacy considerations of the Geolocation API with DAP APIs is important for the potential future benefit - of making any security and privacy mechanisms developed within the DAP WG applicable to the Geolocation API at some point in its own ongoing development. -

- -

- The API defined in this specification can be used to create, retrieve, update and remove contact information from a - user's address books. All API methods disclose information related to a user's contacts such as their phone number(s), - email address(es) and other personally identifying information. The distribution of this information could potentially - compromise the user's privacy. A conforming implementation of this specification must provide a mechanism that protects - the user's privacy and this mechanism should ensure that no contact information is creatable, retrivable, updateable or - removable without the user's express permission. -

- -
-

3.1 Privacy considerations for implementors of the Contacts API

- -

- A user agent must not create, retrieve, update or delete contact information to Web sites without the express permission - of the user. A user agent must acquire permission through a user interface, unless they have prearranged trust - relationships with users, as described below. The user interface must include the URI of the document origin, as defined in [HTML5]. - Those permissions that are acquired through the user interface and that are preserved beyond the - current browsing session (i.e. beyond the time when the browsing context, as defined in [HTML5], is navigated to another URL) - must be revocable and a user agent must respect revoked permissions. -

- -

- Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same - Web site to access other methods provided by this API, or to access the same method with a different set of arguments, as part of the same permission context. If a user has expressed - permission for an implementation to, e.g. find a set of existing contacts, the implementation must seek the user's express - permission if and when any additional create, find, update or remove function is called on this API. -

- -

- A user agent may have prearranged trust relationships that do not require such user interfaces. For example, - while a Web browser will present a user interface when a Web site performs an address book request, a Widget Runtime - may have a prearranged, delegated security relationship with the user and, as such, a suitable alternative security - and privacy mechanism with which to authorize the creation, retrieval, update and/or removal of contact information. -

-
- -
-

3.2 Privacy considerations for recipients of contact information

- -

- Recipients must only request contact information when necessary. Recipients must only use the contact information for - the task for which it was provided to them. Recipients must dispose of contact information once that task is completed, - unless expressly permitted to retain it by the user. Recipients must also take measures to protect this information - against unauthorized access. If contact information is stored, users should be allowed to update and delete this - information. -

- -

- The recipient of contact information must not retransmit the contact information without the user’s express permission. - Care should be taken when retransmitting and use of encryption is encouraged. -

- -

- Recipients must clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the - collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users - can access, update and delete the data, and any other choices that users have with respect to the data. This disclosure - must include an explanation of any exceptions to the guidelines listed above. -

-
- -
-

3.3 Additional implementation considerations

This section is non-normative.

- -

- Further to the requirements listed in the previous section, implementors of the Contacts API are also advised to consider - the following aspects that can negatively affect the privacy of their users: in certain cases, users can inadvertently - grant permission to the User Agent to disclose their contacts to Web sites. In other cases, the content hosted at a certain - URL changes in such a way that the previously granted contact permissions no longer apply as far as the user is concerned. - Or the users might simply change their minds. -

- -

- Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures are an - implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers - are advised to enable user awareness of contact sharing, and to provide easy access to interfaces that enable revocation of - permissions. -

-
- -
-
-

4. API Description

-
-

4.1 ServiceContacts interface

- -

The actual object of which the API will be hanging off is still under discussion (e.g. navigator.service vs from navigator.device); see ISSUE-67

- -

- The ServiceContacts interface is exposed on the navigator.service object, as defined in [CORE-DEVICE]. -

- -
Service implements ServiceContacts;

All instances of the Service type are defined to also implement the ServiceContacts interface.

- -
[NoInterfaceObject]
-interface ServiceContacts {
-    readonly attribute Contacts contacts;
-};
-

4.1.1 Attributes

contacts of type Contacts, readonly
- The root node from which the contacts functionality can be accessed. -
No exceptions.
- -
- - -
-

4.2 Contacts interface

- -

- The Contacts interface exposes a database collecting contacts information, such that they may be created, found, - read, updated, and deleted. -

- -

- Multiple address books, taken - from different sources, can be represented within this unified address book interface. Contacts from different sources can be distinguished using the serviceId field.. In addition, multiple address books can be displayed by filtering - on the required serviceId value via the Contacts find() function. -

- -

- Equally, multiple contact groups can be represented within this unified address book by specifying a consistent categories - value(s) as part of individual Contact objects. Multiple contact groups can be displayed by filtering - on the required categories value(s) via the Contacts find() function. -

- -
[NoInterfaceObject]
-interface Contacts {
-    Contact   create (in ContactProperties attributes);
-    PendingOp find (in ContactProperties filter, in ContactFindSuccessCB successCB, in optional ContactErrorCB? errorCB, in optional ContactOptions options);
-};
-

4.2.1 Methods

create
- Create a new Contact object. - -

This method takes one argument. When called, it returns - a Contact object.

- - -
ParameterTypeNullableOptionalDescription
attributesContactProperties - The attributes to assign to the resulting object. -
No exceptions.
Return type: Contact
find
-

Find contacts in the address book based on a ContactProperties object acting as a filter.

- -

This method takes two, three or four arguments. When called, it immediately returns - a PendingOp object , as defined in [CORE-DEVICE], and then asynchronously starts a find contacts process defined as follows:

- -

-

    -
  1. Search for contacts in the address book according to the contact search processing rules.
  2. -
  3. If successful, invoke the associated successCB. - If the attempt fails, and the method was invoked with a non-null errorCB argument, this method must - invoke the errorCB with a ContactError object as an argument.
  4. -
- - - -
ParameterTypeNullableOptionalDescription
filterContactProperties - The filter used in order to select which contacts are returned. -
successCBContactFindSuccessCB - Function to call when the asynchronous operation completes -
errorCBContactErrorCB - Function to call when the asynchronous operation fails. -
optionsContactOptions - The options to apply to the output of this method. -
No exceptions.
Return type: PendingOp
- -
- -
-

4.3 Contact interface

- -

The Contact interface captures a single contact item. This interface extends ContactProperties attributes.

- -

All Contact objects must include all attributes supported by the implementation, regardless of whether these attributes have been assigned a non-null value or a null value. If a supported attribute - has not been assigned a value by the user and/or implementation, then this attribute must still be present in the resulting Contact object and must have a value of null.

- -

Each resulting Contact object must include a non-null name attribute. - All other attributes may be optionally assigned a value by the user and/or implementation.

- -
[NoInterfaceObject]
-interface Contact : ContactProperties {
-    readonly attribute DOMString id;
-    Contact   clone ();
-    PendingOp save (in ContactSuccessCB successCB, in optional ContactErrorCB? errorCB);
-    PendingOp remove (in ContactSuccessCB successCB, in optional ContactErrorCB? errorCB);
-};
-

4.3.1 Attributes

id of type DOMString, readonly
-

- Perhaps we don't want to recommend the use of UUID URN here. Saying that id must be globally unique could suffice, and there may be good reasons why someone would want to use something else (e.g. a SHA mailbox as in FOAF). -

-

A globally unique identifier for the given Contact object. Each Contact referenced from Contacts must include a non-empty id value.

-

An implementation must maintain this globally unique resource identifier when a Contact is added to, or present within, an Address Book.

-

An implementation may use an IANA registered identifier format. The value can also be a non-standard format.

-

It is recommended that an implementation assign the id attribute as a UUID URN as defined in [RFC4122].

- -
{id: 'urn:uuid:d13d4fd0-4ce9-1cef-b1f2-10a9c1446bf0'}
-
No exceptions.

4.3.2 Methods

clone
-

Create a deep clone copy of the current object minus the current object's id attribute.

- -

The resulting object must be provided with a newly generated id attribute to distiguish the cloned object from the original object.

-
No parameters.
No exceptions.
Return type: Contact
remove
-

Remove the current contact from the address book.

- -

- In the case that the current id attribute is NULL and this method is invoked, a ContactErrorCB must be - triggered as part of the remove contact process. This error must consist of a ContactError object with a code of - ContactError::CONTACT_NOT_FOUND_ERROR. -

- - -

This method takes one or two arguments. When called, it immediately returns - a PendingOp object , as defined in [CORE-DEVICE], and then asynchronously starts a remove contact process defined as follows:

- -

-

    -
  1. Remove the current object from Contacts.
  2. -
  3. If successful, invoke the associated - successCB. If the attempt fails, and the method was - invoked with a non-null errorCB argument, this method must invoke the - errorCB with a ContactError object as an argument.
  4. -
- - - -
ParameterTypeNullableOptionalDescription
successCBContactSuccessCB - Function to call when the asynchronous operation completes -
errorCBContactErrorCB - Function to call when the asynchronous operation fails. -
No exceptions.
Return type: PendingOp
save
-

Add or update (as appropriate) the current Contact object to the Contacts.

- -

- In the case that the name attribute is null and this method is invoked, an ContactErrorCB must be - triggered as part of the save contact process. This error must consist of a ContactError object with a code of - ContactError::CONTACT_INVALID_ERROR. -

- -

This method takes one or two arguments. When called, it immediately returns - a PendingOp object , as defined in [CORE-DEVICE], and then asynchronously starts a save contact process defined as follows:

- -

-

    -
  1. If the Contact.id already exists in Contacts then update the existing object in Contacts.
  2. -
  3. If a current Contact.id value does not current exist in Contacts or the current Contact.id value has not been set, add the current object as a new object to Contacts.
  4. -
  5. If successful, invoke the associated - successCB. If the attempt fails, and the method was - invoked with a non-null errorCB argument, this method must invoke the - errorCB with a ContactError object as an argument.
  6. -
- - - - -
ParameterTypeNullableOptionalDescription
successCBContactSuccessCB - Function to call when the asynchronous operation completes -
errorCBContactErrorCB - Function to call when the asynchronous operation fails. -
No exceptions.
Return type: PendingOp
-
- -
-

4.4 ContactProperties interface

-

- The ContactProperties - interface captures the settable properties of a contact. -

- ContactProperties is used as part of the Contact object. ContactProperties can also be used as the basis of the Contacts.find() searches within the address book. - -

Attributes of the ContactProperties interface that expect a singular value have singular spelling (e.g. name) and attributes that may have one or more values have plural spelling (e.g. phones) to make the distinction of these fields easier.

-

- When ContactProperties is used as an input parameter to Contacts.find() methods, fields that are set to - - null - - are considered to match anything. -

-
[NoInterfaceObject]
-interface ContactProperties {
-    attribute DOMString?       name;
-    attribute DOMString[]      nicknames;
-    attribute ContactField[]   phones;
-    attribute ContactField[]   emails;
-    attribute ContactAddress[] addresses;
-    [PutForwards=value]
-    attribute ContactField[]   impps;
-    attribute DOMString?       serviceId;
-    attribute DOMString[]      categories;
-};
-

4.4.1 Attributes

addresses of type array of ContactAddress
-

- Aligned with Geolocation v2 specification. -

-

One or more addresses associated with the contact.

-

The first object in this sequence is inferred to be the user's preferred/default address.

- -
{addresses: [{streetNumber: '123', 
-              street: 'Main Street', 
-              city: 'My Town', 
-              region: 'CA', 
-              postalCode: '91921-1234', 
-              country: 'USA'}]}
-
No exceptions.
categories of type array of DOMString
-

One or more contact categories/groups to associate the contact with.

- -
{categories: ['friends', 'w3c', 'information technology', 'engineers']}
-
No exceptions.
emails of type array of ContactField
-

One or more email addresses associated with the contact.

-

The first object in this sequence is inferred to be the user's preferred/default email address.

- -

The following constants are defined for use in the types attribute for email addresses:

-
'home', 'work', 'personal', 'business'.
-

Additional values may be provided for the types attribute.

- -
{emails: [{types: ['work'], value: 'john.q.quinlan@barfooinc.com'}, 
-          {types: ['home', 'mobile'], value: 'jquinlan@mail.com'}]}
-
No exceptions.
impps of type array of ContactField
-

One or more instant messaging and presence protocol addresses associated with the contact.

-

The first object in this sequence is inferred to be the user's preferred/default instant messaging and presence protocol address.

- -

The following constants are defined for use in the types attribute for instant messaging and presence protocol addresses:

-
'home', 'work', 'personal', 'business'.
-

Additional values may be provided for the types attribute.

- -
{impps: [{types: ['work'], value:'im:jquinlan@foobarinc.com'},
-         {types: ['work', 'mobile'], value:'sip:jquinlan@foobarinc.com'}]}
-
No exceptions.
name of type DOMString, nullable
-

The contact's name represented in a formatted manner

-

Each contact must include a non-empty name value.

- -
{name: 'Mr. John Q. Public, Esq.'}
-
No exceptions.
nicknames of type array of DOMString
-

One or more nicknames associated with the contact

- -
{nicknames: ['jim', 'jimmie']}
-
No exceptions.
phones of type array of ContactField
-

One or more telephone numbers associated with the contact.

- -

The first object in this sequence is inferred to be the user's preferred/default phone number.

- -

The following constants are defined for use in the types attribute for phone numbers:

-
'home', 'work', 'voice', 'fax', 'fixed', 'mobile', 'car', 'video', 'isdn', 'pager', 'modem', 'pcs'.
-

Additional values may be provided for the types attribute.

- -
{phones: [{types: ['home'], value: '+442088450343'}, 
-          {types: ['work'], value: '+442088450343'}] }
-
No exceptions.
serviceId of type DOMString, nullable
-

An identifier that may be provided that represents the address book owner of the current contact object.

-

This attribute enables multiple address book sources to be tagged and filtered on Contact objects.

-

It is recommended that an implementation assign the serviceId attribute as a URI.

- -
{serviceId: 'http://foobar.com/myservices/v1/addressbook'}
-
No exceptions.
-
- -
-

4.5 ContactField interface

-

- The ContactField/Field interface is a reusable component that is used to support contact fields within the ContactProperties interface. - It defines an optional types parameter that can be provided with a standard value. -

-
[NoInterfaceObject]
-interface ContactField {
-    attribute sequence<DOMString>? types;
-    attribute DOMString            value;
-};
-

4.5.1 Attributes

types of type sequence<DOMString>, nullable
- One or more contexts to associate with the given value. -
No exceptions.
value of type DOMString
- The value of the current object. -
No exceptions.
-
- -
-

4.6 ContactAddress interface

-

- The ContactAddress interface is a reusable component that is used to support address information within the ContactProperties interface. -

-
[NoInterfaceObject]
-interface ContactAddress {
-    attribute DOMString country;
-    attribute DOMString region;
-    attribute DOMString county;
-    attribute DOMString city;
-    attribute DOMString street;
-    attribute DOMString streetNumber;
-    attribute DOMString premises;
-    attribute DOMString additionalInformation;
-    attribute DOMString postalCode;
-};
-

4.6.1 Attributes

additionalInformation of type DOMString
- Additional information (e.g. floor number in a building, an apartment number, the name of an office occupant, etc) not captured in other ContactAddress properties. -
No exceptions.
city of type DOMString
- The city of the address. -
No exceptions.
country of type DOMString
- The country of the address, specified using the two-letter [ISO 3166-1] code. -
No exceptions.
county of type DOMString
- The name of a land area within the larger region. -
No exceptions.
postalCode of type DOMString
- The postal code of the address. -
No exceptions.
premises of type DOMString
- Details of the premises (e.g. block of flats, building name) of the address. -
No exceptions.
region of type DOMString
- The country subdivision (e.g state) of the address. -
No exceptions.
street of type DOMString
- The street of the address. -
No exceptions.
streetNumber of type DOMString
- The street number of the address. -
No exceptions.
-
- -
-

4.7 ContactOptions interface

-

- Rename this to "ContactSearchFilter" or similar? -

- -

- The ContactOptions - interface describes the options that can be applied to contact searching. -

-
[NoInterfaceObject]
-interface ContactOptions {
-    attribute unsigned short limit;
-    attribute unsigned short page;
-    attribute DOMString?     sort;
-    attribute boolean?       group;
-};
-

4.7.1 Attributes

group of type boolean, nullable
-

- The ECMA-262 specification says in, section 12.6.4, "[for the for-in Statement t]he mechanics and order of enumerating the - properties [...] is not specified." -

- However, all major browsers loop over the properties of an object in the order in which they were defined (ref: - [1] - but independently verified). Chrome has some minor issues, but due to the overwhelming implementation of this behaviour in all other major browsers, - the Chrome development team have marked this as a bug and it is due for fix in an upcoming release - [2]. -

-

- Whether the first property in the related ContactProperties object (in the order in which those properties were defined) should be grouped. -

-

- Only the first ContactProperties property provided can be grouped. -

- -
No exceptions.
limit of type unsigned short
-

- The maximum number of results to return from the contacts search. -

-

- If no value is provided, the search will return all search results. -

-
No exceptions.
page of type unsigned short
-

- The page number of the contacts search to return. If the requested page index does not exist, this parameter must be assigned the default value. -

-

- If no value is provided, the search will return all search results. -

-
No exceptions.
sort of type DOMString, nullable
-

- The ECMA-262 specification says in, section 12.6.4, "[for the for-in Statement t]he mechanics and order of enumerating the - properties [...] is not specified." -

- However, all major browsers loop over the properties of an object in the order in which they were defined (ref: - [1] - but independently verified). Chrome has some minor issues, but due to the overwhelming implementation of this behaviour in all other major browsers, - the Chrome development team have marked this as a bug and it is due for fix in an upcoming release - [2]. -

-

- Would it be better to have sort: ['field1', 'field2'] and descending: true|false where the latter is only meaningful if sort was specified? -

-

- The direction in which to sort the first property in the related ContactProperties object (in the order in which those properties were defined). -

-

- Only the first ContactProperties property provided is sortable. -

-

- This attribute must be one of the following constants: -

-
'asc', 'desc'
-

If a different value is provided, this field defaults to null

-
No exceptions.
-
- -
-

4.8 ContactFindSuccessCB interface

- - - -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactFindSuccessCB {
-    void onSuccess (in sequence<Contact> contactObjs);
-};
-

4.8.1 Methods

onSuccess
- - - -
ParameterTypeNullableOptionalDescription
contactObjssequence<Contact> - The sequence of Contact objects resulting from the given Contacts find() method. -
No exceptions.
Return type: void
-
- -
-

4.9 ContactSuccessCB interface

- - - -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactSuccessCB {
-    void onSuccess (in Contact contactObj);
-};
-

4.9.1 Methods

onSuccess
- - - -
ParameterTypeNullableOptionalDescription
contactObjContact - The Contact object resulting from the given Contact commmit() or Contact remove() method. -
No exceptions.
Return type: void
-
- -
-

4.10 ContactErrorCB interface

- - - -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactErrorCB {
-    void onError (in ContactError error);
-};
-

4.10.1 Methods

onError
- - - -
ParameterTypeNullableOptionalDescription
errorContactError - The Contact API related error object of an unsuccessful asynchronous operation. -
No exceptions.
Return type: void
- -
- -
-

4.11 ContactError interface

-

- Add Contacts API specific error codes... -

-

- The ContactError interface encapsulates all errors in the manipulation of Contact objects in the Contacts API. -

-
[NoInterfaceObject]
-interface ContactError : GenericError {
-    const unsigned short CONTACT_NOT_FOUND_ERROR = 30;
-    const unsigned short CONTACT_INVALID_ERROR = 31;
-};
-

4.11.1 Constants

CONTACT_INVALID_ERROR of type unsigned short
- The Contact object does not include all mandatory attributes required in Contacts. -
CONTACT_NOT_FOUND_ERROR of type unsigned short
- The Contact object requested could not be found in Contacts. -
-
- - -
- - -
-

5. General API Support

- - This section defines the general API interfaces required by this specification that may also be in use in other DAP APIs. - -

The following interfaces may be general interfaces for use throughout all APIs. They are included here for now for API spec completion.

- -
-

5.1 GenericError interface

-

- The GenericError interface encapsulates all general errors and is the basis of all errors produced by DAP APIs. -

-
[NoInterfaceObject]
-interface GenericError {
-    const unsigned short UNKNOWN_ERR = 0;
-    const unsigned short INVALID_ARGUMENT_ERROR = 1;
-    const unsigned short NOT_FOUND_ERROR = 2;
-    const unsigned short PENDING_OPERATION_ERROR = 3;
-    const unsigned short IO_ERROR = 4;
-    const unsigned short NOT_SUPPORTED_ERROR = 5;
-    const unsigned short PERMISSION_DENIED_ERROR = 20;
-    readonly attribute unsigned short code;
-};
-

5.1.1 Attributes

code of type unsigned short, readonly
- An error code assigned by an implementation when an error has occurred in Contacts API processing. -
No exceptions.

5.1.2 Constants

INVALID_ARGUMENT_ERROR of type unsigned short
- An invalid parameter was provided when the requested method was invoked. -
IO_ERROR of type unsigned short
- An error occurred in the underlying implementation that meant the requested method could not complete. -
NOT_FOUND_ERROR of type unsigned short
- If no response information can be provided from the requested method. -
NOT_SUPPORTED_ERROR of type unsigned short
- The requested method is not supported by the current implementation. -
PENDING_OPERATION_ERROR of type unsigned short
- If the PendingOp (as defined in [CORE-DEVICE]) associated with the requested callback produces an error on cancel(). -
PERMISSION_DENIED_ERROR of type unsigned short
- The requested method was rejected permission was denied at the implementation or by the user. -
UNKNOWN_ERR of type unsigned short
- An unknown error occurred. -
-
- -
- -
-

6. Contact Search Processing Rules

-

- The Contacts interface find() method - provides a method to search for contacts according to the input of a - ContactProperties - object. - -

- All fields within a ContactProperties object provided to this method represent a logical UNION of value matching. - Fields provided with a null value are considered to match anything. -

-

- For example, the following ContactProperties object is supplied for Contact searching: -

navigator.contacts.find({
-                            name:'Robert', 
-                            nicknames:['Bob']
-                        }, 
-                        /*...*/);
- - The above example logically implies: "find contact objects that contain a name of 'Robert' AND a nickname of 'Bob'". - - -

- We need to be a lot clearer about partial matching included below. It might just be simpler to use pass RegExp objects around. Then again it might not... -

-

- All contact searching should apply a loose-matching policy. If a ContactProperties attribute being searched in Contacts - partially matches the input filter value, a Contact object representing the contact - should be returned as part of the resulting ContactFindSuccessCB. -

- -

The rules for processing filter combinations is defined below and is always provided with an input parameter and, an optional options parameter. Its behaviour depends on the type of input:

- -
- -
-
Let contactsset be initially the set of all known contacts
- -
If input is an Object object
- -
-
    -
  1. Let singlefilter be the input parameter being parsed.
  2. -
  3. Let item be the next enumerable property in singlefilter. If there are no more enumerable properties, go to step 6.
  4. -
  5. If the value of item is null, go to step 2.
  6. -
  7. Let contactsset be the subset of contactsset whose elements have the item value set to the value of item.
  8. -
  9. Go to step 2.
  10. -
  11. If the value of options is not null. apply the provided options to contactsset.
  12. -
  13. Return contactsset.
  14. -
-
- -
If input is another native object type
- -

Return a null value. - -

- - - -

 

- -
- -
-

7. Use Cases and Requirements

- -
-

7.1 Use Cases

- -

-

Use Case 1: Upload a set of contact details to a user's social network

- A user is registered on a number of different social networking sites and would like to upload some or all of their - address book contacts to the service. Using the Contacts API, the Web application has access to the user's address book, - subject to user opt-in, and it is therefore able to import the user's selected contacts in to their service. - - -

-

Use Case 2: Download a set of contact details from a user's social network

- A social networking user would like to download some or all of their social network contacts to their native address book, in to their native - phone dialling application or in to another application for offline / non-web use. Using the Contacts API, the Web application provides the user with an export - function and, subject to user opt-in, the selected contacts can be downloaded and imported in to the user's address book. - - -

-

Use Case 3: A user would like to keep their work address book and personal address book seperate

- The Contacts API will provide all address book contacts in a unified way but the user would like to associate individual contacts - to individual address books - keeping their work and social address books seperated. The Contacts API must allow Web Applications to - distinguish between multiple address book stores and allow the user to manage different address books according to their needs. - - -

-

Use Case 4: A user maintains a single unified address book but would like to maintain groups of contacts within that address book

- A user has a number of friends, family, colleagues and other contacts in their address book. They would like to create groups and assign - existing contacts to these groups. The user can create, update or remove as many groups as they like and equally they would like to be able to - add, remove and update the members assigned to those groups whenever they need to. The user's contacts can belong to multiple groups at the - any one time. - - -

-

Use Case 5: Use a web interface to manage contact details on both the user's device and the web

- A Web Application is built that allows users to add, update and remove friend's contact details stored in their native address book. - The Web Application can add, remove and update contact details, subject to user opt-in, and these details are automatically propagated - from the web interface to the user's address book. - - -

-

Use Case 6: A user would like to export contacts from the one address book store and import them to another address book store

- The user maintains multiple address books that are stored on both the web and on their device(s). The user would like to move some or all of - their contacts from one address book store to another. Using the Contacts API, the user can assign contact details to different address book - stores. The underlying implementation will action the import/export process when the user changes to which address book store a contact is - associated and the user makes an active request, via the Contacts API, to update the modified contacts. - - -

-

Use Case 7: A user would like to be notified when friends have a birthday coming up

- A user would like their favorite Web Application to inform them when all their friend's birthdays are coming up. The user imports some or all - of their address book contacts to the Web Application. The web application can read in the contacts' birthdays as well as other useful identifying - information (e.g. the contacts' names). The Web Application can then email, SMS or otherwise notify the user when a contact's birthday is coming - up. - - -

-

Use Case 8: A user would like his/her contacts to update their own contact details via a mediating Web Application and sync any changes to their - current address book

- User's contact details are constantly changing and being updated. A user has uploaded their address book to a Web Application which has then allowed - the user's contacts to update the details contained therein in a collaborative way. The user can then synchronise any changes made by his/her contacts - when they e.g. visit that Web Application at any point in the future. - -
- -
-

7.2 Requirements

- -
    -
  • The Contacts API must enable listing all available address books on the device;
  • -
  • The Contacts API must enable listing all contacts in the address book(s);
  • -
  • The Contacts API must enable reading the details for a contact;
  • -
  • The Contacts API should enable creating a new contact;
  • -
  • The Contacts API should enable updating a contact;
  • -
  • The Contacts API should enable deleting a contact;
  • - -
  • The Contacts API should enable filtering the list of contacts to search for a subset.
  • -
- - -
- -
- -
-

A. Features for Future Consideration

-

- The requirements document contains a list of features that were considered for this version - but deferred to future work [DAP-REQS]. -

-
- -
-

B. Acknowledgements

-

- The editor would like to thank the input from the PhoneGap, Nokia, and OMTP BONDI groups and the feedback received from W3C DAP members to date ... -

-
-

C. References

C.1 Normative references

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

C.2 Informative references

[CORE-DEVICE]
Robin Berjon. Core Device Interfaces. 02 December 2009. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/device/
[DAP-REQS]
Robin Berjon; et al. Device API Requirements. 05 October 2009. Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/api-reqs/
[HTML5]
Ian Hickson; David Hyatt. HTML 5. 25 August 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-html5-20090825/
[RFC4122]
P. Leach; M. Mealling; R. Salz. A Universally Unique IDentifier (UUID) URN Namespace July 2005. Internet RFC 4122. URL: http://www.ietf.org/rfc/rfc4122.txt
\ No newline at end of file diff -r 52acb4877e86 -r 518970294839 contacts/HTML.html --- a/contacts/HTML.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,295 +0,0 @@ - - - - HTML Contact Sharing - - - - - - - - -
- This specification defines HTML enhancements that provide access to a user's address book. -
- -
-

- This specification defines conformance criteria that apply to a single product: the user agent that implements the - interfaces that it contains. -

-

- Implementations that use ECMAScript to provide the callbacks 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. -

-
- -
-

Information presented in this document is for informational purposes only, and does not reflect final choices in the integration of Device - APIs with HTML within Opera or elsewhere. As such, this document or the need to work on this document has not been formall ratified by the - W3C.

-

- Other routes for integrating Device API access with HTML are also being explored on an active basis - within the W3C DAP Working Group.

- -

All comments on this draft should be directed to the W3C DAP mailing list.

-
- -
-

Introduction

-

- This HTML Contact Sharing recommendation defines an HTML extension to enable websites to quickly and unobtrusively obtain a list of - contacts from the current user based on the records available in their address book. -

-

- This specification builds on the existing HTML device element [[!HTML-DEVICE]]. -

-

- In addition, this recommednation also reuses the basic security and privacy principles and existing low-level parts of the Contacts API [[!CONTACTS-API]] to provide address book data to a web application. -

-

- ... -

- -
-

- The following code illustrates how to obtain contact information from a user's address book. -

-
-<device type="contact" params="fields=name,emails;filter=Bob;updatedSince=2010-05-23T00:00:00Z" 
-   onchange="successContactFindCallback(this.data)" />
-
-<script type="text/javascript">
-  function successContactFindCallback(contacts) {
-    // do something with resulting contact objects
-    for (var i in contacts) alert(contacts[i].name.formatted);
-    // ...
-  }
-</script>
-
-
-
- -
-

- HTML Device Element Integration -

-

- This section is likely to evolve significantly over time due to [[!HTML-DEVICE]] not currently being a mature proposal. This is included to illustrate an HTML integration model for this and - other select Device APIs, hooking in to the same low-level objects of a corresponding programmatic API being actively developed within the W3C DAP WG.
-
- Feedback on this section is encouraged from implementors. -

-

- This section details an extension to the HTML Device specification [[!HTML-DEVICE]] to enable contact information to be shared - through graphical controls embedded on a web page. -

-

- The device element's type attribute MUST be set to contact to indicate the device element is in the contacts - state, according to the table below. -

- - - - - - - - - - - - - - - - - -
- Keyword - - State - - Device Description - - Example -
- contact - - Contacts - - Contacts Database/Storage - - Access to a group of contacts residing on the user's system or in the current user agent. -
-

- A device element in the contacts database state SHOULD render as a graphical control on the current web page. -

-

- TBW: Passing parameters via params in to the UI control widget... -

-

- Once the user has selected the graphical control they MAY be presented with a modal, UI control widget dialog to select and review - contact sharing with the current web page. If the user selects one or more contacts from this dialog then: -

-
    -
  1. - The modal UI Widget control dialog used to select the contact objects MUST be terminated. -
  2. -
  3. - The originating device element's data attribute MUST be set to a corresponding Contact Array object (Contact[]) as defined in [[!CONTACTS-API]]. -
  4. -
  5. - The originating device element's change event MUST be triggered. -
  6. -
-

- [[!HTML-DEVICE]] is not currently provisioned as being a HTML web form element. If serialization of the resulting data is required - for use in a web forms context neither the [[!HTML-DEVICE]] specification or this specification currently provide any - recommendations to that effect. -

-
- -
-

- User Interaction Guidelines -

-

- A website requests access to a user's address book with the following code: -

-
-
-<html>
-<body>
-  <h1>Contacts API Test Page</h1> 
-  <device type="contact" params="fields=name,emails;filter=Bob" onchange="successContactFindCallback(this.data)" />
-  <script type="text/javascript">
-    function successContactFindCallback(contacts) {
-      // do something with resulting contact objects
-      for (var i in contacts) alert(contacts[i].name.formatted);
-      // ...
-    }
-  </script>  
-</body>
-</html>
-
-
-

- This page may render in the user agent as follows: -

-

- Device Element in Contacts State
- (View as PNG) -

-

- If the user clicks on the rendered device control, the user agent may provide the contact picker, utilising all of - the parameters provided in the originating device element. -

-

- Contact Picker
- (View as PNG) -

-

- If the user clicks 'Cancel', then the user is returned to the page and no further action is taken. -

-

- If the user clicks 'Select', the data attribute of the originating device element is set to the contact - information selected by the user as defined in HTML Device Element Integration. -

-
- -
-

Acknowledgements

-

- Many thanks to Wojciech Maslowski for helping to put this initial proposal together. -

-
- - diff -r 52acb4877e86 -r 518970294839 contacts/LC/Overview.html --- a/contacts/LC/Overview.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1981 +0,0 @@ - - - - Contacts API - - - - - - - - -

W3C

Contacts API

W3C Working Draft 16 June 2011

This version:
http://www.w3.org/TR/2011/WD-contacts-api-20110616/
Latest published version:
http://www.w3.org/TR/contacts-api/
Latest editor's draft:
http://dev.w3.org/2009/dap/contacts/
Previous version:
http://www.w3.org/TR/2010/WD-contacts-api-20101209/
Editor:
Richard Tibbett, Opera Software ASA
-

-

Abstract

-

- The Contacts API defines the high-level interfaces required to obtain read access to a user's unified - address book. -

-

- This API includes the following key interfaces: -

- -

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

-

- This document represents the early consensus of the group on the scope and features of the proposed - Contacts API. Issues and editors note in the document highlight some of the points on which the group is - still working and would particularly like to get feedback. -

-

This document was published by the Device APIs and Policy Working Group as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). The Last Call period ends 14 July 2011. All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

- - - -
-

1. Introduction

This section is non-normative.

-

- Every operating system and a large number of web-based service providers have different ways of - representing address book information. Most users are required to maintain a plurality of contact lists - which leads to multiple copies of address book data. This in turn - often leads to disjointed and inconsistent information being stored across a user's - address book providers. -

-

- When sharing contact data with third parties users are, more often than not, required to hand over access to - their whole address book. Users are implicitly required to trust third parties with all of their data - when, in reality, the user may only wish, or need, to share a subset of their address book information so - that an application can fulfil its purpose. -

-

- This specification defines the concept of a user's unified address book - where address book data may - be sourced from a plurality of sources - both online and locally. It then defines the - interfaces through which third party applications can access a user's unified address book, with explicit user - permission and filtering. The focus of this data sharing is on making the user aware of the data that - they will share and putting them at the centre of the data sharing process; free to select both the - extent to which they share their address book information and the ability to restrict which pieces of - information related to which contact gets shared. -

-

- A set of Security and Privacy Considerations are - presented for the discretion of both implementors of the Contacts API and recipients of contact - information (i.e. web pages). This specification provides a set of non-normative - User Interaction Guidelines demonstrating an example user experience - that is compliant with the Security and Privacy Considerations described herein. -

-

- This specification also provides informative examples illustrating how to - add and update contact information, utilising existing web platform - APIs. -

-

- The following code illustrates how to obtain contact information from a user's address book: -

-
function success (contacts) {
-    // do something with resulting contact objects
-    for (var i in contacts) alert(contacts[i].name);
-    // ...
-}
-
-function error (err) {
-    // do something with resulting error
-    alert(err.code);
-    // ...
-}
-
-// Perform an address book search. Obtain the 'name' and 'emails' properties 
-// and initially filter the list to Contact records containing 'Bob':
-navigator.contacts.find(  ['name', 'emails'], success, error, {filter: 'Bob'} );
-// ..is equivalent to: navigator.contacts(/* parameters */)
-
- -

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

-

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

- -

- This specification defines conformance criteria that apply to a single product: the - user agent that implements the interfaces that it contains. -

-

- 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. -

-

- A conforming implementation is required to implement all fields defined in this specification. -

- -
-

2.1 Terminology

-

- The terms document base URL, browsing context, event handler attribute, - event handler event type, task, task source and task queues - are defined by the HTML5 specification [HTML5]. -

-

- The task source used by this specification is the device task source. -

-

- To dispatch a success event means that an event with the name - success, which does not bubble and is not cancellable, and which uses the - Event interface, is to be dispatched at the ContactFindCB object. -

-

- To dispatch an error event means that an event with the name - error, which does not bubble and is not cancellable, and which uses the Event - interface, is to be dispatched at the ContactErrorCB object. -

-
-
- -
-

3. Security and Privacy Considerations

-

- The API defined in this specification can be used to find contact information from a user's address - books. This discloses information related to a user's contacts such as their phone numbers, email - addresses and other personally identifying information. The distribution of this information could - potentially compromise the user's privacy, or the user's contacts' privacy. A conforming implementation - of this specification must provide a mechanism that protects the user's privacy and this mechanism should - ensure that no contact information is retrievable without the user's express permission. -

-
-

3.1 Privacy considerations for implementors of the Contacts API

-

- A user agent must not provide contact information to Web sites without the express - permission of the user. A user agent must acquire permission through a user interface, unless - they have prearranged trust relationships with users, as described below. The user interface must - include the document base URL. Those permissions that are acquired through the user interface - and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing - context is navigated to another URL) must be revocable and a user agent must respect revoked - permissions. -

-

- Obtaining the user's express permission to access one API method does not imply the user has granted - permission for the same Web site to access other methods provided by this API, or to access the same - method with a different set of arguments, as part of the same permission context. If a user has - expressed permission for an implementation to, e.g. find a set of existing contacts, the implementation - must seek the user's express permission if and when any additional find function is called - on this API. -

-

- A user agent may have prearranged trust relationships that do not require such user - interfaces. For example, while a Web browser will present a user interface when a Web site performs an - address book request, a Widget [WIDGETS] runtime may have a prearranged, delegated security - relationship with the user and, as such, a suitable alternative security and privacy mechanism with - which to authorise the retrieval of contact information. -

-
- -
-

3.2 Privacy considerations for recipients of contact information

This section is non-normative.

-

- Web sites operators that retrieve contacts information using this API are denoted as recipients - below. -

-

- Recipients should only request contact information when necessary, and only use the contact - information for the task for which it was provided to them. -

-

- Recipients should dispose of contact information once that task is completed, unless expressly - permitted to retain it by the user. Recipients should also take measures to protect this information - against unauthorised access. If contact information is stored, users should be allowed to update and - delete this information. -

-

- The recipient of contact information should not retransmit the contact information without the - user's express permission. Care should be taken when retransmitting and use of encryption is - encouraged. -

-

- Recipients should clearly and conspicuously disclose the fact that they are collecting contact data, - the purpose for the collection, how long the data is retained, how the data is secured, how the data is - shared if it is shared, how users can access, update and delete the data, and any other choices that - users have with respect to the data. This disclosure should include an explanation of any exceptions to - the guidelines listed above. -

-

- Note that even if a user gives permission to share their contact information this can have serious - privacy implications for those parties whose contacts are shared, as they may not wish such sharing to - occur. This should be considered by web services when requesting and using such information. -

-
-
-

3.3 Additional implementation considerations

This section is non-normative.

-

- Further to the requirements listed in the previous section, implementors of the Contacts API are - also advised to consider the following aspects that can negatively affect the privacy of their users: - in certain cases, users can inadvertently grant permission to the user agent to disclose their contacts - to Web sites. In other cases, the content hosted at a certain URL changes in such a way that the - previously granted contact permissions no longer apply as far as the user is concerned. Or the users - might simply change their minds. -

-

- Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive - measures are an implementation responsibility and not prescribed by this specification. However, in - designing these measures, implementers are advised to enable user awareness of contact sharing, and to - provide easy access to interfaces that enable revocation of permissions that web applications have to - access this API. -

-
-
- -
-

4. API Description

- -
-

4.1 ServiceContacts interface

-

- The ServiceContacts interface is exposed on the Navigator - object [NAVIGATOR]. Its goal is to provide an access point to the functionality in this - specification. -

-
[NoInterfaceObject]
-interface ServiceContacts {
-    readonly attribute Contacts contacts;
-};
-

4.1.1 Attributes

contacts of type Contacts, readonly
The object through which the contacts functionality can be accessed.
No exceptions.
-
Navigator implements ServiceContacts;

All instances of the Navigator type are defined to also implement the ServiceContacts interface.

-
- -
-

4.2 Contacts interface

-

- The Contacts interface exposes a database of contact information that may be retrieved. -

-

- Multiple contact groups can be represented within this unified address book by specifying consistent - categories values as part of individual - Contact objects. Multiple contact groups can be displayed by filtering on the required - categories values via - the Contacts find() operation. -

- -
[NoInterfaceObject]
-interface Contacts {
-    caller void find (DOMString[] fields, ContactFindCB successCB, optional ContactErrorCB errorCB, optional ContactFindOptions options);
-};
-

4.2.1 Methods

find
-

- Find contacts in the address book according to the find contacts process detailed - below. -

-

- This method takes two, three or four arguments. When called, it starts the following - find contacts process: -

-
    -
  1. - Let successCallback be the callback indicated by the method's second argument. -
  2. -
  3. - Let errorCallback be the callback indicated by the method's third argument, if any, or null otherwise. -
  4. -
  5. If successCallback is null, then throw a TypeError (as defined in [WEBIDL]).
  6. -
  7. - If there is a task from the device task source in one of the task - queues (e.g. an existing find() operation is still pending a response), run these - substeps: -
      -
    1. - If errorCallback is not null, let error be a ContactError - object whose code attribute has the value PENDING_OPERATION_ERROR and - queue a task to invoke errorCallback with error as its argument. -
    2. -
    3. Abort this operation.
    4. -
    -
  8. -
  9. - Return, and run the remaining steps asynchronously. -
  10. -
  11. - Let results be the array of Contact objects obtained by searching contacts in the address book - according to the rules defined in Contact Search Processing, - or null if the search has failed. -
  12. -
  13. - If results is null, run these substeps: -
      -
    1. - If errorCallback is not null, let error be a ContactError - object whose code attribute has its value set according to the type of failure that occurred and - queue a task to invoke errorCallback with error as its argument. -
    2. -
    3. Abort this operation.
    4. -
    -
  14. -
  15. Queue a task to invoke successCallback with results as its argument.
  16. -
- - -
ParameterTypeNullableOptionalDescription
fieldsDOMString[]The search qualifier.
successCBContactFindCBFunction to call when the asynchronous operation completes successfully.
errorCBContactErrorCBFunction to call when the asynchronous operation fails.
optionsContactFindOptionsThe options to apply to the output of this method.
No exceptions.
Return type: caller void
-
- -
-

4.3 Contact interface

-

- The Contact interface captures the properties of a contact object. All properties included in this - interface have a corresponding definition in [POCO-SCHEMA], [RFC2426] (aka vCard), and [OMA-CAB], thereby - allowing the API to be supported across implementations supporting these various contact formats. -

-

- All Contact objects must include all attributes supported by the implementation, regardless - of whether these attributes have been assigned a null value or not. If a supported attribute has not been - assigned a value by the user or the implementation, then this attribute must still be present in the - resulting Contact object and must have a value of null. -

-

- Additional attributes may be included according to the provisions detailed in - Extended Contact Properties and Parameters. If an - extended attribute is supported by the current implementation and has not been assigned a value by the - user or the implementation, then this extended attribute must still be present in the resulting - Contact object and must have a value of null. -

- -
[NoInterfaceObject]
-interface Contact {
-    readonly attribute DOMString              id;
-             attribute DOMString?             displayName;
-             attribute ContactName?           name;
-             attribute DOMString?             nickname;
-             attribute ContactField[]?        phoneNumbers;
-             attribute ContactField[]?        emails;
-             attribute ContactAddress[]?      addresses;
-             attribute ContactField[]?        ims;
-             attribute ContactOrganization[]? organizations;
-             attribute Date?                  birthday;
-             attribute DOMString?             note;
-             attribute ContactField[]?        photos;
-             attribute DOMString[]?           categories;
-             attribute ContactField[]?        urls;
-};
-

4.3.1 Attributes

addresses of type array of ContactAddress, nullable
-

- This attribute represents one or more physical addresses associated with this Contact. -

-
No exceptions.
birthday of type Date, nullable
-

- This attribute contains birthday of this Contact. -

-

- The year value may be set to 0000 when the age of the Contact is private or the year is not - available. -

-
No exceptions.
categories of type array of DOMString, nullable
-

- This attribute contains one or more user-defined categories/tags/labels associated with this - Contact. e.g. "family", "favourite", "cryptozoologists". -

-
No exceptions.
displayName of type DOMString, nullable
-

- This attribute contains the name of this Contact in a form that is suitable for display - to the user. -

-
No exceptions.
emails of type array of ContactField, nullable
-

- This attribute represents one or more email addresses associated with this Contact. -

-
No exceptions.
id of type DOMString, readonly
-

- A globally unique identifier for the given Contact object. -

-

- An implementation must maintain this globally unique identifier when a Contact is added - to an address book. -

-
No exceptions.
ims of type array of ContactField, nullable
-

- This attribute represents one or more instant messaging identifiers associated with this - Contact. -

-
No exceptions.
name of type ContactName, nullable
-

- This attribute represents the full name of this Contact indicated by the name components - associated with the ContactName object. -

-
No exceptions.
nickname of type DOMString, nullable
-

- This attribute contains the nickname (or a casual name) for this Contact. -

-
No exceptions.
note of type DOMString, nullable
-

- This attribute contains the personal notes (free-text) for this Contact that is managed by the - user of the address book. -

-
No exceptions.
organizations of type array of ContactOrganization, nullable
-

- This attribute represents one or more organizations associated with this Contact. -

-
No exceptions.
phoneNumbers of type array of ContactField, nullable
-

- This attribute captures one or more phone numbers associated with this Contact. -

-
No exceptions.
photos of type array of ContactField, nullable
-

- This attribute represents one or more photos associated with this Contact. -

-

- The photos must be specified in the value attribute of the ContactField object - by using a URL pointing to an image resource. The data: URI scheme may be used in order - to provide inline data. -

-

- This attribute should not be used to send down arbitrary photos taken by this user, - but specifically profile photos of the contact suitable for display when describing the - contact. -

-
No exceptions.
urls of type array of ContactField, nullable
-

- This attribute represents one or more URLs associated with this Contact e.g. personal web page, - blog. -

-

- The web resources must be specified using the value attribute of the - ContactField object, and its type field may be set to "blog" or - "profile". -

-
No exceptions.
-
- -
-

4.4 ContactName interface

- -

- The ContactName interface describes a contact's name. -

- -
[NoInterfaceObject]
-interface ContactName {
-    attribute DOMString? formatted;
-    attribute DOMString? familyName;
-    attribute DOMString? givenName;
-    attribute DOMString? middleName;
-    attribute DOMString? honorificPrefix;
-    attribute DOMString? honorificSuffix;
-};
-

4.4.1 Attributes

familyName of type DOMString, nullable
-

- This attribute contains the family name (also referred to as the last name) of this Contact. -

-
No exceptions.
formatted of type DOMString, nullable
-

- This attribute contains the full name, including all the individual components such as - givenName, middleName, familyName, prefix, - suffix as appropriate for the user's culture, and formatted for display (e.g. Mr. Joe Smith - Jr). -

-
No exceptions.
givenName of type DOMString, nullable
-

- This attribute contains the given name (also referred to as the first name) of this Contact. -

-
No exceptions.
honorificPrefix of type DOMString, nullable
-

- This attribute contains the honorific prefix (or title) of this Contact. E.g. Mr., Dr., Ms., - Mrs. -

-
No exceptions.
honorificSuffix of type DOMString, nullable
-

- This attribute contains the honorific suffix of this Contact. E.g. Jr, III, Sr. -

-
No exceptions.
middleName of type DOMString, nullable
-

- This attribute contains the middle name of this Contact. -

-
No exceptions.
-
- -
-

4.5 ContactField interface

- -

- The ContactField interface is a reusable component that is used to capture contact fields of the - Contact interface that have some modicum of structure. -

- -
[NoInterfaceObject]
-interface ContactField {
-    attribute DOMString  type;
-    attribute DOMString? value;
-    attribute boolean    pref;
-};
-

4.5.1 Attributes

pref of type boolean
-

- This attribute indicates whether this instance of the ContactField is the - preferred, or primary, value for the contact property this ContactField is - representing in the Contact interface. By default, the value is false. -

-
No exceptions.
type of type DOMString
-

- This attribute contains the type information for this ContactField and its content varies subject - to the contact property this ContactField is representing. For example, if the ContactField - is representing a phoneNumber property, the type attribute can be set to - home, mobile; if the ContactField is representing the ims - property, the type attribute could be set to xmpp, irc, bbm, etc. -

-
No exceptions.
value of type DOMString, nullable
-

- This attribute contains the value for this ContactField and its content varies subject to the - contact property this ContactField is representing. For example, if the ContactField is - representing an email, the value attribute could be set to JoeSmith@example.com, - and if the ContactField is representing a url, the value attribute can be set to - http://www.example.org/joesmith, etc. -

-
No exceptions.
-
- -
-

4.6 ContactAddress interface

- -

- The ContactAddress interface is a reusable component that is used to capture addresses - within the Contact interface. -

-
[NoInterfaceObject]
-interface ContactAddress {
-    attribute boolean    pref;
-    attribute DOMString? type;
-    attribute DOMString? formatted;
-    attribute DOMString? streetAddress;
-    attribute DOMString? locality;
-    attribute DOMString? region;
-    attribute DOMString? postalCode;
-    attribute DOMString? country;
-};
-

4.6.1 Attributes

country of type DOMString, nullable
-

- This attribute contains the country name corresponding to this ContactAddress. -

-
No exceptions.
formatted of type DOMString, nullable
-

- This attribute contains the full physical address including street, locality, - region, postalCode, and country as appropriate, and formatted for - display. -

-
No exceptions.
locality of type DOMString, nullable
-

- This attribute contains the locality (or city) name corresponding to this ContactAddress. -

-
No exceptions.
postalCode of type DOMString, nullable
-

- This attribute contains the postal code (or zip) corresponding to this ContactAddress. -

-
No exceptions.
pref of type boolean
-

- This attribute indicates whether this instance of the ContactAddress is the preferred, or primary, value for the contact. - By default, the value is false. -

-
No exceptions.
region of type DOMString, nullable
-

- This attribute contains the region (or state/province) name corresponding to this ContactAddress. -

-
No exceptions.
streetAddress of type DOMString, nullable
-

- This attribute contains the street address corresponding to this ContactAddress. -

-
No exceptions.
type of type DOMString, nullable
-

- This attribute contains the type of address this object is representing (e.g. work, home, premises, etc). -

-
No exceptions.
-
- -
-

4.7 ContactOrganization interface

- -

- The ContactOrganization interface is a reusable component that is used to support contact - organisations within the Contact interface. -

- -
[NoInterfaceObject]
-interface ContactOrganization {
-    attribute boolean    pref;
-    attribute DOMString? type;
-    attribute DOMString? name;
-    attribute DOMString? department;
-    attribute DOMString? title;
-};
-

4.7.1 Attributes

department of type DOMString, nullable
-

- The department within which this Contact works. -

-
No exceptions.
name of type DOMString, nullable
-

- The name of the organisation. -

-
No exceptions.
pref of type boolean
-

- This attribute indicates whether this instance of the ContactOrganization is the preferred, or - primary, value for the contact. By default, the value is false. -

-
No exceptions.
title of type DOMString, nullable
-

- The job title that the Contact holds inside this organisation. -

-
No exceptions.
type of type DOMString, nullable
-

- This attribute contains the type of organization this object is representing. -

-
No exceptions.
-
- -
-

4.8 ContactFindOptions interface

-

- The ContactFindOptions interface describes the options that can be applied to contact searching. - When a ContactFindOptions parameter is provided to the Contacts find() - operation, it should be processed according to the provisions detailed in - Options Processing. -

-
[NoInterfaceObject]
-interface ContactFindOptions {
-    attribute DOMString? filter;
-    attribute boolean?   multiple;
-};
-

4.8.1 Attributes

filter of type DOMString, nullable
- A string-based search filter which provides a hint to the user agent to facilitate contacts selection by the user. -
No exceptions.
multiple of type boolean, nullable
- A boolean value to indicate whether multiple Contact objects are wanted as part of the - Contacts find() operation. - By default this option is set to false. -
No exceptions.
-
- -
-

4.9 ContactFindCB interface

-

- This is the wrapper interface for callbacks indicating success of the find() - operation. -

- -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactFindCB {
-    void onsuccess (Contact[] contactObjs);
-};
-

4.9.1 Methods

onsuccess
- -
ParameterTypeNullableOptionalDescription
contactObjsContact[] - An array of Contact objects resulting from the given Contacts - find() operation. -
No exceptions.
Return type: void
- -
-

4.9.2 Event Handler Attributes

-

- The following is the event handler attribute (and its corresponding event handler event - type) that must be supported as a DOM attribute by the ContactFindCB object. -

- - - - - - - - - - - - - -
event handler attributeevent handler event type
onsuccesssuccess
-
-
- -
-

4.10 ContactErrorCB interface

-

- This is the wrapper interface for callbacks indicating failure of the find() - operation. -

- -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactErrorCB {
-    void onerror (ContactError error);
-};
-

4.10.1 Methods

onerror
- -
ParameterTypeNullableOptionalDescription
errorContactErrorThe ContactError object capturing the type of the error.
No exceptions.
Return type: void
- -
-

4.10.2 Event Handler Attributes

-

- The following is the event handler attribute (and its corresponding event handler event - type) that must be supported as a DOM attribute by the ContactErrorCB object. -

- - - - - - - - - - - - - - -
event handler attributeevent handler event type
onerrorerror
-
-
- -
-

4.11 ContactError interface

-

- The ContactError interface encapsulates all errors in the manipulation of - Contact objects. -

- -
[NoInterfaceObject]
-interface ContactError {
-    const unsigned short UNKNOWN_ERROR = 0;
-    const unsigned short INVALID_ARGUMENT_ERROR = 1;
-    const unsigned short TIMEOUT_ERROR = 2;
-    const unsigned short PENDING_OPERATION_ERROR = 3;
-    const unsigned short IO_ERROR = 4;
-    const unsigned short NOT_SUPPORTED_ERROR = 5;
-    const unsigned short PERMISSION_DENIED_ERROR = 20;
-    readonly attribute unsigned short code;
-};
-

4.11.1 Attributes

code of type unsigned short, readonly
An error code assigned by an implementation when an error has occurred in Contacts API - processing.
No exceptions.

4.11.2 Constants

INVALID_ARGUMENT_ERROR of type unsigned short
An invalid parameter was provided when the requested method was invoked.
IO_ERROR of type unsigned short
An error occurred in communication with the underlying implementation that meant the requested - method could not complete.
NOT_SUPPORTED_ERROR of type unsigned short
The requested method is not supported by the current implementation.
PENDING_OPERATION_ERROR of type unsigned short
There is already a task in the device task source.
PERMISSION_DENIED_ERROR of type unsigned short
Access to the requested information was denied by the implementation or by the user.
TIMEOUT_ERROR of type unsigned short
The requested method timed out before it could be completed.
UNKNOWN_ERROR of type unsigned short
An unknown error occurred.
-
-
- -
-

5. Contact Search Processing

- -

- The Contacts find() - method provides an operation to search for one of more Contact objects within the Contacts database. -

- -
-

5.1 Search Qualifiers

- -

- The search qualifier provides an application with a way to request the specific subset of - Contact properties it wishes to obtain in any resulting - successful callback. The search qualifier is deployed to minimize the data that needs to be - shared with an application in order to let that application fulfill its function on behalf of the user. - The search qualifier is included within a Contacts find() operation as - the fields parameter. -

- -

- A search qualifier must be specified from a requesting application as a part of any Contacts find() operation. -

- -

- If the search qualifier provided is of zero-length then the current Contacts find() operation and - the current find() operation was invoked with a non-null - errorCB parameter, then the user agent must invoke the errorCB function - with an error code of INVALID_ARGUMENT_ERROR. -

- -

- In the case that the search qualifier provided is of non-zero-length then the - current Contacts find() operation must return only the matching Contact properties within any resulting Contact object(s). -

- -

- If a provided search qualifier element (fields[x]) does not match a Contact attribute, fields[x] should be ignored when - executing the current Contacts find() operation. -

- -
-

5.1.1 Advanced Search Qualifiers

- -

- We call composed attributes Contact - attributes of types object, which contain information only available - only through child attributes of that object, or array. -

- -

- A requesting application must be able to request both the full composed Contact attribute and also be able to request individual parts - of a composed Contact attribute in the search - qualifier provided to a Contacts find() operation. -

- -

- For example, the name attribute of a Contact object is defined to be of composed type ContactName. Therefore, a requesting application may - request either the full composed attribute (i.e. name) or specific individual attributes - of this composed attribute (i.e. name.formatted, name.familyName, - name.givenName, name.middleName, name.honorificPrefix, - name.honorificSuffix) as part of a Contacts find() operation's - search qualifier. -

- -

- In the case that a composed Contact attribute is - defined as an array of composed objects, specific individual attributes can be referenced - by using the composed attribute name, a dot (.) character and the individual attribute - to be retrieved. -

- -

- For example, the addresses attribute of Contact allows multiple ContactAddress objects to be defined. To request - individual attributes of this composed attribute an application would request e.g. - addresses.locality, addresses.region, etc. -

-
- -
-

- The following Contact search is initiated: -

-
 
-     navigator.contacts( ['emails.value', 'name', 'friends'],
-                         function(contacts) { 
-                           for(i in contacts) {
-                             for(j in contacts[i].emails)
-                               alert(contacts[i].emails[j]);
-                           }
-                         } );
-  
- -

- The above example logically implies: -

- -
    -
  1. Return only the valid Contact attributes - requested in the provided search qualifier (name, emails.value - - friends is not a valid Contact attribute - so ignore this element).
  2. -
-
-
- -
-

5.2 Options Processing

- -
-

5.2.1 Search Cardinality

- -

- By default, the Contacts find() operation must return either an empty sequence or a single Contact object, accessible as part of the sequence returned in - the ContactFindCB callback function. -

- -

- If a ContactFindOptions object is - provided to the Contacts find() operation and its multiple attribute is set to - true, the Contacts find() operation must return either an empty sequence, a single Contact object or [X] number of Contact objects, accessible as part of the sequence returned in - the ContactFindCB callback function. -

-
- -
-

5.2.2 Search Filters

- -

- A search filter may be specified from a requesting web application to provide a hint to the user agents as to which contacts the user can select to share with the application.

- -

The search filter is defined through the filter - attribute of the ContactFindOptions object - provided to a Contacts find() operation. -

- -

The actual usage of this search filter is user-agent dependant, but is expected to represent - the logical union of provided values that are matched therein. -

-
-
-
- -
-

6. Extended Contact Properties and Parameters

- -

- The properties and parameters defined on the Contact - interface may be extended by implementors of this specification. -

- -

- Non-standard, private properties and parameters should have a prefixed name starting with - X (U+0058 LATIN CAPITAL LETTER X) or use a vendor-specific prefix. Extended properties and - parameters can be defined bilaterally between user agents without outside - registration or standardization. -

- -

- It is recommended that authors define both a formal vCard grammar and a WebIDL grammar for their - proposed extension to ensure interoperability between vCard databases and other non-standard Contact - databases and formats. It is also recommended that authors provide documentation of their extension - properties and parameters within the public domain. -

- -
-

- A new parameter is required by Company X to provide information related to a user's accounts - registered across different networks and services. -

- -

- The [WEBIDL] syntax for this parameter is defined as follows: -

- -
Contact implements ContactExtended;
-   -
- -
[NoInterfaceObject]
-interface ContactExtended {
-    attribute ContactAccount[] Xaccounts;
-};
-

Attributes

Xaccounts of type array of ContactAccount
One or more user accounts. See [[POCO-SCHEMA] Section 7.2.2. accounts].
No exceptions.
- -
[NoInterfaceObject]
-interface ContactAccount {
-    attribute DOMString domain;
-    attribute DOMString username;
-    attribute DOMString userid;
-};
-

Attributes

domain of type DOMString
-

- See [[POCO-SCHEMA] Section 7.6. domain]. -

-
No exceptions.
userid of type DOMString
-

- See [[POCO-SCHEMA] Section 7.6. userid]. -

-
No exceptions.
username of type DOMString
-

- See [[POCO-SCHEMA] Section 7.6. username]. -

-
No exceptions.
- -

- The corresponding vCard [RFC2426] notation for this parameter is defined as follows: -

-
     The following ABNF grammar extends the grammar found in [RFC2426] (Section 4).
-   
-     X-ACCOUNT
-   
-     Purpose:  To specify the components of the accounts for the vCard 
-        object.
-
-     Value type:  A single structured text value, separated by the SEMI-
-        COLON character (ASCII decimal 59).
-
-     Cardinality:  (0,n)
-
-     Special notes:  The structured type value consists of a sequence of
-        account components.  The component values must be specified in
-        their corresponding position.  The structured type value
-        corresponds, in sequence, to the domain; the username; the userid.
-        When a component value is missing, the associated component 
-        separator must still be specified.    
-
-        The text components are separated by the SEMI-COLON character
-        (ASCII decimal 59).
-      
-     ABNF:
-   
-       X-ACCOUNT-param = ; no parameter allowed
-       X-ACCOUNT-value = list-component 3(";" list-component)
-  
- -

- This parameter will be used within the Contacts API as follows: -

-
     var contact = ...; // ...obtain individual contact object
-     for(var i in contact.Xaccounts) {
-        alert(contact.Xaccounts[i].domain);   // thesocialnetwork.com
-        alert(contact.Xaccounts[i].username); // null
-        alert(contact.Xaccounts[i].userid);   // 344aesq2
-     }            
-  
- -

- This parameter will be used within the vCard format [RFC2426]] as follows: -

-
     X-ACCOUNT;thesocialnetwork.com;;344aesq2
-  
-
-
- -
-

7. API Invocation via DOM Events

- -

- The API contained in this document can be invoked either programmatically (for example, inline within - a general script) or resulting from the interaction of a user. -

- -

- The interaction of a user is when a user invokes the API from an HTMLElement [HTML5] within the current - browsing context via a valid auto-invocation event. -

- -

- A valid auto-invocation event includes any of the following event types, as defined in - [DOM-LEVEL-3-EVENTS]: -

- - - -

- The find() method on Contacts should, if - the method was invoked by an interaction of a user (as opposed to having been created and executed - in general script), display the Contact Picker directly. -

-
- -
-

A. User Interaction Guidelines

This section is non-normative.

- -

- This specification is primarily intended to provide the user with the ability to view and control the - contact information that may be shared from their unified address book. This annex provides some examples - of a conformant user experience that this specification enables. -

- -
-

A.1 Accessing Contact Information - Example #1

- -

- A website requests access to a user's address book with the following code: -

- -
-
   <script type="text/javascript">
- 
-  function successContactFindCallback(contacts) {
-      // do something with resulting contact objects
-      for (var i in contacts) alert(contacts[i].name);
-      // ...
-  }
-
-  function generalErrorCB(error) {
-      // do something with resulting errors
-      alert(error.code);
-      // ...
-  }
-
-  // Perform an address book search. Obtain the 'name' and 'emails' properties 
-  // and initially filter the list to Contact records containing 'Bob':
-  navigator.contacts.find(['name', 'emails'],
-                                  successContactFindCallback, 
-                                  generalErrorCB,
-                                  {filter: 'Bob'}
-                                 );
-                               
-  </script>
-  
-
- -

- As a result of executing this code, the user agent may provide a non-blocking contact - search notification as follows: -

- -

Contact Search Notification
- (View as PNG) -

- -

- If an additional find() operation is called by the current web application before the user has - clicked 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of - PENDING_OPERATION_ERROR if that - operation was defined with a non-null errorCB parameter. -

- -

- If the user clicks 'Cancel', the errorCB, if non-null for the current - find() operation, will be invoked with an error code of PERMISSION_DENIED_ERROR. -

- -

- If the user clicks 'Select', the user agent may provide a contact picker, - utilizing all of the parameters provided in the find() operation as follows: -

- -

Contact Picker
- (View as PNG) -

- -

- In this dialog, the user is provided with a summary of the sharing that the application is - requesting and the option to select one or more contacts (as appropriate) from the user interface. -

- -

- If an additional find() operation is called by the current web application before the user has - clicked 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of - PENDING_OPERATION_ERROR if that - operation was defined with a non-null errorCB parameter. -

- -

- If the user clicks 'Cancel', the errorCB, if non-null for the current - find() operation, will be invoked with an error code of PERMISSION_DENIED_ERROR. -

- -

- If the user clicks 'Select', the ContactFindCB - associated to the current find() operation will be invoked with the contact information selected by the - user provided as the only parameter. -

- -

- Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the - user should easily be able to review and revoke access that web applications have to this API - at a later time. -

-
- -
-

A.2 Accessing Contact Information - Example #2

- -

- A website requests access to a user's address book with the following code: -

- -
-
  <input type="button" value="Share Contacts" onclick="getContacts()" />
- 
-  <script type="text/javascript">
-    function successContactFindCallback(contacts) {
-      // do something with resulting contact objects
-      for (var i in contacts) alert(contacts[i].name);
-      // ...
-    }
-
-    function generalErrorCB(error) {
-      // do something with resulting errors
-      alert(error.code);
-      // ...
-    }
-  
-    function getContacts() {
-      // Perform an address book search. Obtain the 'name' and 'emails' properties 
-      // and initially filter the list to Contact records containing 'Bob':
-      navigator.contacts( ['name', 'emails'],
-                          successContactFindCallback, 
-                          generalErrorCB,
-                          { filter: 'Bob' } ); 
-      // is equivalent to: navigator.contacts.find(/* parameters */);
-    }
-  </script>
-  
-
- -

- This code may render as follows within the user agent: -

- -

Contact Search via DOM Events
- (View as PNG) -

- -

- If the user clicks on the rendered button element then the user agent may directly provide a - contact picker, as defined in API Invocation via - DOM Events, utilizing all of the parameters provided in the find() operation as - follows: -

- -

Contact Picker
- (View as PNG) -

- -

- In this dialog, the user is provided with a summary of the sharing that the application is - requesting and the option to select one or more contacts (as appropriate) from the user interface. -

- -

- If an additional find() operation is called by the current web application before the user has - clicked 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of - PENDING_OPERATION_ERROR if that - operation was defined with a non-null errorCB parameter. -

- -

- If the user clicks 'Cancel', the errorCB, if non-null for the current - find() operation, will be invoked with an error code of PERMISSION_DENIED_ERROR. -

- -

- If the user clicks 'Select', the ContactFindCB - associated to the current find() operation will be invoked with the contact information selected by the - user provided as the only parameter. -

- -

- Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the - user should easily be able to review and revoke access that web applications have to this API - at a later time. -

-
-
- -
-

B. Adding and Updating Contacts

This section is non-normative.

- -

- The ability to add and update contact information is not a function of the API provided in this - specification. Instead, the intention is to reuse existing web platform APIs and paradigms in order to - acheive add and update functionality. -

- -

- In this section we show how the existing web platform would be used to provide add and update - writeback functionality to allow users to add new contacts or update existing contacts from a web page to - their unified address book. -

- -

- A valid Contact resource is a web resource with a .vcard or .vcf - filename extension or a web resource with a MIME-type matching a valid media type. A vCard - object is a text-based representation of contact information provided according to any version of - the vCard family of specifications. -

- -

Need to add informative references to all specs within the 'vCard family of - specifications'. -

- -

- To handle the saving of a new Contact, a user agent should register as the default handler for - any valid Contact resource. -

- -

- A valid media type will be one of the following web resource MIME types: -

- - - -

- On invocation of a valid Contact resource, the user agent should, on successful download - of the valid Contact resource, store the given resource in the user's unified address book - according to the rule for storing a Contact resource. As part of this standard download process, - the user agent may present a dialog to the user allowing them to select a different application - with which to handle the given resource, thereby overriding the use of the unified address book for the - storage of the data contained therein and bypassing the rule for storing a Contact resource. -

- -

- The rule for storing a Contact resource is defined as follows: -

- -

- Let Contact be the parsed key/value pairs contained in the valid Contact - resource. -

- -
    -
  1. If Contact contains a UID key then process the valid Contact - resource as follows. - -
      -
    1. Let MatchedContact be the result of obtaining a Contact object from the user's - unified address book that matches exactly the value of the UID provided.
    2. - -
    3. If a MatchedContact has been found (i.e MatchedContact is - not-null) then update the contents of MatchedContact with the contents of - Contact and exit this rule.
    4. -
    -
  2. - -
  3. Save the contents of Contact in the user's unified address book as a new Contact - object.
  4. -
- -

- As part of the rule for storing a Contact resource, the user agent may provide - additional dialogs to the user after successful completion of the download and before the Contact - information is saved to the unified address book, such as to show a preview of the Contact information - contained therein as it will be stored in the user's unified address book. The user may be able to - override the information provided before accepting the additions and permanently storing the given data - in their unified address book. -

- -
-

B.1 Adding a new Contact

This section is non-normative.

- -

- A web page can dynamically generate a vCard object on the client side for download to the - user's unified address book via either data: URIs [RFC2397] or using the [FILE-WRITER] and - [FILE-API] interfaces. The following examples show two methods for creating a vCard object - dynamically and then presenting this to the user. The user may then save this information by clicking - on the presented information, download the dynamically generated vCard object and invoke a - suitable application with which to handle the dynamic resource. -

- -
-
  <a id="vcard">Save our Contact Details</a>
-
-  <script type="text/javascript">
-    var vcard = 'BEGIN:VCARD\r\n' +
-                'VERSION:2.1\r\n' +
-                'N:Doe;John\r\n' +
-                'FN:John Doe\r\n' +
-                'TEL;WORK;VOICE:123456\r\n' +
-                'END:VCARD';
-
-    // assign vCard as a Data URI to an anchor element for presentation and download by the user
-    document.getElementById('vcard').href = "data:text/x-vcard;charset=utf-8," + encodeURIComponent( vcard ); 
-  </script>
-  
-
- -
-
  <a id="vcard">Save our Contact Details</a>
-
-  <script type="text/javascript">
-    // obtain an ArrayBuffer consisting of valid vCard syntax (out of scope)
-    var vCardObj = getVCard( /* ... */ );
-            
-    // create a new vCard Blob [FILE-WRITER]
-    var contactBlobBuilder = new BlobBuilder();
-    contactBlobBuilder.append( vCardObj );
-    var contactBlob = contactBlobBuilder.getBlob( "text/x-vcard" );
-
-    // obtain a vCard Blob URL [FILE-API]
-    var contactBlobURL = window.URL.createObjectUrl( contactBlob );
-
-    // assign vCard Blob URL to an anchor element for presentation and download by the user
-    document.getElementById('vcard').href = contactBlobURL; 
-  </script>
-  
-
-
- -
-

B.2 Updating an existing Contact

This section is non-normative.

- -

- To update an existing Contact, the user must have already shared the contact information to edit - with the current web page via the find() operation of the Contacts interface. This section assumes that the user is - already sharing some contact information with the current web page via this process. -

- -

- If this existing Contact information is to be updated in the user's unified address book then the - developer will assign the id attribute, as returned in the Contact object, as - the UID property of any resulting vCard object to be processed by the user - agent according to the rule for storing a Contact resource. -

- -

- The examples below show two methods for updating an existing Contact in the user's unified address - book by maintaining a valid UID property while changing other parameters of the Contact card. The user - is then required to click on the resulting anchor element to download the modified Contact - resource. -

- -
-
  <a id="vcard">Save our Contact Details</a>
-
-  <script type="text/javascript">
-    // Obtain a single existing Contact object resulting from navigator.contacts.find()
-    var existingContactObj = ...;
-  
-    var vcard = 'BEGIN:VCARD\r\n' +
-                'VERSION:3.0\r\n' +
-                'UID:' + existingContactObj.id + '\r\n' + // assign the Contact.id to a UID property   
-                'N:Doe;John\r\n' +
-                'FN:John Doe\r\n' +
-                'TEL;HOME;VOICE:654321\r\n' +
-                'END:VCARD';
-
-    // assign vCard as a Data URI to an anchor element for presentation and download by the user
-    document.getElementById('vcard').href = "data:text/x-vcard;charset=utf-8," + encodeURIComponent( vcard ); 
-  </script>
-  
-
- -
-
  <a id="vcard">Update our Contact Details</a>
-
-  <script type="text/javascript">
-    // Obtain a single existing Contact object resulting from navigator.contacts.find()
-    var existingContactObj = ...;
-  
-    // Modify some parameters as required. e.g. add a new phone number
-    existingContactObj.phoneNumbers.push({
-      type: 'home', 
-      value: '654321'
-    });
-
-    // With the existing Contact object, create an ArrayBuffer consisting of valid vCard 
-    // syntax (out of scope) making sure to set the resulting vCard UID property to 
-    // the id parameter returned in the existing Contact object
-    var vCardObj = getVCard( existingContactObj );
-
-    // create a new vCard Blob [FILE-WRITER]
-    var contactBlobBuilder = new BlobBuilder();
-    contactBlobBuilder.append( vCardObj );
-    var contactBlob = contactBlobBuilder.getBlob( "text/x-vcard" );
-
-    // obtain a vCard Blob URL [FILE-API]
-    var contactBlobURL = window.URL.createObjectUrl( contactBlob );
-
-    // assign vCard Blob URL to an anchor element for presentation and download by the user
-    document.getElementById('vcard').href = contactBlobURL; 
-  </script>
-  
-
-
-
- - -

C. References

C.1 Normative references

[DOM-LEVEL-3-EVENTS]
Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. Document Object Model (DOM) Level 3 Events Specification. 31 May 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-DOM-Level-3-Events-20110531/ -
[HTML5]
Ian Hickson; David Hyatt. HTML5. 25 May 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-html5-20110525/ -
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt -
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219 -

C.2 Informative references

[FILE-API]
Arun Ranganathan. File API. 17 November 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-FileAPI-20091117/ -
[FILE-WRITER]
Eric Uhrhane. File Writer API. W3C Working Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/file-system/file-writer.html -
[NAVIGATOR]
Ian Hickson, David Hyatt. Navigator interface in HTML5. 15 April 2011. Editors' draft. (Work in progress.) URL: http://dev.w3.org/html5/spec/timers.html#navigator -
[OMA-CAB]
Converged Address Book Enabler, Version 1.0, Open Mobile Alliance, URL: http://www.openmobilealliance.org/ -
[POCO-SCHEMA]
Joseph Smarr. Portable Contacts 1.0 Draft C: Contact Schema 5 August 2008. URL: http://portablecontacts.net/draft-spec.html#schema -
[RFC2397]
L. Masinter. The "data" URL scheme. August 1998. Internet RFC 2397. URL: http://www.ietf.org/rfc/rfc2397.txt -
[RFC2426]
F. Dawson, T. Howes. vCard MIME Directory Profile. September 1998. URL: http://www.ietf.org/rfc/rfc2426.txt -
[WIDGETS]
Marcos Caceres. Widget Packaging and Configuration. 01 December 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-widgets-20091201/ -
\ No newline at end of file diff -r 52acb4877e86 -r 518970294839 contacts/LC/contacts_element.png Binary file contacts/LC/contacts_element.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/LC/contacts_notification.png Binary file contacts/LC/contacts_notification.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/LC/contacts_picker.png Binary file contacts/LC/contacts_picker.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/Overview.html --- a/contacts/Overview.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,520 +0,0 @@ - - - - Pick Contacts Intent - - - - - -
-

- The Pick Contacts Intent defines a Web Intent [[!WEBINTENTS]] that enables access to a user's - address book service from inside a Web application. It defines both an Intent action/type - pair that selects this operation, and the format of the contacts data that is returned - by services implementing this specification -

-
- -
-

- This document builds atop previous versions that were pure JavaScript APIs and turns them - into an API built using Web Intents, while maintaining the data format which the JavaScript - APIs had defined. -

-
- -
-

Introduction

-

- Every operating system and a large number of Web-based service providers have different ways of - representing address book information. Most users are required to maintain a plurality of contact lists - which leads to multiple copies of address book data. This in turn often leads to disjoint and inconsistent - information being stored across a user's address book providers. -

-

- When sharing contact data with third parties users are, more often than not, required to hand over access to - their whole address book. Users are implicitly required to trust third parties with all of their data - when, in reality, the user may only wish, or need, to share a subset of their address book information so - that an application can fulfil its purpose. When sharing of only a subset of a user's address book is - possible, it often requires the user to type the information into a form herself rather than having it - extracted from one of her address book services. -

-

- This specification enables a Web application to have access to a selected subset of a user's address book, - obtained from arbitrary services not known to the Web application. The interactions, brokered using - Web Intents [[!WEBINTENTS]] are designed in order to maximise the user's security and privacy. - Address book data may be sourced from a plurality of sources — both online and local to the user's device - — so long as those sources are registered as Intent services with the user agent. It defines a common - format which services use to provide data to Web applications in a consistent and interoperable manner. -

-

- The expectation is that data sharing happens with explicit user permission and filtering. The focus of - this data sharing is on making the user aware of the data that they will share and putting them at the - centre of the data sharing process; free to select both the extent to which they share their address - book information and the ability to restrict which pieces of information related to which contact gets shared. -

-

- A set of Security and Privacy Considerations are - presented for the discretion of both implementers of Pick Contacts Intent services and recipients of contact - information (i.e. Web applications). -

-

- The following code illustrates how to obtain contact information from a user's address book: -

-
-        var intent = new Intent({ action:   "http://intents.w3.org/pick",
-                                  type:     "http://intents.w3.org/type/contact",
-                                  extras:   { fields: ["displayName", "emails"] }});
-        navigator.startActivity(intent, contactsOK, contactsFail);
-
-        function contactsOK (contacts) {
-            // iterate over the array of contacts to do something useful with them
-        }
-        function contactsFail (err) {
-            // display an error to the user
-        }
-      
-

- When the above code is run, the user would typically be prompted by her user agent to select - a service able to pick a contact (there may be several such services, if she has multiple address - book sources). Upon selecting a service, she will be presented with an interface enabling her - to choose what contact information is returned to the Web application. Upon completing her - choice, the contacts data would be returned to the Web application in the contactsOK - callback. -

-
- -
-

- There is only one single conformance requirement placed upon the user agent - product: a user agent MUST support Web Intents [[!WEBINTENTS]]. -

-

- The conformance criteria in this specification apply to a single product: the - contact service which exposes a Web Intent service that - handles Pick Contact Intents as defined in this specification. -

-

- The data returned by the contact service is described in this specification using [[!WEBIDL]]. - When this data is provided using JavaScript, then the contact service MUST do so in a manner - consistent with the ECMAScript Bindings defined in the Web IDL specification. -

-
- -
-

Security and Privacy Considerations

-

- The Intent defined in this specification can be used to find contact information from a user's address - books. This discloses information related to a user's contacts such as their phone numbers, email - addresses and other personally identifying information. The distribution of this information could - potentially compromise the user's privacy, or the user's contacts' privacy. A conforming implementation - of this specification should provide a mechanism that protects the user's privacy and this mechanism should - ensure that no contact information is retrievable without the user's express permission. -

-
-

Privacy considerations for implementers of the Pick Contacts Intent

-

- A contact service should not provide contact information to Web sites without the express - permission of the user. Obtaining the user's express permission to access a set of contacts does - not imply that the user has granted permission for the same Web site to access more contact information. - A contact service should take great care to ensure that the user can clearly see which information - is about to be shared, and must not share more information than has been requested by the Web application. -

-

- A user agent may have prearranged trust relationships with a specific contact service - that do not require such user interaction. -

-
-
-

Privacy considerations for recipients of contact information

-

- Web sites operators that retrieve contacts information using this Intent are denoted as recipients - below. -

-

- Recipients should only request contact information when necessary, and only use the contact - information for the task for which it was provided to them. -

-

- Recipients should dispose of contact information once that task is completed, unless expressly - permitted to retain it by the user. Recipients should also take measures to protect this information - against unauthorised access. If contact information is stored, users should be allowed to update and - delete this information. -

-

- The recipient of contact information should not retransmit the contact information without the - user's express permission. Care should be taken when retransmitting and use of encryption is - encouraged. -

-

- Recipients should clearly and conspicuously disclose the fact that they are collecting contact data, - the purpose of the collection, how long the data is retained, how the data is secured, how the data is - shared if it is shared, how users can access, update and delete the data, and any other choices that - users have with respect to the data. This disclosure should include an explanation of any exceptions to - the guidelines listed above. -

-

- Note that even if a user gives permission to share their contact information this can have serious - privacy implications for those parties whose contacts are shared, as they may not wish such sharing to - occur. This should be considered by Web applications when requesting and using such information. -

-
-
-

Additional implementation considerations

-

- Further to the requirements listed in the previous section, implementers of a user agents are - also advised to consider the following aspects that can negatively affect the privacy of their users: - in certain cases, users can inadvertently grant permission to disclose their contacts - to Web sites. In other cases, the content hosted at a certain URL changes in such a way that the - previously granted contact permissions no longer apply as far as the user is concerned. Or the users - might simply change their minds. -

-

- Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive - measures are a user agent's responsibility and not prescribed by this specification. However, in - designing these measures, implementers are advised to enable user awareness of information sharing, and to - provide easy access to user interfaces that enable revocation of permissions that Web applications have to - access this Intent. -

-
-
- -
-

Intent Description

-

- The action for this Intent is http://intents.w3.org/pick. -

-

- The type for this Intent is http://intents.w3.org/type/contact. -

-

- When a contact service is matched for delivery using these action and type, it - MUST respond in one of two ways: -

- -
-

Intent Extras

-

- The Pick Contact Intent can be instantiated with an extras field that adheres to the - following dictionary. -

-
-

The ContactIntentExtras dictionary

-

- The ContactIntentExtras dictionary describes the options that can be applied to contact searching. -

-
-
DOMString search
-
- A string which provides a hint to the contact service to facilitate contacts selection by the user. - The exact manner in which this hint is exploited is entirely up to the contact service. -
-
unsigned long limit
-
- By default a contact service MAY return as many contacts as the user selects. If limit - is specified, the contact service MUST NOT return more than limit contacts. The - contact service SHOULD enforce this limitation in the user interface that it exposes. -
-
sequence<DOMString> fields
-
- An array of field names corresponding to the name of the fields in the Contact dictionary that - the Web application is requesting from the contact service. The contact service MUST - NOT return defined fields on the contact objects that it provides other than those present in this - list. If a field name is provided that the contact service does not recognise as a field - of the Contact dictionary, then it MUST ignore it. -
-
-
-
-
-
-

Data Format

-

- Upon successful invocation, the contact service MUST return an array of Contact dictionaries. -

-
-

The Contact dictionary

-

- The Contact dictionary captures the properties of a contact object. All properties included in this - interface have a corresponding definition in [[POCO-SCHEMA]], [[RFC2426]] (also known as vCard), and - [[OMA-CAB]], thereby allowing the data format to be supported across implementations supporting these - various contact representations. -

-

- Additional attributes MAY be included according to the provisions detailed in - Extended Contact Properties and Parameters. -

-
-
DOMString id
-
- A globally unique identifier for the given Contact object. -
-
DOMString displayName
-
- This attribute contains the name of this Contact in a form that is suitable for display - to the user. -
-
ContactName name
-
- This attribute represents the full name of this Contact indicated by the name components - associated with the ContactName dictionary. -
-
DOMString nickname
-
- This attribute contains the nickname (or a casual name) for this Contact. -
-
sequence<ContactField> phoneNumbers
-
- This attribute captures one or more phone numbers associated with this Contact. -
-
sequence<ContactField> emails
-
- This attribute represents one or more email addresses associated with this Contact. -
-
sequence<ContactAddress> addresses
-
- This attribute represents one or more physical addresses associated with this Contact. -
-
sequence<ContactField> ims
-
- This attribute represents one or more instant messaging identifiers associated with this - Contact. -
-
sequence<ContactOrganization> organizations
-
- This attribute represents one or more organisations associated with this Contact. -
-
Date birthday
-
- This attribute contains birthday of this Contact. The contact service MAY - set the year value to 0000 when the age of the Contact is private or the year is not - available. -
-
DOMString note
-
- This attribute contains the personal notes (free-text) for this Contact that is managed by the - user of the address book. -
-
sequence<ContactField> photos
-
-

- This attribute represents one or more photos associated with this Contact. -

-

- The photos MUST be specified in the value attribute of the ContactField object - by using a URL pointing to an image resource. The data: URI scheme may be used in order - to provide inline data. -

-

- A contact service SHOULD NOT use this attribute to send down arbitrary photos taken by this user, - but specifically profile photos of the contact suitable for display when describing the - contact. -

-
-
sequence<DOMString> categories
-
- This attribute contains one or more user-defined categories/tags/labels associated with this - Contact. e.g. "family", "favourite", "cryptozoologists". -
-
sequence<ContactField> urls
-
-

- This attribute represents one or more URLs associated with this Contact e.g. personal web page, - blog. -

-
-
-
- -
-

The ContactName dictionary

-

- The ContactName dictionary describes a contact's name in detail. -

-
-
DOMString familyName
-
- This attribute contains the family name (also referred to as the last name) of this Contact. -
-
DOMString givenName
-
- This attribute contains the given name (also referred to as the first name) of this Contact. -
-
DOMString middleName
-
- This attribute contains the middle name of this Contact. -
-
DOMString honorificPrefix
-
- This attribute contains the honorific prefix (or title) of this Contact. E.g. Mr., Dr., Ms., Mrs. -
-
DOMString honorificSuffix
-
- This attribute contains the honorific suffix of this Contact. E.g. Jr., III, Sr. -
-
-
- -
-

The ContactField dictionary

-

- The ContactField dictionary is a reusable component that is used to capture contact fields of the - Contact dictionary that have some modicum of structure. -

- -
-
DOMString type
-
- This attribute contains the type information for this ContactField and its content varies subject - to the contact property this ContactField is representing. For example, if the ContactField - is representing a phoneNumber property, the type attribute can be set to - home, mobile; if the ContactField is representing the ims - property, the type attribute could be set to xmpp, irc, bbm, etc. -
-
DOMString value
-
- This attribute contains the value for this ContactField and its content varies subject to the - contact property this ContactField is representing. For example, if the ContactField is - representing an email, the value attribute could be set to JoeSmith@example.com, - and if the ContactField is representing a url, the value attribute can be set to - http://www.example.org/joesmith, etc. -
-
boolean pref
-
- This attribute indicates whether this instance of the ContactField is the - preferred, or primary, value for the contact property this ContactField is - representing in the Contact interface. By default, the value is false. -
-
-
- -
-

The ContactAddress dictionary

-

- The ContactAddress dictionary is a reusable component that is used to capture addresses - within the Contact dictionary. -

-
-
boolean pref
-
- This attribute indicates whether this instance of the ContactAddress is the preferred, - or primary, value for the contact. By default, the value is false. -
-
DOMString type
-
- This attribute contains the type of address this object is representing (e.g. work, - home, premises, etc). -
-
DOMString streetAddress
-
- This attribute contains the street address corresponding to this ContactAddress. -
-
DOMString locality
-
- This attribute contains the locality (or city) name corresponding to this ContactAddress. -
-
DOMString region
-
- This attribute contains the region (or state/province) name corresponding to this ContactAddress. -
-
DOMString postalCode
-
- This attribute contains the postal code (or zip) corresponding to this ContactAddress. -
-
DOMString country
-
- This attribute contains the country name corresponding to this ContactAddress. -
-
-
- -
-

The ContactOrganization dictionary

-

- The ContactOrganization dictionary is a reusable component that is used to support contact - organisations within the Contact dictionary. -

-
-
boolean pref
-
- This attribute indicates whether this instance of the ContactOrganization is the preferred, or - primary, value for the contact. By default, the value is false. -
-
DOMString type
-
- This attribute contains the type of organisation this object is representing. -
-
DOMString name
-
- The name of the organisation. -
-
DOMString department
-
- The department within which this Contact works. -
-
DOMString title
-
- The job title that the Contact holds inside this organisation. -
-
-
-
-

The ContactError dictionary

-

- If the contact service encounters an error then it MUST return an error - (through postFailure()) using the ContactError dictionary. -

-
-
DOMString message
-
A message describing the error.
-
-
-
-

Extended Contact Properties and Parameters

-

- A contact service MAY extend the dictionaries described in in the Data Formats section with - additional fields. If providing an extended field, a contact service MUST prefix its name - with X (U+0058 LATIN CAPITAL LETTER X) or use a vendor-specific prefix. -

-
-
- - diff -r 52acb4877e86 -r 518970294839 contacts/WD1/Overview.html --- a/contacts/WD1/Overview.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,2356 +0,0 @@ - - - - - - Contacts API - - - - - -

W3C

Contacts API

W3C Working Draft 01 July 2010

This version:
http://www.w3.org/TR/2010/WD-contacts-api-20100701/
Latest published version:
http://www.w3.org/TR/contacts-api/
Latest editor's draft:
http://dev.w3.org/2009/dap/contacts/
Previous version:
http://www.w3.org/TR/2010/WD-contacts-api-20100121/
Editor:
Richard Tibbett, Invited Expert

-

Abstract

-

- The Contacts API defines the high-level interfaces required to provide access to a user's unified address book. -

-

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

-

- This document represents the early consensus of the group on the scope and features of the proposed Contacts API. Issues and - editors note in the document highlight some of the points on which the group is still working and would particularly like to get - feedback. -

-

This document was published by the Device APIs and Policy Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

- -

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

-

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

- -

- This specification defines conformance criteria that apply to a single product: the user agent that implements the - interfaces that it contains. -

-

- 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. -

-
-
-

2. - Introduction -

This section is non-normative.

-

- Every operating system and a large number of web-based service providers have different ways of representing address book - information. Most users are required to maintain a plurality of contact lists which leads to multiple copies of address book data. - The multiplicity of address books that a user is required to maintain often leads to disjointed and inconsistent information being - stored across a user's address book providers. -

-

- Providing address book information to these service providers means handing over all of your data and trusting these providers with - the security and privacy of storing and sharing of your information. When sharing this data with 3rd parties users are, more often - than not, required to hand over access to their whole address book. Users are implicitly required to trust 3rd parties with all of - their data when, in reality, the user may only wish, or need, to share a subset of their address book information so that an - application can fulfill its purpose. -

-

- This specification defines the concept of a user's unified address book - where address book data may be sourced from a - plurality of sources - both online and locally. This specification then defines the interfaces on which 3rd party applications can - access a user's unified address book; with explicit user permission and filtering. The focus of this data sharing is on making - the user aware of the data that they will share and putting them at the centre of the data sharing process; free to select both the - extent to which they share their address book information and the ability to restrict which pieces of information related to which - contact gets shared. -

-

- The API itself is agnostic of any underlying address book sources and storage. A conforming implementation is required to implement - all fields defined in this specification. -

-
-

2.1 - Usage Examples -

-

- The following code extracts illustrate how to search, add, remove and update contact information in a given address book: -

-
-

- Searching for matching contacts. -

-
-
function successContactFindCallback(contacts) {
-    // do something with resulting contact objects
-    for (var i in contacts) alert(contacts[i].displayName);
-    // ...
-}
-
-function generalErrorCB(error) {
-    // do something with resulting errors
-    alert(error.code);
-    // ...
-}
-
-// Perform an address book search. Obtain the 'name' and 'emails' properties 
-// and initially filter the list to Contact records containing 'Bob':
-navigator.service.contacts.find(['name', 'emails'],
-                                successContactFindCallback, 
-                                generalErrorCB,
-                                {filter: 'Bob'}
-                               );
-
-

- Creating a new contact. -

-
-
// Create new contact  
-var myContact = navigator.service.contacts.create({displayName: 'Robert'}});
-
-// Add additional contact attributes as required...
-// myContact.nicknames.push('bobby');
-
-

- Saving a new contact in the underlying addressbook. -

-
-
// previous example follow-on...
-
-function successContactCallback(contact) {
-    // do something with resulting contact object
-    alert(contact.displayName);
-    // ...
-}
-
-// Save new contact
-myContact.save(successContactCallback, generalErrorCB);
-
-

- Editing an existing contact. -

-
-
// previous example follow-on...
-
-// e.g. add a new phone number
-myContact.phoneNumbers.push({type: 'home', value: '+440000000002'});
-
-// Update existing contact
-myContact.save(successContactCallback, generalErrorCB);
-
-

- Removing an existing contact. -

-
-
// previous example follow-on...
-
-// Remove existing contact
-myContact.remove(successContactCallback, generalErrorCB);
-
-
-
-

3. - Security and Privacy Considerations -

-

- The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made - to this API to reflect requirements or support for privacy-related functionality. -

-

- The API defined in this specification can be used to create, find, save and remove contact information from a user's address - book(s). All API methods disclose information related to a user's contacts such as their phone number(s), email address(es) and - other personally identifying information. The distribution of this information could potentially compromise the user's privacy. - A conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism - should ensure that no contact information is creatable, retrivable, updateable or removable without the user's express - permission. -

-
-

3.1 - Privacy considerations for implementors of the Contacts API -

-

- A user agent must not create, find, save or delete contact information to Web sites without the express permission of the - user. A user agent must acquire permission through a user interface, unless they have prearranged trust relationships with - users, as described below. The user interface must include the URI of the document origin, as defined in [HTML5]. Those - permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond - the time when the browsing context, as defined in [HTML5], is navigated to another URL) must be revocable and a user - agent must respect revoked permissions. -

-

- Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same - Web site to access other methods provided by this API, or to access the same method with a different set of arguments, as part of - the same permission context. If a user has expressed permission for an implementation to, e.g. find a set of existing contacts, - the implementation must seek the user's express permission if and when any additional create, find, save or remove function - is called on this API. -

-

- A user agent may have prearranged trust relationships that do not require such user interfaces. For example, while a Web - browser will present a user interface when a Web site performs an address book request, a Widget Runtime may have a prearranged, - delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to - authorize the creation, retrieval, update and/or removal of contact information. -

-
-
-

3.2 - Privacy considerations for recipients of contact information -

-

- Recipients must only request contact information when necessary. Recipients must only use the contact information for the task - for which it was provided to them. Recipients must dispose of contact information once that task is completed, unless expressly - permitted to retain it by the user. Recipients must also take measures to protect this information against unauthorized access. - If contact information is stored, users should be allowed to update and delete this information. -

-

- The recipient of contact information must not retransmit the contact information without the user's express permission. Care - should be taken when retransmitting and use of encryption is encouraged. -

-

- Recipients must clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the - collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access, - update and delete the data, and any other choices that users have with respect to the data. This disclosure must include an - explanation of any exceptions to the guidelines listed above. -

-
-
-

3.3 - Additional implementation considerations -

This section is non-normative.

-

- Further to the requirements listed in the previous section, implementors of the Contacts API are also advised to consider the - following aspects that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant - permission to the User Agent to disclose their contacts to Web sites. In other cases, the content hosted at a certain URL changes - in such a way that the previously granted contact permissions no longer apply as far as the user is concerned. Or the users might - simply change their minds. -

-

- Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures are an - implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are - advised to enable user awareness of contact sharing, and to provide easy access to interfaces that enable revocation of - permissions. -

-
-
-
-

4. - API Description -

-
-

4.1 - ServiceContacts interface -

-

- The ServiceContacts interface is exposed on the navigator.service - object, as defined in [CORE-DEVICE]. -

-
Service implements ServiceContacts;
-   -
-
[NoInterfaceObject]
-interface ServiceContacts {
-    readonly attribute Contacts contacts;
-};
-

4.1.1 Attributes

contacts of type Contacts, readonly
- The root node from which the contacts functionality can be accessed. -
No exceptions.
-
-
-

4.2 - Contacts interface -

-

- The Contacts interface exposes a database collecting contacts information, such that they may be created, found, read, - updated, and deleted. -

-

- Multiple address books, taken from different sources, can be represented within this unified address book interface. Contacts - from different sources can be distinguished using the serviceId field.. In addition, multiple address books can be displayed - by filtering on the required serviceId value via the Contacts find() function. -

-

- Equally, multiple contact groups can be represented within this unified address book by specifying consistent tags value(s) as part of individual Contact objects. Multiple contact groups can be displayed by filtering on the - required tags value(s) via the Contacts find() function. -

-
[NoInterfaceObject]
-interface Contacts {
-    Contact   create (in ContactProperties attributes);
-    PendingOp find (in DOMString[] fields, in ContactFindSuccessCB successCB, in optional ContactErrorCB? errorCB, in optional ContactFindOptions? options);
-};
-

4.2.1 Methods

create
- Create a new Contact object. -

- This method takes one argument. When called, it returns a Contact object. -

-

- The newly created Contact object must not be stored in the user's address book as a result of - calling this method. The Contact save() method must be called on the response of this method to store the new Contact object in the user's address book. -

- -
ParameterTypeNullableOptionalDescription
attributesContactProperties - The attributes to assign to the resulting object. -
No exceptions.
Return type: Contact
find
-

- Find contacts in the address book according to the find contacts process detailed below. -

-

- This method takes two, three or four arguments. When called, it immediately returns a PendingOp object , as - defined in [CORE-DEVICE], and then asynchronously starts a find contacts process defined as follows: -

-
    -
  1. - If a current find(), save() or remove() operation is pending a response, invoke the errorCB with a PENDING_OPERATION_ERROR code. -
  2. -
  3. - Search for contacts in the address book according to the rules defined in Contact Search Processing. -
  4. -
  5. - If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a - non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument. -
  6. -
- -
ParameterTypeNullableOptionalDescription
fieldsDOMString[] - The search qualifier. -
successCBContactFindSuccessCB - Function to call when the asynchronous operation completes -
errorCBContactErrorCB - Function to call when the asynchronous operation fails. -
optionsContactFindOptions - The options to apply to the output of this method. -
No exceptions.
Return type: PendingOp
-
-
-

4.3 - Contact interface -

-

- The Contact interface captures a single contact item. This interface extends ContactProperties attributes. -

-

- All Contact objects must include all attributes supported by the implementation, - regardless of whether these attributes have been assigned a non-null value or a null value. -

-

- If a supported attribute has not been assigned a value by the user and/or implementation, then this attribute must still be - present in the resulting Contact object and must have a value of null. -

-
[NoInterfaceObject]
-interface Contact : ContactProperties {
-    readonly attribute DOMString  id;
-             attribute DOMString? serviceId;
-    Contact   clone ();
-    PendingOp save (in ContactSuccessCB successCB, in optional ContactErrorCB? errorCB);
-    PendingOp remove (in ContactSuccessCB successCB, in optional ContactErrorCB? errorCB);
-};
-

4.3.1 Attributes

id of type DOMString, readonly
-

- A globally unique identifier for the given Contact object. Each Contact referenced from - Contacts must include a non-empty id value. -

-

- An implementation must maintain this globally unique resource identifier when a Contact is added to, or present within, an - Address Book. -

-

- See [[POCO-SCHEMA] Section 7.2.1. id] for additional definition of this attribute. -

-
No exceptions.
serviceId of type DOMString, nullable
-

- Can we remove this attribute? Does a web application need to know the storage location of a Contact record?
-
- This directly relates to ISSUE-43 and discussion thread http://lists.w3.org/Archives/Public/public-device-apis/2010Jun/0248.html. -

-

- An identifier that may be provided that represents the address book owner of the current contact object. -

-

- This attribute enables multiple address book sources to be tagged and filtered on Contact objects. -

-

- The following constants are defined for use in the serviceId attribute for addressing non-networked storage - databases: -

-
 
-'uicc', 'device'.
-
-

- A conforming implementation must define a default service identifier on which to store Contact objects that have not yet been assigned to any storage database. The - default service identifier will then be used in the Contact save() operation when a serviceId is not recognized or when the serviceId attribute is - null. -

-

- For all other Contacts sources, it is recommended that the serviceId attribute is assigned as a URI. -

-
No exceptions.

4.3.2 Methods

clone
-

- Create a deep clone copy of the current object minus the current object's id attribute. -

-

- The resulting object must be provided with a newly generated id attribute to distiguish the cloned object from the original object. -

-
No parameters.
No exceptions.
Return type: Contact
remove
-

- Remove the current contact from the address book. -

-

- In the case that the current id attribute is null and this method is invoked, a ContactErrorCB must be triggered as part of the remove contact - process. This error must consist of a ContactError object with a code of NOT_FOUND_ERROR. -

-

- This method takes one or two arguments. When called, it immediately returns a PendingOp object, as defined in - [CORE-DEVICE], and then asynchronously starts a remove contact process defined as follows: -

-
    -
  1. - If a current find(), save() or remove() operation is pending a response, invoke the errorCB with a PENDING_OPERATION_ERROR code. -
  2. -
  3. - Remove the current object from Contacts. -
  4. -
  5. - If the removal of the current object from Contacts was successful, set the current object's Contact.id value to null and the current object's Contact.serviceId value to null. -
  6. -
  7. - If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a - non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument. -
  8. -
- -
ParameterTypeNullableOptionalDescription
successCBContactSuccessCB - Function to call when the asynchronous operation completes -
errorCBContactErrorCB - Function to call when the asynchronous operation fails. -
No exceptions.
Return type: PendingOp
save
-

- Add or update (as appropriate) the current Contact object to the Contacts. -

-

- This method takes one or two arguments. When called, it immediately returns a PendingOp object , as defined in - [CORE-DEVICE], and then asynchronously starts a save contact process defined as follows: -

-
    -
  1. - If a current find(), save() or remove() operation is pending a response, invoke the errorCB with a PENDING_OPERATION_ERROR code. -
  2. -
  3. - If the current Contact.serviceId value is not recognized in Contacts or a Contact.serviceId value has not been set, create and set a new Contact.serviceId value to the default service identifier. -
  4. -
  5. - If the current Contact.id value is not recognized in Contacts or a Contact.id value has not been set, create and set a new Contact.id value and add the current object as a new object to Contacts. -
  6. -
  7. - If the Contact.id already exists in Contacts then update the existing object in Contacts. -
  8. -
  9. - If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a - non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument. -
  10. -
- -
ParameterTypeNullableOptionalDescription
successCBContactSuccessCB - Function to call when the asynchronous operation completes -
errorCBContactErrorCB - Function to call when the asynchronous operation fails. -
No exceptions.
Return type: PendingOp
-
-
-

4.4 - ContactProperties interface -

-

- The use of Portable Contacts schema as the format for contacts is subject to further discussions in the group. -

-

- The ContactProperties interface captures the settable properties of a contact. - All properties included in this interface have a corresponding definition in [POCO-SCHEMA]. -

-

- In addition to the properties defined in this interface, a conforming implementation must support both the Singular and Plural - OpenSocial fields defined in [POCO-SCHEMA]. -

-

- The inclusion of OpenSocial fields in the paragraph above needs further explanation, particularly in relation to contact database - searching and sorting. -

-
[NoInterfaceObject]
-interface ContactProperties {
-    attribute DOMString             displayName;
-    attribute ContactName           name;
-    attribute DOMString             nickname;
-    attribute ContactField[]        phoneNumbers;
-    attribute ContactField[]        emails;
-    attribute ContactAddress[]      addresses;
-    attribute ContactField[]        ims;
-    attribute ContactOrganization[] organizations;
-    attribute DOMString             published;
-    attribute DOMString             updated;
-    attribute DOMString             birthday;
-    attribute DOMString             anniversary;
-    attribute DOMString             gender;
-    attribute DOMString             note;
-    attribute DOMString             preferredUsername;
-    attribute ContactField[]        photos;
-    attribute ContactField[]        tags;
-    attribute ContactField[]        relationships;
-    attribute ContactField[]        urls;
-    attribute ContactAccount[]      accounts;
-    attribute DOMString             utcOffset;
-    attribute DOMString             connected;
-};
-

4.4.1 Attributes

accounts of type array of ContactAccount
-

- See [[POCO-SCHEMA] Section 7.2.2. accounts]. -

-
No exceptions.
addresses of type array of ContactAddress
-

- See [[POCO-SCHEMA] Section 7.2.2. addresses]. -

-
No exceptions.
anniversary of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. anniversary]. -

-
No exceptions.
birthday of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. birthday]. -

-
No exceptions.
connected of type DOMString
-

- Ignore this [POCO-SCHEMA] attribute? -

-

- See [[POCO-SCHEMA] Section 7.2.1. connected]. -

-
No exceptions.
displayName of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. displayName]. -

-
No exceptions.
emails of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. emails]. -

-
No exceptions.
gender of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. gender]. -

-
No exceptions.
ims of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. ims]. -

-
No exceptions.
name of type ContactName
-

- See [[POCO-SCHEMA] Section 7.2.1. name]. -

-
No exceptions.
nickname of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. nickname]. -

-
No exceptions.
note of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. note]. -

-
No exceptions.
organizations of type array of ContactOrganization
-

- See [[POCO-SCHEMA] Section 7.2.2. organizations]. -

-
No exceptions.
phoneNumbers of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. phoneNumbers]. -

-
No exceptions.
photos of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. photos]. -

-
No exceptions.
preferredUsername of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. preferredUsername]. -

-
No exceptions.
published of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. published]. -

-
No exceptions.
relationships of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. relationships]. -

-
No exceptions.
tags of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. tags]. -

-
No exceptions.
updated of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. updated]. -

-
No exceptions.
urls of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. urls]. -

-
No exceptions.
utcOffset of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. utcOffset]. -

-
No exceptions.
-
-
-

4.5 - ContactName interface -

-

- The ContactName interface describes a contact's name. -

-
[NoInterfaceObject]
-interface ContactName {
-    attribute DOMString formatted;
-    attribute DOMString familyName;
-    attribute DOMString givenName;
-    attribute DOMString middleName;
-    attribute DOMString honorificPrefix;
-    attribute DOMString honorificSuffix;
-};
-

4.5.1 Attributes

familyName of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. familyName]. -

-
No exceptions.
formatted of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. formatted]. -

-
No exceptions.
givenName of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. givenName]. -

-
No exceptions.
honorificPrefix of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. honorificPrefix]. -

-
No exceptions.
honorificSuffix of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. honorificSuffix]. -

-
No exceptions.
middleName of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. middleName]. -

-
No exceptions.
-
-
-

4.6 - ContactField interface -

-

- The ContactField interface is a reusable component that is used to support contact fields within the ContactProperties interface. -

-
[NoInterfaceObject]
-interface ContactField {
-    attribute DOMString type;
-    attribute DOMString value;
-    attribute boolean   primary;
-};
-

4.6.1 Attributes

primary of type boolean
-

- See [[POCO-SCHEMA]] Section 7.2.2. primary]. -

-
No exceptions.
type of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.2.2. type]. -

-
No exceptions.
value of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.2.2. value]. -

-
No exceptions.
-
-
-

4.7 - ContactAddress interface -

-

- The ContactAddress interface is a reusable component that is used to support contact addresses within the ContactProperties interface. -

-
[NoInterfaceObject]
-interface ContactAddress {
-    attribute DOMString formatted;
-    attribute DOMString streetAddress;
-    attribute DOMString locality;
-    attribute DOMString region;
-    attribute DOMString postalCode;
-    attribute DOMString country;
-};
-

4.7.1 Attributes

country of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. country]. -

-
No exceptions.
formatted of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. formatted]. -

-
No exceptions.
locality of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. locality]. -

-
No exceptions.
postalCode of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. postalCode]. -

-
No exceptions.
region of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. region]. -

-
No exceptions.
streetAddress of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. streetAddress]. -

-
No exceptions.
-
-
-

4.8 - ContactOrganization interface -

-

- The ContactOrganization interface is a reusable component that is used to support contact organizations within the ContactProperties interface. -

-
[NoInterfaceObject]
-interface ContactOrganization {
-    attribute DOMString name;
-    attribute DOMString department;
-    attribute DOMString title;
-    attribute DOMString startDate;
-    attribute DOMString endDate;
-    attribute DOMString location;
-    attribute DOMString description;
-};
-

4.8.1 Attributes

department of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. department]. -

-
No exceptions.
description of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. description]. -

-
No exceptions.
endDate of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. endDate]. -

-
No exceptions.
location of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. location]. -

-
No exceptions.
name of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. name]. -

-
No exceptions.
startDate of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. startDate]. -

-
No exceptions.
title of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. title]. -

-
No exceptions.
-
-
-

4.9 - ContactAccount interface -

-

- The ContactAccount interface is a reusable component that is used to support contact accounts within the ContactProperties interface. -

-
[NoInterfaceObject]
-interface ContactAccount {
-    attribute DOMString domain;
-    attribute DOMString username;
-    attribute DOMString userid;
-};
-

4.9.1 Attributes

domain of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.6. domain]. -

-
No exceptions.
userid of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.6. userid]. -

-
No exceptions.
username of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.6. username]. -

-
No exceptions.
-
-
-

4.10 - ContactFindOptions interface -

-

- The ContactFindOptions interface describes the options that can be applied to - contact searching. When a ContactFindOptions parameter is provided to the Contacts find() operation, it should be processed according to the provisions detailed in Options Processing. -

-
[NoInterfaceObject]
-interface ContactFindOptions {
-    attribute String?         filter;
-    attribute boolean?        multiple;
-    attribute unsigned short? limit;
-    attribute DOMString       updatedSince;
-};
-

4.10.1 Attributes

filter of type String, nullable
- A DOMString-based search filter with which to search and intially filter the Contacts database. -
No exceptions.
limit of type unsigned short, nullable
-

- The maximum number of results to return from the contacts search. -

-

- This parameter only applies in the case that the associated multiple attribute is equal to true. -

-

- If no value is provided, the search will return all Contact object results. -

-
No exceptions.
multiple of type boolean, nullable
- A boolean value to indicate whether multiple Contact objects are returnable as part of the associated Contacts find() operation. -
No exceptions.
updatedSince of type DOMString
-

- Return only contact records that have been updated on or after the given time, specified as an xs:dateTime. -

-

- This filter is based on the updated field as defined in ContactProperties. -

-
No exceptions.
-
-
-

4.11 - ContactFindSuccessCB interface -

- -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactFindSuccessCB {
-    void onSuccess (in Contact[] contactObjs);
-};
-

4.11.1 Methods

onSuccess
- - -
ParameterTypeNullableOptionalDescription
contactObjsContact[] - The Contact objects resulting from the given Contacts find() method. Contacts find() -
No exceptions.
Return type: void
-
-
-

4.12 - ContactSuccessCB interface -

- -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactSuccessCB {
-    void onSuccess (in Contact contactObj);
-};
-

4.12.1 Methods

onSuccess
- - -
ParameterTypeNullableOptionalDescription
contactObjContact - The Contact object resulting from the given Contact save() or Contact remove() method. -
No exceptions.
Return type: void
-
-
-

4.13 - ContactErrorCB interface -

- -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactErrorCB {
-    void onError (in ContactError error);
-};
-

4.13.1 Methods

onError
- - -
ParameterTypeNullableOptionalDescription
errorContactError - The Contact API related error object. -
No exceptions.
Return type: void
-
-
-

4.14 - ContactError interface -

-

- The ContactError interface encapsulates all errors in the manipulation of Contact objects in the Contacts API. -

-
[NoInterfaceObject]
-interface ContactError {
-    const unsigned short UNKNOWN_ERROR = 0;
-    const unsigned short INVALID_ARGUMENT_ERROR = 1;
-    const unsigned short NOT_FOUND_ERROR = 2;
-    const unsigned short TIMEOUT_ERROR = 3;
-    const unsigned short PENDING_OPERATION_ERROR = 4;
-    const unsigned short IO_ERROR = 5;
-    const unsigned short NOT_SUPPORTED_ERROR = 6;
-    const unsigned short PERMISSION_DENIED_ERROR = 20;
-    readonly attribute unsigned short code;
-};
-

4.14.1 Attributes

code of type unsigned short, readonly
- An error code assigned by an implementation when an error has occurred in Contacts API processing. -
No exceptions.

4.14.2 Constants

INVALID_ARGUMENT_ERROR of type unsigned short
- An invalid parameter was provided when the requested method was invoked. -
IO_ERROR of type unsigned short
- An error occurred in communication with the underlying implementation that meant the requested method could not complete. -
NOT_FOUND_ERROR of type unsigned short
- If no response information can be provided from the requested method. -
NOT_SUPPORTED_ERROR of type unsigned short
- The requested method is not supported by the current implementation. -
PENDING_OPERATION_ERROR of type unsigned short
- If the user agent is currently waiting for a callback on a current find(), save() or remove() operation, as defined in - this specification. -
PERMISSION_DENIED_ERROR of type unsigned short
- Access to the requested method was denied at the implementation or by the user. -
TIMEOUT_ERROR of type unsigned short
- The requested method timed out before it could be completed. -
UNKNOWN_ERROR of type unsigned short
- An unknown error occurred. -
-
-
- -
-

5. - Contact Search Processing -

-

- The Contacts find() method provides an operation to search for one of more Contact objects within the Contacts database. -

-
-

5.1 - Search Qualifiers -

-

- The search qualifier provides an application with a way to request the specific subset of ContactProperties it wishes to obtain in any resulting successful callback. - The search qualifier is deployed to minimize the data that needs to be shared with an application in order to let that - application fulfill its function on behalf of the user. The search qualifier is included within a Contacts find() operation as the filter parameter. -

-

- A search qualifier must be specified from a requesting application as a part of any Contacts find() operation. -

-

- If the search qualifier provided is of zero-length then the current Contacts find() operation must not return any ContactProperties within any resulting Contact object(s). -

-

- In the case that the search qualifier provided is of non-zero-length then the current Contacts find() operation must return only the matching ContactProperties within any resulting Contact object(s). -

-

- If a specific search qualifier element provided, or filter[x], does not match any well-known ContactProperties attribute, filter[x] should be ignored when - executing the current Contacts find() operation. -

-
-

5.1.1 - Complex Search Qualifiers -

-

- Certain ContactProperties attributes can be considered complex by the fact that - the information they contain is available only through child DOMString-based attributes of a complex Object object. -

-

- In such cases, a requesting application must be able to request both the full complex ContactProperties attribute and also be able to request individual parts - of a complex ContactProperties attribute in the search qualifier provided to a - Contacts find() operation. -

-

- For example, the name attribute of ContactProperties is defined to be of complex type ContactName. Therefore, a requesting application may request either the full - complex attribute (i.e. name) or specific individual attributes of this complex attribute (i.e. - name.formatted, name.familyName, name.givenName, name.middleName, - name.honorificPrefix, name.honorificSuffix) as part of a Contacts find() operation's search qualifier. -

-

- In the case that a complex ContactProperties attribute is defined as a sequence or array of complex - objects, specific individual attributes can be referenced by using the complex attribute name, a dot (.) character - and the individual attribute to be retrieved. -

-

- For example, the addresses attribute of ContactProperties allows multiple ContactAddress objects to be defined. To request individual attributes of - this complex attribute an application would request e.g. addresses.locality, addresses.region, etc. -

-
-
-

5.1.2 - Search Qualifier Example -

-

- The following Contact search is initiated: -

-
navigator.service.contacts.find(['emails.value', 'name', 'friends'],
-                                function(contacts) { 
-                                   for(i in contacts) {
-                                      for(j in contacts[i].emails)
-                                         alert(contacts[i].emails[j]);
-                                   }
-                                });
-

- The above example logically implies: -

-
    -
  1. - Return only the valid ContactProperties requested in the provided search qualifier - (name, emails.value - friends is not a valid ContactProperties attribute so ignore this element). -
  2. -
-
-
-
-

5.2 - Options Processing -

-
-

5.2.1 - Search Cardinality -

-

- By default, the Contacts find() operation must return either an empty sequence or a single Contact object, accessible as part of the sequence returned in the ContactFindSuccessCB callback function. -

-

- If a ContactFindOptions object is provided to the Contacts find() operation and its multiple attribute is set to true, the Contacts find() operation must return either an empty sequence, a single Contact object or [X] number of Contact objects, accessible as part of the sequence returned in the ContactFindSuccessCB callback function. -

-

- An implementation must specify a suitable integer-based upper cardinality limit to limit the maximum number of - Contact objects that may be returned in the case that the multiple flag is true and the - limit flag is out of bounds. -

-

- If a ContactFindOptions object is provided to the Contacts find() operation and its limit attribute is greater than zero and less than or - equal to the implementation's upper cardinality limit, then [X] must be set to the provided - limit value. -

-

- The limit attribute is out of bounds if a ContactFindOptions object is provided to the Contacts find() operation and its limit attribute is less than or equal to zero or greater - than the implementation's upper cardinality limit. In this case [X] must be set to the - implementation's upper cardinality limit. -

-
-
-

5.2.2 - Search Sorting -

-

- The Contacts find() operation must return successful callback results according to the sorting guidelines - defined in this section. -

-

- A search weight is a numeric value defined for each attribute in a Contact object. A lower value denotes a higher placing in the ultimate sorting of - Contacts find() results. Search weights for each ContactProperties field are defined in Appendix B. -

-

- For example, if a search filter of 'Bob' matches to name.givenName in Object A and to - displayName in Object B, Object B will be the first result object returned from the successCB of the given Contacts find() operation, followed by Object A. -

-

- Include UNICODE guidelines for intra-attribute sorting of results (where multiple Contact objects match on the same - attribute)... [UNICODE] DUCET -

-
-
-

5.2.3 - Search Filters -

-

- A search filter may be specified from a requesting web application to initially filter the Contacts database to a - more specific set of Contact objects in which it is interested. The search filter is included as - the filter attribute of the ContactFindOptions object provided to a Contacts find() operation. -

-

- A search filter is used to search all the fields of a Contacts database and represents the logical union, or , of - provided values that are matched therein. -

-

- All contact searching must apply a loose-matching policy to the search filter provided. If a ContactProperties attribute being searched in a Contact object, stored within the Contacts database, is a partial value match of the input filter value, that - Contact object must be returned as part of the resulting ContactFindSuccessCB. -

-

- A partial value match refers to both syntactic and semantic partial matching of an input filter value with a - corresponding value in the address book and denotes that a corresponding match was found in the address book that begins with, - contains or ends with the value of the input filter value, or any variation thereof. -

-

- Comparing two strings in a compatibility caseless manner means using the Unicode compatibility caseless - match operation to compare the two strings. [UNICODE] -

-

- A partial value match must use the compatibility caseless manner in which to match against corresponding values - in the Contacts database. -

-

-   -

-

- The rules for processing search filters is defined below and is always provided with a filter parameter, representing the filter attribute of the ContactFindOptions parameter provided within the current Contacts find() operation. -

-
-
-   -
-
- Let contactsets be initially the set of all known contacts in the Contacts database. -

- Let contactsresult be initially an empty Object object. -

-
-
- If filter is a DOMString object -
-
-
    -
  1. - Let contactset be the next enumerable Object in contactsets. If there is no next enumerable Object, go to step 5. -
  2. -
  3. - Let partialMatchFound be the result of applying the partial matching algorithm, - providing filter and contactset as inputs. -
  4. -
  5. - If partialMatchFound is true, add contactset to contactsresult. -
  6. -
  7. - Go to step 1. -
  8. -
  9. - Sort contactsresult according to the guidelines in Search Sorting. -
  10. -
  11. - Return contactsresult. -
  12. -
-
-
- If filter is another native object type -
-
-

- Return contactsets. -

-
-
-

-   -

-

- The partial matching algorithm is defined below and is always provided with a filter parameter, representing the input string to compare; and a contactset parameter, representing an individual Contact object: -

-
-
-   -
-
- Let hasPartialMatch be initially set to false. -
-
- If contactset is an Object object -
-
-
    -
  1. - Let elementvalue be the String value of the next enumerable property in contactset. If there are no more enumerable properties, go to step 5. -
  2. -
  3. - Let hasPartialMatch be the boolean result for the comparison of filter with elementvalue in a compatibility caseless manner and with a partial value match - policy applied to both sides of the comparison operation. -
  4. -
  5. - If hasPartialMatch is true, go to step 5. -
  6. -
  7. - Go to step 1. -
  8. -
  9. - Return hasPartialMatch. -
  10. -
-
-
- If contactset is another native object type -
-
-

- Return false. -

-
-
-

-   -

-
-
5.2.3.1 - Search Filter Example -
-

- The following Contact search is initiated: -

-
navigator.service.contacts.find(['name', 'addresses.locality', 'addresses.country', 'phoneNumbers', 'emails'],
-                                function(contacts) { 
-                                   for(x in contacts) alert(contacts[x].name); 
-                                },
-                                {
-                                  filter: 'Robert'
-                                });
-

- The above example logically implies: -

-
    -
  1. - Using ECMA-262 3rd Edition regular expression syntax and psuedo-code, the search filter provided can be represented - as: -
          ( displayName = /∧.*Robert.*$/i ) ∪ ( name.formatted = /∧.*Robert.*$/i ) ∪ ( nickname = /∧.*Robert.*$/i ) 
    -        ∪ ( tags.value = /∧.*Robert.*$/i ) ∪ ( phoneNumbers.value = /∧.*Robert.*$/i )  ∪ ( addresses.formatted = /∧.*Robert.*$/i ) 
    -          ∪ ... etc for all contact attributes and properties ...
    -
    -
  2. -
  3. - Return only the valid ContactProperties requested in the provided search qualifier - (name, addresses.locality, addresses.country, phoneNumbers, - emails) and only for the Contact objects returned from the rules for processing search filters - with the search filter derived in step 1 provided as the filter input parameter. -
  4. -
-
-
-
-
-
-

A. - User Interaction Guidelines -

This section is non-normative.

-

- This specification is primarily intended to provide the user with the ability to view and control the contact information that may - be shared, saved or removed from their unified address book. This annex provides some examples of a conformant user experience that - this specification enables. -

-
-

A.1 - Sharing Contact Information -

-

- A website requests access to a user's address book with the following code: -

-
function successContactFindCallback(contacts) {
-    // do something with resulting contact objects
-    for (var i in contacts) alert(contacts[i].name);
-    // ...
-}
-
-function generalErrorCB(error) {
-    // do something with resulting errors
-    alert(error.code);
-    // ...
-}
-
-// Perform an address book search. Obtain the 'name' and 'emails' properties 
-// and initially filter the list to Contact records containing 'Bob':
-navigator.service.contacts.find(['name', 'emails'],
-                                successContactFindCallback, 
-                                generalErrorCB,
-                                {filter: 'Bob'}
-                               );
-

- As a result of executing this code, the user agent may provide a non-blocking contact search notification as - follows: -

-

- Contact Search Notification
- (View as PNG) -

-

- If an additional find(), save() or remove() operation is called by the current web application before the user has clicked - 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR. -

-

- If the user clicks 'Cancel', the ContactErrorCB defined for the find() operation will be invoked with an error - code of PERMISSION_DENIED_ERROR. -

-

- If the user clicks 'Select', the user agent may provide a contact picker, utilising all of the - parameters provided in the find() operation as follows: -

-

- Contact Picker
- (View as PNG) -

-

- In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select - one or more contacts (as appropriate) from the user interface. -

-

- If an additional find(), save() or remove() operation is called by the current web application before the user has clicked - 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR. -

-

- If the user clicks 'Cancel', the ContactErrorCB associated to the current find() operation will be invoked with - an error code of PERMISSION_DENIED_ERROR. -

-

- If the user clicks 'Select', the ContactFindSuccessCB associated to the current find() operation will be - invoked with the contact information selected by the user provided as the only parameter. -

-

- Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily - be able to review and revoke permissions to web applications at a later date. -

-

- Include permission review/revocation mockup? -

-
-
-

A.2 - Contact Writebacks -

-
-

A.2.1 - Saving a Contact to the Address Book -

-

- Include Contact creation/modification writeback mockup. -

-
-
-

A.2.2 - Removing a Contact from the Address Book -

-

- Include Contact deletion writeback mockup. -

-
-
-
-
-

B. - Search Weights -

-

- The following table defines the search weight values for each search qualifier provided in this specification. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Search Qualifier - - Search Weight -
- displayName - - 1 -
- name.formatted - - 2 -
- nickname - - 3 -
- tags.value - - 4 -
- phoneNumbers.value - - 5 -
- addresses.formatted - - 6 -
- organizations.name - - 7 -
- emails.value - - 8 -
- ims.value - - 9 -
- preferredUsername - - 10 -
- name.familyName - - 11 -
- name.givenName - - 12 -
- name.middleName - - 13 -
- addresses.country - - 14 -
- addresses.region - - 15 -
- addresses.streetAddress - - 16 -
- addresses.locality - - 17 -
- addresses.postalCode - - 18 -
- organizations.department - - 19 -
- organizations.title - - 20 -
- organizations.startDate - - 21 -
- organizations.endDate - - 22 -
- organizations.location - - 23 -
- organizations.description - - 24 -
- accounts.domain - - 25 -
- accounts.userid - - 26 -
- accounts.username - - 27 -
- photos.value - - 28 -
- relationships.value - - 29 -
- urls.value - - 30 -
- gender - - 31 -
- birthday - - 32 -
- anniversary - - 33 -
- published - - 34 -
- updated - - 35 -
- utcOffset - - 36 -
- notes - - 37 -
- name.honorificPrefix - - 38 -
- name.honorificSuffix - - 39 -
- phoneNumbers.type - - 40 -
- addresses.type - - 41 -
- emails.type - - 42 -
- ims.type - - 43 -
- tags.type - - 44 -
- photos.type - - 45 -
- relationships.type - - 46 -
- urls.type - - 47 -
- connected - - 48 -
- id - - 49 -
- phoneNumbers.primary - - n/a (boolean attribute) -
- addresses.primary - - n/a (boolean attribute) -
- emails.primary - - n/a (boolean attribute) -
- ims.primary - - n/a (boolean attribute) -
- tags.primary - - n/a (boolean attribute) -
- photos.primary - - n/a (boolean attribute) -
- relationships.primary - - n/a (boolean attribute) -
- urls.primary - - n/a (boolean attribute) -
- phoneNumbers - - n/a (complex attribute) -
- addresses - - n/a (complex attribute) -
- emails - - n/a (complex attribute) -
- ims - - n/a (complex attribute) -
- photos - - n/a (complex attribute) -
- tags - - n/a (complex attribute) -
- relationships - - n/a (complex attribute) -
- urls - - n/a (complex attribute) -
-
-
-

C. References

C.1 Normative references

[CORE-DEVICE]
Robin Berjon. Core Device Interfaces. 02 December 2009. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/device/ -
[POCO-SCHEMA]
Joseph Smarr. Portable Contacts 1.0 Draft C: Contact Schema 5 August 2008. URL: http://portablecontacts.net/draft-spec.html#schema -
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt -
[UNICODE]
The Unicode Consortium. The Unicode Standard. 2003. Defined by: The Unicode Standard, Version 4.0 (Boston, MA, Addison-Wesley, ISBN 0-321-18578-1), as updated from time to time by the publication of new versions URL: http://www.unicode.org/unicode/standard/versions/enumeratedversions.html -
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219 -

C.2 Informative references

[HTML5]
Ian Hickson; David Hyatt. HTML 5. 4 March 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-html5-20100304/ -
\ No newline at end of file diff -r 52acb4877e86 -r 518970294839 contacts/WD1/contacts_notification.png Binary file contacts/WD1/contacts_notification.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/WD1/contacts_picker.png Binary file contacts/WD1/contacts_picker.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/WD2/Overview.html --- a/contacts/WD2/Overview.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,2152 +0,0 @@ - - - - - - - Contacts API - - - - - - -

W3C

Contacts API

W3C Working Draft 17 August 2010

This version:
http://www.w3.org/TR/2010/WD-contacts-api-20100817/
Latest published version:
http://www.w3.org/TR/contacts-api/
Latest editor's draft:
http://dev.w3.org/2009/dap/contacts/
Previous version:
http://www.w3.org/TR/2010/WD-contacts-api-20100701/
Editor:
Richard Tibbett, Opera Software ASA
-

-

Abstract

-

- The Contacts API defines the high-level interfaces required to provide read access to a user's unified address book. -

-

- Methods to manipulate a user's unified address book, to add and remove contact information, are being developed in an - accompanying specification [CONTACTS-WRITER-API]. -

-

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

-

- This document represents the early consensus of the group on the scope and features of the proposed Contacts API. Issues and - editors note in the document highlight some of the points on which the group is still working and would particularly like to get - feedback. -

-

This document was published by the Device APIs and Policy Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

- -

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

-

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

- -

- This specification defines conformance criteria that apply to a single product: the user agent that implements the - interfaces that it contains. -

-

- 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. -

-
-
-

2. - Introduction -

This section is non-normative.

-

- Every operating system and a large number of web-based service providers have different ways of representing address book - information. Most users are required to maintain a plurality of contact lists which leads to multiple copies of address book data. - The multiplicity of address books that a user is required to maintain often leads to disjointed and inconsistent information being - stored across a user's address book providers. -

-

- Providing address book information to these service providers means handing over all of your data and trusting these providers with - the security and privacy of storing and sharing of your information. When sharing this data with 3rd parties users are, more often - than not, required to hand over access to their whole address book. Users are implicitly required to trust 3rd parties with all of - their data when, in reality, the user may only wish, or need, to share a subset of their address book information so that an - application can fulfill its purpose. -

-

- This specification defines the concept of a user's unified address book - where address book data may be sourced from a - plurality of sources - both online and locally. This specification then defines the interfaces on which 3rd party applications can - access a user's unified address book; with explicit user permission and filtering. The focus of this data sharing is on making - the user aware of the data that they will share and putting them at the centre of the data sharing process; free to select both the - extent to which they share their address book information and the ability to restrict which pieces of information related to which - contact gets shared. -

-

- The API itself is agnostic of any underlying address book sources and storage. A conforming implementation is required to implement - all fields defined in this specification. -

-
-

2.1 - Usage Examples -

-

- The following code illustrates how to obtain contact information from a user's address book: -

-
function successContactFindCallback(contacts) {
-    // do something with resulting contact objects
-    for (var i in contacts) alert(contacts[i].displayName);
-    // ...
-}
-
-function generalErrorCB(error) {
-    // do something with resulting errors
-    alert(error.code);
-    // ...
-}
-
-// Perform an address book search. Obtain the 'name' and 'emails' properties 
-// and initially filter the list to Contact records containing 'Bob':
-navigator.service.contacts.find(['name', 'emails'],
-                                successContactFindCallback, 
-                                generalErrorCB,
-                                {filter: 'Bob'}
-                               );
-
-
-
-

3. - Security and Privacy Considerations -

-

- The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made - to this API to reflect requirements or support for privacy-related functionality. -

-

- The API defined in this specification can be used to create, find, save and remove contact information from a user's address - book(s). All API methods disclose information related to a user's contacts such as their phone number(s), email address(es) and - other personally identifying information. The distribution of this information could potentially compromise the user's privacy. - A conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism - should ensure that no contact information is creatable, retrivable, updateable or removable without the user's express - permission. -

-
-

3.1 - Privacy considerations for implementors of the Contacts API -

-

- A user agent must not create, find, save or delete contact information to Web sites without the express permission of the - user. A user agent must acquire permission through a user interface, unless they have prearranged trust relationships with - users, as described below. The user interface must include the URI of the document origin, as defined in [HTML5]. Those - permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond - the time when the browsing context, as defined in [HTML5], is navigated to another URL) must be revocable and a user - agent must respect revoked permissions. -

-

- Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same - Web site to access other methods provided by this API, or to access the same method with a different set of arguments, as part of - the same permission context. If a user has expressed permission for an implementation to, e.g. find a set of existing contacts, - the implementation must seek the user's express permission if and when any additional create, find, save or remove function - is called on this API. -

-

- A user agent may have prearranged trust relationships that do not require such user interfaces. For example, while a Web - browser will present a user interface when a Web site performs an address book request, a Widget Runtime may have a prearranged, - delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to - authorize the creation, retrieval, update and/or removal of contact information. -

-
-
-

3.2 - Privacy considerations for recipients of contact information -

-

- Recipients must only request contact information when necessary. Recipients must only use the contact information for the task - for which it was provided to them. Recipients must dispose of contact information once that task is completed, unless expressly - permitted to retain it by the user. Recipients must also take measures to protect this information against unauthorized access. - If contact information is stored, users should be allowed to update and delete this information. -

-

- The recipient of contact information must not retransmit the contact information without the user's express permission. Care - should be taken when retransmitting and use of encryption is encouraged. -

-

- Recipients must clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the - collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access, - update and delete the data, and any other choices that users have with respect to the data. This disclosure must include an - explanation of any exceptions to the guidelines listed above. -

-
-
-

3.3 - Additional implementation considerations -

This section is non-normative.

-

- Further to the requirements listed in the previous section, implementors of the Contacts API are also advised to consider the - following aspects that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant - permission to the User Agent to disclose their contacts to Web sites. In other cases, the content hosted at a certain URL changes - in such a way that the previously granted contact permissions no longer apply as far as the user is concerned. Or the users might - simply change their minds. -

-

- Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures are an - implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are - advised to enable user awareness of contact sharing, and to provide easy access to interfaces that enable revocation of - permissions. -

-
-
-
-

4. - API Description -

-
-

4.1 - ServiceContacts interface -

-

- The ServiceContacts interface is exposed on the navigator.service - object, as defined in [CORE-DEVICE]. -

-
Service implements ServiceContacts;
-   -
-
[NoInterfaceObject]
-interface ServiceContacts {
-    readonly attribute Contacts contacts;
-};
-

4.1.1 Attributes

contacts of type Contacts, readonly
- The root node from which the contacts functionality can be accessed. -
No exceptions.
-
-
-

4.2 - Contacts interface -

-

- The Contacts interface exposes a database collecting contacts information, such that they may be created, found, read, - updated, and deleted. -

-

- Multiple contact groups can be represented within this unified address book by specifying consistent tags value(s) as part of individual Contact objects. Multiple contact groups can be displayed by filtering on the - required tags value(s) via the Contacts find() function. -

-
[NoInterfaceObject]
-interface Contacts {
-    PendingOp find (in DOMString[] fields, in ContactFindSuccessCB successCB, in optional ContactErrorCB? errorCB, in optional ContactFindOptions? options);
-};
-

4.2.1 Methods

find
-

- Find contacts in the address book according to the find contacts process detailed below. -

-

- This method takes two, three or four arguments. When called, it immediately returns a PendingOp object , as - defined in [CORE-DEVICE], and then asynchronously starts a find contacts process defined as follows: -

-
    -
  1. - If a current find(), save() or remove() operation is pending a response, and the method was invoked with a - non-null errorCB argument, invoke the errorCB with a PENDING_OPERATION_ERROR code. -
  2. -
  3. - Search for contacts in the address book according to the rules defined in Contact Search Processing. -
  4. -
  5. - If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a - non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument. -
  6. -
- -
ParameterTypeNullableOptionalDescription
fieldsDOMString[] - The search qualifier. -
successCBContactFindSuccessCB - Function to call when the asynchronous operation completes -
errorCBContactErrorCB - Function to call when the asynchronous operation fails. -
optionsContactFindOptions - The options to apply to the output of this method. -
No exceptions.
Return type: PendingOp
-
-
-

4.3 - Contact interface -

-

- The use of Portable Contacts schema as the format for contacts is subject to further discussions in the group. -

-

- The Contact interface captures the properties of a contact object. All properties - included in this interface have a corresponding definition in [POCO-SCHEMA]. -

-

- In addition to the properties defined in this interface, a conforming implementation must support both the Singular and Plural - OpenSocial fields defined in [POCO-SCHEMA]. -

-

- The inclusion of OpenSocial fields in the paragraph above needs further explanation, particularly in relation to contact database - searching and sorting. -

-

- All Contact objects must include all attributes supported by the implementation, - regardless of whether these attributes have been assigned a non-null value or a null value. -

-

- If a supported attribute has not been assigned a value by the user and/or implementation, then this attribute must still be - present in the resulting Contact object and must have a value of null. -

-
[NoInterfaceObject]
-interface Contact {
-    readonly attribute DOMString             id;
-             attribute DOMString             displayName;
-             attribute ContactName           name;
-             attribute DOMString             nickname;
-             attribute ContactField[]        phoneNumbers;
-             attribute ContactField[]        emails;
-             attribute ContactAddress[]      addresses;
-             attribute ContactField[]        ims;
-             attribute ContactOrganization[] organizations;
-             attribute DOMString             published;
-             attribute DOMString             updated;
-             attribute DOMString             birthday;
-             attribute DOMString             anniversary;
-             attribute DOMString             gender;
-             attribute DOMString             note;
-             attribute DOMString             preferredUsername;
-             attribute ContactField[]        photos;
-             attribute ContactField[]        tags;
-             attribute ContactField[]        relationships;
-             attribute ContactField[]        urls;
-             attribute ContactAccount[]      accounts;
-             attribute DOMString             utcOffset;
-             attribute DOMString             connected;
-};
-

4.3.1 Attributes

accounts of type array of ContactAccount
-

- See [[POCO-SCHEMA] Section 7.2.2. accounts]. -

-
No exceptions.
addresses of type array of ContactAddress
-

- See [[POCO-SCHEMA] Section 7.2.2. addresses]. -

-
No exceptions.
anniversary of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. anniversary]. -

-
No exceptions.
birthday of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. birthday]. -

-
No exceptions.
connected of type DOMString
-

- Ignore this [POCO-SCHEMA] attribute? -

-

- See [[POCO-SCHEMA] Section 7.2.1. connected]. -

-
No exceptions.
displayName of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. displayName]. -

-
No exceptions.
emails of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. emails]. -

-
No exceptions.
gender of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. gender]. -

-
No exceptions.
id of type DOMString, readonly
-

- A globally unique identifier for the given Contact object. Each Contact referenced from - Contacts must include a non-empty id value. -

-

- An implementation must maintain this globally unique resource identifier when a Contact is added to, or present within, an - Address Book. -

-

- See [[POCO-SCHEMA] Section 7.2.1. id] for additional definition of this attribute. -

-
No exceptions.
ims of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. ims]. -

-
No exceptions.
name of type ContactName
-

- See [[POCO-SCHEMA] Section 7.2.1. name]. -

-
No exceptions.
nickname of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. nickname]. -

-
No exceptions.
note of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. note]. -

-
No exceptions.
organizations of type array of ContactOrganization
-

- See [[POCO-SCHEMA] Section 7.2.2. organizations]. -

-
No exceptions.
phoneNumbers of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. phoneNumbers]. -

-
No exceptions.
photos of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. photos]. -

-
No exceptions.
preferredUsername of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. preferredUsername]. -

-
No exceptions.
published of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. published]. -

-
No exceptions.
relationships of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. relationships]. -

-
No exceptions.
tags of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. tags]. -

-
No exceptions.
updated of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. updated]. -

-
No exceptions.
urls of type array of ContactField
-

- See [[POCO-SCHEMA] Section 7.2.2. urls]. -

-
No exceptions.
utcOffset of type DOMString
-

- See [[POCO-SCHEMA] Section 7.2.1. utcOffset]. -

-
No exceptions.
-
-
-

4.4 - ContactName interface -

-

- The ContactName interface describes a contact's name. -

-
[NoInterfaceObject]
-interface ContactName {
-    attribute DOMString formatted;
-    attribute DOMString familyName;
-    attribute DOMString givenName;
-    attribute DOMString middleName;
-    attribute DOMString honorificPrefix;
-    attribute DOMString honorificSuffix;
-};
-

4.4.1 Attributes

familyName of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. familyName]. -

-
No exceptions.
formatted of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. formatted]. -

-
No exceptions.
givenName of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. givenName]. -

-
No exceptions.
honorificPrefix of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. honorificPrefix]. -

-
No exceptions.
honorificSuffix of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. honorificSuffix]. -

-
No exceptions.
middleName of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.3. middleName]. -

-
No exceptions.
-
-
-

4.5 - ContactField interface -

-

- The ContactField interface is a reusable component that is used to support contact fields within the Contact interface. -

-
[NoInterfaceObject]
-interface ContactField {
-    attribute DOMString type;
-    attribute DOMString value;
-    attribute boolean   primary;
-};
-

4.5.1 Attributes

primary of type boolean
-

- See [[POCO-SCHEMA]] Section 7.2.2. primary]. -

-
No exceptions.
type of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.2.2. type]. -

-
No exceptions.
value of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.2.2. value]. -

-
No exceptions.
-
-
-

4.6 - ContactAddress interface -

-

- The ContactAddress interface is a reusable component that is used to support contact addresses within the Contact interface. -

-
[NoInterfaceObject]
-interface ContactAddress {
-    attribute DOMString formatted;
-    attribute DOMString streetAddress;
-    attribute DOMString locality;
-    attribute DOMString region;
-    attribute DOMString postalCode;
-    attribute DOMString country;
-};
-

4.6.1 Attributes

country of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. country]. -

-
No exceptions.
formatted of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. formatted]. -

-
No exceptions.
locality of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. locality]. -

-
No exceptions.
postalCode of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. postalCode]. -

-
No exceptions.
region of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. region]. -

-
No exceptions.
streetAddress of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.4. streetAddress]. -

-
No exceptions.
-
-
-

4.7 - ContactOrganization interface -

-

- The ContactOrganization interface is a reusable component that is used to support contact organizations within the Contact interface. -

-
[NoInterfaceObject]
-interface ContactOrganization {
-    attribute DOMString name;
-    attribute DOMString department;
-    attribute DOMString title;
-    attribute DOMString startDate;
-    attribute DOMString endDate;
-    attribute DOMString location;
-    attribute DOMString description;
-};
-

4.7.1 Attributes

department of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. department]. -

-
No exceptions.
description of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. description]. -

-
No exceptions.
endDate of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. endDate]. -

-
No exceptions.
location of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. location]. -

-
No exceptions.
name of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. name]. -

-
No exceptions.
startDate of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. startDate]. -

-
No exceptions.
title of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.5. title]. -

-
No exceptions.
-
-
-

4.8 - ContactAccount interface -

-

- The ContactAccount interface is a reusable component that is used to support contact accounts within the Contact interface. -

-
[NoInterfaceObject]
-interface ContactAccount {
-    attribute DOMString domain;
-    attribute DOMString username;
-    attribute DOMString userid;
-};
-

4.8.1 Attributes

domain of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.6. domain]. -

-
No exceptions.
userid of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.6. userid]. -

-
No exceptions.
username of type DOMString
-

- See [[POCO-SCHEMA]] Section 7.6. username]. -

-
No exceptions.
-
-
-

4.9 - ContactFindOptions interface -

-

- The ContactFindOptions interface describes the options that can be applied to - contact searching. When a ContactFindOptions parameter is provided to the Contacts find() operation, it should be processed according to the provisions detailed in Options Processing. -

-
[NoInterfaceObject]
-interface ContactFindOptions {
-    attribute String?         filter;
-    attribute boolean?        multiple;
-    attribute unsigned short? limit;
-    attribute DOMString       updatedSince;
-};
-

4.9.1 Attributes

filter of type String, nullable
- A DOMString-based search filter with which to search and intially filter the Contacts database. -
No exceptions.
limit of type unsigned short, nullable
-

- The maximum number of results to return from the contacts search. -

-

- This parameter only applies in the case that the associated multiple attribute is equal to true. -

-

- If no value is provided, the search will return all Contact object results. -

-
No exceptions.
multiple of type boolean, nullable
- A boolean value to indicate whether multiple Contact objects are returnable as part of the associated Contacts find() operation. -
No exceptions.
updatedSince of type DOMString
-

- Return only contact records that have been updated on or after the given time, specified as an xs:dateTime. -

-

- This filter is based on the updated field as defined in Contact. -

-
No exceptions.
-
-
-

4.10 - ContactFindSuccessCB interface -

- -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactFindSuccessCB {
-    void onSuccess (in Contact[] contactObjs);
-};
-

4.10.1 Methods

onSuccess
- - -
ParameterTypeNullableOptionalDescription
contactObjsContact[] - The Contact objects resulting from the given Contacts find() method. Contacts find() -
No exceptions.
Return type: void
-
-
-

4.11 - ContactErrorCB interface -

- -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactErrorCB {
-    void onError (in ContactError error);
-};
-

4.11.1 Methods

onError
- - -
ParameterTypeNullableOptionalDescription
errorContactError - The Contact API related error object. -
No exceptions.
Return type: void
-
-
-

4.12 - ContactError interface -

-

- The ContactError interface encapsulates all errors in the manipulation of Contact objects in the Contacts API. -

-
[NoInterfaceObject]
-interface ContactError {
-    const unsigned short UNKNOWN_ERROR = 0;
-    const unsigned short INVALID_ARGUMENT_ERROR = 1;
-    const unsigned short NOT_FOUND_ERROR = 2;
-    const unsigned short TIMEOUT_ERROR = 3;
-    const unsigned short PENDING_OPERATION_ERROR = 4;
-    const unsigned short IO_ERROR = 5;
-    const unsigned short NOT_SUPPORTED_ERROR = 6;
-    const unsigned short PERMISSION_DENIED_ERROR = 20;
-    readonly attribute unsigned short code;
-};
-

4.12.1 Attributes

code of type unsigned short, readonly
- An error code assigned by an implementation when an error has occurred in Contacts API processing. -
No exceptions.

4.12.2 Constants

INVALID_ARGUMENT_ERROR of type unsigned short
- An invalid parameter was provided when the requested method was invoked. -
IO_ERROR of type unsigned short
- An error occurred in communication with the underlying implementation that meant the requested method could not complete. -
NOT_FOUND_ERROR of type unsigned short
- If no response information can be provided from the requested method. -
NOT_SUPPORTED_ERROR of type unsigned short
- The requested method is not supported by the current implementation. -
PENDING_OPERATION_ERROR of type unsigned short
- If the user agent is currently waiting for a callback on a current find(), save() or remove() operation, as defined in - this specification. -
PERMISSION_DENIED_ERROR of type unsigned short
- Access to the requested method was denied at the implementation or by the user. -
TIMEOUT_ERROR of type unsigned short
- The requested method timed out before it could be completed. -
UNKNOWN_ERROR of type unsigned short
- An unknown error occurred. -
-
-
- -
-

5. - Contact Search Processing -

-

- The Contacts find() method provides an operation to search for one of more Contact objects within the Contacts database. -

-
-

5.1 - Search Qualifiers -

-

- The search qualifier provides an application with a way to request the specific subset of Contact properties it wishes to obtain in any resulting successful callback. The - search qualifier is deployed to minimize the data that needs to be shared with an application in order to let that - application fulfill its function on behalf of the user. The search qualifier is included within a Contacts find() operation as the filter parameter. -

-

- A search qualifier must be specified from a requesting application as a part of any Contacts find() operation. -

-

- If the search qualifier provided is of zero-length then the current Contacts find() operation must not return any Contact properties within any resulting Contact object(s). -

-

- In the case that the search qualifier provided is of non-zero-length then the current Contacts find() operation must return only the matching Contact properties within any resulting Contact object(s). -

-

- If a provided search qualifier element (filter[x]) does not match a Contact attribute, filter[x] should be ignored when executing the - current Contacts find() operation. -

-
-

5.1.1 - Complex Search Qualifiers -

-

- Certain Contact attributes can be considered complex by the fact that the information they - contain is available only through child DOMString-based attributes of a complex Object object. -

-

- In such cases, a requesting application must be able to request both the full complex Contact attribute and also be able to request individual parts of a complex Contact attribute in the search qualifier provided to a Contacts find() operation. -

-

- For example, the name attribute of a Contact object is defined to be of complex type ContactName. Therefore, a requesting application may request either the full - complex attribute (i.e. name) or specific individual attributes of this complex attribute (i.e. - name.formatted, name.familyName, name.givenName, name.middleName, - name.honorificPrefix, name.honorificSuffix) as part of a Contacts find() operation's search qualifier. -

-

- In the case that a complex Contact attribute is defined as a sequence or array of complex objects, specific - individual attributes can be referenced by using the complex attribute name, a dot (.) character and the - individual attribute to be retrieved. -

-

- For example, the addresses attribute of Contact allows multiple ContactAddress objects to be defined. To request individual attributes of - this complex attribute an application would request e.g. addresses.locality, addresses.region, etc. -

-
-
-

5.1.2 - Search Qualifier Example -

-

- The following Contact search is initiated: -

-
navigator.service.contacts.find(['emails.value', 'name', 'friends'],
-                                function(contacts) { 
-                                   for(i in contacts) {
-                                      for(j in contacts[i].emails)
-                                         alert(contacts[i].emails[j]);
-                                   }
-                                });
-

- The above example logically implies: -

-
    -
  1. - Return only the valid Contact attributes requested in the provided search qualifier - (name, emails.value - friends is not a valid Contact attribute so ignore this element). -
  2. -
-
-
-
-

5.2 - Options Processing -

-
-

5.2.1 - Search Cardinality -

-

- By default, the Contacts find() operation must return either an empty sequence or a single Contact object, accessible as part of the sequence returned in the ContactFindSuccessCB callback function. -

-

- If a ContactFindOptions object is provided to the Contacts find() operation and its multiple attribute is set to true, the Contacts find() operation must return either an empty sequence, a single Contact object or [X] number of Contact objects, accessible as part of the sequence returned in the ContactFindSuccessCB callback function. -

-

- An implementation must specify a suitable integer-based upper cardinality limit to limit the maximum number of - Contact objects that may be returned in the case that the multiple flag is true and the - limit flag is out of bounds. -

-

- If a ContactFindOptions object is provided to the Contacts find() operation and its limit attribute is greater than zero and less than or - equal to the implementation's upper cardinality limit, then [X] must be set to the provided - limit value. -

-

- The limit attribute is out of bounds if a ContactFindOptions object is provided to the Contacts find() operation and its limit attribute is less than or equal to zero or greater - than the implementation's upper cardinality limit. In this case [X] must be set to the - implementation's upper cardinality limit. -

-
-
-

5.2.2 - Search Sorting -

-

- The Contacts find() operation must return successful callback results according to the sorting guidelines - defined in this section. -

-

- A search weight is a numeric value defined for each attribute in a Contact object. A lower value denotes a higher placing in the ultimate sorting of - Contacts find() results. The search weights for each Contact attribute are defined in Appendix B. -

-

- For example, if a search filter of 'Bob' matches to name.givenName in Object A and to - displayName in Object B, Object B will be the first result object returned from the successCB of the given Contacts find() operation, followed by Object A. -

-

- Include UNICODE guidelines for intra-attribute sorting of results (where multiple Contact objects match on the same - attribute)... [UNICODE] DUCET -

-
-
-

5.2.3 - Search Filters -

-

- A search filter may be specified from a requesting web application to initially filter the Contacts database to a - more specific set of Contact objects in which it is interested. The search filter is included as - the filter attribute of the ContactFindOptions object provided to a Contacts find() operation. -

-

- A search filter is used to search Contact attributes within the Contacts database and represents the logical union, or , of - provided values that are matched therein. -

-

- All contact searching must apply a loose-matching policy to the search filter provided. If an attribute being - searched in a Contact object, stored within the Contacts database, is a partial value match of the input - filter value, that Contact object must be returned as part of the resulting ContactFindSuccessCB. -

-

- A conforming implementation must only allow the provided search filter to be applied to fields requested in the provided - search qualifier. The id attribute must always be implicitly searchable from any requesting web application - regardless of whether it has been included as part of any provided search qualifier. For example, if the given search - qualifier contains 'name' and 'displayName', then the rules for processing search filters should - only be applied to all sub-fields of the name attribute (i.e. name.formatted, - name.firstName, name.givenName, name.middleName, name.honorificPrefix, - name.honorificSuffix) and the displayName attribute. -

-

- A partial value match refers to both syntactic and semantic partial matching of an input filter value with a - corresponding value in the address book and denotes that a corresponding match was found in the address book that begins with, - contains or ends with the value of the input filter value, or any variation thereof. -

-

- Comparing two strings in a compatibility caseless manner means using the Unicode compatibility caseless - match operation to compare the two strings. [UNICODE] -

-

- A partial value match must use the compatibility caseless manner in which to match against corresponding values - in the Contacts database. -

-

-   -

-

- The rules for processing search filters is defined below and is always provided with a filter parameter, representing the filter attribute of the ContactFindOptions parameter provided within the current Contacts find() operation. -

-
-
-   -
-
- Let contactsets be initially the set of all known contacts in the Contacts database. -

- Let contactsresult be initially an empty Object object. -

-
-
- If filter is a DOMString object -
-
-
    -
  1. - Let contactset be the next enumerable Object in contactsets. If there is no next enumerable Object, go to step 5. -
  2. -
  3. - Let partialMatchFound be the result of applying the partial matching algorithm, - providing filter and contactset as inputs. -
  4. -
  5. - If partialMatchFound is true, add contactset to contactsresult. -
  6. -
  7. - Go to step 1. -
  8. -
  9. - Sort contactsresult according to the guidelines in Search Sorting. -
  10. -
  11. - Return contactsresult. -
  12. -
-
-
- If filter is another native object type -
-
-

- Return contactsets. -

-
-
-

-   -

-

- The partial matching algorithm is defined below and is always provided with a filter parameter, representing the input string to compare; and a contactset parameter, representing an individual Contact object: -

-
-
-   -
-
- Let hasPartialMatch be initially set to false. -
-
- If contactset is an Object object -
-
-
    -
  1. - Let elementvalue be the String value of the next enumerable property in contactset. If there are no more enumerable properties, go to step 5. -
  2. -
  3. - Let hasPartialMatch be the boolean result for the comparison of filter with elementvalue in a compatibility caseless manner and with a partial value match - policy applied to both sides of the comparison operation. -
  4. -
  5. - If hasPartialMatch is true, go to step 5. -
  6. -
  7. - Go to step 1. -
  8. -
  9. - Return hasPartialMatch. -
  10. -
-
-
- If contactset is another native object type -
-
-

- Return false. -

-
-
-

-   -

-
-
5.2.3.1 - Search Filter Example -
-

- The following Contact search is initiated: -

-
navigator.service.contacts.find(['name', 'addresses.locality', 'addresses.country', 'phoneNumbers', 'emails'],
-                                function(contacts) { 
-                                   for(x in contacts) alert(contacts[x].name); 
-                                },
-                                {
-                                  filter: 'Robert'
-                                });
-

- The above example logically implies: -

-
    -
  1. - Using ECMA-262 3rd Edition regular expression syntax and psuedo-code, the search filter provided can be represented - as: -
    ( name.formatted = /∧.*Robert.*$/i ) ∪ ( phoneNumbers.value = /∧.*Robert.*$/i ) 
    -∪ ( emails.value = /∧.*Robert.*$/i ) ∪ ( name.familyName = /∧.*Robert.*$/i ) 
    -∪ ( name.givenName = /∧.*Robert.*$/i )  ∪ ( name.middleName = /∧.*Robert.*$/i )
    -∪ ( addresses.country = /∧.*Robert.*$/i ) ∪ ( addresses.locality = /∧.*Robert.*$/i )  
    -∪ ( phoneNumbers.type = /∧.*Robert.*$/i ) ∪ ( emails.type = /∧.*Robert.*$/i )
    -∪ ( id = /∧.*Robert.*$/i )
    -
    -
    - All searches are case-insensitive and apply a loose-matching policy as defined in Search Filters. Search ordering is sorted according to search weights defined in Search Filters and described in Appendix B.
    -
    - The id attribute is implicitly appended along with any search filter attributes provided, regardless - of whether it was provided as a search qualifier from the requesting application, as defined in Search Filters.
    -
    -
  2. -
  3. - Return only the valid Contact properties requested in the provided search qualifier - (name, addresses.locality, addresses.country, phoneNumbers, - emails) and only for the Contact objects returned from the rules for processing search filters - with the search filter derived in step 1 provided as the filter input parameter. -
  4. -
-
-
-
-
-
-

A. - User Interaction Guidelines -

This section is non-normative.

-

- This specification is primarily intended to provide the user with the ability to view and control the contact information that may - be shared, saved or removed from their unified address book. This annex provides some examples of a conformant user experience that - this specification enables. -

-
-

A.1 - Sharing Contact Information -

-

- A website requests access to a user's address book with the following code: -

-
function successContactFindCallback(contacts) {
-    // do something with resulting contact objects
-    for (var i in contacts) alert(contacts[i].name);
-    // ...
-}
-
-function generalErrorCB(error) {
-    // do something with resulting errors
-    alert(error.code);
-    // ...
-}
-
-// Perform an address book search. Obtain the 'name' and 'emails' properties 
-// and initially filter the list to Contact records containing 'Bob':
-navigator.service.contacts.find(['name', 'emails'],
-                                successContactFindCallback, 
-                                generalErrorCB,
-                                {filter: 'Bob'}
-                               );
-

- As a result of executing this code, the user agent may provide a non-blocking contact search notification as - follows: -

-

- Contact Search Notification
- (View as PNG) -

-

- If an additional find(), save() or remove() operation is called by the current web application before the user has clicked - 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR if that operation was defined with a - non-null errorCB parameter. -

-

- If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be - invoked with an error code of PERMISSION_DENIED_ERROR. -

-

- If the user clicks 'Select', the user agent may provide a contact picker, utilising all of the - parameters provided in the find() operation as follows: -

-

- Contact Picker
- (View as PNG) -

-

- In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select - one or more contacts (as appropriate) from the user interface. -

-

- If an additional find(), save() or remove() operation is called by the current web application before the user has clicked - 'Select' or 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR if that operation was defined with a - non-null errorCB parameter. -

-

- If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be - invoked with an error code of PERMISSION_DENIED_ERROR. -

-

- If the user clicks 'Select', the ContactFindSuccessCB associated to the current find() operation will be - invoked with the contact information selected by the user provided as the only parameter. -

-

- Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily - be able to review and revoke permissions to web applications at a later date. -

-
-
-
-

B. - Search Weights -

-

- The following table defines the search weight values for each search qualifier provided in this specification. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Search Qualifier - - Search Weight -
- displayName - - 1 -
- name.formatted - - 2 -
- nickname - - 3 -
- tags.value - - 4 -
- phoneNumbers.value - - 5 -
- addresses.formatted - - 6 -
- organizations.name - - 7 -
- emails.value - - 8 -
- ims.value - - 9 -
- preferredUsername - - 10 -
- name.familyName - - 11 -
- name.givenName - - 12 -
- name.middleName - - 13 -
- addresses.country - - 14 -
- addresses.region - - 15 -
- addresses.streetAddress - - 16 -
- addresses.locality - - 17 -
- addresses.postalCode - - 18 -
- organizations.department - - 19 -
- organizations.title - - 20 -
- organizations.startDate - - 21 -
- organizations.endDate - - 22 -
- organizations.location - - 23 -
- organizations.description - - 24 -
- accounts.domain - - 25 -
- accounts.userid - - 26 -
- accounts.username - - 27 -
- photos.value - - 28 -
- relationships.value - - 29 -
- urls.value - - 30 -
- gender - - 31 -
- birthday - - 32 -
- anniversary - - 33 -
- published - - 34 -
- updated - - 35 -
- utcOffset - - 36 -
- notes - - 37 -
- name.honorificPrefix - - 38 -
- name.honorificSuffix - - 39 -
- phoneNumbers.type - - 40 -
- addresses.type - - 41 -
- emails.type - - 42 -
- ims.type - - 43 -
- tags.type - - 44 -
- photos.type - - 45 -
- relationships.type - - 46 -
- urls.type - - 47 -
- connected - - 48 -
- id - - 49 -
- phoneNumbers.primary - - n/a (boolean attribute) -
- addresses.primary - - n/a (boolean attribute) -
- emails.primary - - n/a (boolean attribute) -
- ims.primary - - n/a (boolean attribute) -
- tags.primary - - n/a (boolean attribute) -
- photos.primary - - n/a (boolean attribute) -
- relationships.primary - - n/a (boolean attribute) -
- urls.primary - - n/a (boolean attribute) -
- phoneNumbers - - n/a (complex attribute) -
- addresses - - n/a (complex attribute) -
- emails - - n/a (complex attribute) -
- ims - - n/a (complex attribute) -
- photos - - n/a (complex attribute) -
- tags - - n/a (complex attribute) -
- relationships - - n/a (complex attribute) -
- urls - - n/a (complex attribute) -
-
-
-

C. References

C.1 Normative references

[CORE-DEVICE]
Robin Berjon. Core Device Interfaces. 02 December 2009. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/device/ -
[POCO-SCHEMA]
Joseph Smarr. Portable Contacts 1.0 Draft C: Contact Schema 5 August 2008. URL: http://portablecontacts.net/draft-spec.html#schema -
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt -
[UNICODE]
The Unicode Consortium. The Unicode Standard. 2003. Defined by: The Unicode Standard, Version 4.0 (Boston, MA, Addison-Wesley, ISBN 0-321-18578-1), as updated from time to time by the publication of new versions URL: http://www.unicode.org/unicode/standard/versions/enumeratedversions.html -
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219 -

C.2 Informative references

[CONTACTS-WRITER-API]
R. Tibbett. Contacts Writer API. 3rd August 2010. W3C Latest Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/contacts/Writer.html -
[HTML5]
Ian Hickson; David Hyatt. HTML 5. 4 March 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-html5-20100304/ -
\ No newline at end of file diff -r 52acb4877e86 -r 518970294839 contacts/WD2/contacts_notification.png Binary file contacts/WD2/contacts_notification.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/WD2/contacts_picker.png Binary file contacts/WD2/contacts_picker.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/WD3/Overview.html --- a/contacts/WD3/Overview.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1894 +0,0 @@ - - - - - - - Contacts API - - - - - - - -

W3C

Contacts API

W3C Working Draft 09 December 2010

This version:
http://www.w3.org/TR/2010/WD-contacts-api-20101209/
Latest published version:
http://www.w3.org/TR/contacts-api/
Latest editor's draft:
http://dev.w3.org/2009/dap/contacts/
Previous version:
http://www.w3.org/TR/2010/WD-contacts-api-20100817/
Editor:
Richard Tibbett, Opera Software ASA
-

-

Abstract

-

- The Contacts API defines the high-level interfaces required to provide read access to a user's unified address book. -

-

- Methods to manipulate a user's unified address book, to add and remove contact information, are being developed in an - accompanying specification [CONTACTS-WRITER-API]. -

-

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

-

- This document represents the early consensus of the group on the scope and features of the proposed Contacts API. Issues and - editors note in the document highlight some of the points on which the group is still working and would particularly like to get - feedback. -

-

This document was published by the Device APIs and Policy Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

- -

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

-

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

- -

- This specification defines conformance criteria that apply to a single product: the user agent that implements the - interfaces that it contains. -

-

- 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. -

-
-
-

2. - Introduction -

This section is non-normative.

-

- Every operating system and a large number of web-based service providers have different ways of representing address book - information. Most users are required to maintain a plurality of contact lists which leads to multiple copies of address book data. - The multiplicity of address books that a user is required to maintain often leads to disjointed and inconsistent information being - stored across a user's address book providers. -

-

- Providing address book information to these service providers means handing over all of your data and trusting these providers with - the security and privacy of storing and sharing of your information. When sharing this data with third parties users are, more - often than not, required to hand over access to their whole address book. Users are implicitly required to trust third parties with - all of their data when, in reality, the user may only wish, or need, to share a subset of their address book information so that an - application can fulfill its purpose. -

-

- This specification defines the concept of a user's unified address book - where address book data may be sourced from a - plurality of sources - both online and locally. This specification then defines the interfaces on which third party applications - can access a user's unified address book, with explicit user permission and filtering. The focus of this data sharing is on - making the user aware of the data that they will share and putting them at the center of the data sharing process; free to select - both the extent to which they share their address book information and the ability to restrict which pieces of information related - to which contact gets shared. -

-

- A conforming implementation is required to implement all fields defined in this specification. -

-
-

- The following code illustrates how to obtain contact information from a user's address book: -

-
function successContactFindCallback(contacts) {
-    // do something with resulting contact objects
-    for (var i in contacts) alert(contacts[i].displayName);
-    // ...
-}
-
-function generalErrorCB(error) {
-    // do something with resulting errors
-    alert(error.code);
-    // ...
-}
-
-// Perform an address book search. Obtain the 'name' and 'emails' properties 
-// and initially filter the list to Contact records containing 'Bob':
-navigator.service.contacts.find(['name', 'emails'],
-                                successContactFindCallback, 
-                                generalErrorCB,
-                                {filter: 'Bob'}
-                               );
-// ..is equivalent to: navigator.service.contacts(/* parameters */)
-
-
-
-

2.1 - Terminology -

-

- The terms document base URL, browsing context, event handler attributes, event handler event type, task, task - source and task queues are defined by the HTML5 specification [HTML5]. -

-

- The task source used by this specification is the PendingOp task source. -

- -

- PendingOp needs updating in [CORE-DEVICE] to show that it is a valid task source. -

-

- To dispatch a success event means that an event with the name success, which does - not bubble and is not cancelable, and which uses the Event interface, is to be dispatched at the ContactFindCB object. -

-

- To dispatch an error event means that an event with the name error, which does - not bubble and is not cancelable, and which uses the Event interface, is to be dispatched at the ContactErrorCB object. -

-
-
-
-

3. - Security and Privacy Considerations -

-

- The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made - to this API to reflect requirements or support for privacy-related functionality. -

-

- The API defined in this specification can be used to find contact information from a user's address book(s). This discloses - information related to a user's contacts such as their phone number(s), email address(es) and other personally identifying - information. The distribution of this information could potentially compromise the user's privacy, or the - user’s contacts privacy. A conforming implementation of this specification must provide a mechanism that - protects the user's privacy and this mechanism should ensure that no contact information is retrievable without the user's - express permission. -

-
-

3.1 - Privacy considerations for implementors of the Contacts API -

-

- A user agent must not retrieve contact information to Web sites without the express permission of the user. A user - agent must acquire permission through a user interface, unless they have prearranged trust relationships with users, as - described below. The user interface must include the document base URL. Those permissions that are acquired through the - user interface and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing context - is navigated to another URL) must be revocable and a user agent must respect revoked permissions. -

-

- Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same - Web site to access other methods provided by this API, or to access the same method with a different set of arguments, as part of - the same permission context. If a user has expressed permission for an implementation to, e.g. find a set of existing contacts, - the implementation must seek the user's express permission if and when any additional find function is called on - this API. -

-

- A user agent may have prearranged trust relationships that do not require such user interfaces. For example, while a Web - browser will present a user interface when a Web site performs an address book request, a Widget [WIDGETS] runtime may have a - prearranged, delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism - with which to authorize the retrieval of contact information. -

-
-
-

3.2 - Privacy considerations for recipients of contact information -

This section is non-normative.

-

- Web sites owners that retrieve contacts information using this API are denoted as recipients below. -

-

- Recipients should only request contact information when necessary, and only use the contact information for the task for which it - was provided to them. -

-

- Recipients should dispose of contact information once that task is completed, unless expressly permitted to retain it by the - user. Recipients should also take measures to protect this information against unauthorized access. If contact information is - stored, users should be allowed to update and delete this information. -

-

- The recipient of contact information should not retransmit the contact information without the user's express permission. - Care should be taken when retransmitting and use of encryption is encouraged. -

-

- Recipients should clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the - collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access, - update and delete the data, and any other choices that users have with respect to the data. This disclosure should include an - explanation of any exceptions to the guidelines listed above. -

-
-
-

3.3 - Additional implementation considerations -

This section is non-normative.

-

- Further to the requirements listed in the previous section, implementors of the Contacts API are also advised to consider the - following aspects that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant - permission to the User Agent to disclose their contacts to Web sites. In other cases, the content hosted at a certain URL changes - in such a way that the previously granted contact permissions no longer apply as far as the user is concerned. Or the users might - simply change their minds. -

-

- Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures are an - implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are - advised to enable user awareness of contact sharing, and to provide easy access to interfaces that enable revocation of - permissions. -

-
-
-
-

4. - API Description -

-
-

4.1 - ServiceContacts interface -

-

- The ServiceContacts interface is exposed on the navigator.service - object, as defined in [CORE-DEVICE]. -

-
Service implements ServiceContacts;
-   -
-
[NoInterfaceObject]
-interface ServiceContacts {
-    readonly attribute Contacts contacts;
-};
-

4.1.1 Attributes

contacts of type Contacts, readonly
- The root node from which the contacts functionality can be accessed. -
No exceptions.
-
-
-

4.2 - Contacts interface -

-

- The Contacts interface exposes a database collecting contacts information that may be retrieved. -

-

- Multiple contact groups can be represented within this unified address book by specifying consistent categories value(s) as part of individual Contact objects. Multiple contact groups can be displayed by filtering on the - required categories value(s) via the Contacts find() function. -

-
[NoInterfaceObject]
-interface Contacts {
-    caller PendingOp find (in DOMString[] fields, in ContactFindCB successCB, in optional ContactErrorCB? errorCB, in optional ContactFindOptions? options);
-};
-

4.2.1 Methods

find
-

- Find contacts in the address book according to the find contacts process detailed below. -

-

- This method takes two, three or four arguments. When called, it immediately returns a PendingOp object, as - defined in [CORE-DEVICE], and then asynchronously starts a find contacts process defined as follows: -

-
    -
  1. - If there are any tasks from the PendingOp task source in one of the task queues - (i.e. an existing find() operation is still pending a response), and the current method was invoked with a - non-null errorCB argument, dispatch an error event with a PENDING_OPERATION_ERROR code value. -
  2. -
  3. - Search for contacts in the address book according to the rules defined in Contact Search Processing. -
  4. -
  5. - If the attempt was successful, dispatch a success event. If the attempt fails, and the method was - invoked with a non-null errorCB argument, this method must dispatch an error - event with the code attribute set according to the type of failure that has occurred. -
  6. -
- -
ParameterTypeNullableOptionalDescription
fieldsDOMString[] - The search qualifier. -
successCBContactFindCB - Function to call when the asynchronous operation completes -
errorCBContactErrorCB - Function to call when the asynchronous operation fails. -
optionsContactFindOptions - The options to apply to the output of this method. -
No exceptions.
Return type: caller PendingOp
-
-
-

4.3 - Contact interface -

-

- The attributes provided in this interface are under review and are likely to change as the recommendation progresses. -

-

- The Contact interface captures the properties of a contact object. -

-

- All Contact objects must include all attributes supported by the implementation, - regardless of whether these attributes have been assigned a non-null value or a null value. If a - supported attribute has not been assigned a value by the user and/or implementation, then this attribute must still be present in - the resulting Contact object and must have a value of null. -

-

- Additional attributes may be included according to the provisions detailed in Extended Contact Properties and Parameters. If an extended attribute is - supported by the current implementation and has not been assigned a value by the user and/or implementation, then this extended - attribute must still be present in the resulting Contact object and must have a value of null. -

-
[NoInterfaceObject]
-interface Contact {
-    readonly attribute DOMString             id;
-             attribute DOMString             displayName;
-             attribute ContactName           name;
-             attribute DOMString             nickname;
-             attribute ContactField[]        phoneNumbers;
-             attribute ContactField[]        emails;
-             attribute ContactAddress[]      addresses;
-             attribute ContactField[]        ims;
-             attribute ContactOrganization[] organizations;
-             attribute Date                  revision;
-             attribute Date                  birthday;
-             attribute DOMString             gender;
-             attribute DOMString             note;
-             attribute ContactField[]        photos;
-             attribute DOMString[]           categories;
-             attribute ContactField[]        urls;
-             attribute DOMString             timezone;
-};
-

4.3.1 Attributes

addresses of type array of ContactAddress
-

- This attribute represents one or more physical addresses associated with this Contact. -

-
No exceptions.
birthday of type Date
-

- This attribute contains birthday of this Contact. -

-

- The year value may be set to 0000 when the age of the Contact is private or the year is not available. -

-
No exceptions.
categories of type array of DOMString
-

- This attribute contains one or more user-defined categories/tags/labels associated with this Contact. e.g. "family", "favorite". -

-
No exceptions.
displayName of type DOMString
-

- This attribute contains the display name of this Contact which is suitable for display to the end-users. -

-

- Each Contact must include either a displayName or the name attribute. -

-
No exceptions.
emails of type array of ContactField
-

- This attribute represents one or more email addresses associated with this Contact. -

-
No exceptions.
gender of type DOMString
-

- This attribute contains the gender of this Contact. This attribute should have one of the following values: -

-
male, female, undisclosed
-

- This attribute may return a different value if it is not covered by one of these values. -

-
No exceptions.
id of type DOMString, readonly
-

- A globally unique identifier for the given Contact object. Each Contact must - include a non-empty id value. -

-

- An implementation must maintain this globally unique resource identifier when a Contact is added to, or present within, an - Address Book. -

-
No exceptions.
ims of type array of ContactField
-

- This attribute represents one or more instant messaging identifiers associated with this Contact. -

-
No exceptions.
name of type ContactName
-

- This attribute represents the full name of this Contact indicated by the name - components associated with the ContactName object. -

-
No exceptions.
nickname of type DOMString
-

- This attribute contains the nickname (or a casual name) for this Contact. -

-
No exceptions.
note of type DOMString
-

- This attribute contains the personal notes (free-text) for this Contact that is managed by the user of the Address Book. -

-

- This field may contain newlines (\n). -

-
No exceptions.
organizations of type array of ContactOrganization
-

- This attribute represents one or more organizations associated with this Contact. -

-
No exceptions.
phoneNumbers of type array of ContactField
-

- This attribute represents one or more phone numbers associated with this Contact. -

-
No exceptions.
photos of type array of ContactField
-

- This attribute represents one or more photos (that may be displayed) associated with this Contact. -

-

- The photos must be specified in the value attribute of the ContactField object either by using a URL - (representing an actual image file and not a web page pointing to that image file) or base64 encoded string representing the image data. -

-

- Service Providers may return the same image at different sizes, though it is recognized that no standard for describing images of - various sizes currently exists. -

-

- This attribute should not be used to send down arbitrary photos taken by this user, but specifically profile photos of the contact - suitable for display when describing the contact. -

-
No exceptions.
revision of type Date
-

- This atttribute contains the timestamp information associated with this Contact, which represents - the last known modified time. If no modified time exists, then this object contains the timestamp of when - the object was created. -

-
No exceptions.
timezone of type DOMString
-

- The value contains the time zone of this Contact as an offset from UTC. -

-

- The value must be specified as a positive or negative difference - from the UTC in units of hours and minutes (i.e. +hh:mm). Example, by specifying +05:30 indicates the Contact - is associated with a current time zone of GMT+05:30. -

-

- This value may change over time due to daylight saving time, and is thus meant to signify only the current value of the user's timezone offset. -

-
No exceptions.
urls of type array of ContactField
-

- This attribute represents one or more web resources (i.e. URLs) associated with this Contact e.g. personal web page, blog. -

-

- The web resources must be specified by the value attribute of the ContactField object using a URL. -

-

- In addition to the standard values for type, this field also defines the additional type values: -

-
blog, profile
-
No exceptions.
-
-
-

4.4 - ContactName interface -

-

- The ContactName interface describes a contact's name. -

-
[NoInterfaceObject]
-interface ContactName {
-    attribute DOMString formatted;
-    attribute DOMString familyName;
-    attribute DOMString givenName;
-    attribute DOMString middleName;
-    attribute DOMString honorificPrefix;
-    attribute DOMString honorificSuffix;
-};
-

4.4.1 Attributes

familyName of type DOMString
-

- This attribute contains the family name (also referred to as the last name) of this Contact. -

-
No exceptions.
formatted of type DOMString
-

- This attribute contains the full name, including all the individual components such as givenName, middleName, - familyName, prefix, suffix as appropriate, and formatted for display (e.g. Mr. Joe Smith Jr). -

-
No exceptions.
givenName of type DOMString
-

- This attribute contains the given name (also referred to as the first name) of this Contact. -

-
No exceptions.
honorificPrefix of type DOMString
-

- This attribute contains the honorific prefix (or title) of this Contact. E.g. Mr. Dr. Ms. Mrs., -

-
No exceptions.
honorificSuffix of type DOMString
-

- This attribute contains the honorific suffix of this Contact. E.g. Jr, III, Sr. -

-
No exceptions.
middleName of type DOMString
-

- This attribute contains the middle name of this Contact. -

-
No exceptions.
-
-
-

4.5 - ContactField interface -

-

- The ContactField interface is a reusable component that is used to support contact fields within the Contact interface. -

-
[NoInterfaceObject]
-interface ContactField {
-    attribute DOMString type;
-    attribute DOMString value;
-    attribute boolean   pref;
-};
-

4.5.1 Attributes

pref of type boolean
-

- This attribute indicates whether this instance of the ContactField is the preferred, or primary, value for the contact property this - ContactField is representing in the Contact interface. -

-
No exceptions.
type of type DOMString
-

- This attribute contains the type information for this ContactField and is subject to the contact property this - ContactField is representing in the Contact interface. For example, if the ContactField is - representing a phoneNumber property, the type attribute is set to home, mobile, - and if the Contact Field is representing ims property, the type attribute is set to yahoo, gtalk, - bbm, etc. -

-
No exceptions.
value of type DOMString
-

- This attribute contains the value for this ContactField and is subject to the contact property this - ContactField is representing in the Contact interface. For example, if the ContactField is - representing an email, the value attribute is set to JoeSmith@example.com, and if the ContactField is representing a url, the value - attribute is set to http://www.example.org/joesmith, etc. -

-
No exceptions.
-
-
-

4.6 - ContactAddress interface -

-

- The ContactAddress interface is a reusable component that is used to support contact addresses within the Contact interface. -

-
[NoInterfaceObject]
-interface ContactAddress {
-    attribute DOMString formatted;
-    attribute DOMString streetAddress;
-    attribute DOMString locality;
-    attribute DOMString region;
-    attribute DOMString postalCode;
-    attribute DOMString country;
-};
-

4.6.1 Attributes

country of type DOMString
-

- This attribute contains the country name corresponding to this ContactAddress. -

-
No exceptions.
formatted of type DOMString
-

- This attribute contains the full physical address including street, locality, region, postalCode, and country as appropriate, and formatted for display. -

-
No exceptions.
locality of type DOMString
-

- This attribute contains the locality (or city) name corresponding to this ContactAddress. -

-
No exceptions.
postalCode of type DOMString
-

- This attribute contains the postal code (or zip) corresponding to this ContactAddress. -

-
No exceptions.
region of type DOMString
-

- This attribute contains the region (or state/province) name corresponding to this ContactAddress. -

-
No exceptions.
streetAddress of type DOMString
-

- This attribute contains the street address corresponding to this ContactAddress. -

-
No exceptions.
-
-
-

4.7 - ContactOrganization interface -

-

- The ContactOrganization interface is a reusable component that is used to support contact organizations within the Contact interface. -

-
[NoInterfaceObject]
-interface ContactOrganization {
-    attribute DOMString name;
-    attribute DOMString department;
-    attribute DOMString title;
-};
-

4.7.1 Attributes

department of type DOMString
-

- This attribute contains the Job Title information of the Contact associated with this Organization. -

-
No exceptions.
name of type DOMString
-

- This attribute contains the name of the Organization and must be assigned a non-null value. -

-
No exceptions.
title of type DOMString
-

- This attribute contains the department information of the Organization associated with this Contact. -

-
No exceptions.
-
-
-

4.8 - ContactFindOptions interface -

-

- The ContactFindOptions interface describes the options that can be applied to - contact searching. When a ContactFindOptions parameter is provided to the Contacts find() operation, it should be processed according to the provisions detailed in Options Processing. -

-
[NoInterfaceObject]
-interface ContactFindOptions {
-    attribute DOMString? filter;
-    attribute boolean?   multiple;
-    attribute Date?      updatedSince;
-};
-

4.8.1 Attributes

filter of type DOMString, nullable
- A DOMString-based search filter with which to search and initially filter the Contacts database. -
No exceptions.
multiple of type boolean, nullable
- A boolean value to indicate whether multiple Contact objects are returnable as part of the associated Contacts find() operation. - -

- By default this option is set to true. -

-
No exceptions.
updatedSince of type Date, nullable
-

- Return only contact records that have been updated on or after the given time, specified as an ECMAScript Date - object. -

-

- This filter is applied to the revision field as defined in Contact. -

-
No exceptions.
-
-
-

4.9 - ContactFindCB interface -

-
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactFindCB : PendingOp {
-    void onsuccess (in Contact[] contactObjs);
-};
-

4.9.1 Methods

onsuccess
- - -
ParameterTypeNullableOptionalDescription
contactObjsContact[] - The Contact objects resulting from the given Contacts find() method. Contacts find() -
No exceptions.
Return type: void
-
-

4.9.2 - Event Handler Attributes -

-

- The following is the event handler attribute (and its corresponding event handler event type) that must be - supported as a DOM attribute by the ContactFindCB object. -

- - - - - - - - - - - - - -
- event handler attribute - - event handler event type -
- onsuccess - - success -
-
-
-
-

4.10 - ContactErrorCB interface -

- -
[Callback=FunctionOnly, NoInterfaceObject]
-interface ContactErrorCB : PendingOp {
-    void onerror (in ContactError error);
-};
-

4.10.1 Methods

onerror
- - -
ParameterTypeNullableOptionalDescription
errorContactError - The Contact API related error object. -
No exceptions.
Return type: void
-
-

4.10.2 - Event Handler Attributes -

-

- The following is the event handler attribute (and its corresponding event handler event type) that must be - supported as a DOM attribute by the ContactErrorCB object. -

- - - - - - - - - - - - - -
- event handler attribute - - event handler event type -
- onerror - - error -
-
-
-
-

4.11 - ContactError interface -

-

- The ContactError interface encapsulates all errors in the manipulation of Contact objects in the Contacts API. -

-
[NoInterfaceObject]
-interface ContactError {
-    const unsigned short UNKNOWN_ERROR = 0;
-    const unsigned short INVALID_ARGUMENT_ERROR = 1;
-    const unsigned short TIMEOUT_ERROR = 2;
-    const unsigned short PENDING_OPERATION_ERROR = 3;
-    const unsigned short IO_ERROR = 4;
-    const unsigned short NOT_SUPPORTED_ERROR = 5;
-    const unsigned short PERMISSION_DENIED_ERROR = 20;
-    readonly attribute unsigned short code;
-};
-

4.11.1 Attributes

code of type unsigned short, readonly
- An error code assigned by an implementation when an error has occurred in Contacts API processing. -
No exceptions.

4.11.2 Constants

INVALID_ARGUMENT_ERROR of type unsigned short
- An invalid parameter was provided when the requested method was invoked. -
IO_ERROR of type unsigned short
- An error occurred in communication with the underlying implementation that meant the requested method could not complete. -
NOT_SUPPORTED_ERROR of type unsigned short
- The requested method is not supported by the current implementation. -
PENDING_OPERATION_ERROR of type unsigned short
- If the user agent is currently waiting for a callback on a current find() operation, as defined in this specification. -
PERMISSION_DENIED_ERROR of type unsigned short
- Access to the requested method was denied at the implementation or by the user. -
TIMEOUT_ERROR of type unsigned short
- The requested method timed out before it could be completed. -
UNKNOWN_ERROR of type unsigned short
- An unknown error occurred. -
-
-
- -
-

5. - Contact Search Processing -

-

- The Contacts find() method provides an operation to search for one of more Contact objects within the Contacts database. -

-
-

5.1 - Search Qualifiers -

-

- The search qualifier provides an application with a way to request the specific subset of Contact properties it wishes to obtain in any resulting successful callback. The - search qualifier is deployed to minimize the data that needs to be shared with an application in order to let that - application fulfill its function on behalf of the user. The search qualifier is included within a Contacts find() operation as the filter parameter. -

-

- A search qualifier must be specified from a requesting application as a part of any Contacts find() operation. -

-

- If the search qualifier provided is of zero-length then the current Contacts find() operation must not return any Contact properties within any resulting Contact object(s). -

-

- In the case that the search qualifier provided is of non-zero-length then the current Contacts find() operation must return only the matching Contact properties within any resulting Contact object(s). -

-

- If a provided search qualifier element (filter[x]) does not match a Contact attribute, filter[x] should be ignored when executing the - current Contacts find() operation. -

-
-

5.1.1 - Advanced Search Qualifiers -

-

- We call composed attributes Contact attributes of types object, sequence, - array or any which contain information only available only through child attributes of that object. -

-

- A requesting application must be able to request both the full composed Contact attribute and also be able to request individual parts of a composed Contact attribute in the search qualifier provided to a Contacts find() operation. -

-

- For example, the name attribute of a Contact object is defined to be of composed type ContactName. Therefore, a requesting application may request either the full - composed attribute (i.e. name) or specific individual attributes of this composed attribute (i.e. - name.formatted, name.familyName, name.givenName, name.middleName, - name.honorificPrefix, name.honorificSuffix) as part of a Contacts find() operation's search qualifier. -

-

- In the case that a composed Contact attribute is defined as a sequence or array of composed objects, specific - individual attributes can be referenced by using the composed attribute name, a dot (.) character and the - individual attribute to be retrieved. -

-

- For example, the addresses attribute of Contact allows multiple ContactAddress objects to be defined. To request individual attributes of - this composed attribute an application would request e.g. addresses.locality, addresses.region, etc. -

-
-
-

- The following Contact search is initiated: -

-
 
-   navigator.service.contacts.find(['emails.value', 'name', 'friends'],
-                                   function(contacts) { 
-                                      for(i in contacts) {
-                                         for(j in contacts[i].emails)
-                                            alert(contacts[i].emails[j]);
-                                      }
-                                   });
-
-

- The above example logically implies: -

-
    -
  1. - Return only the valid Contact attributes requested in the provided search qualifier - (name, emails.value - friends is not a valid Contact attribute so ignore this element). -
  2. -
-
-
-
-

5.2 - Options Processing -

-
-

5.2.1 - Search Cardinality -

-

- By default, the Contacts find() operation must return either an empty sequence or a single Contact object, accessible as part of the sequence returned in the ContactFindCB callback function. -

-

- If a ContactFindOptions object is provided to the Contacts find() operation and its multiple attribute is set to true, the Contacts find() operation must return either an empty sequence, a single Contact object or [X] number of Contact objects, accessible as part of the sequence returned in the ContactFindCB callback function. -

-
-
-

5.2.2 - Search Filters -

-

- A search filter may be specified from a requesting web application to initially filter the Contacts database to a - more specific set of Contact objects in which it is interested. The search filter is included as - the filter attribute of the ContactFindOptions object provided to a Contacts find() operation. -

-

- A search filter is used to search Contact attributes within the Contacts database and represents the logical union, or , of - provided values that are matched therein. -

-

- All contact searching must apply a loose-matching policy to the search filter provided. If an attribute being - searched in a Contact object, stored within the Contacts database, is a partial value match of the input - filter value, that Contact object must be returned as part of the resulting ContactFindCB. -

-

- A conforming implementation must only allow the provided search filter to be applied to fields requested in the provided - search qualifier. The id attribute must always be implicitly searchable from any requesting web application - regardless of whether it has been included as part of any provided search qualifier. For example, if the given search - qualifier contains 'name' and 'displayName', then the rules for processing search filters should - only be applied to all sub-fields of the name attribute (i.e. name.formatted, - name.firstName, name.givenName, name.middleName, name.honorificPrefix, - name.honorificSuffix), the displayName attribute and the id attribute. -

-

- A partial value match refers to both syntactic and semantic partial matching of an input filter value with a - corresponding value in the address book and denotes that a corresponding match was found in the address book that begins with, - contains or ends with the value of the input filter value, or any variation thereof. -

-

- Comparing two strings in a compatibility caseless manner means using the Unicode compatibility caseless - match operation to compare the two strings. [UNICODE] -

-

- A partial value match must use the compatibility caseless manner in which to match against corresponding values - in the Contacts database. -

-

-   -

-

- The rules for processing search filters is defined below and is always provided with a filter parameter, representing the filter attribute of the ContactFindOptions parameter provided within the current Contacts find() operation. -

-
-
-   -
-
- Let contactsets be initially the set of all known contacts in the Contacts database. -

- Let contactsresult be initially an empty Array object. -

-
-
- If filter is a DOMString object -
-
-
    -
  1. - Let contactset be the next enumerable Object in contactsets. If there is no next enumerable Object, go to step 5. -
  2. -
  3. - Let partialMatchFound be the result of applying the partial matching algorithm, - providing filter and contactset as inputs. -
  4. -
  5. - If partialMatchFound is true, add contactset to contactsresult. -
  6. -
  7. - Go to step 1. -
  8. -
  9. - Return contactsresult. -
  10. -
-
-
- If filter is another native object type -
-
-

- Return contactsets. -

-
-
-

-   -

-

- The partial matching algorithm is defined below and is always provided with a filter parameter, representing the input string to compare; and a contactset parameter, representing an individual Contact object: -

-
-
-   -
-
- Let hasPartialMatch be initially set to false. -
-
- If contactset is an Object object -
-
-
    -
  1. - Let elementvalue be the String value of the next enumerable property in contactset. If there are no more enumerable properties, go to step 5. -
  2. -
  3. - Let hasPartialMatch be the boolean result for the comparison of filter with elementvalue in a compatibility caseless manner and with a partial value match - policy applied to both sides of the comparison operation. -
  4. -
  5. - If hasPartialMatch is true, go to step 5. -
  6. -
  7. - Go to step 1. -
  8. -
  9. - Return hasPartialMatch. -
  10. -
-
-
- If contactset is another native object type -
-
-

- Return false. -

-
-
-
-

- The following Contact search is initiated: -

-
      navigator.service.contacts.find(['name', 'addresses.locality', 'addresses.country', 'phoneNumbers', 'emails'],
-                                      function(contacts) { 
-                                         for(x in contacts) alert(contacts[x].name); 
-                                      },
-                                      {
-                                        filter: 'Robert'
-                                      });
-     
-
-

- The above example logically implies: -

-
    -
  1. - Using ECMA-262 3rd Edition regular expression syntax and pseudo-code, the search filter provided can be represented - as: -
    ( name.formatted = /∧.*Robert.*$/i ) ∪ ( phoneNumbers.value = /∧.*Robert.*$/i ) 
    -∪ ( emails.value = /∧.*Robert.*$/i ) ∪ ( name.familyName = /∧.*Robert.*$/i ) 
    -∪ ( name.givenName = /∧.*Robert.*$/i )  ∪ ( name.middleName = /∧.*Robert.*$/i )
    -∪ ( addresses.country = /∧.*Robert.*$/i ) ∪ ( addresses.locality = /∧.*Robert.*$/i )  
    -∪ ( phoneNumbers.type = /∧.*Robert.*$/i ) ∪ ( emails.type = /∧.*Robert.*$/i )
    -∪ ( id = /∧.*Robert.*$/i )
    -
    -
    - All searches are case-insensitive and apply a loose-matching policy as defined in Search Filters.
    -
    - As noted in Search Filters, the id attribute is implicitly appended along with any search - filter attributes provided, regardless of whether it was provided as a search qualifier from the requesting - application.
    -
    -
  2. -
  3. - Return only the valid Contact properties requested in the provided search qualifier - (name, addresses.locality, addresses.country, phoneNumbers, - emails) and only for the Contact objects returned from the rules for processing search filters - with the search filter derived in step 1 provided as the filter input parameter. -
  4. -
-
-
-
-
-
-

6. - Extended Contact Properties and Parameters -

-

- The properties and parameters defined on the Contact interface may be extended by implementors of this specification. -

-

- Non-standard, private properties and parameters should have a prefixed name starting with X (U+0058 LATIN CAPTIAL - LETTER X) or use a vendor-specific prefix. Extended properties and parameters can be defined bilaterally between user agents without outside registration or standardization. -

-

- It is recommended that authors define both a formal vCard grammar [RFC2426] and a WebIDL grammar [WEBIDL] for their proposed - extension to ensure interoperability between vCard databases and other non-standard Contact databases and formats. It is also - recommended that authors provide documentation of their extension properties and parameters within the public domain. -

-
-

- A new parameter is required by Company X to provide information related to a user's accounts registered across different - networks and services. -

-

- The [WEBIDL] syntax for this parameter is defined as follows: -

-
Contact implements ContactExtended;
-   -
-
[NoInterfaceObject]
-interface ContactExtended {
-    attribute ContactAccount[] Xaccounts;
-};
-

Attributes

Xaccounts of type array of ContactAccount
- One or more user accounts. See [[POCO-SCHEMA] Section 7.2.2. accounts]. -
No exceptions.
-
[NoInterfaceObject]
-interface ContactAccount {
-    attribute DOMString domain;
-    attribute DOMString username;
-    attribute DOMString userid;
-};
-

Attributes

domain of type DOMString
-

- See [[POCO-SCHEMA] Section 7.6. domain]. -

-
No exceptions.
userid of type DOMString
-

- See [[POCO-SCHEMA] Section 7.6. userid]. -

-
No exceptions.
username of type DOMString
-

- See [[POCO-SCHEMA] Section 7.6. username]. -

-
No exceptions.
-

- The corresponding vCard [RFC2426] notation for this parameter is defined as follows: -

-
   The following ABNF grammar extends the grammar found in [RFC2426] (Section 4).
-   
-   X-ACCOUNT
-   
-   Purpose:  To specify the components of the accounts for the vCard 
-      object.
-
-   Value type:  A single structured text value, separated by the SEMI-
-      COLON character (ASCII decimal 59).
-
-   Cardinality:  (0,n)
-
-   Special notes:  The structured type value consists of a sequence of
-      account components.  The component values must be specified in
-      their corresponding position.  The structured type value
-      corresponds, in sequence, to the domain; the username; the userid.
-      When a component value is missing, the associated component 
-      separator must still be specified.    
-
-      The text components are separated by the SEMI-COLON character
-      (ASCII decimal 59).
-      
-   ABNF:
-   
-     X-ACCOUNT-param = ; no parameter allowed
-     X-ACCOUNT-value = list-component 3(";" list-component)
-
-

- This parameter will be used within the Contacts API as follows: -

-
   var contact = ...; // ...obtain individual contact object
-   for(var i in contact.Xaccounts) {
-      alert(contact.Xaccounts[i].domain);   // thesocialnetwork.com
-      alert(contact.Xaccounts[i].username); // null
-      alert(contact.Xaccounts[i].userid);   // 344aesq2
-   }            
-
-

- This parameter will be used within the vCard format [RFC2426]] as follows: -

-
   X-ACCOUNT;thesocialnetwork.com;;344aesq2
-
-
-
-
-

A. API Invocation via DOM Events

This section is non-normative.

- -

The API contained in this document can be invoked either programmatically (for example, inline within a general script) or - resulting from the interaction of a user.

- -

The interaction of a user is when a user invokes the API from an -HTMLElement [HTML5] within the current -browsing context via a valid auto-invocation event.

- -

A valid auto-invocation event includes any of the following event types, as defined in [DOM-LEVEL-3-EVENTS]:

- - - -

The find() method on Contacts should, if the method was invoked -by an interaction of a user (as opposed to having been created and executed in general script), display the -Contact Picker directly.

- - -
- -
-

B. - User Interaction Guidelines -

This section is non-normative.

-

- This specification is primarily intended to provide the user with the ability to view and control the contact information that may - be shared from their unified address book. This annex provides some examples of a conformant user experience that this - specification enables. -

-
-

B.1 - Accessing Contact Information - Example #1 -

-

- A website requests access to a user's address book with the following code: -

-
-
 <script type="text/javascript">
- 
-function successContactFindCallback(contacts) {
-    // do something with resulting contact objects
-    for (var i in contacts) alert(contacts[i].name);
-    // ...
-}
-
-function generalErrorCB(error) {
-    // do something with resulting errors
-    alert(error.code);
-    // ...
-}
-
-// Perform an address book search. Obtain the 'name' and 'emails' properties 
-// and initially filter the list to Contact records containing 'Bob':
-navigator.service.contacts.find(['name', 'emails'],
-                                successContactFindCallback, 
-                                generalErrorCB,
-                                {filter: 'Bob'}
-                               );
-                               
-</script>
-
-
-

- As a result of executing this code, the user agent may provide a non-blocking contact search notification as - follows: -

-

- Contact Search Notification
- (View as PNG) -

-

- If an additional find() operation is called by the current web application before the user has clicked 'Select' or - 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR if that operation was defined with a - non-null errorCB parameter. -

-

- If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be - invoked with an error code of PERMISSION_DENIED_ERROR. -

-

- If the user clicks 'Select', the user agent may provide a contact picker, utilizing all of the - parameters provided in the find() operation as follows: -

-

- Contact Picker
- (View as PNG) -

-

- In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select - one or more contacts (as appropriate) from the user interface. -

-

- If an additional find() operation is called by the current web application before the user has clicked 'Select' or - 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR if that operation was defined with a - non-null errorCB parameter. -

-

- If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be - invoked with an error code of PERMISSION_DENIED_ERROR. -

-

- If the user clicks 'Select', the ContactFindCB associated to the current find() operation will be invoked with - the contact information selected by the user provided as the only parameter. -

-

- Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily - be able to review and revoke permissions to web applications at a later date. -

-
- -
-

B.2 - Accessing Contact Information - Example #2 -

-

- A website requests access to a user's address book with the following code: -

-
-
<input type="button" value="Share Contacts" onclick="getContacts()" />
- 
-<script type="text/javascript">
-  function successContactFindCallback(contacts) {
-    // do something with resulting contact objects
-    for (var i in contacts) alert(contacts[i].name);
-    // ...
-  }
-
-  function generalErrorCB(error) {
-    // do something with resulting errors
-    alert(error.code);
-    // ...
-  }
-  
-  function getContacts() {
-    // Perform an address book search. Obtain the 'name' and 'emails' properties 
-    // and initially filter the list to Contact records containing 'Bob':
-    navigator.service.contacts.find(['name', 'emails'],
-                                    successContactFindCallback, 
-                                    generalErrorCB,
-                                    {filter: 'Bob'}
-                                   );
-  }
-</script>
-
-
-

- This code may render as follows within the user agent: -

-

- Contact Search via DOM Events
- (View as PNG) -

-

- If the user clicks on the rendered button element then the user agent may directly provide a contact picker, as defined in - API Invocation via DOM Events, utilizing all of the - parameters provided in the find() operation as follows: -

-

- Contact Picker
- (View as PNG) -

-

- In this dialog, the user is provided with a summary of the sharing that the application is requesting and the option to select - one or more contacts (as appropriate) from the user interface. -

-

- If an additional find() operation is called by the current web application before the user has clicked 'Select' or - 'Cancel' on the current notification, an error will be invoked with a code of PENDING_OPERATION_ERROR if that operation was defined with a - non-null errorCB parameter. -

-

- If the user clicks 'Cancel', the errorCB, if non-null for the current find() operation, will be - invoked with an error code of PERMISSION_DENIED_ERROR. -

-

- If the user clicks 'Select', the ContactFindCB associated to the current find() operation will be invoked with - the contact information selected by the user provided as the only parameter. -

-

- Further to this initial sharing of Contact information, the Security and Privacy Considerations section expects that the user should easily - be able to review and revoke permissions to web applications at a later date. -

-
- -
-

C. References

C.1 Normative references

[CORE-DEVICE]
Robin Berjon. Core Device Interfaces. 02 December 2009. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/device/ -
[HTML5]
Ian Hickson; David Hyatt. HTML 5. 4 March 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-html5-20100304/ -
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt -
[UNICODE]
The Unicode Consortium. The Unicode Standard. 2003. Defined by: The Unicode Standard, Version 4.0 (Boston, MA, Addison-Wesley, ISBN 0-321-18578-1), as updated from time to time by the publication of new versions URL: http://www.unicode.org/unicode/standard/versions/enumeratedversions.html -
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219 -

C.2 Informative references

[CONTACTS-WRITER-API]
R. Tibbett. Contacts Writer API. 3rd August 2010. W3C Latest Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/contacts/Writer.html -
[DOM-LEVEL-3-EVENTS]
Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. Document Object Model (DOM) Level 3 Events Specification. 21 December 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071221 -
[POCO-SCHEMA]
Joseph Smarr. Portable Contacts 1.0 Draft C: Contact Schema 5 August 2008. URL: http://portablecontacts.net/draft-spec.html#schema -
[RFC2426]
F. Dawson, T. Howes. vCard MIME Directory Profile. September 1998. URL: http://www.ietf.org/rfc/rfc2426.txt -
[WIDGETS]
Marcos Caceres. Widget Packaging and Configuration. 01 December 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-widgets-20091201/ -
\ No newline at end of file diff -r 52acb4877e86 -r 518970294839 contacts/WD3/contacts_element.png Binary file contacts/WD3/contacts_element.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/WD3/contacts_notification.png Binary file contacts/WD3/contacts_notification.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/WD3/contacts_picker.png Binary file contacts/WD3/contacts_picker.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/Writer.html --- a/contacts/Writer.html Thu Dec 20 11:31:22 2012 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,612 +0,0 @@ - - - - - Contacts Writer API - - - - - - - - -
-

- The Contacts Writer API defines the high-level interfaces required to add and remove contact information to and from a user's - unified address book. -

-

- This specification is built on top of an accompanying specification [[CONTACTS-API]] that enables read access to a user's - unified address book. -

-

- Interesting summary of the general issues with a Writer API in the web context: - http://lists.w3.org/Archives/Public/public-device-apis/2010Jul/0112.html - -

- -
-
-

- This document represents the early consensus of the group on the scope and features of the proposed Contacts API. Issues and - editors note in the document highlight some of the points on which the group is still working and would particularly like to get - feedback. -

-
-
-

- This specification defines conformance criteria that apply to a single product: the user agent that implements the - interfaces that it contains. -

-

- 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. -

-
-
-

- Introduction -

-

- Every operating system and a large number of web-based service providers have different ways of representing address book - information. Most users are required to maintain a plurality of contact lists which leads to multiple copies of address book data. - The multiplicity of address books that a user is required to maintain often leads to disjointed and inconsistent information being - stored across a user's address book providers. -

-

- Providing address book information to these service providers means handing over all of your data and trusting these providers with - the security and privacy of storing and sharing of your information. When sharing this data with 3rd parties users are, more often - than not, required to hand over access to their whole address book. Users are implicitly required to trust 3rd parties with all of - their data when, in reality, the user may only wish, or need, to share a subset of their address book information so that an - application can fulfill its purpose. -

-

- This specification defines the concept of a user's unified address book - where address book data may be sourced from a - plurality of sources - both online and locally. This specification then defines the interfaces on which 3rd party applications can - access a user's unified address book; with explicit user permission and filtering. The focus of this data sharing is on making - the user aware of the data that they will share and putting them at the centre of the data sharing process; free to select both the - extent to which they share their address book information and the ability to restrict which pieces of information related to which - contact gets shared. -

-

- The API itself is agnostic of any underlying address book sources and storage. A conforming implementation is required to implement - all fields defined in this specification. -

-
-

- Usage Examples -

-

- The following code extracts illustrate how to search, add, remove and update contact information in a given address book: -

-
-

- Creating a new contact. -

-
-
-// Create new contact  
-var myContact = navigator.service.contacts.create({displayName: 'Robert'}});
-
-// Add additional contact attributes as required...
-// myContact.nicknames.push('bobby');
-
-
-

- Saving a new contact in the underlying addressbook. -

-
-
-// previous example follow-on...
-
-function successContactCallback(contact) {
-    // do something with resulting contact object
-    alert(contact.displayName);
-    // ...
-}
-
-// Save new contact
-myContact.save(successContactCallback, generalErrorCB);
-
-
-

- Editing an existing contact. -

-
-
-// previous example follow-on...
-
-// e.g. add a new phone number
-myContact.phoneNumbers.push({type: 'home', value: '+440000000002'});
-
-// Update existing contact
-myContact.save(successContactCallback, generalErrorCB);
-
-
-

- Removing an existing contact. -

-
-
-// previous example follow-on...
-
-// Remove existing contact
-myContact.remove(successContactCallback, generalErrorCB);
-
-
-
-
-

- Security and Privacy Considerations -

-

- The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made - to this API to reflect requirements or support for privacy-related functionality. -

-

- The API defined in this specification can be used to create, find, save and remove contact information from a user's address - book(s). All API methods disclose information related to a user's contacts such as their phone number(s), email address(es) and - other personally identifying information. The distribution of this information could potentially compromise the user's privacy. - A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism - should ensure that no contact information is creatable, retrivable, updateable or removable without the user's express - permission. -

-
-

- Privacy considerations for implementors of the Contacts API -

-

- A user agent must not create, find, save or delete contact information to Web sites without the express permission of the - user. A user agent must acquire permission through a user interface, unless they have prearranged trust relationships with - users, as described below. The user interface must include the URI of the document origin, as defined in [[HTML5]]. Those - permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond - the time when the browsing context, as defined in [[HTML5]], is navigated to another URL) MUST be revocable and a user - agent must respect revoked permissions. -

-

- Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same - Web site to access other methods provided by this API, or to access the same method with a different set of arguments, as part of - the same permission context. If a user has expressed permission for an implementation to, e.g. find a set of existing contacts, - the implementation must seek the user's express permission if and when any additional create, find, save or remove function - is called on this API. -

-

- A user agent may have prearranged trust relationships that do not require such user interfaces. For example, while a Web - browser will present a user interface when a Web site performs an address book request, a Widget Runtime MAY have a prearranged, - delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to - authorize the creation, retrieval, update and/or removal of contact information. -

-
-
-

- Privacy considerations for recipients of contact information -

-

- Recipients MUST only request contact information when necessary. Recipients MUST only use the contact information for the task - for which it was provided to them. Recipients MUST dispose of contact information once that task is completed, unless expressly - permitted to retain it by the user. Recipients MUST also take measures to protect this information against unauthorized access. - If contact information is stored, users should be allowed to update and delete this information. -

-

- The recipient of contact information MUST not retransmit the contact information without the user's express permission. Care - should be taken when retransmitting and use of encryption is encouraged. -

-

- Recipients MUST clearly and conspicuously disclose the fact that they are collecting contact data, the purpose for the - collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access, - update and delete the data, and any other choices that users have with respect to the data. This disclosure MUST include an - explanation of any exceptions to the guidelines listed above. -

-
-
-

- Additional implementation considerations -

-

- Further to the requirements listed in the previous section, implementors of the Contacts API are also advised to consider the - following aspects that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant - permission to the User Agent to disclose their contacts to Web sites. In other cases, the content hosted at a certain URL changes - in such a way that the previously granted contact permissions no longer apply as far as the user is concerned. Or the users might - simply change their minds. -

-

- Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures are an - implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are - advised to enable user awareness of contact sharing, and to provide easy access to interfaces that enable revocation of - permissions. -

-
-
-
-

- API Description -

-
-

- ContactsWriter interface -

-

- The ContactsWriter interface exposes a database collecting contacts information, such that they may be created, updated, - and deleted. -

-
-
- Contact create () -
-
- Create a new Contact object. -

- This method takes one argument. When called, it returns a Contact object. -

-

- The newly created Contact object MUST NOT be stored in the user's address book as a result of - calling this method. The Contact save() method MUST be called on the response of this method to store the new Contact object in the user's address book. -

-
-
- ContactProperties attributes -
-
- The attributes to assign to the resulting object. -
-
-
-
-
-
-

- ContactWriter interface -

-

- The ContactWriter interface captures a single contact item. This interface extends ContactProperties attributes. -

-

- All Contact objects MUST include all attributes supported by the implementation, - regardless of whether these attributes have been assigned a non-null value or a null value. -

-

- If a supported attribute has not been assigned a value by the user and/or implementation, then this attribute MUST still be - present in the resulting Contact object and MUST have a value of null. -

-
-
- Contact clone () -
-
-

- Create a deep clone copy of the current object minus the current object's id attribute. -

-

- The resulting object MUST be provided with a newly generated id attribute to distiguish the cloned object from the original object. -

-
-
- PendingOp save () -
-
-

- Add or update (as appropriate) the current Contact object to the Contacts. -

-

- This method takes one or two arguments. When called, it immediately returns a PendingOp object, as defined in - [[!CORE-DEVICE]], and then asynchronously starts a save contact process defined as follows: -

-
    -
  1. - If a current find(), save() or remove() operation is pending a response, and the method was invoked with a - non-null errorCB argument, invoke the errorCB with a PENDING_OPERATION_ERROR code. -
  2. -
  3. - If the current Contact.id value is not recognized in Contacts or a Contact.id value has not been set, create and set a new Contact.id value and add the current object as a new object to Contacts. -
  4. -
  5. - If the Contact.id already exists in Contacts then update the existing object in Contacts. -
  6. -
  7. - If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a - non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument. -
  8. -
-
-
- ContactSuccessCB successCB -
-
- Function to call when the asynchronous operation completes -
-
- optional ContactErrorCB? errorCB -
-
- Function to call when the asynchronous operation fails. -
-
-
-
- PendingOp remove () -
-
-

- Remove the current contact from the address book. -

-

- In the case that the current id attribute is null and this method is invoked, a ContactErrorCB MUST be triggered as part of the remove contact - process. This error MUST consist of a ContactError object with a code of NOT_FOUND_ERROR. -

-

- This method takes one or two arguments. When called, it immediately returns a PendingOp object, as defined in - [[!CORE-DEVICE]], and then asynchronously starts a remove contact process defined as follows: -

-
    -
  1. - If a current find(), save() or remove() operation is pending a response, and the method was invoked with a - non-null errorCB argument, invoke the errorCB with a PENDING_OPERATION_ERROR code. -
  2. -
  3. - Remove the current object from Contacts. -
  4. -
  5. - If the removal of the current object from Contacts was successful, set the current object's Contact.id value to null. -
  6. -
  7. - If successful, invoke the associated successCB. If the attempt fails, and the method was invoked with a - non-null errorCB argument, this method must invoke the errorCB with a ContactError object as an argument. -
  8. -
-
-
- ContactSuccessCB successCB -
-
- Function to call when the asynchronous operation completes -
-
- optional ContactErrorCB? errorCB -
-
- Function to call when the asynchronous operation fails. -
-
-
-
-
-
-

- ContactSuccessCB interface -

- -
-
- void onsuccess () -
-
- -
-
- Contact contactObj -
-
- The Contact object resulting from the given Contact save() or Contact remove() method. -
-
-
-
-
-
-

- ContactErrorCB interface -

- -
-
- void onerror () -
-
- -
-
- ContactError error -
-
- The Contact API related error object. -
-
-
-
-
-
-

- ContactError interface -

-

- The ContactError interface encapsulates all errors in the manipulation of Contact objects in the Contacts API. -

-
-
- const unsigned short UNKNOWN_ERROR = 0 -
-
- An unknown error occurred. -
-
- const unsigned short INVALID_ARGUMENT_ERROR = 1 -
-
- An invalid parameter was provided when the requested method was invoked. -
-
- const unsigned short NOT_FOUND_ERROR = 2 -
-
- If no response information can be provided from the requested method. -
-
- const unsigned short TIMEOUT_ERROR = 3 -
-
- The requested method timed out before it could be completed. -
-
- const unsigned short PENDING_OPERATION_ERROR = 4 -
-
- If the user agent is currently waiting for a callback on a current find(), save() or remove() operation, as defined in - this specification. -
-
- const unsigned short IO_ERROR = 5 -
-
- An error occurred in communication with the underlying implementation that meant the requested method could not complete. -
-
- const unsigned short NOT_SUPPORTED_ERROR = 6 -
-
- The requested method is not supported by the current implementation. -
-
- const unsigned short PERMISSION_DENIED_ERROR = 20 -
-
- Access to the requested method was denied at the implementation or by the user. -
-
- readonly attribute unsigned short code -
-
- An error code assigned by an implementation when an error has occurred in Contacts API processing. -
-
-
-
- -
-

- User Interaction Guidelines -

-

- This specification is primarily intended to provide the user with the ability to view and control the contact information that may - be shared, saved or removed from their unified address book. This annex provides some examples of a conformant user experience that - this specification enables. -

-
-

- Contact Writebacks -

-
-

- Saving a Contact to the Address Book -

-

- Include Contact creation/modification writeback mockup. -

-
-
-

- Removing a Contact from the Address Book -

-

- Include Contact deletion writeback mockup. -

-
-
-
- - - diff -r 52acb4877e86 -r 518970294839 contacts/contacts_element.png Binary file contacts/contacts_element.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/contacts_notification.png Binary file contacts/contacts_notification.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/contacts_picker.png Binary file contacts/contacts_picker.png has changed diff -r 52acb4877e86 -r 518970294839 contacts/tests/Overview.html --- a/contacts/tests/Overview.html Thu Dec 20 11:31:22 2012 +0200 +++ b/contacts/tests/Overview.html Wed May 25 11:45:03 2011 +0200 @@ -3,6 +3,10 @@ + + + Test Suite for the Contacts API -
-

- - W3C - -

-

Network Service Discovery

- -

W3C Working Draft 04 October 2012

-
- -
This version:
-
http://www.w3.org/TR/2012/WD-discovery-api-20121004/
-
Latest published version:
-
http://www.w3.org/TR/discovery-api/
- - -
Latest editor's draft:
-
http://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html
- - - - - -
Previous version:
-
http://www.w3.org/TR/2012/WD-discovery-api-20120807/
- - -
Editors:
-
Rich Tibbett, Opera Software ASA
-
Clarke Stevens, CableLabs
- - -
- - - - - - - - -
-
-

Abstract

-

- This specification defines a mechanism for an HTML document to discover and subsequently communicate with - HTTP-based services advertised via common discovery protocols - within the current network. -

-

Status of This Document

- - - -

- This section describes the status of this document at the time of its publication. Other - documents may supersede this document. A list of current W3C publications and the latest revision - of this technical report can be found in the W3C technical reports - index at http://www.w3.org/TR/. -

- -

- This document represents the early consensus of the group on the scope and features of the proposed API. -

- -

- This document was published by the Device APIs Working Group as a Working Draft. - - This document is intended to become a W3C Recommendation. - - If you wish to make comments regarding this document, please send them to - public-device-apis@w3.org - (subscribe, - archives). - - - All feedback is welcome. -

- -

- Publication as a Working Draft does not imply endorsement by the W3C Membership. - This is a draft document and may be updated, replaced or obsoleted by other documents at - any time. It is inappropriate to cite this document as other than work in progress. -

- - -

- - This document was produced by a group operating under the - 5 February 2004 W3C Patent Policy. - - - - - W3C maintains a public list of any patent disclosures - - made in connection with the deliverables of the group; that page also includes instructions for - disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains - Essential Claim(s) must disclose the - information in accordance with section - 6 of the W3C Patent Policy. - - -

- - - - -

Table of Contents

- -
-

1. - Introduction -

This section is non-normative.

-

- To enable Web pages to connect and communicate with Local-networked Services provided over HTTP, this - specification introduces the NavigatorNetworkService - interface. -

-

- Using this API consists of requesting a well-known - service type, known by developers and advertised by Local-networked Devices. User authorization, where the user - connects the web page to one or more discovered services, is expected before the web page is able to interact - with any Local-networked Services. -

-

- A web page creates a request to obtain connectivity to services running in the network by specifying a - well-known discovery service type that it wishes to interact with. -

-

- The user agent, having captured all advertised services on the network from the Service Discovery mechanisms - included in this recommendation, attempts to match the requested service type to a discovered service according - to the processing described herein. -

-

- If a service connectivity request is successful then the Web page is provided with the necessary information to - communicate with the authorized Local-networked Service. If the request fails then the Web page will receive an - error callback containing an error code describing the cause of Local-networked Service connectivity failure. -

-

- Once connected to a Local-networked Service the Web page can send requests and receive responses to the - Local-networked Service via the messaging format and appropriate channel inferred from the service type - authorized via the provided API. The Web page, once connected, can also receive service-pushed events, in the - messaging format supported by the Local-networked Device, if such event subscription functionality is provided - by the connected Local-networked Service. -

-
-

- Example of requesting a DNS-SD advertised service: -

-
-
function showServices( services ) {
-  // Show a list of all the services provided to the web page
-  for(var i = 0, l = services.length; i < l; i++) console.log( services[i].name );
-}
-
-navigator.getNetworkServices('zeroconf:_boxee-jsonrpc._tcp', showServices);
-
-
-

- Example of requesting a UPnP advertised service, also handling error conditions: -

-
-
function showServices( services ) {
-  // Show a list of all the services provided to the web page
-  for(var i = 0, l = services.length; i < l; i++) console.log( services[i].name );
-}
-
-function error( e ) {
-  console.log( "Error occurred: " + e.code );
-}
-
-navigator.getNetworkServices('upnp:urn:schemas-upnp-org:service:ContentDirectory:1', showServices, error);
-
-
-

- Example of requesting either a DNS-SD or UPnP advertised service: -

-
-
function showServices( services ) {
-  // Show a list of all the services provided to the web page (+ service type)
-  for(var i = 0, l = services.length; i < l; i++)
-     console.log( services[i].name + '(' + services[i].type + ')' );
-}
-
-navigator.getNetworkServices([
-  'zeroconf:_boxee-jsonrpc._tcp',
-  'upnp:urn:schemas-upnp-org:service:ContentDirectory:1'
-], showServices);
-
-

- For more detailed examples see the Examples section. -

-
-

2. Conformance

-

- As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, - and notes in this specification are non-normative. Everything else in this specification is - normative. -

-

- The key words must, must not, required, should, should not, recommended, may, - and optional in this specification are to be interpreted as described in [RFC2119]. -

- -

- Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or - "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", - "may", etc) used in introducing the algorithm. -

-

- Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements - are to be interpreted as requirements on user agents. -

-

- Conformance requirements phrased as algorithms or specific steps may be implemented in any - manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification - are intended to be easy to follow, and not intended to be performant.) -

-

- The only conformance class defined by this specification is a user agent. -

-

- User agents may impose implementation-specific limits on otherwise unconstrained inputs, - e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around - platform-specific limitations. -

-

- When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid - in development, or for performance reasons), user agents must act as if they had no support - for the feature whatsoever, and as if the feature was not mentioned in this specification. For example, if a - particular feature is accessed via an attribute in a Web IDL interface, the attribute itself would be omitted - from the objects that implement that interface - leaving the attribute on the object but making it return null - or throw an exception is insufficient. -

-
-

2.1 - Dependencies -

This specification relies on several other underlying specifications. -
-
- HTML -
-
- Many fundamental concepts from HTML are used by this specification. [HTML5] -
-
- WebIDL -
-
- The IDL blocks in this specification use the semantics of the WebIDL specification. [WEBIDL] -
-
-
-
-
-

3. - Terminology -

-

- The construction "a Foo object", where Foo is actually an interface, is sometimes - used instead of the more accurate "an object implementing the interface Foo". -

-

- The term DOM is used to refer to the API set made available to scripts in Web applications, and does not - necessarily imply the existence of an actual Document object or of any other Node - objects as defined in the DOM Core specifications. [DOM4] -

-

- An IDL attribute is said to be getting when its value is being retrieved (e.g. by author script), and - is said to be setting when a new value is assigned to it. -

-

- A valid service type is a string that begins with upnp: or zeroconf: - followed by one or more characters in the ranges U+0021, U+0023 to U+0027, U+002A to U+002B, U+002D to U+002E, - U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E. -

-

- A valid service type provided in the type attribute of the getNetworkServices() method will be matched against the - services currently contained in the list of available service records according to the algorithms - defined in this specification. -

-

- A user-agent generated callback url is a Local-network accessible URL endpoint that a user - agent generates and maintains for receiving HTTP NOTIFY requests from UPnP Event sources. It is only - required when the user agent implements UPnP Service Discovery as defined in this specification. -

-
-
-

4. - Requesting networked services -

-
[Supplemental, NoInterfaceObject]
-interface NavigatorNetworkService {
-  // Obtain a Local-networked Service
-  void getNetworkServices( in any type,
-                           in NavigatorNetworkServiceSuccessCallback successCallback,
-                           in optional NavigatorNetworkServiceErrorCallback errorCallback );
-};
-Navigator implements NavigatorNetworkService;
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface NavigatorNetworkServiceSuccessCallback {
-  void handleEvent( in NetworkServices services );
-};
-
-[NoInterfaceObject]
-interface NavigatorNetworkServiceError {
-  const unsigned short PERMISSION_DENIED_ERR = 1;
-  const unsigned short UNKNOWN_TYPE_PREFIX_ERR = 2;
-  readonly attribute unsigned short code;
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface NavigatorNetworkServiceErrorCallback {
-  void handleEvent( in NavigatorNetworkServiceError error );
-};
-
-
-

4.1 - Methods -

-
-
- window . navigator . - getNetworkServices ( type , successCallback [, errorCallback ] ) -
-
-

- Prompts the user to select one or more discovered network services that have advertised support for the - requested service type. -

-

- The type argument contains one or more valid service type tokens that the web - page would like to interact with. -

-

- If the user accepts, the successCallback is invoked, with one or more NetworkService objects as its argument. -

-

- If the user declines, the errorCallback (if any) is invoked. -

-
-
-
-

- When the getNetworkServices(type, successCallback[, - errorCallback]) method is called, the user agent must run the - following steps: -

-
    -
  1. Let requested control types be initially set to an empty array. -
  2. -
  3. If type is an array consisting of one or more valid service type tokens, then let - requested control types by the value of type, removing any non-valid service - type tokens from the resulting array. -
  4. -
  5. If type is a string consisting of one valid service type token, then let - requested control types be an array containing one item with a value of type. -
  6. -
  7. If requested control types is an array that contains at least one or more valid service type tokens then continue to the step labeled process - below. Otherwise, the user agent must queue a task to invoke errorCallback, if it is provided and is an - object of type Function, with a new NavigatorNetworkServiceError object whose code attribute has the numeric value 2 - (UNKNOWN_TYPE_PREFIX_ERR) as - its argument, abort any remaining steps and return. -
  8. -
  9. - Process: Let services found be an empty array. -
  10. -
  11. For each available service in the list of available service records run the following - steps: -
      -
    1. For each requested control type in requested control types: If available - service's type attribute equals the requested control type then let - matched service equal the value of available service and continue at the step - labeled attach below. -
    2. -
    3. Continue at the next available service. -
    4. -
    5. - Attach: If matched service is not empty then run the following steps: -
        -
      1. Let new service object be a new NetworkService object, mapping the parameters of matched - service to this new object where possible. -
      2. -
      3. Append new service object to the services found array. -
      4. -
      -
    6. -
    -
  12. -
  13. If services found is an empty array, then the user agent must - queue a task to invoke errorCallback, if it is provided and is an - object of type Function, with a new NavigatorNetworkServiceError object whose code attribute has the numeric value 1 - (PERMISSION_DENIED_ERR) as its - argument, abort any remaining steps and return. -
  14. -
  15. Return, and run the remaining steps asynchronously. -
  16. -
  17. Optionally, e.g. based on a previously-established user preference, for security reasons, or due to - platform limitations, the user agent may queue a task to invoke errorCallback, if it is provided and is an - object of type Function, with a new NavigatorNetworkServiceError object whose code attribute has the numeric value 1 - (PERMISSION_DENIED_ERR) as its - argument, abort any remaining steps and return. -
  18. -
  19. The user agent must prompt the user in a user-agent-specific manner for - permission to provide the entry script's origin with an array of NetworkService objects representing the user-authorized subset of - services found. -

    - If the user grants permission to access one or more networked services then the user agent - should include an "ongoing local-network communication" indicator. -

    -

    - If the user denies permission, then the user agent must queue a task to invoke errorCallback, if it is provided and is an - object of type Function, with a new NavigatorNetworkServiceError object whose code attribute has the numeric value 1 - (PERMISSION_DENIED_ERR) as its - argument, abort any remaining steps and return. -

    -

    - If the user never responds, this algorithm stalls on this step. -

    -
  20. -
  21. Let services be the array of one or more NetworkService objects for which the user granted permission. -
  22. -
  23. For each Object service in services, run the following sub-steps: -
      -
    1. Add the service's url parameter to the entry script origin's - URL whitelist. -
    2. -
    3. If service's type parameter begins with the DOMString "upnp:" - and the service's eventsUrl parameter is not empty then setup a UPnP Events - Subscription for service. -
    4. -
    -
  24. -
  25. Let services manager be a new NetworkServices - object. -
  26. -
  27. Set services manager's servicesAvailable attribute to the number of - services currently found in the list of available service records whose type property - matches any of the tokens requested in requested control types. -
  28. -
  29. Add the set of services to the list of authorized service records internally against - the newly created services manager object. -
  30. -
  31. The user agent must queue a task to invoke successCallback with services - manager as its argument. -
  32. -
-

- The task source for these tasks is the user interaction task source. -

-

- When a NetworkService object is provided to a Web page, the - user agent must add the url property to the entry script - origin's URL whitelist. This list enables the Web page to override and initiate cross-site resource - requests towards these URLs, and any sub-resources of these URLs, within the current entry script's origin via various existing mechanisms (e.g. Web Sockets, Server-Sent Events, - Web Messaging, XMLHttpRequest). -

-

- If the user navigates away from the current browsing context, the user agent must remove all previously whitelisted urls from the entry script origin's URL whitelist. - There is no persistence to network service selections provided to a web page. It is not possible to access - a previously white-listed networked service without the necessary user authorization in all of the - following cases: -

-
    -
  • If the current script is reloaded at any point in the same or different window. -
  • -
  • if the current script reinvokes the getNetworkServices() method at any point in its - execution. -
  • -
  • If the user navigates forward or back in their history to reload the current page. -
  • -
  • If a script is running in a different origin. -
  • -
-
-
-
-

4.2 - Error Handling -

-
-
- error . code -
-
-

- Returns the current error's error code. At the current time, this will be 1 or - 2, for which the corresponding error constants PERMISSION_DENIED_ERR and UNKNOWN_TYPE_PREFIX_ERR are - defined. -

-
-
-

- The code attribute of a NavigatorNetworkServiceError object must return the code for the error, which will be one of the following: -

-
-
- PERMISSION_DENIED_ERR - (numeric value 1) -
-
- The user or user agent denied the page permission to access any services. -
-
- UNKNOWN_TYPE_PREFIX_ERR - (numeric value 2) -
-
- No valid service type tokens were provided in the method invocation. -
-
-
-
-
-

5. - Obtaining networked services -

-

- The NetworkServices interface is the top-level response object from - a call to getNetworkServices() and provides access - to a set of user-authorized NetworkService objects for the given - request. -

-
[NoInterfaceObject]
-interface NetworkServices {
-  readonly attribute unsigned long    length;
-  getter NetworkService (unsigned long index);
-  NetworkService? getServiceById(DOMString id);
-
-  readonly attribute unsigned long    servicesAvailable;
-
-  // event handler attributes
-           attribute EventHandler     onserviceavailable;
-           attribute EventHandler     onserviceunavailable;
-
-};
-
-NetworkServices implements EventTarget;
-
-
-

5.1 - Attributes -

-
-
- length -
-
-

- Returns the current number of services belonging in the respective object's list of authorized service - records. -

-
-
- servicesAvailable -
-
-

- Returns the current number of services matching one of the app-requested valid service type tokens - in the list of available service records. -

-
-
-
-

- The length attribute must - return the number of services represented in the object's corresponding list of authorized service - records at the time of getting. -

-

- The servicesAvailable attribute - must return the number of services in the list of available service records - whose type attribute matches any of the valid service type tokens that was initially - used to create the current NetworkServices object. -

-
-
-
-

5.2 - Methods -

-
-
- services [ index ] -
-
-

- Returns the specified NetworkService object. -

-
-
- services . getServiceById ( id ) -
-
-

- Returns the NetworkService object with the given identifier, - or null if no service has that identifier. -

-
-
-

- A NetworkServices object represents the current list of one or - more current authorized services - the list of authorized service records. Each item in the list of - authorized service records is represented by a NetworkService - object. The list of authorized service records is immutable meaning that it cannot be - modified for the lifetime of a NetworkServices object. -

-
Note

- Each service in a NetworkServices object thus has an index; the - first has the index 0, and each subsequent service is numbered one higher than the previous one. -

-

- The supported property indices of NetworkServices objects at any instant are the numbers from zero to - the number of items in the list of authorized service records represented by the respective object - minus one, if any services are represented in the list of authorized service records. -

-

- To determine the value of an indexed property for a given index index in a - NetworkServices object's list of authorized service - records, the user agent must return the NetworkService object that represents the indexth service in - the list of authorized service records. -

-

- The getServiceById(id) method must return the first NetworkService object in the - list of authorized service records represented by the respective object whose id attribute is equal to the value of the id argument. - When no services in the list of authorized service records match the given argument, the method - must return null. -

-

- Services available within the local network can connect and disconnect at different times during the - execution of a web page. A user agent can inform a web page when the state of networked services - matching the requested valid service type change. Web pages can use this information to enable in-page - experiences for communicating the state of networked services with the ability to change the particular - service or set of services the page is connected to by re-invoking the getNetworkServices() method. -

-
-
-

5.3 - Events -

-

- The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the NetworkServices interface: -

- - - - - - - - - - - - - - - - - -
- Event handler - - Event handler event type -
- onserviceavailable - - serviceavailable -
- onserviceunavailable - - serviceunavailable -
-
-
-
-

6. - Communicating with a networked service -

-

- The NetworkService interface is used to provide a set of connection - information for an HTTP service endpoint and if available, service events, running on a networked device. -

-
[NoInterfaceObject]
-interface NetworkService {
-  readonly attribute DOMString        id;
-  readonly attribute DOMString        name;
-  readonly attribute DOMString        type;
-  readonly attribute DOMString        url;
-  readonly attribute DOMString        config;
-
-  readonly attribute boolean          online;
-
-  // event handler attributes
-           attribute EventHandler     onserviceonline;
-           attribute EventHandler     onserviceoffline;
-
-           attribute EventHandler     onnotify;
-};
-
-NetworkService implements EventTarget;
-
-
-

6.1 - Attributes -

-
-
- service . id -
-
-

- A unique identifier for the given user-selected service instance. -

-
-
- service . name -
-
-

- The name of the user-selected service. -

-
-
- service . type -
-
-

- The valid service type token value of the user-selected service. -

-
-
- service . url -
-
-

- The control URL endpoint (including any required port information) of the user-selected control service - that has been added to the entry script origin's URL whitelist. -

-
-
- service . config -
-
-

- The configuration information associated with the service depending on the requested service type. -

-
-
-

- The id attribute is a unique identifier for the service. - The same service provided at different times or on different objects must have the same - id value. -

-

- The name attribute represents a human-readable title for - the service. -

-

- The type attribute reflects the value of the valid - service type of the service. -

-

- The url attribute is an absolute URL pointing to the root HTTP endpoint for the service that has been - added to the entry script origin's URL whitelist. Web pages can subsequently use this value for - implicit cross-document messaging via various existing mechanisms (e.g. Web Sockets, Server-Sent Events, - Web Messaging, XMLHttpRequest). -

-

- The config attribute provides the raw configuration - information extracted from the given network service. -

-
-
-

6.2 - States -

-
-
- service . online -
-
-

- Returns true if the service is reporting that it is accessible on the local network or - false if the service is reporting that it is no longer accessible (temporarily or - permanently) on the local network. -

-
-
-

- The online attribute indicates whether the service is - reporting itself as being either online, and therefore accessible on the local network, in which - case this attribute will return true or, offline, and therefore not accessible on the - local network, either temporarily or permanently, in which case this attribute will return - false. This attribute must default to true. -

-
-
-

6.3 - Events -

-

- The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by all objects implementing the NetworkService interface: -

- - - - - - - - - - - - - - - - - - - - - -
- Event handler - - Event handler event type -
- onnotify - - notify -
- onserviceonline - - serviceonline -
- onserviceoffline - - serviceoffline -
-
-
-
-

7. - Service Discovery -

-

- A user agent conforming to this specification may implement SSDP [UPNP-DEVICEARCH11] and Zeroconf [DNS-SD] + [MDNS] - service discovery mechanisms to enable Web pages to request and connect with HTTP services running on networked - devices, discovered via either mechanism, through this API. When a user agent implements either of these - service discovery mechanisms, then it must conform to the corresponding algorithms provided - in this section of the specification. -

-

- This section presents how the results of these two service discovery mechanisms will be matched to requested - service types, how the user agent stores available and active services, how their properties are applied to any - resulting NetworkService objects. -

-

- It is expected that user agents will perform these service discovery mechanisms asynchronously and - periodically update the list of networked devices as required. The timing of any service discovery - mechanisms is an implementation detail left to the discretion of the implementer (e.g. once on user agent - start-up, every X seconds during user agent execution or on invocation of this API from a Web page). -

-

- The list of available service records is a single dynamic internal lookup table within user agents - that is used to track all the services that have been discovered and are available in the current network at - any given time. At any point during the running of either of the two service discovery mechanisms then existing - entries within this table can be updated, entries can be added and entries can be removed as the status of - networked services changes according to the rules defined in this specification. -

-

- The list of authorized service records is a single dynamic internal lookup table within user agents - that is used to track the current services that are being shared with web pages at any given time from the - list of available service records. Each record in the list of authorized service records is - associated with a services manager object that is assigned as part of the getNetworkServices() algorithm. -

-

- The rule for adding an available service is the process of adding a new service or updating an - existing service in the list of available service records that is generally available on the user's - current network. This rule takes one argument, network service record, and consists of running the - following steps: -

-
    -
  1. Let new service registration flag be true. -
  2. -
  3. For each existing service record in the current list of available service records, run - the following sub-steps: -
      -
    1. If the existing service record's id property does not equal network - service record's id property then abort any remaining sub-steps and continue at the next - available existing service record. -
    2. -
    3. Set new service registration flag to false. -
    4. -
    5. Replace the value of existing service record in the current list of available service - records with the value of network service record. -
    6. -
    -
  4. -
  5. If new service registration flag is set to true then add network service - record to the list of available service records as a new entry. -
  6. -
  7. For each active service in the list of authorized service records run the following - steps: -
      -
    1. If network service record's type property does not equal the current - active service's type attribute then abort any remaining sub-steps for this - active service and continue at the next available active service. -
    2. -
    3. If the new service registration flag is set to true then increment the - servicesAvailable attribute of the - services manager associated with the current active service object by - 1 and then queue a task to dispatch a newly created event with the name serviceavailable that uses the Event interface, which does not bubble, is not cancellable, and - has no default action, at the services manager associated with the current active - service object. -
    4. -
    5. Set active service's online attribute - to true and then queue a task to dispatch a newly created event with the name serviceonline that uses the Event interface, which does not bubble, is not cancellable, and - has no default action, at the current active service object. -
    6. -
    -
  8. -
-

- The rule for removing an available service is the general process of removing a service from the - list of available service records that has left the user's current network or has otherwise expired. - This rule takes one argument, service identifier, and consists of running the following steps: -

-
    -
  1. For each existing service record in the current list of available service records, run - the following sub-steps: -
      -
    1. If the existing service record's id property does not match service - identifier then skip any remaining sub-steps for the current existing service record and - continue at the next available existing service record. -
    2. -
    3. If the existing service record's type property begins with the DOMString - "upnp:" and existing service record's eventsURL property is set then - run the rule to terminate an existing UPnP Events Subscription, if one is currently active (as a - result of having previously called setup a UPnP Events Subscription against the current - existing service record). -
    4. -
    5. For each active service in list of authorized service records run the following - steps: -
        -
      1. If existing service record's type property does not equal the current - active service's type attribute then abort any remaining sub-steps for this - active service and continue at the next available active service. -
      2. -
      3. Decrement the servicesAvailable - attribute of the services manager associated with the current active service - object by 1 and then queue a task to dispatch a newly created event with the name serviceunavailable that uses the Event interface, which does not bubble, is not cancellable, - and has no default action, at the services manager associated with the current - active service object. -
      4. -
      5. Set active service's online - attribute to false and then queue a task to dispatch a newly created event with the name serviceoffline that uses the Event interface, which does not bubble, is not cancellable, - and has no default action, at the current active service object. -
      6. -
      -
    6. -
    7. Remove existing service record from the current list of available service records. -
    8. -
    -
  2. -
-

- User agents should expire a service record from the list of available service - records when its expiryTimestamp attribute exceeds the current UTC timestamp. When this - condition is met the user agent should run the rule for removing an available service, passing in - the expired service record's id attribute as the only argument. -

-
-

7.1 - Zeroconf (mDNS + DNS-SD) -

-

- For each DNS response received from a user-agent-initiated Multicast DNS Browse for PTR records with the name _services._dns-sd._udp on the resolved - recommended automatic browsing domain [MDNS], the user agent must run the - following steps: -

-
    -
  1. Let service mDNS responses be an array of PTR records received by issuing a Multicast DNS - Browse for PTR records with the name of the current discovered service type. -
  2. -
  3. For each Object service mDNS response in service mDNS responses, run the following - steps: -
      -
    1. Let network service record be an Object consisting of the following empty properties: - id, name, type, url, config, - expiryTimestamp. -
    2. -
    3. Set network service record's id property to the value of the full PTR Service - Instance Name [MDNS]. -
    4. -
    5. Set network service record's name property to the value of the PTR Service - Instance Name's Instance component [MDNS]. -
    6. -
    7. Set network service record's type property to the concatenation of the string - zeroconf: followed be the value of the PTR Service Instance Name's Service - component [MDNS]. -
    8. -
    9. Set network service record's url property to the resolvable Service URL - obtained from performing an DNS-SD Lookup [DNS-SD] of the current service from the PTR record provided - [MDNS]. -
    10. -
    11. Set network service record's config property to the string value of the - contents of the first DNS-SD TXT record associated with the service mDNS response as defined - in [DNS-SD]. -
    12. -
    13. Set network service record's expiryTimestamp property to the value of the - current date, in UTC timestamp format, plus a value of 120 seconds. -
    14. -
    15. Run the general rule for adding an available service, passing in the current network - service record as the only argument. -
    16. -
    -
  4. -
-
-
-

7.2 - Simple Service Discovery Protocol (SSDP) -

-

- A user agent that implements UPnP service discovery must issue an advertisement for - UPnP root devices against the user's current local network according to the full normative text and - timing provided in 'Section 1.3.2: Search request with M-SEARCH' detailed in [UPNP-DEVICEARCH11]. -

-

- The user agent must issue all advertisements for UPnP root devices with a HTTP request line equal - to M-SEARCH * HTTP/1.1, with a HOST header equal to the reserved multicast address and port of - 239.255.255.250:1900, a MAN header equal to ssdp:discover, an ST header equal to - upnp:rootdevice and a user-agent defined MX header equal to a maximum UPnP advertisement - response wait time value between 1 and 5 seconds. -

-

- The user agent must listen for incoming requests and process any incoming responses to - any advertisement for UPnP root devices on the standard UPnP address and port, on all - current local network interface addresses with the port 1900, according to the rules defined in - this section. -

-

- For each HTTP Response following an initial advertisement for UPnP root devices sent on a - standard UPnP address and port the user agent must run the following steps: -

-
    -
  1. If the HTTP Response is not a HTTP 200 OK response then this response is invalid and the user - agent must discard this response, abort any remaining steps and return. The user agent - may issue a new advertisement for UPnP root devices as a result of this error - occurring. -
  2. -
  3. If the maximum UPnP advertisement response wait time has been exceeded since the initial - advertisement for UPnP root devices was sent then the HTTP Response is invalid and the user - agent must discard this response, abort any remaining steps and return. -
  4. -
  5. Let ssdp device be an Object with a property for each HTTP header received in the HTTP - Response, with each key being the name of a HTTP response header and each value being that HTTP response - header's value. -
  6. -
  7. If ssdp device does not contain at least one CACHE-CONTROL entry, at least one - USN entry, at least one ST entry and at least one LOCATION entry or the - value of its ST entry is not upnp:rootdevice, then the HTTP Response is - invalid and the user agent must discard this response, abort any remaining steps - and return. -
  8. -
  9. The user agent must run the rule for obtaining a UPnP Device Description File - passing in the first occurrence of LOCATION from ssdp device as the device - descriptor URL argument and the first occurrence of USN from ssdp device as the - device identifier argument and the first occurrence of CACHE-CONTROL from ssdp - device as the device expiry argument. -
  10. -
-

- For each HTTP Request received on a standard UPnP address and port the user agent - must run the following steps: -

-
    -
  1. If the HTTP Request is not a HTTP NOTIFY request then it is not a valid UPnP Request and the user - agent must return a HTTP 200 OK response, discard this request, abort any remaining steps - and return. -
  2. -
  3. Let ssdp device be an Object with a property for each HTTP header received in the HTTP - Request, with each key being the name of a HTTP header and each value being that HTTP header's value. -
  4. -
  5. If ssdp device does not contain at least one CACHE-CONTROL entry, at least one - USN entry, at least one NT entry, at least one NTS entry and at least one - LOCATION entry or the value of its NT entry is not upnp:rootdevice, then - the HTTP Request is a malformed UPnP Request and the user agent must return - a 400 Bad Request response, discard this request, abort any remaining steps and return. -
  6. -
  7. If ssdp device's NTS entry is equal to ssdp:alive or - ssdp:update then the user agent must run the rule for obtaining a UPnP - Device Description File passing in the first occurrence of LOCATION from ssdp - device as the device descriptor URL argument and the first occurrence of USN from - ssdp device as the device identifier argument and the first occurrence of - CACHE-CONTROL from ssdp device as the device expiry.
    -
    - Otherwise, if ssdp device's NTS entry is equal to ssdp:byebye then the - user agent must run the rule for removing all services from a registered UPnP - Device passing in the first occurrence of USN from ssdp device as the device - identifier argument. -
  8. -
-

- The rule for obtaining a UPnP Device Description File is the process of obtaining the contents of - a standard UPnP Device Description [UPNP-DEVICEARCH11] from a URL-based resource. This rule takes three - arguments - device descriptor URL, device identifier and device expiry - and - when called the user agent must run the following steps: -

-
    -
  1. Let device descriptor file contain the contents of the file located at the URL provided in - device descriptor URL obtained according to the rules defined in 'Section 2.11: Retrieving a - description using HTTP' in [UPNP-DEVICEARCH11]. -
  2. -
  3. If the value provided in device descriptor URL cannot be resolved as a reachable URL on the - current network or the root device descriptor file remains empty then it is invalid and the - user agent must abort any remaining steps and return. -
  4. -
  5. Run the rule for processing a UPnP Device Description File, passing in the current device - descriptor file, device identifier and device expiry arguments. -
  6. -
  7. If the current device descriptor file contains a <deviceList> element then - for each <device> element within <deviceList> - herein known as an - embedded device descriptor file - the user agent must run the rule for - processing a UPnP Device Description File, passing in the current embedded device descriptor - file as the device descriptor file argument, along with the common device - identifier and device expiry arguments. -
  8. -
-

- The rule for processing a UPnP Device Description File is the process of parsing the contents of a - standard UPnP Device Description [UPNP-DEVICEARCH11] and registering the UPnP services contained therein - within the list of available service records. -

-

- The rule for processing a UPnP Device Description File takes three arguments - device descriptor - file, device identifier and device expiry - and when called the user agent - must run the following steps: -

-
    -
  1. Let advertised services be a list of all advertised services obtained from the device - descriptor file containing the value of the first occurrence of the <serviceList> - element as it is defined in 'Section 2.3: Device Description' in [UPNP-DEVICEARCH11]. -
  2. -
  3. For each <service> element - known as an advertised service - in - advertised services run the following steps: -
      -
    1. Let network service record be a new Object consisting of the following empty properties: - id, deviceId, name, type, url, - eventsUrl, config, expiryTimestamp. -
    2. -
    3. Set network service record's id property to the concatenated string value of - device identifier with the advertised service's <serviceId> - sub-element. -
    4. -
    5. Set network service record's deviceId property to the value of device - identifier. -
    6. -
    7. Set network service record's name property to the string value of the first - occurrence of the advertised service's <serviceId> sub-element. -
    8. -
    9. Set network service record's type property to the concatenation of the string - upnp: followed by the string value of the first occurrence of the advertised - service's <serviceType> sub-element. -
    10. -
    11. Set network service record's url property to the string value of the first - occurrence of the advertised service's <controlURL> sub-element. -
    12. -
    13. Set network service record's config property to the string value of the - contents of the first occurrence of the <device> element in the device descriptor - file. -
    14. -
    15. If advertised service's <eventSubURL> sub-element is not empty, then - set network service record's eventsUrl property to the string value of the first - occurrence of the advertised service's <eventSubURL> sub-element. - Otherwise, do not set network service record's eventsUrl property. -
    16. -
    17. Set network service record's expiryTimestamp property to the value of the - current date, in UTC timestamp format, plus the value of device expiry. -
    18. -
    19. Run the general rule for adding an available service, passing in the current network - service record as the only argument. -
    20. -
    -
  4. -
-

- The rule for removing all services from a registered UPnP Device is the process of removing all - services associated with a device from the list of available service records that has left the user's - current network or has otherwise timed out or expired. This rule takes one argument, device - identifier, and consists of running the following steps: -

-
    -
  1. For each existing service record in the current list of available service records, run - the following sub-steps: -
      -
    1. If the existing service record's deviceId property does not match device - identifier then skip any remaining sub-steps for the current existing service record and - continue at the next available existing service record. -
    2. -
    3. Run the general rule for removing an available service passing in existing service - record's id property as the only argument. -
    4. -
    -
  2. -
-

- When the user agent is to setup a UPnP Events Subscription, it is to run the following - steps with the current network service record object as defined in 'Section 4.1.2: SUBSCRIBE with - NT and CALLBACK' in [UPNP-DEVICEARCH11]: -

-
    -
  1. If network service record's eventsUrl property is empty then the user - agent must abort these steps. -
  2. -
  3. Let callback URL be the value of creating a new user-agent generated callback url. -
  4. -
  5. Send a HTTP SUBSCRIBE request with a NT header with a string value of upnp:event, a - TIMEOUT header with a user-agent defined timeout value (in the form Second-XX where - XX is the user-agent defined timeout value in seconds) and a CALLBACK header with a - string value of callback URL towards the network service record's - eventsUrl property. -
  6. -
  7. If a non-200 OK response is received from the HTTP SUBSCRIBE request then the user agent - must abort these steps. -
  8. -
  9. On receiving a valid 200 OK response, run the following steps: -
      -
    1. Let callback ID equal the string value of the first included SID header, if it - exists. -
    2. -
    3. Let timeout date equal the sum of the current UTC date value plus the integer value of the - first included TIMEOUT header (minus the leading string of Second-), if it exists. -
    4. -
    5. Run the following steps asynchronously and continue to the step labeled listen below. -
    6. -
    7. - Refresh Subscription: Run the following steps at a set interval (X) within the user - agent: -
        -
      1. Let current date equal the current UTC date. -
      2. -
      3. If current date is less than the timeout date then continue to the step - labeled refresh subscription above. -
      4. -
      5. Send a HTTP SUBSCRIBE request with a SID header with the string value of callback - ID and a user-agent defined TIMEOUT header (in the form Second-XX where - XX is the user-agent defined timeout value in seconds) towards the network service - record's eventsUrl property. -
      6. -
      7. On receiving a valid 200 OK, update callback ID with the string value of the first - included SID header, if it exists. All other HTTP responses should cause the user - agent to continue from the step labeled refresh subscription above. -
      8. -
      -
    8. -
    9. - Listen: For each HTTP NOTIFY request received at the callback URL the user - agent is to run the following steps: -
        -
      1. Let content clone be the result of obtaining the message body of the HTTP NOTIFY - request. If content clone is empty, then the user agent must - abort these steps. -
      2. -
      3. Let notification event be a new simple event that uses the Event interface with the name notify, which does not bubble, is not cancellable, and has no - default action. -
      4. -
      5. Let the data attribute of notification event have the DOMString value of - content clone. -
      6. -
      7. - Queue a task to dispatch notification event at the current - NetworkService object. -
      8. -
      -
    10. -
    -
  10. -
-

- A user agent can terminate an existing UPnP Events Subscription at any time for any - active service in the list of authorized service records by sending an HTTP UNSUBSCRIBE - request - as defined in 'Section 4.1.4: Cancelling a subscription with UNSUBSCRIBE' in [UPNP-DEVICEARCH11] - - with a HOST header set to that active service's eventsUrl property and a SID header - set to the callback ID obtained when the initial setup a UPnP Events Subscription action - occurred. -

-
-
-

7.3 - Network Topology Monitoring -

-
-

- When the user agent detects that the user has dropped from their connected network then, for each - existing service record in the list of available service records, the user agent - must run the general rule for removing an available service passing in each - existing service record's id property as the only argument for each call. -

-

- When the user agent detects that the user has connected to a new network or reconnected to an - existing network, then it should restart its discovery mechanisms as defined in the - Service Discovery section of this specification, maintaining the existing - list of authorized service records currently in use. -

-
-
-
-
-

8. - Events Summary -

-

- The following events are dispatched on the NetworkServices and/or - NetworkService objects: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Event name - - Interface - - Dispatched when... -
- serviceavailable - - Event - - When a new service that matches one of the requested type tokens is found in the current network. -
- serviceunavailable - - Event - - When an existing service that matches one of the requested type tokens gracefully leaves or - expires from the current network. -
- serviceonline - - Event - - When a current service renews its service registration within the current network. -
- serviceoffline - - Event - - When a current service gracefully leaves or otherwise expires from the current network. -
- notify - - Event - - When a valid UPnP Events Subscription Message is received on a user-agent generated callback url - for a current service. This event never fires for Zeroconf-based services. -
-
-
-

9. - Garbage collection -

-

- Only when the user navigates away from the current browsing context can NetworkService - objects be garbage-collected, its records in the entry script origin's URL whitelist be removed and its - corresponding entry in the list of authorized service records be removed according to passing each - expired object identifier through the rule for removing an available service. -

-
-
-

10. - Use Cases and Requirements -

-

- This section covers what the requirements are for this API, as well as illustrates some use cases. -

- -
-
-

A. - Examples -

This section is non-normative.

-
-

- This sample code exposes a button. When clicked, this button is disabled and the user is prompted to offer a - network service. The user may also select multiple network services. When the user has authorized a network - service to be connected to the web page then the web page issues a simple command to get a list of all the - albums stored on the connected media player service. -

-

- The button is re-enabled only when the connected network service disconnects for whatever reason (the service - becomes unavailable on the network, the user disconnects from their current network or the user revokes - access to the service from the current web page). At this point the user can re-click the button to select a - new network service to connect to the web page and the above steps are repeated. -

-

- The provided service type identifier and service interaction used in this example is based on the - well-defined service type and messaging format supported by the XBMC Media - Server. -

-
-
<input type="button" value="Start" onclick="start()" id="startBtn"/>
-<div id="debugconsole"></div>
-
-<script>
- var startBtn = document.getElementById('startBtn'),
-     debug = document.getElementById('debugconsole');
-
- function start() {
-   if(navigator.getNetworkServices) {
-      navigator.getNetworkServices('zeroconf:_xbmc-jsonrpc._tcp', gotXBMCService, error);
-      startBtn.disabled = true;
-   } else {
-      debug.innerHTML += "<br>Service Discovery not supported!"