chrome/common/extensions/api/location.idl

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 // TODO(vadimt): Consider reusing WebKit/Blink types, if this is possible.
   5
   6 // Use the <code>chrome.location</code> API to retrieve the geographic location
   7 // of the host machine. This API is a version of the <a
   8 // href="http://dev.w3.org/geo/api/spec-source.html">HTML Geolocation API</a>
   9 // that is compatible with event pages.
  10 namespace location {
  11   // Coordinates part of the Location object.
  12   dictionary Coordinates {
  13     // The geographic latitude specified in degrees.
  14     double latitude;
  15
  16     // The geographic longitude specified in degrees.
  17     double longitude;
  18
  19     // The height of the position, specified in meters above the [WGS84]
  20     // ellipsoid, or null if Chrome cannot provide altitude information.
  21     double? altitude;
  22
  23     // The accuracy of the latitude and longitude coordinates, in meters. This
  24     // represents the radius of a circle around the given location.
  25     double accuracy;
  26
  27     // The accuracy in meters of the 'altitude' attribute if it's not null,
  28     // otherwise, null.
  29     double? altitudeAccuracy;
  30
  31     // The direction of travel of the hosting device and is specified in
  32     // degrees, where 0 <= heading < 360, counting clockwise relative to the
  33     // true north. If the Chrome cannot provide heading information, the value
  34     // of this attribute is null. If the hosting device is stationary (i.e. the
  35     // value of the speed attribute is 0), then the value of the heading
  36     // attribute is NaN.
  37     double? heading;
  38
  39     // The magnitude of the horizontal component of the hosting device's current
  40     // velocity and is specified in meters per second. If the Chrome cannot
  41     // provide speed information, the value of this attribute is null.
  42     double? speed;
  43   };
  44
  45   // Parameter of onLocationUpdate event's listener.
  46   dictionary Location {
  47     // Location watch request name.
  48     DOMString name;
  49
  50     // Coordinates and their accuracy.
  51     Coordinates coords;
  52
  53     // The time when the Location object was acquired in milliseconds since the
  54     // start of the Unix Epoch.
  55     double timestamp;
  56   };
  57
  58   // Parameter of watchLocation call.
  59   dictionary WatchLocationRequestInfo {
  60     // Minimum distance between location updates, in meters. Defaults to 0 - any
  61     // change in location will be reported.
  62     double? minDistanceInMeters;
  63
  64     // Minimum time interval between location updates, in milliseconds. Defaults
  65     // to 0 - system-defined frequency of updates will be used.
  66     double? minTimeInMilliseconds;
  67
  68     // Maximum age of a cached location, in milliseconds, that Chrome can pass
  69     // to the first onLocationUpdate event for this location watch request.
  70     // If this value <= 0, Chrome will always attempt to acquire a new location.
  71     // Defaults to 0.
  72     long? maximumAge;
  73   };
  74
  75   // TODO(vadimt): Consider adding getWatch() and getAllWatches().
  76   interface Functions {
  77     // Starts a location watching request. If there is another location watching
  78     // request with the same name (or no name if none is specified), it will be
  79     // cancelled and replaced by this request.
  80     // |name| : Optional name to identify this request. Defaults to the empty
  81     // string.
  82     // |requestInfo| : Optional parameters for this request.
  83     static void watchLocation(DOMString name,
  84                               WatchLocationRequestInfo requestInfo);
  85
  86     // Ends a location watching request.
  87     // |name| : Optional name to identify the request to remove. Defaults to the
  88     // empty string.
  89     static void clearWatch(DOMString name);
  90   };
  91
  92   interface Events {
  93     // Fired when a location change is detected.
  94     // |location| : An object containing matching events and new location.
  95     static void onLocationUpdate(Location location);
  96
  97     // Fired when detecting location in not possible.
  98     // |error| : Human-readable error description.
  99     static void onLocationError(DOMString error);
 100   };
 101 };