2 Copyright (c) 2005, David M Howard (daveh at dmh2000.com)
5 This product is licensed for use and distribution under the BSD Open Source License.
6 see the file COPYING for more details.
8 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
9 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
10 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
11 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
12 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
13 OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
14 OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
15 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
16 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
17 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
18 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 ============================================
31 COMPILE TIME CONFIGURATION CONSTANTS
32 ============================================
35 /* these constants affect the size of the context object. tweak them as desired but know what you are doing */
37 /** maximum number of sentence parsers supported */
38 #define NMEAP_MAX_SENTENCES 8
39 /** length of sentence name. leave this at 5 unless you really know what you are doing */
40 #define NMEAP_MAX_SENTENCE_NAME_LENGTH 5
41 /** max length of a complete sentence. the standard says 82 bytes, but its probably better to go at least 128 since
42 * some units don't adhere to the 82 bytes especially for proprietary sentences */
43 #define NMEAP_MAX_SENTENCE_LENGTH 255
44 /** max tokens in one sentence. 24 is enough for any standard sentence */
45 #define NMEAP_MAX_TOKENS 24
47 /* predefined message ID's */
54 /** user defined parsers should make ID numbers using NMEAP_USER as the base value, plus some increment */
55 #define NMEAP_USER 100
57 /* forward references */
59 struct nmeap_sentence;
62 ============================================
64 ============================================
68 * sentence callout function type
69 * a callout is fired for each registered sentence type
70 * the callout gets the object context and a pointer to sentence specific data.
71 * the callout must cast the 'sentence_data' to the appropriate type for that callout
72 * @param context nmea object context
73 * @param sentence_data sentence specific data
75 typedef void (*nmeap_callout_t)(struct nmeap_context *context,void *sentence_data,void *user_data);
78 * sentence parser function type
79 * stored in the object context and called internally when the sentence name matches
81 * the callout gets the object context and a pointer to sentence specific data.
82 * the callout must cast the 'sentence_data' to the appropriate type for that callout
83 * @param context nmea object context
84 * @param sentence_data sentence specific data
85 * @return id of sentence (each sentence parser knows its own ID)
87 typedef int (*nmeap_sentence_parser_t)(struct nmeap_context *context,struct nmeap_sentence *sentence);
90 /* ==== opaque types === */
91 #include "nmeap_def.h"
95 ============================================
96 STANDARD SENTENCE DATA STRUCTURES
97 ============================================
100 /** extracted data from a GGA message */
111 typedef struct nmeap_gga nmeap_gga_t;
113 /** extracted data from an RMC message */
125 typedef struct nmeap_rmc nmeap_rmc_t;
128 ============================================
130 ============================================
134 * initialize an NMEA parser. call this function to initialize a user allocated context object
135 * @param context nmea object context. allocated by user statically or dynamically.
136 * @param user_data pointer to user defined data
137 * @return 0 if ok, -1 if initialization failed
139 int nmeap_init(nmeap_context_t *context,void *user_data);
142 * register an NMEA sentence parser
143 * @param context nmea object context
144 * @param sentence_name string matching the sentence name for this parser. e.g. "GPGGA". not including the '$'
145 * @param sentence_parser parser function for this sentence
146 * @param sentence_callout callout triggered when this sentence is received and parsed.
147 * if null, no callout is triggered for this sentence
148 * @param sentence_data user allocated sentence specific data defined by the application. the parser uses
149 this data item to store the extracted data. This data object needs to persist over the life
150 of the parser, so be careful if allocated on the stack.
151 * @return 0 if registered ok, -1 if registration failed
153 int nmeap_addParser(nmeap_context_t *context,
154 const char *sentence_name,
155 nmeap_sentence_parser_t sentence_parser,
156 nmeap_callout_t sentence_callout,
161 * parse a buffer of nmea data.
162 * @param context nmea object context
163 * @param buffer buffer of input characters
164 * @param length [in,out] pointer to length of buffer. on return, contains number of characters not used for
165 * the current sentence
166 * @return -1 if error, 0 if the data did not complete a sentence, sentence code if a sentence was found in the stream
168 int nmeap_parseBuffer(nmeap_context_t *context,const char *buffer,int *length);
171 * parse one character of nmea data.
172 * @param context nmea object context
173 * @param ch input character
174 * @return -1 if error, 0 if the data did not complete a sentence, sentence code if a sentence was found in the stream
176 int nmeap_parse(nmeap_context_t *context,char ch);
180 * built-in parser for GGA sentences.
181 * @param context nmea object context
182 * @param sentence sentence object for this parser
184 int nmeap_gpgga(nmeap_context_t *context,nmeap_sentence_t *sentence);
187 * built-in parser for RMC sentences.
188 * @param context nmea object context
189 * @param sentence sentence object for this parser
191 int nmeap_gprmc(nmeap_context_t *context,nmeap_sentence_t *sentence);
194 * extract latitude from 2 tokens in ddmm.mmmm,h format.
195 * @param plat pointer to token with numerical latitude
196 * @param phem pointer to token with hemisphere
197 * @return latitude in degrees and fractional degrees
199 double nmeap_latitude(const char *plat,const char *phem);
203 * extract longitude from 2 tokens in ddmm.mmmm,h format.
204 * @param plat pointer to token with numerical longitude
205 * @param phem pointer to token with hemisphere
206 * @return longitude in degrees and fractional degrees
208 double nmeap_longitude(const char *plat,const char *phem);