new code on git.freedesktop.org

[Jussi Kukkonen]

I wrote:
> I'm writing a proper mail that describes the code at a higher
> level but that's harder than I thought, so I decided to post a quick
> notice first...

Hello again,

I tried to be brief, but didn't succeed too well... Contents of this mail:
	Client API
	Provider implementations
	Provider API
	Code structure

There's quite a bit of documentation in git already, but it's not easily
available yet -- I'll see how to get that on to fd.o.


API overview
------------

Here's a very brief overview of the geoclue components from the POV of a
client developer:

Interface              GObject wrapper        provider implementations
(org.freedesktop.*)
-----------------------------------------------------------------------
Geoclue                GeoclueCommon          all (8 + example)
Geoclue.Position       GeocluePosition        4
Geoclue.Address        GeoclueAddress         4
Geoclue.Velocity       GeoclueVelocity        2
Geoclue.Geocode        GeoclueGeocode         2
Geoclue.ReverseGeocode GeoclueReverseGeocode  1

These APIs are in my opinion stable (with one minor exception**) and the
provider implementations should be as well.

Using these objects/interfaces is straight forward, and similar to the
old API. See examples/-directory and the documentation. The main
difference at the moment is that network providers do not watch for
network events, as this functionality is now in the master process
only... I'm not 100% sure of this approach (and it wouldn't be difficult
to change again) but this is how it is at the moment.


Then the master service: This is still experimental, the code will
change. Even API changes are not impossible.

Geoclue.Master         GeoclueMaster
Geoclue.MasterClient   GeoclueMasterClient

Master is a singleton: apps use it to get an instance of
GeoclueMasterClient.

MasterClient is per-application (all instances run in the same
master-service, though), as applications use MasterClient to set their
requirements (like needed accuracy). Apps then access MasterClients data
via the basic interfaces (e.g. Position) described above, just like any
other providers data. Currently Address and Position are supported in
MasterClient.

** ) The exception to API stability: I just found out that we can get
rid of the Shutdown() provider method -- it is possible to shutdown
providers automatically by making them reference count clients with
D-Bus NameOwnerChanged signals... This is a small change and in fact it
will not change the C API at all. I'll do this by monday.


Provider implementations
------------------------

Same providers as before (gpsd, hostip, yahoo, plazes, geonames) with a
couple of additions:

 * "Gypsy" (GPS daemon) provider, now fully functional
 * "Manual" provider is now D-Bus -based, otherwise the same: any
   application can send a message "at address XYZ, valid for x seconds"
 * "Localnet" (local gateway mac address db) provider. Localnet has a
   key-file with mac addresses and physical addresses. When current
   gateway mac address matches one on file, localnet provides the
   physical address.

Localnet + Manual is a cool combination and solves a long-standing
problem: what to do when there is no good data available for a place
that user commonly visits? Now he can just input the address once (using
a panel applet or whatever): Localnet watches Manual provider signals
and saves that address data to keyfile (with current gateway mac
address). Next time in the same place localnet provides the address.


Provider API
------------

From a C provider developers point of view it looks like this:


Interface              How to implement as a GObject?
(org.freedesktop.*)
------------------------------------------------------------------
Geoclue                inherit from GcProvider
                       (which implements interface GcIfaceGeoclue)
Geoclue.Position       implement interface GcIfacePosition
Geoclue.Address        implement interface GcIfaceAddress
Geoclue.Velocity       implement interface GcIfaceVelocity
Geoclue.Geocode        implement interface GcIfaceGeocode
Geoclue.ReverseGeocode implement interface GcIfaceReverseGeocode



Code structure (directories)
----------------------------

There are two namespaces, "gc" for provider interfaces and helpers, and
"geoclue" for client side files. Documentation is done "in-file", both
for C code and the D-Bus interfaces.

geoclue/      - Client C wrapper (geoclue-*),
                Provider C helpers and ifaces (gc-*)
src/          - Master and MasterClient, and related objects
interfaces/   - D-Bus interface definitions
example/
providers/
docs/


Jussi

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 307 bytes
Desc: OpenPGP digital signature
Url : http://lists.freedesktop.org/archives/geoclue/attachments/20080308/b4ac475a/attachment.pgp