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
|
<sect1 id="libgps.c"><title><filename>libgps.c</filename></title>
<informaltable frame='all' pgwide='1'>
<tgroup cols='2'>
<colspec colname='c1'></colspec>
<colspec colname='c2'></colspec>
<spanspec spanname='s1' namest='c1' nameend='c2'></spanspec>
<thead>
<row>
<entry>Functions:-</entry><entry>The client interface library for the <application>gpsd</application> daemon.</entry>
</row>
</thead>
<tbody>
<row>
<entry><function>char *deg_to_str( enum deg_str_type type, double f)</function></entry>
<entry><para>Convert double degrees to a static string and return a pointer to it.</para><para>Makes a simple check on invalid degree values (less than 0 or more than 360) and returns "nan" if found.</para><para>For valid values, it generates the appropriate string according to the string type enumeration, defaulting to DD MM SS.sss</para></entry>
</row>
<row>
<entry><function>enum unit gpsd_units(void)</function></entry>
<entry><para>Simple check of the environment to determine what units are required. If all else fails, use compiled in units.</para></entry>
</row>
<row>
<entry><function>struct gps_data_t *gps_open(const char *host, const char *port)</function></entry>
<entry><para>Open a connection to a gps daemon.</para><para>Try to get a <function>gps_data_t</function> structure. If it fails, return a NULL.</para><para>Test for a specified host and/or port number, using defaults if nothing is specified in the command line invocation.</para><para>Try to connect to the now defined socket; on error, release the resources and return NULL. On success, initialise the data structure and return the pointer to it.</para></entry>
</row>
<row>
<entry><function>int gps_close(struct gps_data_t *gpsdata)</function></entry>
<entry><para>Close the fd associated with the <function>gps_data_t</function> structure and stash the result.</para><para>If there is a device id stored, NULL it and the associated path.</para><para>If the device list has any data in it, free this and mark the number of available devices as invalid.</para><para>Free the <function>gps_data_t</function> structure itself and return the stashed <function>close()</function> result.</para></entry>
</row>
<row>
<entry><function>void gps_set_raw_hook(struct gps_data_t *gpsdata, void (*hook)(struct gps_data_t *, char *, size_t len, int level))</function></entry>
<entry><para>Fill in the hook to the data for use in raw mode.</para></entry>
</row>
<row>
<entry><function>static void gps_unpack(char *buf, struct gps_data_t *gpsdata)</function></entry>
<entry><para>Keep looping through the data in <function>buf</function> finding an occurrence of <quote>GPSD</quote>.</para><para>Each time one is found, read data in, discarding the initial <quote>GPSD</quote>.</para><para>The data is parsed by scanning to either a <quote>,</quote> or a CR or a LF. This will break the response into <application>gpsd</application> tuples. These are analysed by a big switch statement and the relevant fields and flags are set in the <function>gps_data_t</function> structure.</para><para>Any empty fields (<quote>?</quote> in them) are set to a safe value such as NaN.</para><para>If either of the raw data or thread data hooks is valid, hook the new data in at level 1 (raw mode).</para></entry>
</row>
<row>
<entry><function>int gps_poll(struct gps_data_t *gpsdata)</function></entry>
<entry><para>Poll the daemon and if there is no data or an error, return -1.</para><para>If there is something to read, clear the buffer, note the time as the received data time and the online time, then unpack the data.</para><para>If profiling is active, use the received data time, the fix time and the present time to calcluate the decode time and the client receipt time.</para></entry>
</row>
<row>
<entry><function>int gps_query(struct gps_data_t *gpsdata, const char *fmt, ... )</function></entry>
<entry><para>Gather up the instructions to a <application>gpsd</application> instance for information to return and write them to the device.</para><para>If the write fails, return -1; if it succeeds, call <function>gps_poll()</function> to get any response and return its result.</para></entry>
</row>
<row>
<entry><function>static void *poll_gpsd(void *args)</function></entry>
<entry><para>Set the thread parameters the way we need them (asynchronously cancellable) and then call <function>gps_poll()</function> continuously until we get a failure.</para></entry>
</row>
<row>
<entry><function>int gps_set_callback(struct gps_data_t *gpsdata, void (*callback)(struct gps_data_t *sentence, char *buf, size_t len, int level), pthread_t *handler)</function></entry>
<entry><para>Set <application>gpsd</application> into watcher mode, so it will be generating data.</para><para>If the thread hook is already active, set it to hook to our data and return a 0, otherwise set it to hook to our data and make a call to <function>pthread_create()</function> and return its value (0 if it succeeded).</para></entry>
</row>
<row>
<entry><function>int gps_del_callback(struct gps_data_t *gpsdata, pthread_t *handler)</function></entry>
<entry><para>Cancel the thread and stash the return value.</para><para>Set the hook to NULL now it is not needed.</para><para>If the stashed result was good, switch <application>gpsd</application> out of watcher mode.</para><para>In all cases, return the stashed result.</para></entry>
</row>
<row>
<entry></entry>
<entry><para>The following three functions are guarded by an <function>#ifdef</function> so they only compile if it is required to be able to test the library and set up a command line exerciser interface.</para></entry>
</row>
<row>
<entry><function>static void data_dump(struct gps_data_t *collect, time_t now)</function></entry>
<entry><para>A data dumper used when debugging. It outputs data according to the command line input data.</para></entry>
</row>
<row>
<entry><function>static void dumpline(struct gps_data_t *ud UNUSED, char *buf, size_t ulen UNUSED, int level UNUSED)</function></entry>
<entry><para>A simple call to UNIX <function>puts()</function>.</para></entry>
</row>
<row>
<entry><function>int main(int argc, char *argv[])</function></entry>
<entry><para>A simple command line parser and endless loop to exercise the daemon when debugging.</para></entry>
</row>
</tbody>
<tfoot>
<row>
<entry spanname='s1' align='left'>Notes based on <function>$Id: libgps.c 4377 2007-06-02 14:52:38Z esr $</function></entry>
</row>
</tfoot>
</tgroup>
</informaltable>
</sect1>
|
