Add the first very basic bits of a geofencing API.

Source/modules/geolocation/CircularRegion.idl

Index: Source/modules/geolocation/CircularRegion.idl
diff --git a/Source/modules/geolocation/CircularRegion.idl b/Source/modules/geolocation/CircularRegion.idl
new file mode 100644
index 0000000000000000000000000000000000000000..bc8ce0b45e73475607117f8a1421339ad0f2a2af
--- /dev/null
+++ b/Source/modules/geolocation/CircularRegion.idl
@@ -0,0 +1,16 @@
+// Copyright 2014 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+[
+    RuntimeEnabled=Geofencing,
+    GarbageCollected,
+    Constructor(Dictionary init)

[Peter Beverloo, 2014/07/10 13:17:28]

What is the expected behavior of the following?

var x = new CircularRegion({});

Would it have any use at all? Does the spec allow for it, or should we throw an
exception? If it's allowed, we may as well make the |init| argument optional to
allow the following syntax for empty circular regions:

var x = new CircularRegion();

[Marijn Kruisselbrink, 2014/07/10 15:11:01]

I don't think a CircularRegion without at least a latitude and longitude makes
sense, so yes, we should probably throw an exception if one of those fields
isn't present (for radius we can probably come up with some default value).
What do other web APIs do for things like this?

[Peter Beverloo, 2014/07/10 16:31:36]

What else do you imagine to be required for a circular reason? I would imagine
that |longitude| and |latitude| are required, |radius| is optional (to some sane
default) and |id| is optional as well (defaulting to empty, which is fine if we
only need one region).

For consistency with the Geolocation specification, you could have something
like (in which |options| currently provides for [id, radius]:

Constructor(double latitude, double longitude, optional Dictionary options);

However, this really isn't the forum to discuss the API. You should do that on
the Geolocation Working Group list.

[Marijn Kruisselbrink, 2014/07/11 10:06:39]

Yes, I agree that this isn't the place to discuss the API. And I'm sure that
whatever API I will commit here will change later. But to actually write an
implementation I will need some API, and I don't think it makes sense to block
that on first figuring out the perfect API.

+] interface CircularRegion : GeofencingRegion {
+    const double MIN_RADIUS = 1.0;

[Peter Beverloo, 2014/07/10 13:17:27]

I share Jochen's concern that this isn't clear without a unit. These constants
will be exposed to developers. Even if you're not sure whether they'll stick
around, could we suffix them with a unit?

Given that a range of [1, 100] only makes sense in meters (kilometers would be
way too long), perhaps MIN_RADIUS_METERS? A hundred meters is not a very long
distance either for some of the geofencing use-cases (e.g. nearby attractions).

Let's not even consider imperial units? :-)

[Marijn Kruisselbrink, 2014/07/10 15:11:01]

I agree that it isn't immediately clear what unit "radius" is in, and that that
should be documented somehow. I'm not sure I agree that suffixing these
constants with a unit makes sense though. If they're suffixed like that I would
at least assume that that must mean that they're in a different unit than the
radius field, unless radius is also renamed to radius_meters (but then where do
you stop, should longitude and latitude than also be longitude_degrees?
And I know it isn't really relevant to naming things in web APIs, but at least
the iOS geofencing API also just calls this "maximumRegionMonitoringDistance".
Are there other examples of web APIs where constants embed the unit they are in
in the name of the constant? 

+    const double MAX_RADIUS = 100.0;
+
+    readonly attribute double latitude;
+    readonly attribute double longitude;
+    readonly attribute double radius;
+};