## GeocluePosition

GeocluePosition — Geoclue position client API

## Synopsis

    #define             GEOCLUE_POSITION_INTERFACE_NAME
                        GeocluePosition;
    GeocluePosition *   geoclue_position_new                (const char *service,
                                                             const char *path);
    GeocluePositionFields  geoclue_position_get_position    (GeocluePosition *position,
                                                             int *timestamp,
                                                             double *latitude,
                                                             double *longitude,
                                                             double *altitude,
                                                             GeoclueAccuracy **accuracy,
                                                             GError **error);
    void                (*GeocluePositionCallback)          (GeocluePosition *position,
                                                             GeocluePositionFields fields,
                                                             int timestamp,
                                                             double latitude,
                                                             double longitude,
                                                             double altitude,
                                                             GeoclueAccuracy *accuracy,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_position_get_position_async (GeocluePosition *position,
                                                             GeocluePositionCallback callback,
                                                             gpointer userdata);

## Object Hierarchy

      GObject
       +----GeoclueProvider
             +----GeocluePosition

## Signals

      "position-changed"                               : Run First / No Recursion

## Description

GeocluePosition contains position-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 GeocluePosition is created with `geoclue_position_new()` or using `geoclye_master_client_create_position()`, the `geoclue_position_get_position()` and `geoclue_position_get_position_async()` method and the position-changed signal can be used to obtain the current position.

## Details

### GEOCLUE_POSITION_INTERFACE_NAME

    #define GEOCLUE_POSITION_INTERFACE_NAME "org.freedesktop.Geoclue.Position"

### GeocluePosition

    typedef struct _GeocluePosition GeocluePosition;

### geoclue_position_new ()

    GeocluePosition *   geoclue_position_new                (const char *service,
                                                             const char *path);

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

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

### geoclue_position_get_position ()

    GeocluePositionFields  geoclue_position_get_position    (GeocluePosition *position,
                                                             int *timestamp,
                                                             double *latitude,
                                                             double *longitude,
                                                             double *altitude,
                                                             GeoclueAccuracy **accuracy,
                                                             GError **error);

Obtains the current position. `timestamp` will contain the time of the actual position measurement. `accuracy` is a rough estimate of the accuracy of the current position.

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

`position` : | A GeocluePosition object
`timestamp` : | Pointer to returned time of position measurement (Unix timestamp) or `NULL`
`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 position values.

### GeocluePositionCallback ()

    void                (*GeocluePositionCallback)          (GeocluePosition *position,
                                                             GeocluePositionFields fields,
                                                             int timestamp,
                                                             double latitude,
                                                             double longitude,
                                                             double altitude,
                                                             GeoclueAccuracy *accuracy,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for `geoclue_position_get_position_async()`.

`position` : | A GeocluePosition object
`fields` : | A GeocluePositionFields bitfield representing the validity of the position values
`timestamp` : | Time of position measurement (Unix timestamp)
`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 set in `geoclue_position_get_position_async()`

### geoclue_position_get_position_async ()

    void                geoclue_position_get_position_async (GeocluePosition *position,
                                                             GeocluePositionCallback callback,
                                                             gpointer userdata);

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

`position` : | A GeocluePosition object
`callback` : | A GeocluePositionCallback function that should be called when return values are available
`userdata` : | pointer for user specified data

## Signal Details

### The `"position-changed"` signal

    void                user_function                      (GeocluePosition *position,
                                                            gint             fields,
                                                            gint             timestamp,
                                                            gdouble          latitude,
                                                            gdouble          longitude,
                                                            gdouble          altitude,
                                                            gpointer         accuracy,
                                                            gpointer         user_data)      : Run First / No Recursion

The position-changed signal is emitted each time the position changes. Clients should note that not all providers support signals.

`position` : | the GeocluePosition object emitting the signal
`fields` : | A GeocluePositionFields bitfield representing the validity of the position values
`timestamp` : | Time of position measurement (Unix timestamp)
`latitude` : | Latitude in degrees
`longitude` : | Longitude in degrees
`altitude` : | Altitude in meters
`accuracy` : | Accuracy of measurement as GeoclueAccuracy
`user_data` : | user data set when the signal handler was connected.