summaryrefslogtreecommitdiff
path: root/src/lib/elocation/Elocation.h
blob: 4f8e33a5176977470ac6956a875e0a1b58d3e962 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
/**
 * @file Elocation.h
 * @brief Elocation Library
 *
 * @defgroup Location Location
 */

/**
 *
 * @section intro Elocation Use Cases
 *
 * 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 GeoClue DBus service. Its has
 * providers for various techniques to get hold off the current position.
 * Ranging from GeoIP over wifi and GSM cell location to GPS. As well as
 * provider to translates between location in a textual form to coordinates
 * (GeoCode).
 *
 * Elocation covers all of these interfaces but in the end it depends on your
 * system and the installed GeoClue providers what can be used.
 *
 * Currently it offer the following functionality:
 * @li Request current address in textual form
 * @li Request current position in GPS format
 * @li Translate a position into and address or an address in a position
 *
 * You can find the API documentation at @ref Location
*/
#ifndef _ELOCATION_H
#define _ELOCATION_H

#ifdef EAPI
# undef EAPI
#endif

#ifdef _WIN32
# ifdef EFL_ECORE_BUILD
#  ifdef DLL_EXPORT
#   define EAPI __declspec(dllexport)
#  else
#   define EAPI
#  endif /* ! DLL_EXPORT */
# else
#  define EAPI __declspec(dllimport)
# endif /* ! EFL_ECORE_BUILD */
#else
# ifdef __GNUC__
#  if __GNUC__ >= 4
#   define EAPI __attribute__ ((visibility("default")))
#  else
#   define EAPI
#  endif
# else
#  define EAPI
# endif
#endif /* ! _WIN32 */

#include <stdio.h>

#include <Ecore.h>
#include <Eldbus.h>

/**
 * @ingroup Location
 * @brief Available location events that are emitted from the library
 * @since 1.13
 *
 * Ecore events emitted by the library. Applications can register ecore event
 * handlers to react on such events. After the initial query this can be used
 * to keep track of changes and update your UI or data accordingly.
 * @{
 */
EAPI extern int ELOCATION_EVENT_STATUS; /**< Status changed */
EAPI extern int ELOCATION_EVENT_POSITION; /**< Position changed */
EAPI extern int ELOCATION_EVENT_ADDRESS; /**< Address changed */
EAPI extern int ELOCATION_EVENT_VELOCITY; /**< Velocity changed */
EAPI extern int ELOCATION_EVENT_GEOCODE; /**< Reply for geocode translation arrived */
EAPI extern int ELOCATION_EVENT_REVERSEGEOCODE; /**< Reply for geocode translation arrived */
EAPI extern int ELOCATION_EVENT_NMEA; /**< NMEA update */
EAPI extern int ELOCATION_EVENT_SATELLITE; /**< Satellite info changed */
EAPI extern int ELOCATION_EVENT_POI; /**< POI reply */
EAPI extern int ELOCATION_EVENT_META_READY; /**< Meta provider is ready to be used */
/**@}*/

/**
 * @ingroup Location
 * @typedef Elocation_Accuracy_Level
 * @since 1.13
 *
 * Different location accuracy levels from country level up to detailed,
 * e.g. GPS, information.
 * @{
 */
typedef enum {
   ELOCATION_ACCURACY_LEVEL_NONE = 0,
   ELOCATION_ACCURACY_LEVEL_COUNTRY,
   ELOCATION_ACCURACY_LEVEL_REGION,
   ELOCATION_ACCURACY_LEVEL_LOCALITY,
   ELOCATION_ACCURACY_LEVEL_POSTALCODE,
   ELOCATION_ACCURACY_LEVEL_STREET,
   ELOCATION_ACCURACY_LEVEL_DETAILED,
} Elocation_Accuracy_Level;
/**@}*/

/**
 * @ingroup Location
 * @typedef Elocation_Resource_Flags
 * @since 1.13
 *
 * Flags for available system resources to be used for locating. So far they
 * cover physical resources like network connection, cellular network
 * connection and GPS.
 * @{
 */
typedef enum {
   ELOCATION_RESOURCE_NONE = 0,
   ELOCATION_RESOURCE_NETWORK = 1 << 0, /**< Internet connection is available */
   ELOCATION_RESOURCE_CELL = 1 << 1, /**< Cell network information, e.g. GSM, is available */
   ELOCATION_RESOURCE_GPS = 1 << 2, /**< GPS information is available */

   ELOCATION_RESOURCE_ALL = (1 << 10) - 1 /**< All resources are available */
} Elocation_Resource_Flags;
/**@}*/

/**
 * @ingroup Location
 * @typedef Elocation_Accuracy
 * @since 1.13
 *
 * Information about the accuracy of the reported location. For details about
 * the level of accuracy see #Elocation_Accuracy_Level. It also covers
 * horizontal and vertical accuracy. The values depend on the used provider
 * and may very in quality.
 */
typedef struct _Elocation_Accuracy
{
   Elocation_Accuracy_Level level;
   double horizontal;
   double vertical;
} Elocation_Accuracy;

/**
 * @ingroup Location
 * @typedef Elocation_Address
 * @since 1.13
 *
 * Location information in textual form. Depending on the used provider this
 * can cover only the country or a detailed address with postcode and street.
 * The level of detail varies depending on the used provider.
 * A timestamp is available to calculate the age of the address data.
 */
typedef struct _Elocation_Address
{
   unsigned int timestamp; /**< Timestamp of data read out in seconds since epoch */
   char *country;
   char *countrycode;
   char *locality;
   char *postalcode;
   char *region;
   char *timezone;
   Elocation_Accuracy *accur;
} Elocation_Address;

/**
 * @ingroup Location
 * @typedef Elocation_Position
 * @since 1.13
 *
 * Location information based on the GPS grid. Latitude, longitude and altitude.
 * A timestamp is available to calculate the age of the address data.
 */
typedef struct _Elocation_Postion
{
   unsigned int timestamp; /**< Timestamp of data read out in seconds since epoch */
   double latitude;
   double longitude;
   double altitude;
   Elocation_Accuracy *accur;
} Elocation_Position;

/**
 * @ingroup Location
 * @typedef Elocation_Velocity
 * @since 1.13
 *
 * Velocity information. So far this interface is only offered with GPS based
 * providers. It offers information about speed, direction and climb.
 * A timestamp is available to calculate the age of the address data.
 *
 * FIXME: check units and formats of this values coming in from GeoClue
 */
typedef struct _Elocation_Velocity
{
   unsigned int timestamp; /**< Timestamp of data read out in seconds since epoch */
   double speed;
   double direction;
   double climb;
} Elocation_Velocity;

/**
 * @ingroup Location
 * @typedef Elocation_Requirements
 * @since 1.13
 *
 * Requirement settings for the location provider. Requirements can be a level
 * of accuracy or allowed resources like network access or GPS. See
 * #Elocation_Resource_Flags for all available resource flags.
 *
 * Based on this setting the best provider is chosen between the available
 * providers of GeoClue.
 */
typedef struct _Elocation_Requirements
{
   Elocation_Accuracy_Level accurancy_level;
   int min_time; /**< Minimal time between updates. Not implemented upstream */
   Eina_Bool require_update;
   Elocation_Resource_Flags allowed_resources;
} Elocation_Requirements;

/**
 * @brief Create a new address object to operate on.
 * @return Address object.
 *
 * The returned address object is safe to be operated on. It can be used for
 * all other elocation functions. Once finished with it it need to be destroyed
 * with a call to #elocation_address_free.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Elocation_Address *elocation_address_new(void);

/**
 * @brief Free an address object
 * @param address Address object to be freed.
 *
 * Destroys an address object created with #elocation_address_new. Should be
 * used during the cleanup of the application or whenever the address object is
 * no longer needed.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI void elocation_address_free(Elocation_Address *address);

/**
 * @brief Create a new position object to operate on.
 * @return Position object.
 *
 * The returned address object is safe to be operated on. It can be used for
 * all other elocation functions. Once finished with it it need to be destroyed
 * with a call to #elocation_address_free.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Elocation_Position *elocation_position_new(void);

/**
 * @brief Free an position object
 * @param position Position object to be freed.
 *
 * Destroys a position object created with #elocation_address_new. Should be
 * used during the cleanup of the application or whenever the location object is
 * no longer needed.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI void elocation_position_free(Elocation_Position *position);

/**
 * @brief Get the current address information.
 * @param address Address struct to be filled with information.
 * @return EINA_TRUE for success and EINA_FALSE for failure.
 *
 * Request the latest address. The requested to the underling components might
 * be asynchronous so better check the timestamp if the data has changed. To get
 * events when the address changes one can also subscribe to the
 * #ELOCATION_EVENT_ADDRESS ecore event which will have the address object as
 * event.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Eina_Bool elocation_address_get(Elocation_Address *address);

/**
 * @brief Get the current position information.
 * @param position Position struct to be filled with information.
 * @return EINA_TRUE for success and EINA_FALSE for failure.
 *
 * Request the latest position. The requested to the underling components might
 * be asynchronous so better check the timestamp if the data has changed. To get
 * events when the position changes one can also subscribe to the
 * #ELOCATION_EVENT_POSITION ecore event which will have the position object as
 * event.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Eina_Bool elocation_position_get(Elocation_Position *position);

/**
 * @brief Get the current status.
 * @param status Status
 * @return EINA_TRUE for success and EINA_FALSE for failure.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Eina_Bool elocation_status_get(int *status);

/**
 * @brief Set the requirements.
 * @param requirements Requirements
 * @return EINA_TRUE for success and EINA_FALSE for failure.
 *
 * Set the requirements for selecting a provider.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Eina_Bool elocation_requirements_set(Elocation_Requirements *requirements);

/**
 * @brief Convert position to address
 * @param position_shadow Position input
 * @param address_shadow Address output
 * @return EINA_TRUE for success and EINA_FALSE for failure.
 *
 * Use a GeoCode provider to translate from a given GPS coordinate
 * representation of a location to a representation in textual form.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Eina_Bool elocation_position_to_address(Elocation_Position *position_shadow, Elocation_Address *address_shadow);

/**
 * @brief Convert address to position
 * @param address_shadow Address input
 * @param position_shadow Position output
 * @return EINA_TRUE for success and EINA_FALSE for failure.
 *
 * Use a GeoCode provider to translate from a given textual form
 * representation of a location to a representation as GPS coordinates.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Eina_Bool elocation_address_to_position(Elocation_Address *address_shadow, Elocation_Position *position_shadow);

/**
 * @brief Convert free form address tring to position
 * @param freeform_address Address string in free form
 * @param position_shadow Position output
 * @return EINA_TRUE for success and EINA_FALSE for failure.
 *
 * Similar GeoCode translation from textual form to GPS coordinates as
 * #elocation_address_to_position but in this case the address is a simple
 * string which hopefully contains enough information for the provider to
 * understand and translate.
 *
 * Useful for an easy search interface in an application but also more error
 * prone regarding correct results.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Eina_Bool elocation_freeform_address_to_position(const char *freeform_address, Elocation_Position *position_shadow);

/**
 * @brief Request a landmark position
 * @param position_shadow Position ouput
 * @param address_shadow Address input
 * @return EINA_TRUE for success and EINA_FALSE for failure.
 *
 * Request a landmark position also known as Point Of Interest (POI) from
 * GeoClue.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Eina_Bool elocation_landmarks_get(Elocation_Position *position_shadow, Elocation_Address *address_shadow);

/**
 * @brief Initialize the elocation  subsystem.
 * @return EINA_TRUE for success and EINA_FALSE for failure.
 *
 * This function must be called before using any of the Elocation functionality
 * in your application to make sure it it setup correctly for usage.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI Eina_Bool elocation_init(void);

/**
 * @brief Cleanup and shutdown the elocation  subsystem.
 *
 * This function must be called when the application is no longer using any of
 * the Elocation functionality to allow the subsystem to shutdown cleanly.
 *
 * @ingroup Location
 * @since 1.13
 */
EAPI void elocation_shutdown(void);
#endif