ubuntu-location-service  ..
An aggregating location service providing positioning and geocoding capabilities to applications.
provider.h
Go to the documentation of this file.
1 /*
2  * Copyright © 2012-2013 Canonical Ltd.
3  *
4  * This program is free software: you can redistribute it and/or modify it
5  * under the terms of the GNU Lesser General Public License version 3,
6  * as published by the Free Software Foundation.
7  *
8  * This program is distributed in the hope that it will be useful,
9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11  * GNU Lesser General Public License for more details.
12  *
13  * You should have received a copy of the GNU Lesser General Public License
14  * along with this program. If not, see <http://www.gnu.org/licenses/>.
15  *
16  * Authored by: Thomas Voß <thomas.voss@canonical.com>
17  */
18 #ifndef LOCATION_SERVICE_COM_UBUNTU_LOCATION_PROVIDER_H_
19 #define LOCATION_SERVICE_COM_UBUNTU_LOCATION_PROVIDER_H_
20 
28 
29 #include <core/property.h>
30 #include <core/signal.h>
31 
32 #include <atomic>
33 #include <bitset>
34 #include <memory>
35 
36 namespace com
37 {
38 namespace ubuntu
39 {
40 namespace location
41 {
45 class Provider
46 {
47 public:
48  typedef std::shared_ptr<Provider> Ptr;
49 
53  enum class Features : std::size_t
54  {
55  none = 0,
56  position = 1 << 0,
57  velocity = 1 << 1,
58  heading = 1 << 2
59  };
60 
64  enum class Requirements : std::size_t
65  {
66  none = 0,
67  satellites = 1 << 0,
68  cell_network = 1 << 1,
69  data_network = 1 << 2,
70  monetary_spending = 1 << 3
71  };
72 
80  class Controller
81  {
82  public:
83  typedef std::shared_ptr<Controller> Ptr;
84 
85  virtual ~Controller() = default;
86  Controller(const Controller&) = delete;
87  Controller& operator=(const Controller&) = delete;
88 
93  void disable();
94 
99  void enable();
100 
104  virtual void start_position_updates();
105 
109  virtual void stop_position_updates();
110 
115  bool are_position_updates_running() const;
116 
120  virtual void start_heading_updates();
121 
125  virtual void stop_heading_updates();
126 
131  bool are_heading_updates_running() const;
132 
136  virtual void start_velocity_updates();
137 
141  virtual void stop_velocity_updates();
142 
147  bool are_velocity_updates_running() const;
148 
149  protected:
150  friend class Provider;
151  explicit Controller(Provider& instance);
152 
153  private:
154  Provider& instance;
155  std::atomic<int> position_updates_counter;
156  std::atomic<int> heading_updates_counter;
157  std::atomic<int> velocity_updates_counter;
158  };
159 
163  struct Updates
164  {
166  core::Signal<Update<Position>> position;
168  core::Signal<Update<Heading>> heading;
170  core::Signal<Update<Velocity>> velocity;
172  core::Signal<Update<std::set<SpaceVehicle>>> svs;
173  };
174 
175  virtual ~Provider() = default;
176 
177  Provider(const Provider&) = delete;
178  Provider& operator=(const Provider&) = delete;
179 
184  virtual const Updates& updates() const;
185 
189  virtual const Controller::Ptr& state_controller() const;
190 
196  virtual bool supports(const Features& f) const;
197 
203  virtual bool requires(const Requirements& r) const;
204 
210  virtual bool matches_criteria(const Criteria& criteria);
211 
217 
222  virtual void on_reference_location_updated(const Update<Position>& position);
223 
228  virtual void on_reference_velocity_updated(const Update<Velocity>& velocity);
229 
234  virtual void on_reference_heading_updated(const Update<Heading>& heading);
235 
236 protected:
237  explicit Provider(
240 
241  virtual Updates& mutable_updates();
242 
246  virtual void start_position_updates();
247 
251  virtual void stop_position_updates();
252 
256  virtual void start_heading_updates();
257 
261  virtual void stop_heading_updates();
262 
266  virtual void start_velocity_updates();
267 
271  virtual void stop_velocity_updates();
272 
273 private:
274  struct
275  {
280  } d;
281 };
282 
285 
288 }
289 }
290 }
291 
292 #endif // LOCATION_SERVICE_COM_UBUNTU_LOCATION_PROVIDER_H_
The provider does not support any feature.
virtual void start_heading_updates()
Implementation-specific, empty by default.
std::shared_ptr< Controller > Ptr
Definition: provider.h:83
virtual void start_velocity_updates()
Request to start velocity updates if not already running.
Requirements
Enumerates the requirements of a provider implementation.
Definition: provider.h:64
The provider requires satellites to be visible.
void enable()
enable switches the provider to an enabled state, such that subsequent calls to start* methods succee...
Provider(const Provider &)=delete
Controller & operator=(const Controller &)=delete
virtual Updates & mutable_updates()
Templated class that wraps a value and timestamp.
Definition: update.h:36
void disable()
disable switches the provider to a disabled state, such that subsequent calls to start* methods fail...
Wraps all updates that can be delivered by a provider.
Definition: provider.h:163
virtual void stop_velocity_updates()
Request to stop velocity updates. Only stops the provider when the last observer calls this function...
bool are_position_updates_running() const
Checks if position updates are currently running.
core::Signal< Update< Velocity > > velocity
Definition: provider.h:170
bool are_heading_updates_running() const
Checks if position updates are currently running.
Features
Enumerates the known features that can be supported by providers.
Definition: provider.h:53
Provider::Features operator|(Provider::Features lhs, Provider::Features rhs)
Definition: accuracy.h:23
virtual void on_reference_heading_updated(const Update< Heading > &heading)
Called by the engine whenever the reference heading changed.
virtual void on_reference_location_updated(const Update< Position > &position)
Called by the engine whenever the reference location changed.
virtual void start_velocity_updates()
Implementation-specific, empty by default.
The Provider class is the abstract base of all positioning providers.
Definition: provider.h:45
The provider features heading updates.
virtual bool matches_criteria(const Criteria &criteria)
Checks if a provider satisfies a set of accuracy criteria.
std::shared_ptr< Provider > Ptr
Definition: provider.h:48
virtual void stop_position_updates()
Implementation-specific, empty by default.
The provider features velocity updates.
virtual bool requires(const Requirements &r) const
Checks if the provider has got a specific requirement.
The provider does not require anything.
core::Signal< Update< Heading > > heading
Definition: provider.h:168
virtual void start_position_updates()
Implementation-specific, empty by default.
bool are_velocity_updates_running() const
Checks if velocity updates are currently running.
Using the provider results in monetary cost.
core::Signal< Update< Position > > position
Definition: provider.h:166
Controller(const Controller &)=delete
virtual void stop_position_updates()
Request to stop position updates. Only stops the provider when the last observer calls this function...
virtual void stop_heading_updates()
Request to stop heading updates. Only stops the provider when the last observer calls this function...
Provider::Features operator&(Provider::Features lhs, Provider::Features rhs)
Provider & operator=(const Provider &)=delete
virtual void start_position_updates()
Request to start position updates if not already running.
virtual void stop_heading_updates()
Implementation-specific, empty by default.
The provider requires a cell-network to work correctly.
Facade for controlling the state of position/heading/velocity updates.
Definition: provider.h:80
Summarizes criteria of a client session with respect to functionality and accuracy for position...
Definition: criteria.h:34
The provider requires a data-network to work correctly.
virtual void on_wifi_and_cell_reporting_state_changed(WifiAndCellIdReportingState state)
Called by the engine whenever the wifi and cell ID reporting state changes.
virtual void stop_velocity_updates()
Implementation-specific, empty by default.
Controller::Ptr controller
Definition: provider.h:279
virtual bool supports(const Features &f) const
Checks if the provider supports a specific feature.
virtual const Controller::Ptr & state_controller() const
Access to the controller facade of this provider instance.
virtual void start_heading_updates()
Request to start heading updates if not already running.
virtual const Updates & updates() const
Provides non-mutable access to this provider's updates.
virtual void on_reference_velocity_updated(const Update< Velocity > &velocity)
Called by the engine whenever the reference velocity changed.
core::Signal< Update< std::set< SpaceVehicle > > > svs
Definition: provider.h:172
The provider features position updates.