RE: Geolocation API

Two comments:

(1) I think pretty much all device APIs (location, battery, connection
status, SMS message queue, camera, ...) should have asynchronous APIs.
Certainly in the general case not every API will be able to respond
synchronously. Some implementations might require some network
communication for either completion of the operation or verify identity and
credentials. Since at least some of the future set of mobile device APIs
will need to be asynchronous and that in at least some cases (albeit
perhaps a small percentage) the geolocation API in particular will need to
be asynchronous, I suggest that the geolocation API have an async design
(i.e., the "getlocation()" method passes a callback function).

(2) For notification APIs (e.g., listenForReports()), why not use
AddEventListener and therefore leverage DOM events?

Jon



                                                                           
             Alec Berntson                                                 
             <alecb@windows.mi                                             
             crosoft.com>                                               To 
             Sent by:                  Andrei Popescu <andreip@google.com> 
             public-geolocatio                                          cc 
             n-request@w3.org          Shyam Habarakada                    
                                       <shyamh@microsoft.com>,             
                                       "public-geolocation@w3c.org"        
             06/12/08 05:47 PM         <public-geolocation@w3c.org>        
                                                                   Subject 
                                       RE: Geolocation API                 
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           




Andrei,

My intent was that the API support synchronous and asynchronous operation.
If you wanted to use it synchronously (i.e. single shot of location data to
fill in a form, or place the user on a map once) you could use
        GetLocation() to get the data - (there shouldn't be a callback
there, my mistake)
        GetReportStatus() to get the state of the report generation

If you wanted to use it asynchronously (i.e. track the user on a map, or
give periodic updates), you could use:
        listenForReports() to get data and state changes via callbacks
(LocationCallback and StatusCallback)
        ChangeOptions() to modify your event report generation options

For report status:
NOT_AVAILABLE:0,
ERROR:1,
ACCESS_DENIED:2,
INITIALIZING:3,
READY:4

Updated API ideas:

interface Geolocation {
  // Get the current position.
  // The result will be returned directly
 LocationReport getLocation( ReportOptions options);

  // Watch the current position over time.
  // The callback function will be called with the result.
  void listenForReports(  LocationCallback locationCallback,
                          StatusCallback statusCallback,
                          ReportOptions options);

  // Get the report generation status
  ReportStatus getReportStatus()

  // Stop watching the current position.
  void stopListeningForReports();

// change the current report generation options.
  void setOptions(ReportOptions options);
};

void LocationCallback(  LocationReport report);
void StatusCallback(    ReportStatus status);

interface ReportOptions {
// Optional. Provides a hint about how accurate a location fix the
application would like to receive. This should be in meters or possibly a
fixed range of values (such as 1-10)if more accurate data is available,
noise should be added to reduce the accuracy to this level. This allows for
the ‘enableHighAccuracy’ field on a continuous scale.
int requestedAccuracy;

// Optional. Provides a hint as to what the minimum time (ms) that should
be allowed to elapsed between asynchronous calls. For example, if this were
called with 10 min, the callback should only be called every 10 min with a
new report
int minReportInterval

// Optional. Requests reverse geocoded address information as part of the
position data. Reverse geocoding is not performed if this flag is not
specified or set to false.
bool requestAddress;

// Optional. Specifies the language in which the address (if requested)
should be returned. Uses RFC 3066.
string addressLanguage.
};

Use Cases
      One Shot
            Any application where you just need a location 'seed'
            Get directions from 'here' (opposite of find POI)
            Fill in forms with your current address (good use of reverse
            geocoding))
            Metadata for any sort of submission (geocode a blog post,
            email, etc)
            Social networking - play games with people around you (doesn't
            have to be continuously updated to get the game started)

      Position monitoring
            Continuously updating local information (traffic, weather, etc)


-----Original Message-----
From: Andrei Popescu [mailto:andreip@google.com.]
Sent: Thursday, June 12, 2008 2:22 PM
To: Alec Berntson
Cc: Shyam Habarakada; public-geolocation@w3c.org
Subject: Re: Geolocation API

Alec, I also have some questions about your API suggestions:

On Mon, Jun 9, 2008 at 7:03 PM, Alec Berntson
<alecb@windows.microsoft.com> wrote:
> interface Geolocation {
>   // Last known position, or null if there is no last known position.
>   readonly LocationReport lastLocation;
>
>   // Get the current position.
>   // The callback function will be called with the result.
>   ReportStatus getLocation(        LocationCallback locationCallback,
>                                    optional ReportOptions options);
>
>   // Watch the current position over time.
>   // The callback function will be called with the result.
>   int listenForReports(   LocationCallback locationCallback,
>                           StatusCallback statusCallback,
>                           optional ReportOptions options);
>
>   // Get the report generation status
>   ReportStatus getReportStatus();

Your changes seem to suggest that you'd want the statusCallback to be
called periodically, whenever there is a transition between the
possible states of ReportStatus, right? First of all, what use cases
did you have in mind for that (I intend to publish a new draft
tomorrow with some more use cases) ? Then, why would getReportStatus(),
be needed? If I understand this right, this function cannot possibly
return any new status information, since the statusCallback must have),
been already invoked if a status transition occurred. Also, exactly
which ReportStatus would this function return (assuming one may have
issued several calls to getLocation / listenForReports)?

Thanks,
Andrei,