W3C home > Mailing lists > Public > public-device-apis@w3.org > November 2009

RE: [contacts] Comments on editors draft of Contacts API

From: <richard.tibbett@orange-ftgroup.com>
Date: Mon, 30 Nov 2009 18:05:05 +0100
Message-ID: <355A518BC0575547B2A3D6773AAF8EEF6CA58F@ftrdmel1>
To: <dom@w3.org>
Cc: <public-device-apis@w3.org>
Hi Dom,

Thanks for the review. I've included some responses below.

I welcome further review of this API [1] from other DAP participants. 


On 30th Nov 2009 10:21, Dominique Hazael-Massieux [dom@w3.org] wrote:
> Hi Rich,
> Here come a few comments on the current editors draft [1] of 
> the Contacts API; I think the questions are likely to apply 
> to other APIs in the future, so hopefully looking at them now 
> will help for later too.
> * all the interfaces defined in the API are annotated with 
> [NoInterfaceObject] [2] ; I think it's may make sense for the 
> Contacts interface depending on the mechanism used to secure 
> the access to the addressbooks, it's probably not appropriate 
> for many of the other interfaces; for instance, I don't see 
> how one would add a contact right now, since one cannot 
> instantiate the Contact interface; was there a rationale for 
> hiding the interface object? Maybe some of the interfaces 
> can/should remain hidden through convenience functions, but 
> they're not defined in the API right now

I picked this up and the latest draft deals in both [NoInterfaceObject]
and [Constructor(..)] as appropriate.

> * assuming the Contact interface becomes instantiable, it 
> would probably need a constructor with a non-optional 
> formatted name parameter?

Contact does become instantiable in the latest Contacts draft.

> * should there be convenience-functions to add/remove 
> elements to the sequence properties in Contact that are more 
> than just DOMString?

This is a good idea. Rather than having to deal directly with nested
array and object literals it would be easier to expose convenience
functions to developers.

I will include this in the next draft of the specification.

> * I think all the attributes in Contact but "name" should be 
> annotated with a "?" since they are optional [3]; likewise, 
> all the attributes in ContactName should be marked with "?" 
> but "formatted"

In the latest draft of the API the attributes of Contact have been
abstracted out to ContactProperties (in a move for the new
ContactProperties to also replace the previously included ContactFilter

When a Contact object is instantiated, ALL attributes supported by the
current implementation MUST be provided in the resulting Contact object
-> a developer can then enumerate over the resulting objects to see
which attributes are supported or not in the current implementation (and
therefore whether it is necessary to set/get these attributes).

To represent this, I've placed a description to this effect in the
Contact interface section. When the ContactProperties are used as a
filter to a find() method, then the strict provision of these attributes
in the filter object is not necessary.

So rather than annotate with a "?" I've chosen to directly express the
optionality of all components in the related interface descriptions.

Does this work?

> * I think the ContactAddress interface should mark as an 
> editors note or as an issue the possible relation to the work 
> in Geolocation v2:
> http://dev.w3.org/geo/api/spec-source-v2.html#address_interface
> I think we'll want to converge with it over time; note that 
> they define it as read-only since in their case they exchange 
> immutable objects, but we would clearly need a mutable one 
> [side note: I wonder if that's something that would be better 
> defined as property of a specific instance rather than 
> hardcoded in the interface, but I don't think WebIDL allows 
> for this currently]

Added to the latest draft specification.

> * I am a bit nervous about using SQL as the formal language 
> to describe the filtering algorithm; I think given that the 
> filtering we're doing is rather simple (OR / AND / LIMIT / 
> OFFSET), I would go with a prose or mathematical description 
> on the set of known contacts.

I'm not particularly pleased with the 'Contact Search Processing Rules'
section for this reason. This is currently highlighted as an editor's
note. Perhaps you have some examples on which I could draw to rework
this section?

> 1. http://dev.w3.org/2009/dap/contacts/
> More specifically, v1.13
> http://dev.w3.org/cvsweb/~checkout~/2009/dap/contacts/Overview
> .html?rev=1.13&content-type=text/html;%20charset=utf-8
> 2. http://dev.w3.org/2006/webapi/WebIDL/#NoInterfaceObject
> 3. http://dev.w3.org/2006/webapi/WebIDL/#idl-nullable-type


Received on Monday, 30 November 2009 17:05:52 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:45:56 UTC