content/browser/geolocation/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_BROWSER_GEOLOCATION_GEOLOCATION_PROVIDER_H_
   6 #define CONTENT_BROWSER_GEOLOCATION_GEOLOCATION_PROVIDER_H_
   7
   8 #include <map>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/compiler_specific.h"
  13 #include "base/threading/thread.h"
  14 #include "content/browser/geolocation/geolocation_observer.h"
  15 #include "content/common/content_export.h"
  16 #include "content/public/browser/geolocation.h"
  17 #include "content/public/common/geoposition.h"
  18
  19 template<typename Type> struct DefaultSingletonTraits;
  20
  21 namespace content {
  22 class GeolocationArbitrator;
  23 class GeolocationProviderTest;
  24
  25 // This is the main API to the geolocation subsystem. The application will hold
  26 // a single instance of this class and can register multiple clients to be
  27 // notified of location changes:
  28 // * Observers are registered by AddObserver() and will keep receiving updates
  29 //   until unregistered by RemoveObserver().
  30 // * Callbacks are registered by RequestCallback() and will be called exactly
  31 //   once when the next update becomes available.
  32 // The application must instantiate the GeolocationProvider on the IO thread and
  33 // must communicate with it on the same thread.
  34 // The underlying location arbitrator will only be enabled whilst there is at
  35 // least one registered observer or pending callback. The arbitrator and the
  36 // location providers it uses run on a separate Geolocation thread.
  37 class CONTENT_EXPORT GeolocationProvider
  38     : public base::Thread, public GeolocationObserver {
  39  public:
  40   // The GeolocationObserverOptions passed are used as a 'hint' for the provider
  41   // preferences for this particular observer, however the observer could
  42   // receive updates for best available locations from any active provider
  43   // whilst it is registered.
  44   // If an existing observer is added a second time, its options are updated
  45   // but only a single call to RemoveObserver() is required to remove it.
  46   void AddObserver(GeolocationObserver* delegate,
  47                    const GeolocationObserverOptions& update_options);
  48
  49   // Remove a previously registered observer. No-op if not previously registered
  50   // via AddObserver(). Returns true if the observer was removed.
  51   bool RemoveObserver(GeolocationObserver* delegate);
  52
  53   // Request a single callback when the next location update becomes available.
  54   // Callbacks must only be requested by code that is allowed to access the
  55   // location. No further permission checks will be made.
  56   void RequestCallback(const GeolocationUpdateCallback& callback);
  57
  58   void OnPermissionGranted();
  59   bool HasPermissionBeenGranted() const;
  60
  61   // GeolocationObserver implementation.
  62   virtual void OnLocationUpdate(const Geoposition& position) OVERRIDE;
  63
  64   // Overrides the location for automation/testing. Suppresses any further
  65   // updates from the actual providers and sends an update with the overridden
  66   // position to all registered clients.
  67   void OverrideLocationForTesting(const Geoposition& override_position);
  68
  69   // Gets a pointer to the singleton instance of the location relayer, which
  70   // is in turn bound to the browser's global context objects. This must only be
  71   // called on the IO thread so that the GeolocationProvider is always
  72   // instantiated on the same thread. Ownership is NOT returned.
  73   static GeolocationProvider* GetInstance();
  74
  75  protected:
  76   friend struct DefaultSingletonTraits<GeolocationProvider>;
  77   GeolocationProvider();
  78   virtual ~GeolocationProvider();
  79
  80   // Useful for injecting mock geolocation arbitrator in tests.
  81   virtual GeolocationArbitrator* CreateArbitrator();
  82
  83  private:
  84   typedef std::map<GeolocationObserver*, GeolocationObserverOptions>
  85       ObserverMap;
  86
  87   typedef std::vector<GeolocationUpdateCallback> CallbackList;
  88
  89   bool OnGeolocationThread() const;
  90
  91   // Start and stop providers as needed when clients are added or removed.
  92   void OnClientsChanged();
  93
  94   // Stops the providers when there are no more registered clients. Note that
  95   // once the Geolocation thread is started, it will stay alive (but sitting
  96   // idle without any pending messages).
  97   void StopProviders();
  98
  99   // Starts the geolocation providers or updates their options (delegates to
 100   // arbitrator).
 101   void StartProviders(const GeolocationObserverOptions& options);
 102
 103   // Updates the providers on the geolocation thread, which must be running.
 104   void InformProvidersPermissionGranted();
 105
 106   // Notifies all registered clients that a position update is available.
 107   void NotifyClients(const Geoposition& position);
 108
 109   // Thread
 110   virtual void Init() OVERRIDE;
 111   virtual void CleanUp() OVERRIDE;
 112
 113   // Only used on the IO thread
 114   ObserverMap observers_;
 115   CallbackList callbacks_;
 116   bool is_permission_granted_;
 117   Geoposition position_;
 118
 119   // True only in testing, where we want to use a custom position.
 120   bool ignore_location_updates_;
 121
 122   // Only to be used on the geolocation thread.
 123   GeolocationArbitrator* arbitrator_;
 124
 125   DISALLOW_COPY_AND_ASSIGN(GeolocationProvider);
 126 };
 127
 128 }  // namespace content
 129
 130 #endif  // CONTENT_BROWSER_GEOLOCATION_GEOLOCATION_PROVIDER_H_