libgps.xml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!-- lifted from troff+man by doclifter -->
<refentry>
<refentryinfo><date>14 Aug 2004</date></refentryinfo>
<refmeta>
<refentrytitle>3</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class='source'>Linux</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>libgps</refname>
<refpurpose>service library for communicationg with the GPS daemon</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>
<funcsynopsis>
<funcsynopsisinfo>

C:

#include &lt;gps.h&gt;

</funcsynopsisinfo>
<funcprototype>
<funcdef>struct gps_data_t *<function>gps_open</function></funcdef>
    <paramdef>char *<parameter>server</parameter></paramdef>
    <paramdef>char * <parameter>port</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>gps_query</function></funcdef>
    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
    <paramdef>char *<parameter>requests</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>gps_set_raw_hook</function></funcdef>
    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
    <paramdef>void (*<parameter>hook</parameter>)(char *buf)</paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>gps_poll</function></funcdef>
    <paramdef>struct gps_data_t * <parameter>gpsdata</parameter></paramdef>
    <paramdef>void *<parameter>raw_hook</parameter>(char *buf)</paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>gps_close</function></funcdef>
    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
</funcprototype>
<funcsynopsisinfo>

Python:

import gps

session = gps.gps(host="localhost", port="2947")

session.set_raw_hook(raw_hook)

session.query(commands)

session.poll()

del session

</funcsynopsisinfo>
</funcsynopsis>
</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<para><emphasis remap='B'>libgps</emphasis> is a service library which
supports querying GPS devices; link it with the linker option
-lgps. There are two interfaces supported in it; one high-level
interface that goes through
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
and is intended for concurrent use by several applications, and one
low-level interface that speaks directly with the serial or USB device
to which the GPS is attached. This page describes the high-level
interface that is safe for multiple applications to use simultaneously; it
is probably the one you want.  The low-level interface is documented
at
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

<para>Calling <function>gpsd_open()</function> initializes a GPS-data
structure to hold the data collected by the GPS, and returns a socket
attached to
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Negative
return values indicate errors at the socket layer; see
<filename>gps.h</filename> for values and explanations.</para>

<para><function>gpsd_close()</function> ends the session.</para>

<para><function>gpsd_query()</function> queries the daemon, accepts a
one-line response, and updates parts of the GPS-data structure that
correspond to data changed since the last call.  The second argument
must be a string containing letters from the command set documented at
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
This function returns a 1 if any data changed since the last query, a
0 if no data changed, or a -1 if there was a Unix-level read error.</para>

<para><function>gpsd_poll()</function> accepts a one-line response from
the daemon and interprets it as though it were a query response (the
return value is as for a query).  It is meant to be used after the
user has issued an 'R' or 'W' command with
<function>gpsd_query()</function>, telling the daemon to stream updates
to the client.  If the third argument is non-NULL, it is used as a
hook function to be called on each line of streamed data. </para>

<para>Several member groups within the GPS-data structure have
last-modified timestamps and change-flag members associated with them;
these get updated on each query or poll as well.
Consult <filename>gps.h</filename> to learn about the data members 
and associated timestamps.</para>

<para>The Python implementation supports the same facilities as the C
library.  <function>gps_open()</function> is replaced by the
initialization of a gps session object; the other calls are methods of
that object.  Resources within the session object will be properly
released when it is garbage-collected.</para>

</refsect1>

<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>

<refsect1 id='author'><title>AUTHOR</title>
<para>Eric S. Raymond &lt;esr@thyrsus.com&gt;.</para>
</refsect1>
</refentry>