GypsyDevice

## GypsyDevice GypsyDevice — Object for obtaining device information |

## Synopsis

                        GypsyDevice;
    #define             GYPSY_DEVICE_DBUS_SERVICE
    #define             GYPSY_DEVICE_DBUS_INTERFACE
    enum                GypsyDeviceFixStatus;
    GypsyDevice *       gypsy_device_new                    (const char *object_path);
    gboolean            gypsy_device_get_connection_status  (GypsyDevice *device,
                                                             GError **error);
    GypsyDeviceFixStatus gypsy_device_get_fix_status        (GypsyDevice *device,
                                                             GError **error);
    gboolean            gypsy_device_set_start_options      (GypsyDevice *device,
                                                             GHashTable *options,
                                                             GError **error);
    gboolean            gypsy_device_start                  (GypsyDevice *device,
                                                             GError **error);
    gboolean            gypsy_device_stop                   (GypsyDevice *device,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GypsyDevice

## Properties

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

## Signals

      "connection-changed"                             : No Recursion
      "fix-status-changed"                             : No Recursion

## Description

GypsyDevice is used whenever the client program wishes to know about changes in the device's status. It has signals for connection status and fix status. It can also be used to tell gypsy-daemon to start or stop parsing sentences from the GPS device.

A GypsyDevice object is created using `gypsy_device_new()` using the D-Bus path of the GPS device. This path is returned from the `gypsy_control_create()` function. The client can start the GPS data stream with `gypsy_device_start()`, stop it with `gypsy_device_stop()`, or find out about the status with `gypsy_device_get_fix_status()` and `gypsy_device_get_connection_status()`.

As the fix status and connection status change, GypsyDevice will emit the "fix-status-changed" and "connection-changed" signals respectively.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    GypsyDevice *device;
    GError *error = NULL;

    . . .

    /* path comes from the <a class="link" href="gypsy-gypsy-control.html#gypsy-control-create" title="gypsy_control_create ()">gypsy_control_create</a>() function */
    device = <a class="link" href="GypsyDevice.html#gypsy-device-new" title="gypsy_device_new ()">gypsy_device_new</a> (path);
    g_signal_connect (device, "connection-changed", G_CALLBACK (connection_changed), NULL);
    <a class="link" href="GypsyDevice.html#gypsy-device-start" title="gypsy_device_start ()">gypsy_device_start</a> (device, &error);
    if (error != NULL) {
      g_warning ("Error starting GPS: %s", error->message);
      g_error_free (error);
    }

    . . .

    static void connection_changed (GypsyDevice *device, gboolean connected, gpointer data)
    {
      g_print ("Connection status: %s\n", connected ? "Connected" : "Disconnected");
    }

## Details

### GypsyDevice

    typedef struct _GypsyDevice GypsyDevice;

There are no public fields in GypsyDevice.

### GYPSY_DEVICE_DBUS_SERVICE

    #define GYPSY_DEVICE_DBUS_SERVICE "org.freedesktop.Gypsy"

A define containing the name of the Device service

### GYPSY_DEVICE_DBUS_INTERFACE

    #define GYPSY_DEVICE_DBUS_INTERFACE "org.freedesktop.Gypsy.Device"

A define containing the name of the Device interface

### enum GypsyDeviceFixStatus

    typedef enum {
    	GYPSY_DEVICE_FIX_STATUS_INVALID = 0,
    	GYPSY_DEVICE_FIX_STATUS_NONE,
    	GYPSY_DEVICE_FIX_STATUS_2D,
    	GYPSY_DEVICE_FIX_STATUS_3D
    } GypsyDeviceFixStatus;

An enumeration representing the various fix states that a GPS device can be in.

`GYPSY_DEVICE_FIX_STATUS_INVALID` | The fix is invalid
`GYPSY_DEVICE_FIX_STATUS_NONE` | A fix has not yet been obtained
`GYPSY_DEVICE_FIX_STATUS_2D` | A fix with latitude and longitude has been obtained
`GYPSY_DEVICE_FIX_STATUS_3D` | A fix with latitude, longitude and altitude has been obtained

### gypsy_device_new ()

    GypsyDevice *       gypsy_device_new                    (const char *object_path);

Creates a new GypsyDevice that points to `object_path`

`object_path` : | Object path to the device
Returns : | A pointer to a GypsyDevice

### gypsy_device_get_connection_status ()

    gboolean            gypsy_device_get_connection_status  (GypsyDevice *device,
                                                             GError **error);

Obtains the connection status of `device`.

`device` : | A GypsyDevice
`error` : | A pointer to a GError to return an error in.
Returns : | TRUE if the device is connected, FALSE otherwise.

### gypsy_device_get_fix_status ()

    GypsyDeviceFixStatus gypsy_device_get_fix_status        (GypsyDevice *device,
                                                             GError **error);

Obtains the current fix status of `device`.

`device` : | A GypsyDevice
`error` : | A pointer to a GError to return a error in.
Returns : | A GypsyDeviceFixStatus

### gypsy_device_set_start_options ()

    gboolean            gypsy_device_set_start_options      (GypsyDevice *device,
                                                             GHashTable *options,
                                                             GError **error);

Sets options on the device before calling gypsy_device_start. The only valid option currently is "BaudRate", used for serial devices.

`device` : | GypsyDevice
`options` : | a GHashTable of string keys and GValue values
`error` : | A pointer to a GError to return the error in
Returns : | TRUE on success, FALSE otherwise.

### gypsy_device_start ()

    gboolean            gypsy_device_start                  (GypsyDevice *device,
                                                             GError **error);

Starts the connection to the physical device pointed to by `device`, and listens for incoming messages.

`device` : | A GypsyDevice
`error` : | A pointer to a GError to return the error in
Returns : | TRUE on success, FALSE otherwise.

### gypsy_device_stop ()

    gboolean            gypsy_device_stop                   (GypsyDevice *device,
                                                             GError **error);

Stops the physical device pointed to by `device`.

`device` : | A GypsyDevice
`error` : | A pointer to a GError to return the error in
Returns : | TRUE on success, FALSE otherwise.

## Property Details

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

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

The path of the Gypsy GPS object

Default value: ""

## Signal Details

### The `"connection-changed"` signal

    void                user_function                      (GypsyDevice *connected,
                                                            gboolean     arg1,
                                                            gpointer     user_data)      : No Recursion

The ::connection-changed signal is emitted whenever the device connection changes.

`connected` : | Whether or not the device is connected
`user_data` : | user data set when the signal handler was connected.

### The `"fix-status-changed"` signal

    void                user_function                      (GypsyDevice *fix_status,
                                                            gint         arg1,
                                                            gpointer     user_data)       : No Recursion

The ::fix-status-changed signal is emitted whenever the GPS device reports that its fix status has changed. `fix_status` is a GypsyDeviceFixStatus

`fix_status` : | The new fix status
`user_data` : | user data set when the signal handler was connected.