chrome/common/extensions/api/location.idl

// Copyright (c) 2013 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.
// TODO(vadimt): Consider reusing WebKit/Blink types, if this is possible.

// Use the <code>chrome.location</code> API to retrieve the geographic location
// of the host machine. This API is a version of the <a
// href="http://dev.w3.org/geo/api/spec-source.html">HTML Geolocation API</a>
// that is compatible with event pages.
namespace location {
  // Coordinates part of the Location object.
  dictionary Coordinates {
    // The geographic latitude specified in degrees.
    double latitude;

    // The geographic longitude specified in degrees.
    double longitude;

    // The height of the position, specified in meters above the [WGS84]
    // ellipsoid, or null if Chrome cannot provide altitude information.
    double? altitude;

    // The accuracy of the latitude and longitude coordinates, in meters. This
    // represents the radius of a circle around the given location.
    double accuracy;

    // The accuracy in meters of the 'altitude' attribute if it's not null,
    // otherwise, null.
    double? altitudeAccuracy;

    // The direction of travel of the hosting device and is specified in
    // degrees, where 0 <= heading < 360, counting clockwise relative to the
    // true north. If the Chrome cannot provide heading information, the value
    // of this attribute is null. If the hosting device is stationary (i.e. the
    // value of the speed attribute is 0), then the value of the heading
    // attribute is NaN.
    double? heading;

    // The magnitude of the horizontal component of the hosting device's current
    // velocity and is specified in meters per second. If the Chrome cannot
    // provide speed information, the value of this attribute is null.
    double? speed;
  };

  // Parameter of onLocationUpdate event's listener.
  dictionary Location {
    // Location watch request name.
    DOMString name;

    // Coordinates and their accuracy.
    Coordinates coords;

    // The time when the Location object was acquired in milliseconds since the
    // start of the Unix Epoch.
    double timestamp;
  };

  // Parameter of watchLocation call.
  dictionary WatchLocationRequestInfo {
    // Minimum distance between location updates, in meters. Defaults to 0 - any
    // change in location will be reported.
    double? minDistanceInMeters;

    // Minimum time interval between location updates, in milliseconds. Defaults
    // to 0 - system-defined frequency of updates will be used.
    double? minTimeInMilliseconds;

    // Maximum age of a cached location, in milliseconds, that Chrome can pass
    // to the first onLocationUpdate event for this location watch request.
    // If this value <= 0, Chrome will always attempt to acquire a new location.
    // Defaults to 0.
    long? maximumAge;
  };

  // TODO(vadimt): Consider adding getWatch() and getAllWatches().
  interface Functions {
    // Starts a location watching request. If there is another location watching
    // request with the same name (or no name if none is specified), it will be
    // cancelled and replaced by this request.
    // |name| : Optional name to identify this request. Defaults to the empty
    // string.
    // |requestInfo| : Optional parameters for this request.
    static void watchLocation(DOMString name,
                              WatchLocationRequestInfo requestInfo);

    // Ends a location watching request.
    // |name| : Optional name to identify the request to remove. Defaults to the
    // empty string.
    static void clearWatch(DOMString name);
  };

  interface Events {
    // Fired when a location change is detected.
    // |location| : An object containing matching events and new location.
    static void onLocationUpdate(Location location);

    // Fired when detecting location in not possible.
    // |error| : Human-readable error description.
    static void onLocationError(DOMString error);
  };
};