[OpenAjaxMobile] Analysis of W3C's latest geolocation APIs and proposals for how to generalize

[Jon Ferraiolo]

This email contains an analysis of the W3C's latest geolocation spec and
some thoughts about whether it would be good to pattern other device APIs
to use the same approaches. The email also makes various proposals about
several open issues. We could probably spend the entire hour on Thursday
walking through this email (and the inevitable email reponses that will
arise between now and then).

These comments refer to the Aug. 15 draft of the Geolocation API spec found
at:

* http://dev.w3.org/geo/api/spec-source.html

---------------------------
EXECUTIVE SUMMARY
---------------------------

Here are the key APIs defined in the geolocation spec:

* navigator.geolocation.lastPosition - an object holding most recent
geolocation position

* navigator.geolocation.getCurrentPosition(successCallback [, errorCallback
[,options]])
--- successCallback is the callback function
--- errorCallback (optional) is the error callback function
--- options (optional) can include extra parameters and provides for future
extensibility

* navigator.geolocation.watchPosition(successCallback [, errorCallback
[,options]])
--- see getCurrentPosition()

* navigator.geolocation.clearWatch(watchId) - where watchId is the return
value from watchPosition()

The successCallback receives a Position object defined as follows:

  interface Position {
    readonly attribute double latitude:;
    readonly attribute double longitude;
    readonly attribute double altitude:;
    readonly attribute double accuracy:;
    readonly attribute double altitudeAccuracy;
    readonly attribute double heading
    readonly attribute double velocity:
    readonly attribute DOMTimeStamp timestamp;
  };


---------------------------
JON'S EVALUATION
---------------------------

The W3C geolocation APIs are generally fine as is. The things I like about
this API:

* Simple and straightforward
* Good design for future extensibility due to the options object and the
position object
* I think it is good that they have both successCallback and errorCallback
as the first two parameters. This emphasizes to the developer that he might
want to pay close attention to error handling, such as being denied access
to the API for security reasons.
* I think it is good that it the API is placed onto navigator.geolocation
(versus omtp.whatever or OpenAjax.device.whatever)
* I think it is good to allow direct JS access to the most recent position,
such as window.geolocation.lastPosition.latitude, but the W3C spec needs to
warn developers that if they attempt to access that property and they don't
have permission, the property's value will be "undefined".

My concerns about this API:

(1) Not really a concern per se, but there is nothing in the spec yet about
security.OMTP's efforts will supplement the work done by the W3C.
(2) There needs to be additional query APIs for:
--(a) Checking to see if geolocation APIs are available
--(b) If so, what version of the APIs are available
--(c) Whether this particular application has permission to access those
APIs
(3) There is no support for Bondi's requirements about dynamically loading
of an implementation of particular APIs

Regarding (1), the W3C geolocation spec could say something general about
how a USER AGENT SHOULD provide a secure computing environment that has
careful implementation strategy to protect the user's privacy, and then
references OMTP's security spec as a security framework that can be used.
My thinking is that the W3C isn't a good place to write security specs. In
other words, as a general approach, W3C defines the APIs and OMTP defines
the security model. (Although OMTP should work on APIs that the W3C isn't
moving fast enough on yet and then probably turn those APIs over to the W3C
when the W3C is ready.)

Regarding (2a), the application can just check to see if the
navigator.geolocation object is present (i.e., not "undefined").

Regarding (2b), the W3C simply needs to put a 'version' read-only property
on the Geolocation interface.

Regarding (2c), I suggest that OMTP define the APIs for checking on whether
an application has permission to use the APIs. I would suggest something
like:

* navigator.apiPermissionsCheck(api_uri, successCallback [, errorCallback
[,options]])

where the 'api_uri' is a unique URI for a given API module. The 'options'
parameter provides an extensible architecture for the application to pass
in parameters. (One warning to the Bondi folks: the W3C has some specs with
feature URLs already, such as
http://www.w3.org/TR/SVGMobile12/feature.html. My guess is that Rotan can
educate us about other relevant work at the W3C.)

Regarding (3), long-term, I believe browsers will implement device APIs
natively, in which case dynamically attaching an implementation is the
minority case. Therefore, I think it is fine that the primary geolocation
APIs are simple and don't deal with the dynamic loading features. Instead,
dynamic loading should be a separate set of JS APIs. The geolocation APIs
would use the currently loaded implementation.

---------------------------
GOOD MODEL FOR OTHER APIs?
---------------------------

Are the W3C geolocation APIs a good model for other device APIs? I would
say yes. Here is a sketch for how other device APIs might look following
the pattern established by the geolocation APIs. (I used
http://www.openajax.org/member/wiki/OpenAjax_Device_APIs_Modules to help
build this analysis.)

Note that the parameters to the APIs would align with what the W3C has done
with geolocation: successCallback, errorCallback, and options.

Phone call APIs:
* navigator.phone.call() - calls a given number
* navigator.phone.answer() - answers the current call
* navigator.phone.hangup() - terminates the current call
* navigator.phone.{inbox,outbox,missed,all} - list management APIs (e.g.,
delete, get details)
* navigator.phone.{watchIncoming(),watchOutgoing(),watchMissed()}

SMS and MMS:
* navigator.{sms,mms}.send() - sends an SMS or MMS,
* navigator.{sms,mms}.{inbox,outbox,drafts} - list management APIs (e.g.,
delete, get details)
* navigator.{sms,mms}.{watchIncoming(),watchOutgoing()}

EMail:
* navigator.email.send() - sends an email
* navigator.email.{inbox,outbox,drafts,trash} - list management APIs (e.g.,
delete, get details)
* navigator.email.{watchIncoming(),watchOutgoing()}
(there will be a number of other email APIs, but I am only providing a
sketch)

AddressBook:
* navigator.contacts: list management APIs (e.g., add, delete, get details)

Calendar:
* navigator.calendar.{inbox,outbox,drafts,trash} - list management APIs
(e.g., add, delete, get details)
* navigator.calendar.{addReminder()}

Tasks:
* navigator.tasks: list management APIs (e.g., add, delete, get details)
* navigator.tasks.{addReminder()}

Power:
* navigator.power.{powerSource,chargeLevel,criticalBattery,charging,...}
* navigator.power.watchCriticalBattery(),watchChargeCompleted
(),watchPowerSourceChanged(),,...}

Network:
*
navigator.network.{current,cellular,wifi,bluetooth}.{signalStrength,networkType,criticalBattery,roaming,,...}
* navigator.network.watchOutOfCoverage(),,...}

Time:
(Not sure what exists already in the browser, but if we need to invent
something, here goes)
* navigator.clock.{date,time,timezone}
* navigator.clock.watchTimeZoneChange(),,...}

Media:
* navigator.resources.{images,audio, video} - list management APIs (e.g.,
delete, get details)
* (need other APIs for capture and annotate)

File I/O:
* W3C is working on APIs in this area

Camera:
navigator.camera.*

Effectors:
* navigator.effectors.mode
* navigator.effectors.setMode()
* navigator.effectors.watchModeChange()

Accelerometer:
* navigator.accelerometer.mode
* navigator.accelerometer.setMode()
* navigator.accelerometer.watchModeChange())

Memory:
* navigator.memory.watchOutOfMemory()

Console:
(Need to see what browser APIs exist already. Firefox/Firebug definitely
has a console object)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://openajax.org/pipermail/mobile/attachments/20080902/6857b31d/attachment.html