## GypsyCourse

GypsyCourse — Object for obtaining course information

## Synopsis

                        GypsyCourse;
    #define             GYPSY_COURSE_DBUS_INTERFACE
    #define             GYPSY_COURSE_DBUS_SERVICE
    enum                GypsyCourseFields;
    GypsyCourse *       gypsy_course_new                    (const char *object_path);
    GypsyCourseFields   gypsy_course_get_course             (GypsyCourse *course,
                                                             int *timestamp,
                                                             double *speed,
                                                             double *direction,
                                                             double *climb,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GypsyCourse

## Properties

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

## Signals

      "course-changed"                                 : Run First / No Recursion

## Description

GypsyCourse is used whenever the client program wishes to know about GPS course changes. It can report the current course, and has a signal to notify listeners of changes. The course consists of the speed, direction and rate of ascent or descent (called the climb).

A GypsyCourse object is created using `gypsy_course_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 course with `gypsy_course_get_course()`.

As the course information changes GypsyCourse will emit the course-changed signal. This signal contains the course information if gypsy-daemon knows it. It has a fields paramater which is a bitmask of GypsyCourseFields which indicates which of the speed, direction or climb 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
    22

    GypsyCourse *course;
    GError *error = NULL;

    . . .

    / * path comes from the gypsy_control_create() function * /
    course = gypsy_course_new (path);
    g_signal_connect (course, "course-changed", G_CALLBACK (course_changed), NULL);

    . . .

    static void
    course_changed (GypsyCourse *course,
    GypsyCourseFields fields,
    int timestamp,
    double speed,
    double direction,
    double climb,
    gpointer userdata)
    {
      g_print ("speed: %fm/s\n", (fields & GYPSY_COURSE_FIELDS_SPEED) ? speed : -1.0);
    }

## Details

### GypsyCourse

    typedef struct _GypsyCourse GypsyCourse;

There are no public fields in GypsyCourse.

### GYPSY_COURSE_DBUS_INTERFACE

    #define GYPSY_COURSE_DBUS_INTERFACE "org.freedesktop.Gypsy.Course"

A define containing the name of the Course interface

### GYPSY_COURSE_DBUS_SERVICE

    #define GYPSY_COURSE_DBUS_SERVICE "org.freedesktop.Gypsy"

A define containing the address of the Course service

### enum GypsyCourseFields

    typedef enum {
    	GYPSY_COURSE_FIELDS_NONE = 0,
    	GYPSY_COURSE_FIELDS_SPEED = 1 << 0,
    	GYPSY_COURSE_FIELDS_DIRECTION = 1 << 1,
    	GYPSY_COURSE_FIELDS_CLIMB = 1 << 2
    } GypsyCourseFields;

A bitfield telling which fields in the course_changed callback are valid

`GYPSY_COURSE_FIELDS_NONE` | None of the fields are valid
`GYPSY_COURSE_FIELDS_SPEED` | The speed field is valid
`GYPSY_COURSE_FIELDS_DIRECTION` | The direction field is valid
`GYPSY_COURSE_FIELDS_CLIMB` | The climb field is valid

### gypsy_course_new ()

    GypsyCourse *       gypsy_course_new                    (const char *object_path);

Creates a new GypsyCourse object that listens for course changes from the GPS device found at `object_path`.

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

### gypsy_course_get_course ()

    GypsyCourseFields   gypsy_course_get_course             (GypsyCourse *course,
                                                             int *timestamp,
                                                             double *speed,
                                                             double *direction,
                                                             double *climb,
                                                             GError **error);

Obtains the course details from `course`. `timestamp`, `speed`, `direction` and `climb` can be NULL if that detail is not required.

`course` : | A GypsyCourse object
`timestamp` : | Pointer for the timestamp to be returned
`speed` : | Pointer for the speed to be returned
`direction` : | Pointer for the direction to be returned
`climb` : | Pointer for the climb to be returned
`error` : | A GError for error return
Returns : | A bitmask of the fields that are 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 `"course-changed"` signal

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

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

`fields` : | A bitmask of GypsyCourseFields indicating which of the following fields are valid
`timestamp` : | The time this change occurred
`speed` : | The new speed
`direction` : | The new direction
`climb` : | The new rate of climb
`user_data` : | user data set when the signal handler was connected.