- From: Allan Thomson (althomso) <althomso@cisco.com>
- Date: Mon, 30 Mar 2009 10:32:45 -0700
- To: "public-geolocation" <public-geolocation@w3.org>
- Message-ID: <18B307BFDE5098438B0BF42A4E508FB508156C10@xmb-sjc-228.amer.cisco.com>
All - it would seem this is an extremely inefficient way to solicit
comments on the document. If you are open to alternate ways of getting
comments I have experience on how the IEEE does it which makes it easier
to track comments and respond to them. But here goes anyway...
Allan
Introduction Section
Comment #1:
"The API is designed to enable both "one-shot" position requests and
repeated position updates",
This suggests a periodic update rather than what I think it is intended
to suggest is asynchronous updates. It is not clear from the document
when and what causes an asynchronous location update to occur. It is
movement? Time? Suggest that you change "repeated position updates" to
"asynchronous updates" and clarify what triggers the updates to be sent.
Comment #2:
"...the ability to explicitly query the cached positions"
Define cached? Where is it cached? Client or server side? What is the
criteria for caching vs not caching. Suggest the concept of caching is
not something this API should address or should be a separate document
Comment #3:
"Location information is represented by latitude and longitude
coordinates".
As we are including CIVIC address elements also this is no longer
strictly the only way to represent location. Sentence needs to address
both formats.
Comment #4:
The examples don't really highlight the high-level goals of the API
which would be better for an introductory section. They seem to show
examples of how the programmer would use each API call. Suggest they be
moved to a later section where the API is described for each method or
to an appendix.
Scope Section
Comment #5:
It would seem that the scope of this document is to not define the
underlying mechanisms that the API provides such location data (whether
locally or remotely determined). This should be explicitly stated so
that no one thinks that the API requires a specific underlying transport
mechanism or local determination capability.
Comment #6:
This API provides a mechanism to provide location of the calling agent
ONLY. Might be obvious but I think it is worth stating due to security
concerns that may arise if someone thought they can use this API to find
out location of someone else.
API Description - Geolocation Interface
Comment #7:
interface Geolocation {
void getCurrentPosition
<http://dev.w3.org/geo/api/spec-source-v2.html#get-current-position#get-
current-position> (in PositionCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#position-callback#positio
n-callback> successCallback);
void getCurrentPosition
<http://dev.w3.org/geo/api/spec-source-v2.html#get-current-position#get-
current-position> (in PositionCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#position-callback#positio
n-callback> successCallback, in PositionErrorCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#error-callback#error-call
back> errorCallback);
void getCurrentPosition
<http://dev.w3.org/geo/api/spec-source-v2.html#get-current-position#get-
current-position> (in PositionCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#position-callback#positio
n-callback> successCallback, in PositionErrorCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#error-callback#error-call
back> errorCallback, in PositionOptions
<http://dev.w3.org/geo/api/spec-source-v2.html#position-options#position
-options> options);
int watchPosition
<http://dev.w3.org/geo/api/spec-source-v2.html#watch-position#watch-posi
tion> (in PositionCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#position-callback#positio
n-callback> successCallback);
int watchPosition
<http://dev.w3.org/geo/api/spec-source-v2.html#watch-position#watch-posi
tion> (in PositionCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#position-callback#positio
n-callback> successCallback, in PositionErrorCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#error-callback#error-call
back> errorCallback);
int watchPosition
<http://dev.w3.org/geo/api/spec-source-v2.html#watch-position#watch-posi
tion> (in PositionCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#position-callback#positio
n-callback> successCallback, in PositionErrorCallback
<http://dev.w3.org/geo/api/spec-source-v2.html#error-callback#error-call
back> errorCallback, in PositionOptions
<http://dev.w3.org/geo/api/spec-source-v2.html#position-options#position
-options> options);
Are these methods completely orthogonal (i.e. thread safe)?
i.e. can a client call multiple methods at the same time before a result
is received? What are the semantics of multi-threading applications on
this API. Suggest they should be thread safe and a client can call
methods multiple times without waiting for a result. If that is the
case then each call of the method should return a unique handle as part
of the registration if the client is to be able to differentiate results
to each call of a method especially if they are using the same callback
method.
Comment #8:
interface PositionCallback {
void handleEvent(in Position
<http://dev.w3.org/geo/api/spec-source-v2.html#position#position>
position);
};
interface PositionErrorCallback {
void handleEvent(in PositionError
<http://dev.w3.org/geo/api/spec-source-v2.html#position-error#position-e
rror> error);
};
Why are there two functions rather than just one function with a status
code? For example there may be situations where a location object will
be returned but some additional status still needs to be conveyed back
to the caller also. In that case there is no way to do that right now.
Also, having two methods will create code bloat unnecessarily.
Suggest make a single method for callback with a status object (code +
other attributes) and a location position object.
Comment #9:
"The getCurrentPosition() takes one, two or three arguments. When
called, it must immediately return and then asynchronously acquire a new
Position
<http://dev.w3.org/geo/api/spec-source-v2.html#position#position>
object. If successful, this method must invoke its associated
successCallback argument with a Position
<http://dev.w3.org/geo/api/spec-source-v2.html#position#position>
object as an argument. If the attempt fails, and the method was invoked
with a non-null errorCallback argument, this method must invoke the
errorCallback with a PositionError
<http://dev.w3.org/geo/api/spec-source-v2.html#position-error#position-e
rror> object as an argument"
The getCurrentPosition method needs to return a success or failed result
code so that the caller knows the callback has been registered
successfully. Or define an exception but there needs to be a way for an
implementation to return "callback not registered" or other unusual
programmatic errors.
API Description - PositionOptions Interface
Comment #10:
"The enableHighAccuracy attribute provides a hint that the application
would like to receive the best possible results. This may result in
slower response times or increased power consumption. The user might
also deny this capability, or the device might not be able to provide
more accurate results than if the flag wasn't specified"
The definition of "high" accuracy is dependent on many things outside
the control of the user and they have no way of understanding why they
are or are not getting high accuracy. 99% clients will always want the
best accuracy you can give. Suggest you remove this attribute as it is
not useful and will cause many comments in the future on what is the
definition of high accuracy. Another possible option is to define a
polygon and error estimates on the location result so that you can
represent accuracy more correctly. To do this see comment regarding X,Y
positional information in civic attributes.
API Description - Coordinates Interface
Comment #11:
interface Coordinates {
readonly attribute double latitude
<http://dev.w3.org/geo/api/spec-source-v2.html#lat#lat> ;
readonly attribute double longitude
<http://dev.w3.org/geo/api/spec-source-v2.html#lon#lon> ;
readonly attribute double altitude
<http://dev.w3.org/geo/api/spec-source-v2.html#altitude#altitude> ;
readonly attribute double accuracy
<http://dev.w3.org/geo/api/spec-source-v2.html#accuracy#accuracy> ;
readonly attribute double altitudeAccuracy
<http://dev.w3.org/geo/api/spec-source-v2.html#altitude-accuracy#altitud
e-accuracy> ;
readonly attribute double heading
<http://dev.w3.org/geo/api/spec-source-v2.html#heading#heading> ;
readonly attribute double speed
<http://dev.w3.org/geo/api/spec-source-v2.html#speed#speed> ;
};
Heading/Direction (less so) and speed (more so) are not specific to
geospatial information AND are common to both civic as well as
geospatial location objects. Suggest heading/direction and speed should
be a separate object that can be referenced by both civic and geospatial
positions.
API Description - Address Interface
Comment #12:
interface Address {
readonly attribute DOMString country
<http://dev.w3.org/geo/api/spec-source-v2.html#country#country> ;
readonly attribute DOMString region
<http://dev.w3.org/geo/api/spec-source-v2.html#region#region> ;
readonly attribute DOMString county
<http://dev.w3.org/geo/api/spec-source-v2.html#county#county> ;
readonly attribute DOMString city
<http://dev.w3.org/geo/api/spec-source-v2.html#city#city> ;
readonly attribute DOMString street
<http://dev.w3.org/geo/api/spec-source-v2.html#street#street> ;
readonly attribute DOMString streetNumber
<http://dev.w3.org/geo/api/spec-source-v2.html#street-number#street-numb
er> ;
readonly attribute DOMString premises
<http://dev.w3.org/geo/api/spec-source-v2.html#permises#permises> ;
readonly attribute DOMString additionalInformation
<http://dev.w3.org/geo/api/spec-source-v2.html#additional-info#additiona
l-info> ;
readonly attribute DOMString postalCode
<http://dev.w3.org/geo/api/spec-source-v2.html#postal-code#postal-code>
;
};
This object is missing attributes for
1) Building
2) Floor
3) Area
4) X,Y (on a floor) or a polygon that represents the position and
error at the same time
Comment #13:
AdditionalInformation is inadequate for the "rest" of the information
for buildings, floors...etc as the spec currently states.
API Description - PositionError Interface
Comment #14:
Need to add "format unavailable" for times when lat/long or civic
formats are not available due to lack of support of a particular format
either from the underlying location determination capability or
environment you are currently in. This is different from a position
being unavailable due to lack of gps sync or civic information available
from a location server due to network problems.
Use Cases and Requirements
Comment #15:
The use case examples are all outdoor/consumer related use cases. We
need to add indoor use cases that can also help explain how location is
used for business like environments. Can provide information in a
separate submission.
Comment #16:
"The Geolocation API must allow an application to register to receive
repeated position updates."
Again what does "repeated" really mean. Time or movement based. Suggest
this is not a well defined requirement.
Comment #17:
"The Geolocation API must allow an application to cheaply query the last
known position."
As opposed to the current location? Define cheap? This is not a
well-defined requirement. Please revise.
Comment #18:
"The Geolocation API must allow an application to specify a desired
accuracy level of the location information."
Add "even if that accuracy level is not possible or achievable by the
location determination function"
Comment #19:
"The Geolocation API must be agnostic to the underlying sources of
location information".
This can never be STRICTLY enforced. A lat/long value can only be
provided by a system that is lat/long aware. Therefore there has to be
some dependence on the underlying function to provide this information.
I would suggest the API "may" be agnostic. Not "must be agnostic".
________________________________
Received on Monday, 30 March 2009 17:33:34 UTC