## GypsyPosition

GypsyPosition — Object for obtaining positions from gypsy-daemon

## Synopsis

                        GypsyPosition;
    #define             GYPSY_POSITION_DBUS_INTERFACE
    #define             GYPSY_POSITION_DBUS_SERVICE
    enum                GypsyPositionFields;
    GypsyPosition *     gypsy_position_new                  (const char *object_path);
    GypsyPositionFields  gypsy_position_get_position        (GypsyPosition *position,
                                                             int *timestamp,
                                                             double *latitude,
                                                             double *longitude,
                                                             double *altitude,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GypsyPosition

## Properties

      "object-path"              gchar*                : Write / Construct Only

## Signals

      "position-changed"                               : Run First / No Recursion

## Description

GypsyPosition is used whenever the client program wishes to know about GPS position changes. It can report the current position, and has a signal to notify listeners of changes.

A GypsyPosition object is created using `gypsy_position_new()` using the D-Bus path of the GPS device. This path is returned from the `gypsy_control_create()` function. The client can then find out about the position with `gypsy_position_get_position()`.

As the position information changes GypsyPosition will emit the position-changed signal. This signal contains the fix position if gypsy-daemon knows it. It has a fields paramater which is a bitmask of GypsyPositionFields which indicates which of the latitude, longitude or altitude contains valid information. The timestamp will always be valid if it is greater than 0.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21

    GypsyPosition *position;
    GError *error = NULL;

    . . .

    / * path comes from the gypsy_control_create() function * /
    position = gypsy_position_new (path);
    g_signal_connect (position, "position-changed", G_CALLBACK (position_changed), NULL);

    . . .

    static void position_changed (GypsyPosition *position,
    GypsyPositionFields fields,
    int timestamp,
    double latitude,
    double longitude,
    double altitude,
    gpointer userdata)
    {
      g_print ("latitude, longitude (%f, %f)\n", (fields & GYPSY_POSITION_FIELDS_LATITUDE) ? latitude : -1.0, (fields & GYPSY_POSITION_FIELDS_LONGITUDE) ? longitude : -1.0);
    }

## Details

### GypsyPosition

    typedef struct _GypsyPosition GypsyPosition;

There are no public fields in GypsyPosition.

### GYPSY_POSITION_DBUS_INTERFACE

    #define GYPSY_POSITION_DBUS_INTERFACE "org.freedesktop.Gypsy.Position"

A define containing the name of the Position interface

### GYPSY_POSITION_DBUS_SERVICE

    #define GYPSY_POSITION_DBUS_SERVICE "org.freedesktop.Gypsy"

A define containing the address of the Position service

### enum GypsyPositionFields

    typedef enum {
    	GYPSY_POSITION_FIELDS_NONE = 0,
    	GYPSY_POSITION_FIELDS_LATITUDE = 1 << 0,
    	GYPSY_POSITION_FIELDS_LONGITUDE = 1 << 1,
    	GYPSY_POSITION_FIELDS_ALTITUDE = 1 << 2
    } GypsyPositionFields;

A bitmask telling which fields in the position_changed callback are valid

`GYPSY_POSITION_FIELDS_NONE` | None of the fields are valid
`GYPSY_POSITION_FIELDS_LATITUDE` | The latitude field is valid
`GYPSY_POSITION_FIELDS_LONGITUDE` | The longitude field is valid
`GYPSY_POSITION_FIELDS_ALTITUDE` | The altitude field is valid

### gypsy_position_new ()

    GypsyPosition *     gypsy_position_new                  (const char *object_path);

Creates a new GypsyPosition object that listens for position changes from the GPS found at `object_path`.

`object_path` : | Object path to the GPS device
Returns : | A GypsyPosition object

### gypsy_position_get_position ()

    GypsyPositionFields  gypsy_position_get_position        (GypsyPosition *position,
                                                             int *timestamp,
                                                             double *latitude,
                                                             double *longitude,
                                                             double *altitude,
                                                             GError **error);

Obtains the current position, if known, from the GPS device. `timestamp`, `latitude`, `longitude` and `altitude` can be NULL if the result is not required.

`position` : | A GypsyPosition
`timestamp` : | Pointer to store the timestamp
`latitude` : | Pointer to store the latitude
`longitude` : | Pointer to store the longitude
`altitude` : | Pointer to store the altitude
`error` : | Pointer to store a GError
Returns : | Bitmask of GypsyPositionFields indicating what field was set

## Property Details

### The `"object-path"` property

      "object-path"              gchar*                : Write / Construct Only

The path of the Gypsy GPS object

Default value: ""

## Signal Details

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

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

The ::position-changed signal is emitted when the GPS device indicates that one or more of the position fields has changed. The fields which have changed will be indicated in the `fields` bitmask.

`fields` : | A bitmask of GypsyPositionFields indicating which of the following fields are valid
`timestamp` : | The timestamp when this change occurred
`latitude` : | The new latitude
`longitude` : | The new longitude
`altitude` : | The new altitude
`user_data` : | user data set when the signal handler was connected.