Ticket #312: gypsy_doc.patch

File gypsy_doc.patch, 5.2 KB (added by RedDog, 12 years ago)
  • navit/vehicle/gypsy/vehicle_gypsy.c

     
    1 /**
     1/** @file vehicle_gypsy.c
     2 * @brief gypsy uses dbus signals
     3 *
    24 * Navit, a modular navigation system.
    35 * Copyright (C) 2005-2008 Navit Team
    46 *
     
    1517 * along with this program; if not, write to the
    1618 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    1719 * Boston, MA  02110-1301, USA.
     20 *
     21 * @Author Tim Niemeyer <reddog@mastersword.de>
     22 * @date 2008-2009
    1823 */
    1924
    2025#include <config.h>
     
    6065#define DEFAULT_RETRY_INTERVAL 10 // seconds
    6166#define MIN_RETRY_INTERVAL 1 // seconds
    6267
     68/**
     69 * @brief When the fixstatus has changed, this function get called
     70 *
     71 * fixstatus can be one of this:
     72 * GYPSY_DEVICE_FIX_STATUS_INVALID = 0
     73 * GYPSY_DEVICE_FIX_STATUS_NONE = 1
     74 * GYPSY_DEVICE_FIX_STATUS_2D = 2
     75 * GYPSY_DEVICE_FIX_STATUS_3D = 3
     76 *
     77 * Anytime this functions get called, we have to call the global
     78 * callback.
     79 *
     80 * @param device The GypsyDevice
     81 * @param fixstatus The fisstatus 0, 1, 2 or 3
     82 * @param userdata
     83 * @returns nothing
     84 */
    6385static void
    6486vehicle_gypsy_fixstatus_changed(GypsyDevice *device,
    6587                gint fixstatus,
     
    7799        callback_list_call_0(priv->cbl);
    78100}
    79101
     102/**
     103 * @brief When the position has changed, this function get called
     104 *
     105 * The fields_set can hold:
     106 * GYPSY_POSITION_FIELDS_NONE = 1 << 0,
     107 * GYPSY_POSITION_FIELDS_LATITUDE = 1 << 1,
     108 * GYPSY_POSITION_FIELDS_LONGITUDE = 1 << 2,
     109 * GYPSY_POSITION_FIELDS_ALTITUDE = 1 << 3
     110 *
     111 * If we get any new information, we have to call the global
     112 * callback.
     113 *
     114 * @param position The GypsyPosition
     115 * @param fields_set Bitmask indicating what field was set
     116 * @param timestamp the time since Unix Epoch
     117 * @param latitude
     118 * @param longitude
     119 * @param altitude
     120 * @param userdata
     121 * @returns nothing
     122 */
    80123static void
    81124vehicle_gypsy_position_changed(GypsyPosition *position,
    82125                GypsyPositionFields fields_set, int timestamp,
     
    112155        }
    113156}
    114157
     158/**
     159 * @brief Everytime any Sat-Details are changed, this function get called
     160 *
     161 * Going through all Sats, counting those wich are in use.
     162 *
     163 * Anytime this functions get called, we have to call the global
     164 * callback.
     165 *
     166 * @param satellite The GypsySatellite
     167 * @param satellites An GPtrArray wich hold information of all sats
     168 * @param userdata
     169 * @returns nothing
     170 */
    115171static void
    116172vehicle_gypsy_satellite_changed(GypsySatellite *satellite,
    117173                GPtrArray *satellites,
     
    134190        callback_list_call_0(priv->cbl);
    135191}
    136192
     193/**
     194 * @brief When the course or speed has changed, this function get called
     195 *
     196 * Only speed and direction are used!
     197 *
     198 * If we get any new information, we have to call the global
     199 * callback.
     200 *
     201 * @param course The GypsyCourse
     202 * @param fields Bitmask indicating what field was set
     203 * @param timestamp the time since Unix Epoch
     204 * @param speed
     205 * @param direction
     206 * @param climb
     207 * @param userdata
     208 * @returns nothing
     209 */
    137210static void
    138211vehicle_gypsy_course_changed (GypsyCourse *course,
    139212                GypsyCourseFields fields,
     
    162235}
    163236
    164237/**
    165  * Attempt to open the gps device.
    166  * Return FALSE if retry not required
    167  * Return TRUE to try again
     238 * @brief Attempt to open the gypsy device.
     239 *
     240 * Tells gypsy wich functions to call when anything occours.
     241 *
     242 * @param data
     243 * @returns TRUE to try again; FALSE if retry not required
    168244 */
    169245static gboolean
    170246vehicle_gypsy_try_open(gpointer *data)
     
    207283}
    208284
    209285/**
    210  * Open a connection to gypsy. Will re-try the connection if it fails
     286 * @brief Open a connection to gypsy. Will re-try the connection if it fails
     287 *
     288 * @param priv
     289 * @returns nothing
    211290 */
    212291static void
    213292vehicle_gypsy_open(struct vehicle_priv *priv)
     
    218297        }
    219298}
    220299
     300/**
     301 * @brief Stop retry timer; Free alloced memory
     302 *
     303 * @param priv
     304 * @returns nothing
     305 */
    221306static void
    222307vehicle_gypsy_close(struct vehicle_priv *priv)
    223308{
     
    244329                g_object_unref(G_OBJECT (priv->control));
    245330}
    246331
     332/**
     333 * @brief Free the gypsy_vehicle
     334 *
     335 * @param priv
     336 * @returns nothing
     337 */
    247338static void
    248339vehicle_gypsy_destroy(struct vehicle_priv *priv)
    249340{
     
    253344        g_free(priv);
    254345}
    255346
     347/**
     348 * @brief Provide the outside with information
     349 *
     350 * @param priv
     351 * @param type TODO: What can this be?
     352 * @param attr
     353 * @returns true/false
     354 */
    256355static int
    257356vehicle_gypsy_position_attr_get(struct vehicle_priv *priv,
    258357                               enum attr_type type, struct attr *attr)
     
    314413        vehicle_gypsy_position_attr_get,
    315414};
    316415
     416/**
     417 * @brief Create gypsy_vehicle
     418 *
     419 * @param meth
     420 * @param cbl
     421 * @param attrs
     422 * @returns vehicle_priv
     423 */
    317424static struct vehicle_priv *
    318 vehicle_gypsy_new_gypsy(struct vehicle_methods
    319                       *meth, struct callback_list
    320                       *cbl, struct attr **attrs)
     425vehicle_gypsy_new_gypsy(struct vehicle_methods *meth,
     426                        struct callback_list *cbl,
     427                        struct attr **attrs)
    321428{
    322429        struct vehicle_priv *ret;
    323430        struct attr *source, *retry_int;
     
    345452        return ret;
    346453}
    347454
     455/**
     456 * @brief register vehicle_gypsy
     457 *
     458 * @returns nothing
     459 */
    348460void
    349461plugin_init(void)
    350462{