{"id":83,"date":"2010-07-08T19:31:52","date_gmt":"2010-07-08T18:31:52","guid":{"rendered":"http:\/\/blogs.igalia.com\/jfernandez\/?p=83"},"modified":"2010-07-08T19:31:52","modified_gmt":"2010-07-08T18:31:52","slug":"geoclue-analysis-and-architecture","status":"publish","type":"post","link":"https:\/\/blogs.igalia.com\/jfernandez\/2010\/07\/08\/geoclue-analysis-and-architecture\/","title":{"rendered":"GeoClue: Analysis and Architecture"},"content":{"rendered":"<p>After the first <a href=\"http:\/\/blogs.igalia.com\/jfernandez\/2010\/05\/13\/my-new-trip-geoclue-and-beyond\/\">post<\/a> 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.<\/p>\n<p>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:<\/p>\n<p><a href=\"http:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-class-diagram.png\"><\/a><a href=\"http:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-class-diagram1.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-medium wp-image-95\" src=\"http:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-class-diagram1-300x212.png\" alt=\"\" width=\"300\" height=\"212\" srcset=\"https:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-class-diagram1-300x212.png 300w, https:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-class-diagram1-1024x723.png 1024w, https:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-class-diagram1-424x300.png 424w\" sizes=\"auto, (max-width: 300px) 100vw, 300px\" \/><\/a><\/p>\n<p>Lets start analyzing the architecture, exploring each module and the relationship and interactions between the internal components.<\/p>\n<p><strong>Interfaces<\/strong><\/p>\n<p>GeoClue provides several interfaces to expose the different locations services and configuration operations. The following interfaces are currently defined:<\/p>\n<ul>\n<li><em>GcIfaceGeoclue:<\/em> Interface for administrative and configuration operations.<\/li>\n<li><em>GcIfaceAddress:<\/em> Interface for address acquiring operations.<\/li>\n<li>GcIfacePosition: Interface for global positioning operations.<\/li>\n<li>GcIfaceGeocode: Interface for geocoding\u00a0 operations.<\/li>\n<li>GcIfaceReverseGeocode: Interface for reverse-geocoding\u00a0 operations.<\/li>\n<li>GcIfaceVeolcity: Interface for velocity monitoring operations.<\/li>\n<\/ul>\n<p>Some of those interfaces are exposed through DBus interfaces. An XML file define the structure of the DBus bindings. The <em>*Glue<\/em> generated classes are created from those specification files.<\/p>\n<p><strong>Location Providers<\/strong><\/p>\n<p>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.<\/p>\n<p>Every Location Provider is defined through the following configuration files:<\/p>\n<ul>\n<li><em>geoclue-localnet.xml:<\/em> This file defines the exposed DBus methods and signals. The associated <em>*Glue<\/em> classes are generated from this file.<\/li>\n<li> <em>geoclue-localnet.provider:<\/em> 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).<\/li>\n<li><em>org.freedesktop.Geoclue.providers.Localnet:<\/em> DBus service launcher file.<\/li>\n<\/ul>\n<p>The Location Provider class, in this case called GeoclueLocalnet, should inherit from the GcProvider abstract class, which implements the <em>GcIfaceGeoclue<\/em> interface. It also should implement the abstract methods defined in the corresponding generated <em>*Glue<\/em> class, which allows the provider to receive calls through the DBus system or session bus.<\/p>\n<p><strong>Location Data Containers<\/strong><\/p>\n<p>In order to retrieve different kind of Location data there are several classes defined for that purpose, all of them derived classes from <em>GeoclueProvider<\/em>. 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\u00a0 <em>org.freedesktop.Geoclue.Providers.Localent<\/em> and <em>\/org\/freedesktop\/Geoclue\/Providers\/Localnet<\/em>.<\/p>\n<p><strong>Master Provider<\/strong><\/p>\n<p>The <em>Master<\/em> 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 <strong>client<\/strong> will evaluate the available providers choosing the best one, following a provider selection algorithm and based on the user requirements.<\/p>\n<p>The <em>Master<\/em> <strong>server<\/strong> could attend several clients and it monitors the currently selected Location Provider, notifying all the clients any status transition and events,\u00a0 or even the change of the selected provider.<\/p>\n<p>Both components, client and server, are accessed through the DBus interface, <em>org.freedesktop.Geolcue.MasterClient<\/em> and <em>org.freedesktop.Geolcue.Master <\/em>interfaces respectively.<\/p>\n<p><strong>Master client\/server<\/strong><\/p>\n<p>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.<\/p>\n<p>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, &#8230;) 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).<\/p>\n<p>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.<\/p>\n<p>The following sequence diagram could help to understand how the classes interact to get the address, for instance:<\/p>\n<p><a href=\"http:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-seq-diagram.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-medium wp-image-94\" src=\"http:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-seq-diagram-300x218.png\" alt=\"\" width=\"300\" height=\"218\" srcset=\"https:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-seq-diagram-300x218.png 300w, https:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-seq-diagram-412x300.png 412w, https:\/\/blogs.igalia.com\/jfernandez\/files\/2010\/07\/Geoclue-seq-diagram.png 1010w\" sizes=\"auto, (max-width: 300px) 100vw, 300px\" \/><\/a><\/p>\n<p>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 \ud83d\ude09 stay tunned.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 &hellip; <a href=\"https:\/\/blogs.igalia.com\/jfernandez\/2010\/07\/08\/geoclue-analysis-and-architecture\/\" class=\"more-link\">Continue reading <span class=\"screen-reader-text\">GeoClue: Analysis and Architecture<\/span><\/a><\/p>\n","protected":false},"author":20,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5,6],"tags":[],"class_list":["post-83","post","type-post","status-publish","format-standard","hentry","category-geolocation","category-gnome"],"_links":{"self":[{"href":"https:\/\/blogs.igalia.com\/jfernandez\/wp-json\/wp\/v2\/posts\/83","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blogs.igalia.com\/jfernandez\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.igalia.com\/jfernandez\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.igalia.com\/jfernandez\/wp-json\/wp\/v2\/users\/20"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.igalia.com\/jfernandez\/wp-json\/wp\/v2\/comments?post=83"}],"version-history":[{"count":0,"href":"https:\/\/blogs.igalia.com\/jfernandez\/wp-json\/wp\/v2\/posts\/83\/revisions"}],"wp:attachment":[{"href":"https:\/\/blogs.igalia.com\/jfernandez\/wp-json\/wp\/v2\/media?parent=83"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.igalia.com\/jfernandez\/wp-json\/wp\/v2\/categories?post=83"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.igalia.com\/jfernandez\/wp-json\/wp\/v2\/tags?post=83"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}