geolocation_provider.h revision cedac228d2dd51db4b79ea1e72c7f249408ee061 
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
11namespace content {
12struct 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.
25class 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_
64