 |
 |
Geoclue Reference Manual |  |
|---|
Why use Geoclue
Building context-sensitive applications is difficult. Location-sensitivy is no exception, but Geoclue tries to help there. With Geoclue it is possible to build location-aware applications with less work and less knowledge about the actual geoinformation sources.
Main features of Geoclue are:
- Standardized D-Bus (and GObject) interfaces to various geographical data sources
- Easy and fast to implement: Need to get data from provider XYZ? Chances are, Geoclue is the easiest way to do that...
- Geoclue Master provider (experimental at the moment) makes things eaven easier: you don't even have to choose a data provider, just let Geoclue choose the best possible provider for you.
- Adding new providers (data sources) is straight-forward: Even when the geoinformation source you want is not already in Geoclue, Implementing a Geoclue provider may well turn out to be the easiest way forward.
Requirements
Geoclue is a collection of D-Bus APIs. Internally it's implemented with GLib and GObject (as is the C wrapper library). Several included providers also use Libxml2, and the master provider uses GConf.
There is a GObject-based C API, but using Geoclue is possible from any programming language with D-Bus support.
Using basic Geoclue providers
D-Bus can automatically start services as they're needed so basic method calls can be made without any preparation. However, geoclue providers may shut down when they're not used. This means that clients using signals and clients that set any options should always use AddReference() and RemoveReference() methods to ensure server persistence. In C the wrapper takes care of this.
Clients should not assume that method calls will return instantly or that the response will contain valid data. Examples of possible problems
- Many geoclue providers use web services so method calls may take seconds or even time out.
- GPS providers usually respond instantly, but will not have a valid data until after getting a fix (which may take anything from a few seconds to minutes)
Using signals should be the first option whenever the used provider supports them. When signals are not available, asynchronous method calls can be used in applications where UI responsiveness is important.
Using Geoclue Master
Master provider was designed to solve the following problems:
- A single provider cannot be the best solution to all problems
- The "best" providers will be different depending on the user
- Supporting a single geodata source can be a big job for an application developer, supporting several would be a nightmare
Master provider implements the same interfaces as regular providers, but internally it uses whichever regular provider happens to be the best one (with "best" defined as a provider that fulfills the accuracy requirements and does not surpass resource restrictions). The internally used provider may change over time -- this does not interrupt clients use in any way, but the changes can be observed using the MasterClient API.
A typical Master provider use includes:
- Getting a client-specific GeoclueMasterClient from GeoclueMaster
- Setting GeoclueMasterClient requirements (such as accuracy)
- Starting the wanted interfaces (such as Position)
- Using the client just like a regular provider
Master provider is fairly new and may not be as stable as the rest of Geoclue.