Location

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files
- Examples

Typedefs | Functions
Location

## Typedefs
typedef struct _Elocation_Accuracy | Elocation_Accuracy
typedef struct _Elocation_Address | Elocation_Address
typedef struct _Elocation_Position | Elocation_Position
typedef struct _Elocation_Velocity | Elocation_Velocity
typedef struct _Elocation_Requirements | Elocation_Requirements

## Functions
EAPI Elocation_Address * | elocation_address_new (void)
| Create a new address object to operate on. More...
EAPI void | elocation_address_free (Elocation_Address *address)
| Free an address object. More...
EAPI Elocation_Position * | elocation_position_new (void)
| Create a new position object to operate on. More...
EAPI void | elocation_position_free (Elocation_Position *position)
| Free an position object. More...
EAPI Eina_Bool | elocation_address_get (Elocation_Address *address)
| Get the current address information. More...
EAPI Eina_Bool | elocation_position_get (Elocation_Position *position)
| Get the current position information. More...
EAPI Eina_Bool | elocation_status_get (int *status)
| Get the current status. More...
EAPI Eina_Bool | elocation_requirements_set (Elocation_Requirements *requirements)
| Set the requirements. More...
EAPI Eina_Bool | elocation_position_to_address (Elocation_Position *position_shadow, Elocation_Address *address_shadow)
| Convert position to address. More...
EAPI Eina_Bool | elocation_address_to_position (Elocation_Address *address_shadow, Elocation_Position *position_shadow)
| Convert address to position. More...
EAPI Eina_Bool | elocation_freeform_address_to_position (const char *freeform_address, Elocation_Position *position_shadow)
| Convert free form address tring to position. More...
EAPI Eina_Bool | elocation_landmarks_get (Elocation_Position *position_shadow, Elocation_Address *address_shadow)
| Request a landmark position. More...
EAPI Eina_Bool | elocation_init (void)
| Initialize the elocation subsystem. More...
EAPI void | elocation_shutdown (void)
| Cleanup and shutdown the elocation subsystem. More...
EAPI int | ELOCATION_EVENT_STATUS
| Available location events that are emitted from the library. More...
EAPI int | ELOCATION_EVENT_POSITION
| Position changed.
EAPI int | ELOCATION_EVENT_ADDRESS
| Address changed.
EAPI int | ELOCATION_EVENT_VELOCITY
| Velocity changed.
EAPI int | ELOCATION_EVENT_GEOCODE
| Reply for geocode translation arrived.
EAPI int | ELOCATION_EVENT_REVERSEGEOCODE
| Reply for geocode translation arrived.
EAPI int | ELOCATION_EVENT_NMEA
| NMEA update.
EAPI int | ELOCATION_EVENT_SATELLITE
| Satellite info changed.
EAPI int | ELOCATION_EVENT_POI
| POI reply.
EAPI int | ELOCATION_EVENT_META_READY
| Meta provider is ready to be used.
enum | Elocation_Accuracy_Level { ELOCATION_ACCURACY_LEVEL_NONE = 0, ELOCATION_ACCURACY_LEVEL_COUNTRY = 1, ELOCATION_ACCURACY_LEVEL_REGION, ELOCATION_ACCURACY_LEVEL_LOCALITY, ELOCATION_ACCURACY_LEVEL_POSTALCODE, ELOCATION_ACCURACY_LEVEL_CITY = 4, ELOCATION_ACCURACY_LEVEL_NEIGHBORHOOD = 5, ELOCATION_ACCURACY_LEVEL_STREET = 6, ELOCATION_ACCURACY_LEVEL_DETAILED, ELOCATION_ACCURACY_LEVEL_EXACT = 8 }
enum | Elocation_Resource_Flags { ELOCATION_RESOURCE_NONE = 0, ELOCATION_RESOURCE_NETWORK = 1 << 0, ELOCATION_RESOURCE_CELL = 1 << 1, ELOCATION_RESOURCE_GPS = 1 << 2, ELOCATION_RESOURCE_ALL = (1 << 10) - 1 }

## Detailed Description

## Typedef Documentation

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.

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.

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.

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

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.

## Enumeration Type Documentation

enum Elocation_Accuracy_Level

Since
  1.13

Different location accuracy levels from country level up to detailed, e.g. GPS, information.

enum 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.

Enumerator
ELOCATION_RESOURCE_NETWORK | Internet connection is available.
ELOCATION_RESOURCE_CELL | Cell network information, e.g. GSM, is available
ELOCATION_RESOURCE_GPS | GPS information is available.
ELOCATION_RESOURCE_ALL | All resources are available.

## Function Documentation

EAPI Elocation_Address* elocation_address_new | ( | void |  | ) |

Create a new address object to operate on.

Returns
  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.

Since
  1.13

EAPI void elocation_address_free | ( | Elocation_Address * | address | ) |

Free an address object.

Parameters

  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.

Since
  1.13

References ERR.

EAPI Elocation_Position* elocation_position_new | ( | void |  | ) |

Create a new position object to operate on.

Returns
  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.

Since
  1.13

EAPI void elocation_position_free | ( | Elocation_Position * | position | ) |

Free an position object.

Parameters

  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.

Since
  1.13

References ERR.

EAPI Eina_Bool elocation_address_get | ( | Elocation_Address * | address | ) |

Get the current address information.

Parameters

  address | Address struct to be filled with information.

Returns
  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.

Since
  1.13

References EINA_FALSE, and EINA_TRUE.

EAPI Eina_Bool elocation_position_get | ( | Elocation_Position * | position | ) |

Get the current position information.

Parameters

  position | Position struct to be filled with information.

Returns
  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.

Since
  1.13

References EINA_FALSE, and EINA_TRUE.

EAPI Eina_Bool elocation_status_get | ( | int * | status | ) |

Get the current status.

Parameters

  status | Status

Returns
  EINA_TRUE for success and EINA_FALSE for failure.

Since
  1.13

References EINA_FALSE, and EINA_TRUE.

EAPI Eina_Bool elocation_requirements_set | ( | Elocation_Requirements * | requirements | ) |

Set the requirements.

Parameters

  requirements | Requirements

Returns
  EINA_TRUE for success and EINA_FALSE for failure.

Set the requirements for selecting a provider.

Since
  1.13

EAPI Eina_Bool elocation_position_to_address | ( | Elocation_Position * | position_shadow,
|  | Elocation_Address * | address_shadow
| ) |  |

Convert position to address.

Parameters

  position_shadow | Position input
  address_shadow | Address output

Returns
  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.

Since
  1.13

References EINA_FALSE, EINA_TRUE, eldbus_message_iter_basic_append(), eldbus_message_iter_container_close(), eldbus_message_iter_container_new(), eldbus_message_iter_get(), eldbus_message_unref(), eldbus_proxy_method_call_new(), eldbus_proxy_send(), and ERR.

EAPI Eina_Bool elocation_address_to_position | ( | Elocation_Address * | address_shadow,
|  | Elocation_Position * | position_shadow
| ) |  |

Convert address to position.

Parameters

  address_shadow | Address input
  position_shadow | Position output

Returns
  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.

Since
  1.13

References EINA_FALSE, EINA_TRUE, eldbus_message_iter_arguments_append(), eldbus_message_iter_container_close(), eldbus_message_iter_container_new(), eldbus_message_iter_get(), eldbus_message_unref(), eldbus_proxy_method_call_new(), eldbus_proxy_send(), and ERR.

EAPI Eina_Bool elocation_freeform_address_to_position | ( | const char * | freeform_address,
|  | Elocation_Position * | position_shadow
| ) |  |

Convert free form address tring to position.

Parameters

  freeform_address | Address string in free form
  position_shadow | Position output

Returns
  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.

Since
  1.13

References EINA_FALSE, EINA_TRUE, eldbus_proxy_call(), and ERR.

EAPI Eina_Bool elocation_landmarks_get | ( | Elocation_Position * | position_shadow,
|  | Elocation_Address * | address_shadow
| ) |  |

Request a landmark position.

Parameters

  position_shadow | Position ouput
  address_shadow | Address input

Returns
  EINA_TRUE for success and EINA_FALSE for failure.

Request a landmark position also known as Point Of Interest (POI) from GeoClue.

Since
  1.13

References EINA_FALSE, EINA_TRUE, eldbus_message_iter_basic_append(), eldbus_message_iter_get(), eldbus_message_unref(), eldbus_proxy_method_call_new(), eldbus_proxy_send(), and ERR.

EAPI Eina_Bool elocation_init | ( | void |  | ) |

Initialize the elocation subsystem.

Returns
  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.

Since
  1.13

References ecore_event_handler_add(), ecore_event_type_new(), ecore_init(), EINA_FALSE, eina_init(), eina_log_domain_register(), EINA_LOG_ERR, EINA_TRUE, eldbus_connection_get(), eldbus_init(), eldbus_name_owner_changed_callback_add(), eldbus_object_get(), eldbus_proxy_call(), eldbus_proxy_get(), ELOCATION_EVENT_ADDRESS, ELOCATION_EVENT_GEOCODE, ELOCATION_EVENT_META_READY, ELOCATION_EVENT_NMEA, ELOCATION_EVENT_POI, ELOCATION_EVENT_POSITION, ELOCATION_EVENT_REVERSEGEOCODE, ELOCATION_EVENT_SATELLITE, ELOCATION_EVENT_STATUS, ELOCATION_EVENT_VELOCITY, and ERR.

EAPI void elocation_shutdown | ( | void |  | ) |

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.

Since
  1.13

References ecore_shutdown(), eina_log_domain_unregister(), eina_shutdown(), eldbus_connection_unref(), eldbus_name_owner_changed_callback_del(), eldbus_proxy_call(), eldbus_proxy_unref(), eldbus_shutdown(), and ERR.

## Variable Documentation

EAPI int ELOCATION_EVENT_STATUS

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.Status changed

Referenced by elocation_init().