libgpsd.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!--
   3 This file is Copyright (c) 2010 by the GPSD project
   4 BSD terms apply: see the file COPYING in the distribution root for details.
   5 -->
   6 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   7                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   8 <refentry>
   9 <refentryinfo><date>14 Aug 2004</date></refentryinfo>
  10 <refmeta>
  11 <refentrytitle>3</refentrytitle>
  12 <manvolnum>3</manvolnum>
  13 <refmiscinfo class="source">The GPSD Project</refmiscinfo>
  14 <refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
  15 </refmeta>
  16 <refnamediv id='name'>
  17 <refname>libgpsd</refname>
  18 <refpurpose>service library for GPS applications</refpurpose>
  19 </refnamediv>
  20 <refsynopsisdiv id='synopsis'>
  21 <funcsynopsis>
  22 <funcsynopsisinfo>
  23 C:
  24
  25 #include &lt;gpsd.h&gt;
  26
  27 </funcsynopsisinfo>
  28
  29
  30 <funcprototype>
  31 <funcdef>int <function>gpsd_open_dgps</function></funcdef>
  32     <paramdef>char * <parameter>dgpsserver</parameter></paramdef>
  33 </funcprototype>
  34 <funcprototype>
  35 <funcdef>void <function>gpsd_init</function></funcdef>
  36     <paramdef>struct gps_device_t *<parameter>session</parameter></paramdef>
  37     <paramdef>struct * <parameter>gps_context_t *</parameter></paramdef>
  38     <paramdef>char * <parameter>device</parameter></paramdef>
  39 </funcprototype>
  40 <funcprototype>
  41 <funcdef>int <function>gpsd_activate</function></funcdef>
  42     <paramdef>struct gps_device_t *<parameter>session</parameter></paramdef>
  43 </funcprototype>
  44 <funcprototype>
  45 <funcdef>void <function>gpsd_deactivate</function></funcdef>
  46     <paramdef>struct gps_device_t * <parameter>session</parameter></paramdef>
  47 </funcprototype>
  48 <funcprototype>
  49 <funcdef>gps_mask_t <function>gpsd_poll</function></funcdef>
  50     <paramdef>struct gps_device_t * <parameter>session</parameter></paramdef>
  51 </funcprototype>
  52 <funcprototype>
  53 <funcdef>void <function>gpsd_wrap</function></funcdef>
  54     <paramdef>struct gps_device_t * <parameter>session</parameter></paramdef>
  55 </funcprototype>
  56
  57 <funcprototype>
  58 <funcdef>void <function>gpsd_report</function></funcdef>
  59     <paramdef>int <parameter>d</parameter></paramdef>
  60     <paramdef>const char * <parameter>fmt</parameter></paramdef>
  61     <paramdef><parameter>...</parameter></paramdef>
  62 </funcprototype>
  63 </funcsynopsis>
  64 </refsynopsisdiv>
  65
  66 <refsect1 id='description'><title>DESCRIPTION</title>
  67 <para><emphasis remap='B'>libgpsd</emphasis>
  68 is a service library which supports querying GPS devices; link it with
  69 the linker option -lgpsd.  It is a set of low-level
  70 device-handling calls, which
  71 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  72 itself uses.  See
  73 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  74 for a description of the high-level interface, which is almost
  75 certainly what you want.</para>
  76
  77 <para>Calling
  78 <function>gpsd_init()</function>
  79 initializes a session structure to hold the data collected by the GPS.</para>
  80
  81 <para>The second argument must be a context structure.  The library
  82 will use it for information that need to be shared between sessions;
  83 presently this includes the leap-second correction and possibly a
  84 pointer to a shared-memory segment used to communicate with the
  85 Network Time Protocol daemon.</para>
  86
  87 <para>After the session structure has been set up, you may modify some
  88 of its members.</para>
  89
  90 <variablelist>
  91 <varlistentry>
  92 <term><structfield>gpsd_device</structfield></term>
  93 <listitem>
  94 <para>This member should hold the path name of the device.</para>
  95 </listitem>
  96 </varlistentry>
  97 <varlistentry>
  98 <term><structfield>baudrate</structfield></term>
  99 <listitem>
 100 <para>Communication speed in bits per second.  For NMEA or SiRF devices, the
 101 library automatically hunts through all plausible baud rates, stopping
 102 on the one where it sees valid packets.  By setting this field you can
 103 designate a speed to be tried at the front of the hunt queue</para>
 104 </listitem>
 105 </varlistentry>
 106 <varlistentry>
 107 <term><structfield>raw_hook</structfield></term>
 108 <listitem>
 109 <para>A hook function to be executed on each NMEA
 110 sentence or as it is read from the GPS.  The data from non-NMEA GPSes like
 111 the EarthMate will be translated to an NMEA sentence before being
 112 passed to the hook.  Parameters are a pointer to a gps_data structure
 113 full of parsed data, the sentence, and the length of the sentene..</para>
 114 </listitem>
 115 </varlistentry>
 116 </variablelist>
 117
 118 <para><function>gpsd_activate()</function>
 119 initializes the connection to the GPS.
 120 <function>gpsd_deactivate()</function>
 121 closes the connection. These functions are provided so that
 122 long-running programs can release a connection when there is no
 123 activity requiring the GPS, and re-acquire it later.</para>
 124
 125 <para><function>gpsd_poll()</function>
 126 queries the GPS and updates the part of the session structure that
 127 holds position, speed, GPS signal quality, and other data returned
 128 by the GPS. It returns a mask describing which fields have changed.</para>
 129
 130 <para><function>gpsd_wrap()</function>
 131 ends the session, implicitly performing a
 132 <function>gpsd_deactivate()</function>.</para>
 133
 134 <para>The calling application must define one additional function:
 135 <function>gpsd_report()</function>.
 136 The library will use this to issue ordinary status messages.  Use
 137 first argument of 0 for errors, 1 for ordinary status messages,
 138 and 2 or higher for debugging messages.</para>
 139
 140 <para>The low-level functions do not allocate or free any dynamic
 141 storage.  They can thus be used in a long-running application (such as
 142 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 143 itself) with a guarantee that they won't cause memory leaks.</para>
 144
 145 </refsect1>
 146
 147 <refsect1 id='bugs'><title>BUGS</title>
 148
 149 <para>Writes to the context structure members are not guarded by
 150 a mutex.</para>
 151
 152 </refsect1>
 153
 154 <refsect1 id='see_also'><title>SEE ALSO</title>
 155 <para>
 156 <citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 157 <citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 158 <citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 159 </para>
 160 </refsect1>
 161
 162 <refsect1 id='author'><title>AUTHOR</title>
 163 <para>Eric S. Raymond &lt;esr@thyrsus.com&gt; based partly on earlier work by
 164 Remco Treffkorn, Derrick Brashear, and Russ Nelson.</para>
 165 </refsect1>
 166 </refentry>
 167