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"              gchararray            : 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. 

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"              gchararray            : 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.