summaryrefslogtreecommitdiff
path: root/src/lib/elocation/Elocation.h
diff options
context:
space:
mode:
authorStefan Schmidt <s.schmidt@samsung.com>2014-10-28 11:22:55 +0100
committerStefan Schmidt <s.schmidt@samsung.com>2014-11-11 11:02:08 +0100
commita2d2cdaf9f258ec4c6c7c33d912bbe41625e8532 (patch)
tree62f61f67cd6a74790e1b11f35a55f3a22e82b5ea /src/lib/elocation/Elocation.h
parentc2f130a2f77f7f319e819ff7883c8695aa45319e (diff)
elocation: Add elocation libraray to EFL.
Elocation is meant as a convenience library to ease application developers the usage of geo information in their apps. Adding a geo tag to a picture or translating an address to a GPS position and show it on a map widget are just some of the use cases. In the beginning elocation will rely on the GeoClue1 DBus service. Supporting the new GeoClue2 DBus service is planned and worked on. GeoClue offers providers for various techniques to get hold off the current position. Ranging from GeoIP over wifi and GSM cell location to GPS. This has been developed a while ago and was living in my private dev space. It is about time to move this into EFL and bring it forward. The detection of the GeoClue service is being handled on runtime and no new dependency is added due to this library. @feature
Diffstat (limited to 'src/lib/elocation/Elocation.h')
-rw-r--r--src/lib/elocation/Elocation.h418
1 files changed, 418 insertions, 0 deletions
diff --git a/src/lib/elocation/Elocation.h b/src/lib/elocation/Elocation.h
new file mode 100644
index 0000000000..851b679172
--- /dev/null
+++ b/src/lib/elocation/Elocation.h
@@ -0,0 +1,418 @@
1/**
2 * @brief Elocation Library
3 *
4 * @mainpage Elocation
5 * @version 0.0.0
6 * @author Stefan Schmidt <stefan@datenfreihafen.org>
7 * @date 2012
8 *
9 * @section intro Elocation Use Cases
10 *
11 * Elocation is meant as a convenience library to ease application developers
12 * the usage of geo information in their apps. Adding a geo tag to a picture or
13 * translating an address to a GPS position and show it on a map widget are just
14 * some of the use cases.
15 *
16 * In the beginning elocation will rely on the GeoClue DBus service. Its has
17 * providers for various techniques to get hold off the current position.
18 * Ranging from GeoIP over wifi and GSM cell location to GPS. As well as
19 * provider to translates between location in a textual form to coordinates
20 * (GeoCode).
21 *
22 * Elocation covers all of these interfaces but in the end it depends on your
23 * system and the installed GeoClue providers what can be used.
24 *
25 * Currently it offer the following functionality:
26 * @li Request current address in textual form
27 * @li Request current position in GPS format
28 * @li Translate a position into and address or an address in a position
29 *
30 * You can find the API documentation at @ref Location
31*/
32#ifndef _ELOCATION_H
33#define _ELOCATION_H
34
35#ifdef EAPI
36# undef EAPI
37#endif
38
39#ifdef _WIN32
40# ifdef EFL_ECORE_BUILD
41# ifdef DLL_EXPORT
42# define EAPI __declspec(dllexport)
43# else
44# define EAPI
45# endif /* ! DLL_EXPORT */
46# else
47# define EAPI __declspec(dllimport)
48# endif /* ! EFL_ECORE_BUILD */
49#else
50# ifdef __GNUC__
51# if __GNUC__ >= 4
52# define EAPI __attribute__ ((visibility("default")))
53# else
54# define EAPI
55# endif
56# else
57# define EAPI
58# endif
59#endif /* ! _WIN32 */
60
61#include <stdio.h>
62
63#include <Ecore.h>
64#include <Eldbus.h>
65
66/**
67 * @file Elocation.h
68 *
69 * @defgroup Location Location
70 */
71
72/**
73 * @ingroup Location
74 * @brief Available location events that are emitted from the library
75 * @since 1.8
76 *
77 * Ecore events emitted by the library. Applications can register ecore event
78 * handlers to react on such events. After the initial query this can be used
79 * to keep track of changes and update your UI or data accordingly.
80 * @{
81 */
82EAPI extern int ELOCATION_EVENT_STATUS; /**< Status changed */
83EAPI extern int ELOCATION_EVENT_POSITION; /**< Position changed */
84EAPI extern int ELOCATION_EVENT_ADDRESS; /**< Address changed */
85EAPI extern int ELOCATION_EVENT_VELOCITY; /**< Velocity changed */
86EAPI extern int ELOCATION_EVENT_GEOCODE; /**< Reply for geocode translation arrived */
87EAPI extern int ELOCATION_EVENT_REVERSEGEOCODE; /**< Reply for geocode translation arrived */
88EAPI extern int ELOCATION_EVENT_NMEA; /**< NMEA update */
89EAPI extern int ELOCATION_EVENT_SATELLITE; /**< Satellite info changed */
90EAPI extern int ELOCATION_EVENT_POI; /**< POI reply */
91EAPI extern int ELOCATION_EVENT_META_READY; /**< Meta provider is ready to be used */
92/**@}*/
93
94/**
95 * @ingroup Location
96 * @typedef Elocation_Accuracy_Level
97 * @since 1.8
98 *
99 * Different location accuracy levels from country level up to detailed,
100 * e.g. GPS, information.
101 * @{
102 */
103typedef enum {
104 ELOCATION_ACCURACY_LEVEL_NONE = 0,
105 ELOCATION_ACCURACY_LEVEL_COUNTRY,
106 ELOCATION_ACCURACY_LEVEL_REGION,
107 ELOCATION_ACCURACY_LEVEL_LOCALITY,
108 ELOCATION_ACCURACY_LEVEL_POSTALCODE,
109 ELOCATION_ACCURACY_LEVEL_STREET,
110 ELOCATION_ACCURACY_LEVEL_DETAILED,
111} Elocation_Accuracy_Level;
112/**@}*/
113
114/**
115 * @ingroup Location
116 * @typedef Elocation_Resource_Flags
117 * @since 1.8
118 *
119 * Flags for available system resources to be used for locating. So far they
120 * cover physical resources like network connection, cellular network
121 * connection and GPS.
122 * @{
123 */
124typedef enum {
125 ELOCATION_RESOURCE_NONE = 0,
126 ELOCATION_RESOURCE_NETWORK = 1 << 0, /**< Internet connection is available */
127 ELOCATION_RESOURCE_CELL = 1 << 1, /**< Cell network information, e.g. GSM, is available */
128 ELOCATION_RESOURCE_GPS = 1 << 2, /**< GPS information is available */
129
130 ELOCATION_RESOURCE_ALL = (1 << 10) - 1 /**< All resources are available */
131} Elocation_Resource_Flags;
132/**@}*/
133
134/**
135 * @ingroup Location
136 * @typedef Elocation_Accuracy
137 * @since 1.8
138 *
139 * Information about the accuracy of the reported location. For details about
140 * the level of accuracy see #Elocation_Accuracy_Level. It also covers
141 * horizontal and vertical accuracy. The values depend on the used provider
142 * and may very in quality.
143 */
144typedef struct _Elocation_Accuracy
145{
146 Elocation_Accuracy_Level level;
147 double horizontal;
148 double vertical;
149} Elocation_Accuracy;
150
151/**
152 * @ingroup Location
153 * @typedef Elocation_Address
154 * @since 1.8
155 *
156 * Location information in textual form. Depending on the used provider this
157 * can cover only the country or a detailed address with postcode and street.
158 * The level of detail varies depending on the used provider.
159 * A timestamp is available to calculate the age of the address data.
160 */
161typedef struct _Elocation_Address
162{
163 unsigned int timestamp; /**< Timestamp of data read out in seconds since epoch */
164 char *country;
165 char *countrycode;
166 char *locality;
167 char *postalcode;
168 char *region;
169 char *timezone;
170 Elocation_Accuracy *accur;
171} Elocation_Address;
172
173/**
174 * @ingroup Location
175 * @typedef Elocation_Position
176 * @since 1.8
177 *
178 * Location information based on the GPS grid. Latitude, longitude and altitude.
179 * A timestamp is available to calculate the age of the address data.
180 */
181typedef struct _Elocation_Postion
182{
183 unsigned int timestamp; /**< Timestamp of data read out in seconds since epoch */
184 double latitude;
185 double longitude;
186 double altitude;
187 Elocation_Accuracy *accur;
188} Elocation_Position;
189
190/**
191 * @ingroup Location
192 * @typedef Elocation_Velocity
193 * @since 1.8
194 *
195 * Velocity information. So far this interface is only offered with GPS based
196 * providers. It offers information about speed, direction and climb.
197 * A timestamp is available to calculate the age of the address data.
198 *
199 * FIXME: check units and formats of this values coming in from GeoClue
200 */
201typedef struct _Elocation_Velocity
202{
203 unsigned int timestamp; /**< Timestamp of data read out in seconds since epoch */
204 double speed;
205 double direction;
206 double climb;
207} Elocation_Velocity;
208
209/**
210 * @ingroup Location
211 * @typedef Elocation_Requirements
212 * @since 1.8
213 *
214 * Requirement settings for the location provider. Requirements can be a level
215 * of accuracy or allowed resources like network access or GPS. See
216 * #Elocation_Resource_Flags for all available resource flags.
217 *
218 * Based on this setting the best provider is chosen between the available
219 * providers of GeoClue.
220 */
221typedef struct _Elocation_Requirements
222{
223 Elocation_Accuracy_Level accurancy_level;
224 int min_time; /**< Minimal time between updates. Not implemented upstream */
225 Eina_Bool require_update;
226 Elocation_Resource_Flags allowed_resources;
227} Elocation_Requirements;
228
229/**
230 * @brief Create a new address object to operate on.
231 * @return Address object.
232 *
233 * The returned address object is safe to be operated on. It can be used for
234 * all other elocation functions. Once finished with it it need to be destroyed
235 * with a call to #elocation_address_free.
236 *
237 * @ingroup Location
238 * @since 1.8
239 */
240EAPI Elocation_Address *elocation_address_new(void);
241
242/**
243 * @brief Free an address object
244 * @param address Address object to be freed.
245 *
246 * Destroys an address object created with #elocation_address_new. Should be
247 * used during the cleanup of the application or whenever the address object is
248 * no longer needed.
249 *
250 * @ingroup Location
251 * @since 1.8
252 */
253EAPI void elocation_address_free(Elocation_Address *address);
254
255/**
256 * @brief Create a new position object to operate on.
257 * @return Position object.
258 *
259 * The returned address object is safe to be operated on. It can be used for
260 * all other elocation functions. Once finished with it it need to be destroyed
261 * with a call to #elocation_address_free.
262 *
263 * @ingroup Location
264 * @since 1.8
265 */
266EAPI Elocation_Position *elocation_position_new(void);
267
268/**
269 * @brief Free an position object
270 * @param position Position object to be freed.
271 *
272 * Destroys a position object created with #elocation_address_new. Should be
273 * used during the cleanup of the application or whenever the location object is
274 * no longer needed.
275 *
276 * @ingroup Location
277 * @since 1.8
278 */
279EAPI void elocation_position_free(Elocation_Position *position);
280
281/**
282 * @brief Get the current address information.
283 * @param address Address struct to be filled with information.
284 * @return EINA_TRUE for success and EINA_FALSE for failure.
285 *
286 * Request the latest address. The requested to the underling components might
287 * be asynchronous so better check the timestamp if the data has changed. To get
288 * events when the address changes one can also subscribe to the
289 * #ELOCATION_EVENT_ADDRESS ecore event which will have the address object as
290 * event.
291 *
292 * @ingroup Location
293 * @since 1.8
294 */
295EAPI Eina_Bool elocation_address_get(Elocation_Address *address);
296
297/**
298 * @brief Get the current position information.
299 * @param position Position struct to be filled with information.
300 * @return EINA_TRUE for success and EINA_FALSE for failure.
301 *
302 * Request the latest position. The requested to the underling components might
303 * be asynchronous so better check the timestamp if the data has changed. To get
304 * events when the position changes one can also subscribe to the
305 * #ELOCATION_EVENT_POSITION ecore event which will have the position object as
306 * event.
307 *
308 * @ingroup Location
309 * @since 1.8
310 */
311EAPI Eina_Bool elocation_position_get(Elocation_Position *position);
312
313/**
314 * @brief Get the current status.
315 * @param status Status
316 * @return EINA_TRUE for success and EINA_FALSE for failure.
317 *
318 * @ingroup Location
319 * @since 1.8
320 */
321EAPI Eina_Bool elocation_status_get(int *status);
322
323/**
324 * @brief Set the requirements.
325 * @param requirements Requirements
326 * @return EINA_TRUE for success and EINA_FALSE for failure.
327 *
328 * Set the requirements for selecting a provider.
329 *
330 * @ingroup Location
331 * @since 1.8
332 */
333EAPI Eina_Bool elocation_requirements_set(Elocation_Requirements *requirements);
334
335/**
336 * @brief Convert position to address
337 * @param position_shadow Position input
338 * @param address_shadow Address output
339 * @return EINA_TRUE for success and EINA_FALSE for failure.
340 *
341 * Use a GeoCode provider to translate from a given GPS coordinate
342 * representation of a location to a representation in textual form.
343 *
344 * @ingroup Location
345 * @since 1.8
346 */
347EAPI Eina_Bool elocation_position_to_address(Elocation_Position *position_shadow, Elocation_Address *address_shadow);
348
349/**
350 * @brief Convert address to position
351 * @param address_shadow Address input
352 * @param position_shadow Position output
353 * @return EINA_TRUE for success and EINA_FALSE for failure.
354 *
355 * Use a GeoCode provider to translate from a given textual form
356 * representation of a location to a representation as GPS coordinates.
357 *
358 * @ingroup Location
359 * @since 1.8
360 */
361EAPI Eina_Bool elocation_address_to_position(Elocation_Address *address_shadow, Elocation_Position *position_shadow);
362
363/**
364 * @brief Convert free form address tring to position
365 * @param freeform_address Address string in free form
366 * @param position_shadow Position output
367 * @return EINA_TRUE for success and EINA_FALSE for failure.
368 *
369 * Similar GeoCode translation from textual form to GPS coordinates as
370 * #elocation_address_to_position but in this case the address is a simple
371 * string which hopefully contains enough information for the provider to
372 * understand and translate.
373 *
374 * Useful for an easy search interface in an application but also more error
375 * prone regarding correct results.
376 *
377 * @ingroup Location
378 * @since 1.8
379 */
380EAPI Eina_Bool elocation_freeform_address_to_position(const char *freeform_address, Elocation_Position *position_shadow);
381
382/**
383 * @brief Request a landmark position
384 * @param position_shadow Position ouput
385 * @param address_shadow Address input
386 * @return EINA_TRUE for success and EINA_FALSE for failure.
387 *
388 * Request a landmark position also known as Point Of Interest (POI) from
389 * GeoClue.
390 *
391 * @ingroup Location
392 * @since 1.8
393 */
394EAPI Eina_Bool elocation_landmarks_get(Elocation_Position *position_shadow, Elocation_Address *address_shadow);
395
396/**
397 * @brief Initialize the elocation subsystem.
398 * @return EINA_TRUE for success and EINA_FALSE for failure.
399 *
400 * This function must be called before using any of the Elocation functionality
401 * in your application to make sure it it setup correctly for usage.
402 *
403 * @ingroup Location
404 * @since 1.8
405 */
406EAPI Eina_Bool elocation_init(void);
407
408/**
409 * @brief Cleanup and shutdown the elocation subsystem.
410 *
411 * This function must be called when the application is no longer using any of
412 * the Elocation functionality to allow the subsystem to shutdown cleanly.
413 *
414 * @ingroup Location
415 * @since 1.8
416 */
417EAPI void elocation_shutdown(void);
418#endif