## GeoclueVelocity

GeoclueVelocity — Geoclue velocity client API

## Synopsis

    #define             GEOCLUE_VELOCITY_INTERFACE_NAME
                        GeoclueVelocity;
    GeoclueVelocity *   geoclue_velocity_new                (const char *service,
                                                             const char *path);
    GeoclueVelocityFields  geoclue_velocity_get_velocity    (GeoclueVelocity *velocity,
                                                             int *timestamp,
                                                             double *speed,
                                                             double *direction,
                                                             double *climb,
                                                             GError **error);
    void                (*GeoclueVelocityCallback)          (GeoclueVelocity *velocity,
                                                             GeoclueVelocityFields fields,
                                                             int timestamp,
                                                             double speed,
                                                             double direction,
                                                             double climb,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_velocity_get_velocity_async (GeoclueVelocity *velocity,
                                                             GeoclueVelocityCallback callback,
                                                             gpointer userdata);

## Object Hierarchy

      GObject
       +----GeoclueProvider
             +----GeoclueVelocity

## Signals

      "velocity-changed"                               : Run First / No Recursion

## Description

GeoclueVelocity contains velocity-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 GeoclueVelocity is created with `geoclue_velocity_new()`, the `geoclue_velocity_get_velocity()` method and the VelocityChanged-signal can be used to obtain the current velocity.

## Details

### GEOCLUE_VELOCITY_INTERFACE_NAME

    #define GEOCLUE_VELOCITY_INTERFACE_NAME "org.freedesktop.Geoclue.Velocity"

### GeoclueVelocity

    typedef struct _GeoclueVelocity GeoclueVelocity;

### geoclue_velocity_new ()

    GeoclueVelocity *   geoclue_velocity_new                (const char *service,
                                                             const char *path);

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

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

### geoclue_velocity_get_velocity ()

    GeoclueVelocityFields  geoclue_velocity_get_velocity    (GeoclueVelocity *velocity,
                                                             int *timestamp,
                                                             double *speed,
                                                             double *direction,
                                                             double *climb,
                                                             GError **error);

Obtains the current velocity. `timestamp` will contain the time of the actual velocity measurement.

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

`velocity` : | A GeoclueVelocity object
`timestamp` : | Pointer to returned time of velocity measurement (unix timestamp) or `NULL`
`speed` : | Pointer to returned horizontal speed or `NULL`
`direction` : | Pointer to returned horizontal direction (bearing) or `NULL`
`climb` : | Pointer to returned vertical speed or `NULL`
`error` : | Pointer to returned GError or `NULL`
Returns : | A GeoclueVelocityFields bitfield representing the validity of the velocity values.

### GeoclueVelocityCallback ()

    void                (*GeoclueVelocityCallback)          (GeoclueVelocity *velocity,
                                                             GeoclueVelocityFields fields,
                                                             int timestamp,
                                                             double speed,
                                                             double direction,
                                                             double climb,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for `geoclue_velocity_get_velocity_async()`.

`velocity` : | A GeoclueVelocity object
`fields` : | A GeoclueVelocityFields bitfield representing the validity of the velocity values
`timestamp` : | Time of velocity measurement (unix timestamp)
`speed` : | Horizontal speed
`direction` : | Horizontal direction (bearing)
`climb` : | Vertical speed
`error` : | Error as GError (may be `NULL`)
`userdata` : | User data pointer set in `geoclue_velocity_get_velocity_async()`

### geoclue_velocity_get_velocity_async ()

    void                geoclue_velocity_get_velocity_async (GeoclueVelocity *velocity,
                                                             GeoclueVelocityCallback callback,
                                                             gpointer userdata);

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

`velocity` : | A GeoclueVelocity object
`callback` : | A GeoclueVelocityCallback function that should be called when return values are available
`userdata` : | pointer for user specified data

## Signal Details

### The `"velocity-changed"` signal

    void                user_function                      (GeoclueVelocity *velocity,
                                                            gint             fields,
                                                            gint             timestamp,
                                                            gdouble          speed,
                                                            gdouble          direction,
                                                            gdouble          climb,
                                                            gpointer         user_data)      : Run First / No Recursion

The geoclue-changed signal is emitted each time the velocity changes.

Note that not all providers support signals.

`velocity` : | the GeoclueVelocity object emitting the signal
`fields` : | A GeoclueVelocityFields bitfield representing the validity of the velocity values
`timestamp` : | Time of velocity measurement (Unix timestamp)
`speed` : | horizontal speed
`direction` : | horizontal direction (bearing)
`climb` : | vertical speed
`user_data` : | user data set when the signal handler was connected.