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

*       Position monitoring
o       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