GeoClue: Analysis and Architecture

After the first post introducing this cool project is time to go further and deeply analyze the GeoClue internals and general behavior, describing briefly he most relevant components of its architecture.

The first thing I noticed during the analysis of this piece of software is that is a quite complex component, at least, from the architecture design point of view. It provides a set of interfaces and DBus bindings to provide a very general and flexible tool for handling and extending location providers implementations. The following picture illustrate this idea:

Lets start analyzing the architecture, exploring each module and the relationship and interactions between the internal components.


GeoClue provides several interfaces to expose the different locations services and configuration operations. The following interfaces are currently defined:

  • GcIfaceGeoclue: Interface for administrative and configuration operations.
  • GcIfaceAddress: Interface for address acquiring operations.
  • GcIfacePosition: Interface for global positioning operations.
  • GcIfaceGeocode: Interface for geocoding  operations.
  • GcIfaceReverseGeocode: Interface for reverse-geocoding  operations.
  • GcIfaceVeolcity: Interface for velocity monitoring operations.

Some of those interfaces are exposed through DBus interfaces. An XML file define the structure of the DBus bindings. The *Glue generated classes are created from those specification files.

Location Providers

The most direct way to obtain the location is through the specific Location Providers implementation, each one using a different strategy for acquiring the data. There are several implementations for both, Position and Address providers, but lets analyze one simple for the time being, say Localnet.

Every Location Provider is defined through the following configuration files:

  • geoclue-localnet.xml: This file defines the exposed DBus methods and signals. The associated *Glue classes are generated from this file.
  • geoclue-localnet.provider: This file defines the settings of the Location Providers, like description, Dbus specification (path, service, iface), accuracy and some special features provided by the provider (e.g. automatic updates).
  • org.freedesktop.Geoclue.providers.Localnet: DBus service launcher file.

The Location Provider class, in this case called GeoclueLocalnet, should inherit from the GcProvider abstract class, which implements the GcIfaceGeoclue interface. It also should implement the abstract methods defined in the corresponding generated *Glue class, which allows the provider to receive calls through the DBus system or session bus.

Location Data Containers

In order to retrieve different kind of Location data there are several classes defined for that purpose, all of them derived classes from GeoclueProvider. This class holds a DBus proxy object to the instance which actually implement the Location mechanism. The specific provider container instantiated, GeoclueAddress for instance, should receive the DBus service specification (path, service); in the case of the Localnet example, it would be  org.freedesktop.Geoclue.Providers.Localent and /org/freedesktop/Geoclue/Providers/Localnet.

Master Provider

The Master provider is designed by a client/server structure, where the server holds a reference to a DBus proxy object to the selected Location provider. The client will evaluate the available providers choosing the best one, following a provider selection algorithm and based on the user requirements.

The Master server could attend several clients and it monitors the currently selected Location Provider, notifying all the clients any status transition and events,  or even the change of the selected provider.

Both components, client and server, are accessed through the DBus interface, org.freedesktop.Geolcue.MasterClient and org.freedesktop.Geolcue.Master interfaces respectively.

Master client/server

As commented before, the Master Provider has a client/server based design; the server is defined as a singleton of the class GeoclueMaster and its the responsible of the clients instantiation.

The GeoclueMasterClient class instances are the ones used for external applications to interact with the Location framework. It creates the necessary providers (Address, Position, Velocity, …) associated to the Master DBus interface (org,freedesktop,Geoclue.MasterClient. The corresponding GcMasterClient instance will receive all the requests, forwarded thought the Master Dbus interface (org.freedesktop.Geoclue.Master) to the Master server, which will derive the call to the selected Location Provider, using the specific provider DBus interface (org.freedesktop.Geoclue.Providers.Localnet).

And thats all; there are other components, like the connectivity manager and the related interfaces, or the web services supporting classes, but i think the contents described in this post are far enough to understand how GeoClue works, or at least, to show what a complex structure it has.

The following sequence diagram could help to understand how the classes interact to get the address, for instance:

A more interesting debate would be if such a complex design is necessary, or if the advantages it provides, in terms of flexibility and generalization, are enough to justify that, or even they could be obtained as a result of a different design, perhaps simpler. But such an interesting debate will take place in future posts 😉 stay tunned.