location-service

Merge lp:~thomas-voss/location-service/export-dbus-api into lp:location-service

  1. export-dbus-api
  2. Merge into next
Proposed by Thomas Voß
Status: Merged
Approved by: Thomas Voß
Approved revision: 302
Merged at revision: 300
Proposed branch: lp:~thomas-voss/location-service/export-dbus-api
Merge into: lp:location-service
Diff against target: 398 lines (+195/-125)
6 files modified
data/location/dbus/provider.xml (+66/-38)
data/location/dbus/service.xml (+60/-42)
data/location/dbus/session.xml (+30/-20)
doc/api.md (+18/-4)
src/location/CMakeLists.txt (+20/-20)
src/location/providers/remote/provider.h (+1/-1)
To merge this branch: bzr merge lp:~thomas-voss/location-service/export-dbus-api
Reviewer Review Type Date Requested Status
Simon Fels (community) Approve
Thomas Voß Pending
Review via email: mp+321965@code.launchpad.net

Commit message

Export the dbus APIs for service and session.

Description of the change

Export the dbus APIs for service and session.

To post a comment you must log in.
Revision history for this message
Simon Fels (morphis) wrote :

LGTM

review: Approve
lp:~thomas-voss/location-service/export-dbus-api updated
302. By Thomas Voß

Factor out Provider interface.

Revision history for this message
Simon Fels (morphis) wrote :

LGTM

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== added directory 'data/location'
2=== added directory 'data/location/dbus'
3=== renamed file 'src/location/providers/remote/provider.xml' => 'data/location/dbus/provider.xml'
4--- src/location/providers/remote/provider.xml 2017-03-04 21:43:23 +0000
5+++ data/location/dbus/provider.xml 2017-04-05 12:35:26 +0000
6@@ -1,40 +1,68 @@
7 <node>
8- <interface name='com.ubuntu.location.Service.Provider'>
9- <method name='Satisfies'>
10- <!--
11- The following keys are optional:
12- * position: boolean
13- * heading: boolean
14- * velocity: boolean
15- -->
16- <arg name="requirements" type="a{sv}" direction='in'/>
17- <arg name="result" type="b" direction='out'/>
18- </method>
19- <method name='Enable'/>
20- <method name='Disable'/>
21- <method name='Activate'/>
22- <method name='Deactivate'/>
23- <method name='OnNewEvent'>
24- <arg name="event" type="a{sv}" direction="in"/>
25- </method>
26- <!--
27- The following keys are optional:
28- * position: boolean
29- * heading: boolean
30- * velocity: boolean
31- -->
32- <property name='Requirements' type='a{sv}' access='read'/>
33- <!--
34- The following keys are always available in the dictionary:
35- * latitude: double
36- * longitude: double
37- The following keys are optional:
38- * horizontal-accuracy: double
39- * altitude: double
40- * vertical-accuracy: double
41- -->
42- <property name='Position' type='(ta{sv})' access='read'/>
43- <property name='Velocity' type='(t(d))' access='read' />
44- <property name='Heading' type='(t(d))' access='read' />
45- </interface>
46+ <interface name='com.ubuntu.location.Service.Provider'>
47+ <!-- Satisfies checks if a given set of requirements
48+ can be satisfied by a Provider -->
49+ <method name='Satisfies'>
50+ <!--
51+ The following keys are optional:
52+ - position: boolean
53+ - heading: boolean
54+ - velocity: boolean
55+ -->
56+ <arg name="requirements" type="a{sv}" direction='in'/>
57+ <!-- Result is true if the requirements can be satsified, false otherwise -->
58+ <arg name="result" type="b" direction='out'/>
59+ </method>
60+ <!-- Enable requests the Provider to prepare for subsequent activation calls -->
61+ <method name='Enable'/>
62+ <!-- Disable requests the Provider to give up as many resources required for operation as possible -->
63+ <method name='Disable'/>
64+ <!-- Activate requests the Provider to start up and provide position/velocity/heading updates -->
65+ <method name='Activate'/>
66+ <!-- Deactivate requests the Provider to stop providing position/velocity/heading updates -->
67+ <method name='Deactivate'/>
68+ <!--
69+ OnNewEvent is called whenever new system events are available. The 'event' will always
70+ contain the following key/value pairs:
71+ - 'type': string, one of {location::ReferencePositionUpdated, location::WifiAndCellReportingStateChanged}
72+ Depending on 'type', the following key/value pairs are present in 'event':
73+ - location::ReferencePositionUpdated:
74+ - 'when': uint64, timestamp of the event, unix time in [µs}
75+ - 'latitude': double, latitude of the position in [°]
76+ - 'longitude': double, longitude of the position in [°]
77+ - optional['altitude']: double, height above mean sea level of the position in [m]
78+ - optional['horizontal-accuracy']: double, accuracy estimate of the position in [m]
79+ - optional['vertical-accurady']: double, accuracy estimate of the altitue in [m]
80+ - location::WifiAndCellReportingStateChanged:
81+ - 'new-state': string, one of {enabled, disabled}
82+ -->
83+ <method name='OnNewEvent'>
84+ <arg name="event" type="a{sv}" direction="in"/>
85+ </method>
86+ <!--
87+ Describes the minimum requirements of a Provider.
88+ The following key/value pairs are known:
89+ - 'needs-cell-network': boolean
90+ - 'needs-data-network': boolean
91+ - 'needs-monetary-spending': boolean
92+ - 'needs-satellites': boolean
93+ -->
94+ <property name='Requirements' type='a{sv}' access='read'/>
95+ <!--
96+ Timestamped updates of position. Clock refers to unix time in
97+ microseconds. The following keys are always available in the
98+ dictionary:
99+ - latitude: double, in [°]
100+ - longitude: double, in [°]
101+ The following keys are optional:
102+ - horizontal-accuracy: double, in [m]
103+ - altitude: double, in [m]
104+ - vertical-accuracy: double, in [m]
105+ -->
106+ <property name='Position' type='(ta{sv})' access='read'/>
107+ <!-- Timestamped updates to the current velocity in [m/s]. Clock refers to unix time in microseconds. -->
108+ <property name='Velocity' type='(t(d))' access='read' />
109+ <!-- Timestamped updates to the current heading in [°]. Clock refers to unix time in microseconds. -->
110+ <property name='Heading' type='(t(d))' access='read' />
111+ </interface>
112 </node>
113
114=== renamed file 'src/location/dbus/service.xml' => 'data/location/dbus/service.xml'
115--- src/location/dbus/service.xml 2017-03-04 21:43:23 +0000
116+++ data/location/dbus/service.xml 2017-04-05 12:35:26 +0000
117@@ -1,44 +1,62 @@
118 <node name='/com/ubuntu/location/Service'>
119- <interface name='com.ubuntu.location.Service'>
120- <!--
121- Within the extras dictionary, the following keys
122- are handled by the service implementation:
123- * 'wants-position': boolean
124- * 'wants-heading': boolean
125- * 'wants-velocity': boolean
126- * 'horizontal-accuracy': double, in [m]
127- * 'vertical-accuracy': double, in [m]
128- * 'velocity-accuracy': double, in [m/s]
129- * 'heading-accuracy': double, in [°]
130- -->
131- <method name='CreateSessionForCriteria'>
132- <arg name='requirements' type='a{sv}' direction='in'/>
133- <arg name='path' type='o' direction='out'/>
134- </method>
135-
136- <method name='AddProvider'>
137- <arg name='object' type='o' direction='in'/>
138- </method>
139-
140- <method name='RemoveProvider'>
141- <arg name='object' type='o' direction='in'/>
142- </method>
143-
144- <property name='State' type='s' access='readwrite'/>
145- <property name='DoesSatelliteBasedPositioning' type='b' access='readwrite'/>
146- <property name='DoesReportCellAndWifiIds' type='b' access='readwrite'/>
147- <property name='IsOnline' type='b' access='readwrite'/>
148- <!--
149- Within every dict, at least the following keys are available:
150- * 'type': string
151- * 'id': int32
152- * 'snr': double
153- * 'has-almanac-data': boolean
154- * 'has-ephimeris-data': boolean
155- * 'used-in-fix': boolean
156- * 'azimuth': double
157- * 'elevation': double
158- -->
159- <property name='VisibleSpaceVehicles' type='aa{sv}' access='read'/>
160- </interface>
161+ <interface name='com.ubuntu.location.Service'>
162+ <!-- Creates a new session for monitoring updates delivered by the
163+ service. Returns a path to an object implementing
164+ com.ubuntu.location.Session.Service on success, an error
165+ otherwise.
166+ -->
167+ <method name='CreateSessionForCriteria'>
168+ <!--
169+ The following keys are handled by the service implementation:
170+ - 'wants-position': boolean
171+ - 'wants-heading': boolean
172+ - 'wants-velocity': boolean
173+ - 'horizontal-accuracy': double, in [m]
174+ - 'vertical-accuracy': double, in [m]
175+ - 'velocity-accuracy': double, in [m/s]
176+ - 'heading-accuracy': double, in [°]
177+ -->
178+ <arg name='requirements' type='a{sv}' direction='in'/>
179+ <!--
180+ Path to an object implementation to
181+ com.ubuntu.location.Service.Session.
182+ -->
183+ <arg name='path' type='o' direction='out'/>
184+ </method>
185+
186+ <!-- Registers 'object' implementing com.ubuntu.location.Service.Provider
187+ with the service. Returns an error in case of issues.
188+ -->
189+ <method name='AddProvider'>
190+ <!-- Path to an object implementing com.ubuntu.location.Service.Provider -->
191+ <arg name='object' type='o' direction='in'/>
192+ </method>
193+
194+ <!-- Removes 'object' implementing com.ubuntu.location.Service.Provider
195+ from the service -->
196+ <method name='RemoveProvider'>
197+ <!-- Path to an object implementing com.ubuntu.location.Service.Provider -->
198+ <arg name='object' type='o' direction='in'/>
199+ </method>
200+
201+ <!-- The current state of the service, takes values from {disabled, enabled, active} -->
202+ <property name='State' type='s' access='readwrite'/>
203+ <!-- Indicates whether the service considers providers relying on
204+ satellite constellation for positioning requests -->
205+ <property name='DoesSatelliteBasedPositioning' type='b' access='readwrite'/>
206+ <!-- Indicates whether the service considers providers relying
207+ on visible cell and wifi networks for positioning requests -->
208+ <property name='DoesReportCellAndWifiIds' type='b' access='readwrite'/>
209+ <!-- Indicates whether the positioning engine powering the service
210+ is online or not. -->
211+ <property name='IsOnline' type='b' access='readwrite'/>
212+ <!--
213+ Within every dict, at least the following keys are available:
214+ * 'type': string * 'id': int32 * 'snr': double *
215+ 'has-almanac-data': boolean * 'has-ephimeris-data': boolean *
216+ 'used-in-fix': boolean * 'azimuth': double * 'elevation':
217+ double
218+ -->
219+ <property name='VisibleSpaceVehicles' type='aa{sv}' access='read'/>
220+ </interface>
221 </node>
222
223=== renamed file 'src/location/dbus/session.xml' => 'data/location/dbus/session.xml'
224--- src/location/dbus/session.xml 2017-03-08 11:31:54 +0000
225+++ data/location/dbus/session.xml 2017-04-05 12:35:26 +0000
226@@ -1,22 +1,32 @@
227 <node>
228- <interface name='com.ubuntu.location.Service.Session'>
229- <method name='StartPositionUpdates'/>
230- <method name='StopPositionUpdates'/>
231- <method name='StartVelocityUpdates'/>
232- <method name='StopVelocityUpdates'/>
233- <method name='StartHeadingUpdates'/>
234- <method name='StopHeadingUpdates'/>
235- <!--
236- The following keys are always available in the dictionary:
237- * latitude: double, in degrees
238- * longitude: double, in degrees
239- The following keys are optional:
240- * horizontal-accuracy: double, in meters
241- * altitude: double, in meters
242- * vertical-accuracy: double, in meteres
243- -->
244- <property name='Position' type='(ta{sv})' access='read'/>
245- <property name='Velocity' type='(t(d))' access='read' />
246- <property name='Heading' type='(t(d))' access='read' />
247- </interface>
248+ <interface name='com.ubuntu.location.Service.Session'>
249+ <!-- Requests the session to start delivering updates to Position -->
250+ <method name='StartPositionUpdates'/>
251+ <!-- Requests the session to stop delivering updates to Position -->
252+ <method name='StopPositionUpdates'/>
253+ <!-- Requests the session to start delivering updates to Velocity -->
254+ <method name='StartVelocityUpdates'/>
255+ <!-- Requests the session to stop delivering updates to Velocity -->
256+ <method name='StopVelocityUpdates'/>
257+ <!-- Requests the session to start delivering updates to Heading -->
258+ <method name='StartHeadingUpdates'/>
259+ <!-- Requests the session to stop delivering updates to Heading -->
260+ <method name='StopHeadingUpdates'/>
261+ <!--
262+ Timestamped updates of position. Clock refers to unix time in
263+ microseconds. The following keys are always available in the
264+ dictionary:
265+ - latitude: double, in [°]
266+ - longitude: double, in [°]
267+ The following keys are optional:
268+ - horizontal-accuracy: double, in [m]
269+ - altitude: double, in [m]
270+ - vertical-accuracy: double, in [m]
271+ -->
272+ <property name='Position' type='(ta{sv})' access='read'/>
273+ <!-- Timestamped updates to the current velocity in [m/s]. Clock refers to unix time in microseconds. -->
274+ <property name='Velocity' type='(t(d))' access='read' />
275+ <!-- Timestamped updates to the current heading in [°]. Clock refers to unix time in microseconds. -->
276+ <property name='Heading' type='(t(d))' access='read' />
277+ </interface>
278 </node>
279
280=== modified file 'doc/api.md'
281--- doc/api.md 2016-09-22 10:46:17 +0000
282+++ doc/api.md 2017-04-05 12:35:26 +0000
283@@ -1,12 +1,26 @@
284 # API
285
286-Location service exposes a DBus API to interact with a service instance.
287-We do not expose introspection for the API, yet. Instead, we provide a C++ client API that
288-abstracts away from the underlying IPC mechanism.
289+Locationd offers multiple different ways of interfacing with the
290+service. The primary protocol is using DBus. We offer a plain C++ API,
291+too, that abstracts away the protocol details.
292+
293+All APIs we expose are guaranteed to remain ABI stable within any
294+given major release.
295+
296+## DBus
297+
298+The DBus introspection files are available in
299+[`${SOURCE}/data/location/dbus`](http://bazaar.launchpad.net/~thomas-voss/location-service/next/files/head:/data/) ready
300+for consumption by static and dynamic binding generators. Methods,
301+properties and signals are documented within the respective
302+introspection files.
303+
304+## C++
305
306 A client application then uses the API to establish a session with a
307 service, register observers to receive updates and to control the
308-status of updates. The following snippet illustrates basic usage of the client API:
309+status of updates. The following snippet illustrates basic usage of
310+the client API:
311
312 ```{cpp}
313 auto service = location::connect_to_service(...);
314
315=== modified file 'src/location/CMakeLists.txt'
316--- src/location/CMakeLists.txt 2017-03-31 16:19:41 +0000
317+++ src/location/CMakeLists.txt 2017-04-05 12:35:26 +0000
318@@ -9,26 +9,26 @@
319 )
320
321 include_directories(
322- ${CMAKE_BINARY_DIR}/src
323- ${UBUNTU_PLATFORM_HARDWARE_API_INCLUDE_DIRS})
324+ ${CMAKE_BINARY_DIR}/src
325+ ${CMAKE_BINARY_DIR}/data
326+ ${UBUNTU_PLATFORM_HARDWARE_API_INCLUDE_DIRS})
327
328-file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/dbus")
329-file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/providers/remote")
330+file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/data/location/dbus")
331 file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/connectivity")
332
333 find_program(GDBUS_CODEGEN_EXECUTABLE NAMES gdbus-codegen)
334
335 add_custom_command(
336- OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/dbus/service_gen.h" "${CMAKE_CURRENT_BINARY_DIR}/dbus/service_gen.c"
337- COMMAND ${GDBUS_CODEGEN_EXECUTABLE} --generate-c-code "${CMAKE_CURRENT_BINARY_DIR}/dbus/service_gen" "${CMAKE_CURRENT_SOURCE_DIR}/dbus/service.xml")
338-
339-add_custom_command(
340- OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/dbus/session_gen.h" "${CMAKE_CURRENT_BINARY_DIR}/dbus/session_gen.c"
341- COMMAND ${GDBUS_CODEGEN_EXECUTABLE} --c-generate-object-manager --generate-c-code "${CMAKE_CURRENT_BINARY_DIR}/dbus/session_gen" "${CMAKE_CURRENT_SOURCE_DIR}/dbus/session.xml")
342-
343-add_custom_command(
344- OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/providers/remote/provider_gen.h" "${CMAKE_CURRENT_BINARY_DIR}/providers/remote/provider_gen.c"
345- COMMAND ${GDBUS_CODEGEN_EXECUTABLE} --generate-c-code "${CMAKE_CURRENT_BINARY_DIR}/providers/remote/provider_gen" "${CMAKE_CURRENT_SOURCE_DIR}/providers/remote/provider.xml")
346+ OUTPUT "${CMAKE_BINARY_DIR}/data/location/dbus/service_gen.h" "${CMAKE_BINARY_DIR}/data/location/dbus/service_gen.c"
347+ COMMAND ${GDBUS_CODEGEN_EXECUTABLE} --generate-c-code "${CMAKE_BINARY_DIR}/data/location/dbus/service_gen" "${CMAKE_SOURCE_DIR}/data/location/dbus/service.xml")
348+
349+add_custom_command(
350+ OUTPUT "${CMAKE_BINARY_DIR}/data/location/dbus/session_gen.h" "${CMAKE_BINARY_DIR}/data/location/dbus/session_gen.c"
351+ COMMAND ${GDBUS_CODEGEN_EXECUTABLE} --c-generate-object-manager --generate-c-code "${CMAKE_BINARY_DIR}/data/location/dbus/session_gen" "${CMAKE_SOURCE_DIR}/data/location/dbus/session.xml")
352+
353+add_custom_command(
354+ OUTPUT "${CMAKE_BINARY_DIR}/data/location/dbus/provider_gen.h" "${CMAKE_BINARY_DIR}/data/location/dbus/provider_gen.c"
355+ COMMAND ${GDBUS_CODEGEN_EXECUTABLE} --generate-c-code "${CMAKE_BINARY_DIR}/data/location/dbus/provider_gen" "${CMAKE_SOURCE_DIR}/data/location/dbus/provider.xml")
356
357 add_custom_command(
358 OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/connectivity/w11t_gen.h" "${CMAKE_CURRENT_BINARY_DIR}/connectivity/w11t_gen.c"
359@@ -95,11 +95,11 @@
360 util/cli.cpp
361 util/do_not_copy_or_move.h
362
363- "${CMAKE_CURRENT_BINARY_DIR}/dbus/service_gen.h"
364- "${CMAKE_CURRENT_BINARY_DIR}/dbus/service_gen.c"
365+ "${CMAKE_BINARY_DIR}/data/location/dbus/service_gen.h"
366+ "${CMAKE_BINARY_DIR}/data/location/dbus/service_gen.c"
367
368- "${CMAKE_CURRENT_BINARY_DIR}/dbus/session_gen.h"
369- "${CMAKE_CURRENT_BINARY_DIR}/dbus/session_gen.c"
370+ "${CMAKE_BINARY_DIR}/data/location/dbus/session_gen.h"
371+ "${CMAKE_BINARY_DIR}/data/location/dbus/session_gen.c"
372
373 dbus/bus.h
374 dbus/bus.cpp
375@@ -141,8 +141,8 @@
376 providers/state_tracking_provider.h
377 providers/state_tracking_provider.cpp
378
379- "${CMAKE_CURRENT_BINARY_DIR}/providers/remote/provider_gen.h"
380- "${CMAKE_CURRENT_BINARY_DIR}/providers/remote/provider_gen.c"
381+ "${CMAKE_BINARY_DIR}/data/location/dbus/provider_gen.h"
382+ "${CMAKE_BINARY_DIR}/data/location/dbus/provider_gen.c"
383 providers/remote/provider.h
384 providers/remote/provider.cpp
385 )
386
387=== modified file 'src/location/providers/remote/provider.h'
388--- src/location/providers/remote/provider.h 2017-03-09 09:13:24 +0000
389+++ src/location/providers/remote/provider.h 2017-04-05 12:35:26 +0000
390@@ -25,7 +25,7 @@
391
392 #include <location/glib/shared_object.h>
393
394-#include <location/providers/remote/provider_gen.h>
395+#include <location/dbus/provider_gen.h>
396
397 namespace location
398 {

Subscribers

People subscribed via source and target branches

to all changes: