## GeoclueAddress GeoclueAddress — Geoclue address client API |

## Synopsis

    #define             GEOCLUE_ADDRESS_INTERFACE_NAME
                        GeoclueAddress;
    GeoclueAddress*     geoclue_address_new                 (const char *service,
                                                             const char *path);
    gboolean            geoclue_address_get_address         (GeoclueAddress *address,
                                                             int *timestamp,
                                                             GHashTable **details,
                                                             GeoclueAccuracy **accuracy,
                                                             GError **error);
    void                (*GeoclueAddressCallback)           (GeoclueAddress *address,
                                                             int timestamp,
                                                             GHashTable *details,
                                                             GeoclueAccuracy *accuracy,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_address_get_address_async   (GeoclueAddress *address,
                                                             GeoclueAddressCallback callback,
                                                             gpointer userdata);

## Object Hierarchy

      GObject
       +----GeoclueProvider
             +----GeoclueAddress

## Signals

      "address-changed"                                : Run First / No Recursion

## Description

GeoclueAddress contains Address-related methods and signals. It is part of the Geoclue public C client API which uses D-Bus to communicate with the actual provider.

After a GeoclueAddress is created with `geoclue_address_new()` or `geoclue_master_client_create_address()`, the `geoclue_address_get_address()` and `geoclue_address_get_address_async()` methods and the address-changed signal can be used to obtain the current address.

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

## Details

### GEOCLUE_ADDRESS_INTERFACE_NAME

    #define GEOCLUE_ADDRESS_INTERFACE_NAME "org.freedesktop.Geoclue.Address"

### GeoclueAddress

    typedef struct _GeoclueAddress GeoclueAddress;

### geoclue_address_new ()

    GeoclueAddress*     geoclue_address_new                 (const char *service,
                                                             const char *path);

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

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

### geoclue_address_get_address ()

    gboolean            geoclue_address_get_address         (GeoclueAddress *address,
                                                             int *timestamp,
                                                             GHashTable **details,
                                                             GeoclueAccuracy **accuracy,
                                                             GError **error);

Obtains the current address. `timestamp` will contain the time of the actual address measurement. `accuracy` is the estimated of the accuracy of the current address information (see GeoclueAccuracy for more details). `details` is a hashtable with the address data, see geoclue-types.h for the hashtable keys.

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

`address` : | A GeoclueAddress object
`timestamp` : | Pointer to returned time of address measurement (Unix timestamp) or `NULL`
`details` : | Pointer to returned GHashTable with address details or `NULL`
`accuracy` : | Pointer to returned GeoclueAccuracy or NULL
`error` : | Pointer to returned Gerror or `NULL`
Returns : | `TRUE` if there is no `error`

### GeoclueAddressCallback ()

    void                (*GeoclueAddressCallback)           (GeoclueAddress *address,
                                                             int timestamp,
                                                             GHashTable *details,
                                                             GeoclueAccuracy *accuracy,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for `geoclue_address_get_address_async()`.

`address` : | the GeoclueAddress object emitting the signal
`timestamp` : | Time of address measurement (Unix timestamp)
`details` : | Address details as GHashTable.
`accuracy` : | Accuracy of measurement as GeoclueAccuracy
`error` : | Error as Gerror (may be `NULL`)
`userdata` : | User data pointer set in `geoclue_position_get_position_async()`

### geoclue_address_get_address_async ()

    void                geoclue_address_get_address_async   (GeoclueAddress *address,
                                                             GeoclueAddressCallback callback,
                                                             gpointer userdata);

Function returns (essentially) immediately and calls `callback` when current address is available or when D-Bus timeouts.

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

## Signal Details

### The `"address-changed"` signal

    void                user_function                      (GeoclueAddress *address,
                                                            gint            timestamp,
                                                            gpointer        details,
                                                            gpointer        accuracy,
                                                            gpointer        user_data)      : Run First / No Recursion

The address-changed signal is emitted each time the address changes. See geoclue-types.h for the possible GEOCLUE_ADDRESS_KEY_* keys used in `details`.

Note that not all providers support signals.

`address` : | the GeoclueAddress object emitting the signal
`timestamp` : | Time of address measurement (Unix timestamp)
`details` : | Address details as GHashTable.
`accuracy` : | Accuracy of measurement as GeoclueAccuracy
`user_data` : | user data set when the signal handler was connected.