## GeoclueGeocode

GeoclueGeocode — Geoclue geocode client API

## Synopsis

    #define             GEOCLUE_GEOCODE_INTERFACE_NAME
                        GeoclueGeocode;
    GeoclueGeocode *    geoclue_geocode_new                 (const char *service,
                                                             const char *path);
    GeocluePositionFields  geoclue_geocode_address_to_position
                                                            (GeoclueGeocode *geocode,
                                                             GHashTable *details,
                                                             double *latitude,
                                                             double *longitude,
                                                             double *altitude,
                                                             GeoclueAccuracy **accuracy,
                                                             GError **error);
    void                (*GeoclueGeocodeCallback)           (GeoclueGeocode *geocode,
                                                             GeocluePositionFields fields,
                                                             double latitude,
                                                             double longitude,
                                                             double altitude,
                                                             GeoclueAccuracy *accuracy,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_geocode_address_to_position_async
                                                            (GeoclueGeocode *geocode,
                                                             GHashTable *details,
                                                             GeoclueGeocodeCallback callback,
                                                             gpointer userdata);

## Object Hierarchy

      GObject
       +----GeoclueProvider
             +----GeoclueGeocode

## Description

GeoclueGeocode contains geocoding methods. It is part of the Geoclue public C client API which uses D-Bus to communicate with the actual provider.

After a GeoclueGeocode is created with `geoclue_geocode_new()`, the `geoclue_geocode_address_to_position()`, `geoclue_geocode_freeform_address_to_position()` methods and their asynchronous counterparts can be used to obtain the position (coordinates) of the given address.

Address GHashTable keys are defined in geoclue-types.h. See also convenience functions in geoclue-address-details.h.

## Details

### GEOCLUE_GEOCODE_INTERFACE_NAME

    #define GEOCLUE_GEOCODE_INTERFACE_NAME "org.freedesktop.Geoclue.Geocode"

### GeoclueGeocode

    typedef struct _GeoclueGeocode GeoclueGeocode;

### geoclue_geocode_new ()

    GeoclueGeocode *    geoclue_geocode_new                 (const char *service,
                                                             const char *path);

Creates a GeoclueGeocode with given D-Bus service name and path.

`service` : | D-Bus service name
`path` : | D-Bus path name
Returns : | Pointer to a new GeoclueGeocode

### geoclue_geocode_address_to_position ()

    GeocluePositionFields  geoclue_geocode_address_to_position
                                                            (GeoclueGeocode *geocode,
                                                             GHashTable *details,
                                                             double *latitude,
                                                             double *longitude,
                                                             double *altitude,
                                                             GeoclueAccuracy **accuracy,
                                                             GError **error);

Geocodes given address to coordinates (`latitude`, `longitude`, `altitude`). see geoclue-types.h for the hashtable keys usable in `details`. `accuracy` is a rough estimate of the accuracy of the returned position.

If the caller is not interested in some values, the pointers can be left `NULL`.

`geocode` : | A GeoclueGeocode object
`details` : | Hashtable with address data
`latitude` : | Pointer to returned latitude in degrees or `NULL`
`longitude` : | Pointer to returned longitude in degrees or `NULL`
`altitude` : | Pointer to returned altitude in meters or `NULL`
`accuracy` : | Pointer to returned GeoclueAccuracy or `NULL`
`error` : | Pointer to returned Gerror or `NULL`
Returns : | A GeocluePositionFields bitfield representing the validity of the returned coordinates.

### GeoclueGeocodeCallback ()

    void                (*GeoclueGeocodeCallback)           (GeoclueGeocode *geocode,
                                                             GeocluePositionFields fields,
                                                             double latitude,
                                                             double longitude,
                                                             double altitude,
                                                             GeoclueAccuracy *accuracy,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for the asynchronous methods.

`geocode` : | A GeoclueGeocode object
`fields` : | A GeocluePositionFields bitfield representing the validity of the position values
`latitude` : | Latitude in degrees
`longitude` : | Longitude in degrees
`altitude` : | Altitude in meters
`accuracy` : | Accuracy of measurement as GeoclueAccuracy
`error` : | Error as Gerror or `NULL`
`userdata` : | User data pointer

### geoclue_geocode_address_to_position_async ()

    void                geoclue_geocode_address_to_position_async
                                                            (GeoclueGeocode *geocode,
                                                             GHashTable *details,
                                                             GeoclueGeocodeCallback callback,
                                                             gpointer userdata);

Function returns (essentially) immediately and calls `callback` when the geocoded position data is available or when D-Bus timeouts.

see geoclue-types.h for the hashtable keys usable in `details`.

`geocode` : | A Geocluegeocode object
`details` : | A GHashTable with address data
`callback` : | A GeoclueAddressCallback function that should be called when return values are available
`userdata` : | pointer for user specified data