## GypsySatellite

GypsySatellite — Object for obtaining satellite information

## Synopsis

                        GypsySatellite;
    #define             GYPSY_SATELLITE_DBUS_INTERFACE
    #define             GYPSY_SATELLITE_DBUS_SERVICE
                        GypsySatelliteDetails;
    GypsySatellite *    gypsy_satellite_new                 (const char *object_path);
    GPtrArray *         gypsy_satellite_get_satellites      (GypsySatellite *satellite,
                                                             GError **error);
    void                gypsy_satellite_free_satellite_array
                                                            (GPtrArray *satellites);

## Object Hierarchy

      GObject
       +----GypsySatellite

## Properties

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

## Signals

      "satellites-changed"                             : Run Last

## Description

GypsySatellite is used whenever the client program wishes to know about changes in the satellite details. The satellite details contain the satellite ID number (the PRN), the elevation, the azimuth, the signal-to-noise ratio (SNR) and whether or not the satellite was used to calculate the fix.

A GypsySatellite object is created using `gypsy_satellite_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 visible satellites with `gypsy_satellite_get_satellites()` which returns a GPtrArray containing the GypsySatelliteDetails for each visible satellite. Once the client is finished with this GPtrArray `gypsy_satellite_free_satellite_array()` should be used to free the data.

As the satellite information changes GypsySatellite will emit the satellite-changed signal. This signal contains the satellite details in a GPtrArray. In this case the satellite array does not need to be freed with `gypsy_satellite_free_satellite_array()`.

Although gypsy-daemon only emits signals whenever the associated data has changed, satellite data is constantly changing, so so the satellite-changed signal will be emitted at a rate of once every second.

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

    GypsySatellite *satellite;
    GError *error = NULL;

    . . .

    / * path comes from the gypsy_control_create() function * /
    satellite = gypsy_satellite_new (path);
    g_signal_connect (satellite, "satellite-changed", G_CALLBACK (satellite_changed), NULL);

    . . .

    static void satellite_changed (GypsySatellite *satellite,
    GPtrArray *satellites,
    gpointer userdata)
    {
      int i;

      for (i = 0; i < satellites->len; i++) {
        GypsySatelliteDetails *details = satellites->pdata[i];
        g_print ("Satellite %d: %s", details->satellite_id, details->in_use ? "In use" : "Not in use");
      }
    }

## Details

### GypsySatellite

    typedef struct _GypsySatellite GypsySatellite;

There are no public fields in GypsySatellite.

### GYPSY_SATELLITE_DBUS_INTERFACE

    #define GYPSY_SATELLITE_DBUS_INTERFACE "org.freedesktop.Gypsy.Satellite"

A define containing the name of the Satellite interface

### GYPSY_SATELLITE_DBUS_SERVICE

    #define GYPSY_SATELLITE_DBUS_SERVICE "org.freedesktop.Gypsy"

A define containing the address of the Satellite service.

### GypsySatelliteDetails

    typedef struct {
    	int satellite_id;
    	gboolean in_use;
    	guint elevation;
    	guint azimuth;
    	guint snr;
    } GypsySatelliteDetails;

A structure defining a satellite

int `satellite_id`; | The satellite PRN id
gboolean `in_use`; | Whether this satellite was used in calculating the fix
guint `elevation`; | The satellite elevation
guint `azimuth`; | The satellite azimuth
guint `snr`; | The signal to noise ratio

### gypsy_satellite_new ()

    GypsySatellite *    gypsy_satellite_new                 (const char *object_path);

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

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

### gypsy_satellite_get_satellites ()

    GPtrArray *         gypsy_satellite_get_satellites      (GypsySatellite *satellite,
                                                             GError **error);

Retrieves the GypsySatelliteDetails about the satellites that the GPS is able to see.

`satellite` : | A GypsySatellite
`error` : | A GError for error return
Returns : | A GPtrArray of GypsySatelliteDetails or NULL on error. Should be freed using `gypsy_satellite_free_satellite_array()`.

### gypsy_satellite_free_satellite_array ()

    void                gypsy_satellite_free_satellite_array
                                                            (GPtrArray *satellites);

Frees all resources used in the array.

`satellites` : | GPtrArray containing GypsySatelliteDetails

## Property Details

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

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

The DBus path to the object.

Default value: ""

## Signal Details

### The `"satellites-changed"` signal

    void                user_function                      (GypsySatellite *satellites,
                                                            gpointer        arg1,
                                                            gpointer        user_data)       : Run Last

The ::satellites-changed signal is emitted every time the GPS reports a change in the satellite data.

`satellites` : | A GPtrArray containing GypsySatelliteDetails
`user_data` : | user data set when the signal handler was connected.