content/public/browser/geolocation_provider.h

   1 // Copyright (c) 2012 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
   5 #ifndef CONTENT_PUBLIC_BROWSER_GEOLOCATION_PROVIDER_H_
   6 #define CONTENT_PUBLIC_BROWSER_GEOLOCATION_PROVIDER_H_
   7
   8 #include "base/callback_list.h"
   9 #include "content/common/content_export.h"
  10
  11 namespace content {
  12 struct Geoposition;
  13
  14 // This is the main API to the geolocation subsystem. The application will hold
  15 // a single instance of this class and can register multiple clients to be
  16 // notified of location changes:
  17 // * Callbacks are registered by AddLocationUpdateCallback() and will keep
  18 //   receiving updates until the returned subscription object is destructed.
  19 // The application must instantiate the GeolocationProvider on the UI thread and
  20 // must communicate with it on the same thread.
  21 // The underlying location arbitrator will only be enabled whilst there is at
  22 // least one registered observer or pending callback (and only after
  23 // UserDidOptIntoLocationServices). The arbitrator and the location providers it
  24 // uses run on a separate Geolocation thread.
  25 class GeolocationProvider {
  26  public:
  27   CONTENT_EXPORT static GeolocationProvider* GetInstance();
  28
  29   typedef base::Callback<void(const Geoposition&)> LocationUpdateCallback;
  30   typedef base::CallbackList<void(const Geoposition&)>::Subscription
  31       Subscription;
  32
  33   // |use_high_accuracy| is used as a 'hint' for the provider preferences for
  34   // this particular observer, however the observer could receive updates for
  35   // best available locations from any active provider whilst it is registered.
  36   virtual scoped_ptr<Subscription> AddLocationUpdateCallback(
  37       const LocationUpdateCallback& callback, bool use_high_accuracy) = 0;
  38
  39   // Calling this method indicates the user has opted into using location
  40   // services, including sending network requests to [Google servers to] resolve
  41   // the user's location. Use this method carefully, in line with the rules in
  42   // go/chrome-privacy-doc.
  43   virtual void UserDidOptIntoLocationServices() = 0;
  44
  45   // Overrides the current location for testing.
  46   //
  47   // Overrides the location for automation/testing. Suppresses any further
  48   // updates from the actual providers and sends an update with the overridden
  49   // position to all registered clients.
  50   //
  51   // Do not use this function in unit tests. The function instantiates the
  52   // singleton geolocation stack in the background and manipulates it to report
  53   // a fake location. Neither step can be undone, breaking unit test isolation
  54   // (crbug.com/125931).
  55   virtual void OverrideLocationForTesting(const Geoposition& position) = 0;
  56
  57  protected:
  58   virtual~GeolocationProvider() {}
  59 };
  60
  61 }  // namespace content
  62
  63 #endif  // CONTENT_PUBLIC_BROWSER_GEOLOCATION_PROVIDER_H_