W3C home > Mailing lists > Public > public-dap-commits@w3.org > December 2009

2009/dap/contacts Overview.html,1.19,1.20

From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
Date: Wed, 16 Dec 2009 16:15:36 +0000
To: public-dap-commits@w3.org
Message-Id: <E1NKwXI-0004LK-Oh@lionel-hutz.w3.org>
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv16674

Modified Files:
	Overview.html 
Log Message:
Latest editorial updates based on mailing list feedback:

http://lists.w3.org/Archives/Public/public-device-apis/2009Dec/0214.html
http://lists.w3.org/Archives/Public/public-device-apis/2009Dec/0219.html

Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -d -r1.19 -r1.20
--- Overview.html	11 Dec 2009 16:28:36 -0000	1.19
+++ Overview.html	16 Dec 2009 16:15:34 -0000	1.20
@@ -25,22 +25,22 @@
         </section>
         <section id='conformance'>
             <p>
-                This specification defines conformance criteria that apply to a single product:
+                This specification defines conformance criteria that apply to a single product: the
                 <dfn>
-                    user agents
+                    user agent
                 </dfn>
-                that implement the interfaces that it contains.
+                that implements the interfaces that it contains.
             </p>
         </section>
         <section class="informative">
             <h2>Introduction</h2>
             <p>
-                The Contacts API defines a high-level interface to Contacts information, such as names, addresses and other contact information. The API itself is agnostic of any underlying address book sources.
-            </p>
-            <p>
-                The requirements for this set of interfaces are listed in the Device API Requirements
-                document [[DAP-REQS]].
+            	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. 
             </p>
+			<p>
+				The API itself is agnostic of any underlying address book sources and data formats.
+			</p>
             <section>
                 <h2>Usage Examples</h2>
                 <p>
@@ -85,14 +85,12 @@
                     <pre class='example sh_javascript_dom'>// previous example follow-on...
 
 function successContactCallback(updatedContact) {
-    // keep myContact updated
-    myContact = this.updatedContact;	
     // do something with resulting contact object
     // ...
 }
 
 // Add new contact
-myContact.commit(successContactCallback, genericErrorCB);</pre>
+myContact.save(successContactCallback, genericErrorCB);</pre>
                 </div>
 				
                 <div>
@@ -105,7 +103,7 @@
 myContact.phones.push({types: ['home'], value: '+440000000002'});
 
 // Update existing contact
-myContact.commit(successContactCallback, genericErrorCB);</pre>
+myContact.save(successContactCallback, genericErrorCB);</pre>
                 </div>
 				
                 <div>
@@ -132,12 +130,7 @@
 				
 				<br /><br />There are a number of reasons for this approach:
 				
-				<br /><br />1. Very long discussions have been held in the <a href='http://lists.w3.org/Archives/Public/public-geolocation/'>Geolocation WG mailing lists</a> on the subject of security and privacy. It makes 
-				a lot of sense to continue discussions where the Geolocation WG left-off rather than cover the same basic ground again, because:
-				
-				<br /><br />1a. While many proposals were submitted and discussed within the Geolocation WG, the primary issue revolved around the inability to reach concensus on any specific security and privacy mechanisms to include in the specification.
-				
-				<br /><br />1b.  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
+				<br /><br />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.
 				
 				<br /><br />2. The ability to align the security and privacy considerations of the Geolocation API with DAP APIs is important for the potential future benefit 
@@ -157,23 +150,23 @@
 				<h2>Privacy considerations for implementors of the Contacts API</h2>
 				
 				<p>
-					User Agents MUST NOT create, retrieve, update or delete contact information to Web sites without the express permission 
-					of the user. User Agents 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]]. 
+					A <a>user agent</a> must not create, retrieve, update or delete contact information to Web sites without the express permission 
+					of the user. A <a>user agent</a> 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 User Agents MUST respect revoked permissions.
+					MUST be revocable and a <a>user agent</a> must respect revoked permissions.
 				</p>
 				
 				<p>
-					<strong>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.</strong> 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 
+					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. 
 				</p>
 				
 				<p>
-					Some User Agents will have prearranged trust relationships that do not require such user interfaces. For example, 
+					A <a>user agent</a> 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.					
@@ -230,7 +223,7 @@
 				<h2><a>DeviceContacts</a> interface</h2>
 				
 				<p>
-					The Contacts interface is typically exposed on the <code>navigator.device</code> object, as defined in [[CORE-DEVICE]]. 
+					The <a href='#devicecontacts-interface'><code>DeviceContacts</code></a> interface is exposed on the <code>navigator.device</code> object, as defined in [[CORE-DEVICE]]. 
 				</p>
 				
 				<div class='idl' title='Device implements DeviceContacts'></div>
@@ -240,7 +233,7 @@
 						readonly attribute Contacts contacts
 					</dt>
 					<dd>
-						The root node from which the contacts functionality can be accessed from the DOM.
+						The root node from which the contacts functionality can be accessed.
 					</dd>
 				</dl>
 				
@@ -251,15 +244,13 @@
                 <h2><a>Contacts</a> interface</h2>
 				
                 <p>
-                    The <a>Contacts</a>
-                    interface exposes an interface to a database collecting contacts information,
-                    such that they may be created, found, read, updated, and deleted. 
+                    The <a>Contacts</a> interface exposes a database collecting contacts information, such that they may be created, found, 
+					read, updated, and deleted. 
 				</p>
 				
 				<p>
 					Multiple address books, taken
-				from different sources, can be represented within this unified address book by specifying a consistent <a href='#widl-ContactProperties-serviceId'><code>serviceId</code></a>
-				value as part of individual <a href="#contact-interface"><code>Contact</code></a> objects. In addition, multiple address books can be displayed by filtering 
+				from different sources, can be represented within this unified address book interface. Contacts from different sources can be distinguished using the <a href='#widl-ContactProperties-serviceId'><code>serviceId</code></a> field.. In addition, multiple address books can be displayed by filtering 
 				on the required <a href='#widl-ContactProperties-serviceId'><code>serviceId</code></a> value via the <code>Contacts</code> <a href='#widl-Contacts-find'>find()</a> function.
 				</p>
 				
@@ -273,11 +264,10 @@
                     <dt>
                         Contact create ()
                     </dt>
-                    <dd>
-                    	
+                    <dd>                    	
 						Create a new <code>Contact</code> object. 
 						
-						<p>This method takes one argument. When called, it must immediately return 
+						<p>This method takes one argument. When called, it returns 
 						a <a href='#contact=interface'><code>Contact</code></a> object.</p>
 						
                         <dl class='parameters'>
@@ -290,23 +280,20 @@
                         </dl>
                     </dd>
 
-
-
-
                     <dt>
                         PendingOp find ()
                     </dt>
                     <dd>
                     	<p>Find contacts in the address book based on a <a href='#contactproperties-interface'><code>ContactProperties</code></a> object acting as a filter.</p>
 						
-						<p>This method takes two, three or four arguments. When called, it must immediately return 
-						a <code>PendingOp</code> object , as defined in [[CORE-DEVICE]], and then asynchronously start a <dfn>find contacts process</dfn> defined as follows:</p> 
+						<p>This method takes two, three or four arguments. When called, it immediately returns 
+						a <code>PendingOp</code> object , as defined in [[CORE-DEVICE]], and then asynchronously starts a <dfn>find contacts process</dfn> defined as follows:</p> 
 						
 						<p>		
 							<ol>
 								<li>Search for contacts in the address book according to the <a href='#contact-search-processing-rules'>contact search processing rules</a>.</li> 
 								<li>If successful, invoke the associated <code>successCB</code>. 
-						If the attempt fails, and the method was invoked with a non-null <code>errorCB</code> argument, this method must 
+						If the attempt fails, and the method was invoked with a non-<code>null</code> <code>errorCB</code> argument, this method must 
 						invoke the <code>errorCB</code> with a <a href='#contacterror-interface'><code>ContactError</code></a> object as an argument.</li>
 							</ol>
                         </p>
@@ -328,13 +315,13 @@
                                 optional ErrorCB errorCB
                             </dt>
                             <dd>
-                                Function to call when the asynchronous operation fails. This parameter is OPTIONAL.
+                                Function to call when the asynchronous operation fails. 
                             </dd>
                             <dt>
                                 optional ContactOptions options
                             </dt>
                             <dd>
-                                The options to apply to the output of this method. This parameter is OPTIONAL.
+                                The options to apply to the output of this method. 
                             </dd>
                         </dl>
                     </dd>
@@ -347,17 +334,12 @@
 				
                 <p>The <a href="#contact-interface"><code>Contact</code></a> interface captures a single contact item. This interface extends <a href='#contactproperties-interface'><code>ContactProperties</code></a> attributes.</p>
 				
-				<p>All <a href="#contact-interface"><code>Contact</code></a> objects MUST include ALL attributes supported by the implementation, regardless of whether these attributes have been assigned a non-<code>NULL</code> value or a <code>NULL</code> 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 <a href="#contact-interface"><code>Contact</code></a> object and MUST have a value of <code>NULL</code>.</p>
+				<p>All <a href="#contact-interface"><code>Contact</code></a> objects MUST include all attributes supported by the implementation, regardless of whether these attributes have been assigned a non-<code>null</code> value or a <code>null</code> 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 <a href="#contact-interface"><code>Contact</code></a> object and MUST have a value of <code>null</code>.</p>
 				
-				<p>Each resulting <a href="#contact-interface"><code>Contact</code></a> object MUST include a non-NULL <a href='#widl-ContactProperties-name'><code>name</code></a> attribute. 
+				<p>Each resulting <a href="#contact-interface"><code>Contact</code></a> object MUST include a non-<code>null</code> <a href='#widl-ContactProperties-name'><code>name</code></a> attribute. 
 				All other attributes MAY be optionally assigned a value by the user and/or implementation.</p>
-				
-				<p>In the case that the current <a href="#contact-interface"><code>Contact</code></a> object <a href='#widl-ContactProperties-name'><code>name</code></a> attribute is <code>NULL</code> and a <a href="#contact-interface"><code>Contact</code></a> 
-				object <a href="#widl-Contact-commit">commit()</a> method is invoked, an <a href='#errorcallback-interface'><code>ErrorCB</code></a> MUST be 
-				triggered consisting of a <a href="#contacterror-interface"><code>ContactError</code></a> object with a <a href='#widl-ContactError-code'><code>code</code></a> of 
-				<a href='#widl-ContactError-INVALID_ARGUMENT_ERROR'><code>ContactError::INVALID_ARGUMENT_ERROR</code></a>.</p>
-						
+									
                 <dl title='[NoInterfaceObject] interface Contact : ContactProperties' class='idl'>
                     <dt>
                         readonly attribute DOMString id
@@ -374,33 +356,39 @@
                         Contact clone ()
                     </dt>
                     <dd>                    	
-                        <p>Create an exact copy of the current object minus the current object's <a href='#widl-Contact-id'><code>id</code></a> attribute.</p>
+                        <p>Create a deep clone copy of the current object minus the current object's <a href='#widl-Contact-id'><code>id</code></a> attribute.</p>
 						
 						<p>The resulting object MUST be provided with a newly generated <a href='#widl-Contact-id'><code>id</code></a> attribute to distiguish the cloned object from the original object.</p>	
                     </dd>
                     <dt>
-                        PendingOp commit ()
+                        PendingOp save ()
                     </dt>
                     <dd>						
                     	<p>Add or update (as appropriate) the current <a href="#contact-interface"><code>Contact</code></a> object to the <a href="#contacts-interface"><code>Contacts</code></a>.</p>
+
+						<p>
+							In the case that the <a href='#widl-ContactProperties-name'><code>name</code></a> attribute is <code>null</code> and this method is invoked, an <a href='#errorcallback-interface'><code>ErrorCB</code></a> MUST be 
+							triggered as part of the <a>save contact process</a>. This error MUST consist of a <a href="#contacterror-interface"><code>ContactError</code></a> object with a <a href='#widl-ContactError-code'><code>code</code></a> of 
+							<a href='#widl-ContactError-CONTACT_INVALID_ERROR'><code>ContactError::CONTACT_INVALID_ERROR</code></a>.
+						</p>
 						
-						<p>This method takes one or two arguments. When called, it must immediately return 
-						a <code>PendingOp</code> object , as defined in [[CORE-DEVICE]], and then asynchronously start a <dfn>commit contact process</dfn> defined as follows:</p> 
+						<p>This method takes one or two arguments. When called, it immediately returns 
+						a <code>PendingOp</code> object , as defined in [[CORE-DEVICE]], and then asynchronously starts a <dfn>save contact process</dfn> defined as follows:</p> 
 
 						<p>		
 							<ol>
 								<li>If the <a href='#widl-Contact-id'><code>Contact.id</code></a> already exists in <a href='#contacts-interface'><code>Contacts</code></a> then update the existing object in <a href='#contacts-interface'><code>Contacts</code></a>.</li>
-								<li>If a current <a href='#widl-Contact-id'><code>Contact.id</code></a> value does not current exist in <a href='#contacts-interface'><code>Contacts</code></a> OR the current <a href='#widl-Contact-id'><code>Contact.id</code></a> value has not been set, add the current object as a new object to <a href='#contacts-interface'><code>Contacts</code></a>.</li>
+								<li>If a current <a href='#widl-Contact-id'><code>Contact.id</code></a> value does not current exist in <a href='#contacts-interface'><code>Contacts</code></a> or the current <a href='#widl-Contact-id'><code>Contact.id</code></a> value has not been set, add the current object as a new object to <a href='#contacts-interface'><code>Contacts</code></a>.</li>
 								<li>If successful, invoke the associated 
 								<code>successCB</code>. If the attempt fails, and the method was 
-								invoked with a non-null <code>errorCB</code> argument, this method must invoke the 
+								invoked with a non-<code>null</code> <code>errorCB</code> argument, this method must invoke the 
 								<code>errorCB</code> with a <a href='#contacterror-interface'>ContactError</a> object as an argument.</li>
 							</ol>
                         </p>     						
 						
 						<dl class='parameters'>
 							<dt>
-                                ContactCommitSuccessCB successCB
+                                ContactSuccessCB successCB
                             </dt>
                             <dd>
                                 Function to call when the asynchronous operation completes
@@ -409,47 +397,40 @@
                                 optional ErrorCB errorCB
                             </dt>
                             <dd>
-                                Function to call when the asynchronous operation fails. This parameter is OPTIONAL.
+                                Function to call when the asynchronous operation fails. 
                             </dd>
 						</dl>
 
                     </dd>
-                </dl>
-            </section>
-
-			<section>
-                <h2><a>ContactResult</a> interface</h2>
-				
-                <p>The <a href="#contactresult-interface"><code>ContactResult</code></a> interface extends the <a href="#contactproperties-interface"><code>Contact</code></a> object and provides methods that relate only to contact items that currently exist within <a href="#contacts-interface"><code>Contacts</code></a>.</p>
-
-				<p>In the case that the current <a href="#contactresult-interface"><code>ContactResult</code></a> object <a href='#widl-Contact-id'><code>id</code></a> attribute is <code>NULL</code> and a <a href="#contactresult-interface"><code>ContactResult</code></a> 
-				object <a href="#widl-ContactResult-remove">remove()</a> method is invoked, an <a href="#errorcallback-interface"><code>ErrorCB</code></a> MUST be 
-				triggered consisting of a <a href="#contacterror-interface"><code>ContactError</code></a> object with a <a href='#widl-ContactError-code'><code>code</code></a> of 
-				<a href='#widl-ContactError-INVALID_ARGUMENT_ERROR'><code>ContactError::INVALID_ARGUMENT_ERROR</code></a>.</p>
-
-                <dl title='[NoInterfaceObject] interface ContactResult : Contact' class='idl'>
                     <dt>
                         PendingOp remove ()
                     </dt>
                     <dd>                    	
                         <p>Remove the current contact from the address book.</p>	
 						
-						<p>This method takes one or two arguments. When called, it must immediately return 
-						a <code>PendingOp</code> object , as defined in [[CORE-DEVICE]], and then asynchronously start a <dfn>remove contact process</dfn> defined as follows:</p>
+						<p>
+							In the case that the current <a href='#widl-Contact-id'><code>id</code></a> attribute is <code>NULL</code> and this method is invoked, an <a href="#errorcallback-interface"><code>ErrorCB</code></a> MUST be 
+							triggered as part of the <a>remove contact process</a>. This error MUST consist of a <a href="#contacterror-interface"><code>ContactError</code></a> object with a <a href='#widl-ContactError-code'><code>code</code></a> of 
+							<a href='#widl-ContactError-CONTACT_NOT_FOUND_ERROR'><code>ContactError::CONTACT_NOT_FOUND_ERROR</code></a>.
+						</p>
+
+						
+						<p>This method takes one or two arguments. When called, it immediately returns 
+						a <code>PendingOp</code> object , as defined in [[CORE-DEVICE]], and then asynchronously starts a <dfn>remove contact process</dfn> defined as follows:</p>
 						
 						<p>		
 							<ol>
 								<li>Remove the current object from <a href='#contacts-interface'><code>Contacts</code></a>.</li> 
 								<li>If successful, invoke the associated 
 								<code>successCB</code>. If the attempt fails, and the method was 
-								invoked with a non-null <code>errorCB</code> argument, this method must invoke the 
+								invoked with a non-<code>null</code> <code>errorCB</code> argument, this method must invoke the 
 								<code>errorCB</code> with a <a href='#contacterror-interface'><code>ContactError</code></a> object as an argument.</li>
 							</ol>
                         </p>						
 						
                         <dl class='parameters'>
                             <dt>
-                                ContactRemoveSuccessCB successCB
+                                ContactSuccessCB successCB
                             </dt>
                             <dd>
                                 Function to call when the asynchronous operation completes
@@ -458,14 +439,13 @@
                                 optional ErrorCB errorCB
                             </dt>
                             <dd>
-                                Function to call when the asynchronous operation fails. This parameter is OPTIONAL.
+                                Function to call when the asynchronous operation fails. 
                             </dd> 
                         </dl>
                     </dd>
                 </dl>
             </section>
 
-
             <section>
                 <h2><a>ContactProperties</a> interface</h2>
                 <p>
@@ -478,7 +458,7 @@
 				<p>					
 					When <a href="#contactproperties-interface"><code>ContactProperties</code></a> is used as an input parameter to <a href='#widl-Contacts-find'><code>Contacts.find()</code></a> methods, fields that are set to 
                     <code>
-                        NULL
+                        null
                     </code>
                     are considered to match anything.
                 </p>
@@ -493,7 +473,7 @@
 						<pre class="example sh_javascript">{name: 'Mr. John Q. Public, Esq.'}</pre>
                     </dd>					
                     <dt>
-                        attribute sequence&lt;DOMString&gt;? nicknames
+                        attribute DOMString[] nicknames
                     </dt>
                     <dd>
                         <p>One or more nicknames associated with the contact</p>
@@ -501,7 +481,7 @@
 						<pre class="example sh_javascript">{nicknames: ['jim', 'jimmie']}</pre>
                     </dd>
 					<dt>
-                        attribute sequence&lt;ContactNode>? phones
+                        attribute ContactField[] phones
                     </dt>
                     <dd>
                         <p>One or more telephone numbers associated with the contact.</p>
@@ -516,7 +496,7 @@
           {types: ['work'], value: '+442088450343'}] }</pre>
 					</dd> 
 					<dt>
-                        attribute sequence&lt;ContactNode>? emails
+                        attribute ContactField[] emails
                     </dt>
                     <dd>
                         <p>One or more email addresses associated with the contact.</p>
@@ -530,7 +510,7 @@
           {types: ['home'], value: 'jquinlan@mail.com'}]}</pre>
 					</dd>
 					<dt>
-                        attribute sequence&lt;ContactNode>? addresses
+                        attribute ContactField[] addresses
                     </dt>
                     <dd>
                         <p>One or more addresses associated with the contact.</p>
@@ -544,7 +524,7 @@
              value: '123 Main Street,\nMain Business Park,\nAny Town, CA,\n91921-1234\nUSA'}]}</pre>
 					</dd>		
 					<dt>
-                        attribute sequence&lt;ContactNode>? impps
+                        attribute ContactField[] impps
                     </dt>
                     <dd>
                         <p>One or more instant messaging and presence protocol addresses associated with the contact.</p>
@@ -569,7 +549,7 @@
 						<pre class="example sh_javascript_dom">{serviceId: '-//BarFoo//ENTITIES MyContacts 1.4//EN'}</pre>
                     </dd>				
 					<dt>
-                        attribute sequence&lt;DOMString>? categories
+                        attribute DOMString[] categories
                     </dt>
                     <dd>
                         <p>One or more contact categories/groups to associate the contact with.</p>
@@ -580,11 +560,12 @@
             </section>
 
             <section>
-                <h2><a>ContactNode</a> interface</h2>
+                <h2><a>ContactField</a> interface</h2>
                 <p>
-                    The <a href='#contactcomplex-interface'><code>ContactNode</code></a> interface is a reusable component that defines an optional <code>type</code> parameter that can be provided with a standard <code>value</code>.
+                    The ContactField/Field interface is a reusable component that is used to support contact fields within the <a href='#contactproperties-interface'><code>ContactProperties</code></a> interface. 
+					It defines an optional <a href='#widl-ContactField-types'><code>types</code></a> parameter that can be provided with a standard <a href='#widl-ContactField-value'><code>value</code></a>.
                 </p>
-                <dl title='[NoInterfaceObject] interface ContactNode' class='idl'>
+                <dl title='[NoInterfaceObject] interface ContactField' class='idl'>
                 	<dt>
                         attribute sequence&lt;DOMString>? types
                     </dt>
@@ -614,9 +595,9 @@
                         <p>
                             The maximum number of results to return from the contacts search.
                         </p>
-                        <p>
-                            DEFAULT = 200
-                        </p>
+						<p>
+							If no value is provided, the search will return all search results.
+						</p>
                     </dd>
                     <dt>
                         attribute unsigned short page
@@ -624,10 +605,10 @@
                     <dd>
                         <p>
                             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.
-                        </p>
-                        <p>
-                            DEFAULT = 1
-                        </p>
+                        </p>						
+						<p>
+							If no value is provided, the search will return all search results.
+						</p>
                     </dd>
                     <dt>
                         attribute DOMString? sort
@@ -643,7 +624,7 @@
 							This attribute MUST be one of the following constants:
 						</p>						
 						<pre>'asc', 'desc'</pre>
-						<p>If a different constant is provided, this field defaults to <code>NULL</code></p>
+						<p>If a different value is provided, this field defaults to <code>null</code></p>
                     </dd>
                     <dt>
                         attribute DOMString? group
@@ -659,7 +640,7 @@
 							This attribute MUST be one of the following constants:
 						</p>						
 						<pre>'asc', 'desc'</pre>
-						<p>If a different constant is provided, this field defaults to <code>NULL</code></p>
+						<p>If a different value is provided, this field defaults to <code>null</code></p>
                     </dd>					
 					
                 </dl>
@@ -679,10 +660,10 @@
 						
                         <dl class='parameters'>
                             <dt>
-                                sequence&lt;ContactResult> contactObjs
+                                sequence&lt;Contact> contactObjs
                             </dt>
                             <dd>
-                                The sequence of ContactResult objects resulting from the given <a href='#contacts-interface'><code>Contacts</code></a> <a href='#widl-Contacts-find'>find()</a> method.
+                                The sequence of Contact objects resulting from the given <a href='#contacts-interface'><code>Contacts</code></a> <a href='#widl-Contacts-find'>find()</a> method.
                             </dd>
                         </dl>			
 					</dd>
@@ -690,35 +671,11 @@
 			</section>
 
             <section>
-                <h2><a>ContactCommitSuccessCB</a> interface</h2>
-
-				<!-- interface intro here -->
-					
-                <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactCommitSuccessCB' class='idl'>
-                	<dt>
-                        void onSuccess ()
-                    </dt>
-					<dd>
-						<!-- interface description here -->
-						
-                        <dl class='parameters'>
-                            <dt>
-                                ContactResult contactObj
-                            </dt>
-                            <dd>
-                                The ContactResult object resulting from the given <a href='#contact-interface'><code>Contact</code></a> <a href='#widl-Contact-commit'>commmit()</a> method.
-                            </dd>
-                        </dl>			
-					</dd>
-                </dl>				
-			</section>
-			
-            <section>
-                <h2><a>ContactRemoveSuccessCB</a> interface</h2>
+                <h2><a>ContactSuccessCB</a> interface</h2>
 
 				<!-- interface intro here -->
 					
-                <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactRemoveSuccessCB' class='idl'>
+                <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactSuccessCB' class='idl'>
                 	<dt>
                         void onSuccess ()
                     </dt>
@@ -730,14 +687,13 @@
                                 Contact contactObj
                             </dt>
                             <dd>
-                                The Contact object resulting from the given <a href='#contactresult-interface'><code>ContactResult</code></a> <a href='#widl-ContactResult-commit'>remove()</a> method.
+                                The Contact object resulting from the given <a href='#contact-interface'><code>Contact</code></a> <a href='#widl-Contact-save'>commmit()</a> or <a href='#contact-interface'><code>Contact</code></a> <a href='#widl-Contact-remove'>remove()</a> method.
                             </dd>
                         </dl>			
 					</dd>
                 </dl>				
 			</section>
-
-				
+						
 			<section>
                 <h2><a>ContactError</a> interface</h2>
 				<p class="note">
@@ -747,7 +703,14 @@
                    The <a href='#contacterror-interface'><code>ContactError</code></a> interface encapsulates all errors in the manipulation of <a href='#contact-interface'><code>Contact</code></a> objects in the Contacts API.
                 </p>
                 <dl title='[NoInterfaceObject] interface ContactError : GenericError' class='idl'>
-
+						<dt>const unsigned short CONTACT_NOT_FOUND_ERROR = 30</dt>
+						<dd>
+							The <a href='#contact-interface'><code>Contact</code></a> object requested could not be found in <a href='#contacts-interface'><code>Contacts</code></a>.
+						</dd>
+						<dt>const unsigned short CONTACT_INVALID_ERROR = 31</dt>
+						<dd>
+							The <a href='#contact-interface'><code>Contact</code></a> object does not include all mandatory attributes required in <a href='#contacts-interface'><code>Contacts</code></a>.
+						</dd>
                 </dl>
              </section>
 
@@ -831,7 +794,7 @@
         </section>
         <!-- end api description section -->
         <section>
-            <h2><a>Contact Search processing rules</a></h2>
+            <h2><a>Contact Search Processing Rules</a></h2>
             <p>
                 The <a href="#contacts-interface"><code>Contacts</code></a> interface <a href='#widl-Contacts-find'>find()</a> method 
                  provides a method to search for contacts according to the input of a  
@@ -840,7 +803,7 @@
 				
                 <p>
                 	All fields within a <a href="#contactproperties-interface"><code>ContactProperties</code></a> object provided to this method represent a logical UNION of value matching. 
-					Fields provided with a <code>NULL</code> value are considered to match anything.
+					Fields provided with a <code>null</code> value are considered to match anything.
 				</p>
 				<p>
 					For example, the following <a href="#contactproperties-interface"><code>ContactProperties</code></a> object is supplied for Contact searching: 
@@ -872,7 +835,7 @@
 			  	  <ol>
 					 <li>Let <var title="">singlefilter</var> be the <var title="">input</var> parameter being parsed.</li>
 					 <li>Let <var title="">item</var> be the next enumerable property in <var title="">singlefilter</var>. If there are no more enumerable properties, go to step 6.</li>
-					 <li>If the value of <var title="">item</var> is null, go to step 2.</li>
+					 <li>If the value of <var title="">item</var> is <code>null</code>, go to step 2.</li>
 					 <li>Let <var title="">contactsset</var> be the subset of <var title="">contactsset</var> whose elements have the item value set to the value of <var title="">item</var>.</li>
 					 <li>Go to step 2.</li>
 					 <li>Return <var title="">contactsset</var>.</li>
@@ -881,7 +844,7 @@
 	
 			  <dt>If <var title="">input</var> is another native object type</dt>
 	
-			  <dd><p>Return a null value.</dd>
+			  <dd><p>Return a <code>null</code> value.</dd>
 	
 		    </dl>
 		
Received on Wednesday, 16 December 2009 16:16:00 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Wednesday, 16 December 2009 16:16:01 GMT