2 * Prototype file for a gpsmon monitor object.
4 * This file is Copyright (c) 2010 by the GPSD project
5 * BSD terms apply: see the file COPYING in the distribution root for details.
14 #endif /* S_SPLINT_S */
19 #include "gpsd_config.h"
25 #endif /* HAVE_NCURSES_H */
32 * Replace PROTO everywhere with the name of the GPSD driver describing
33 * the device you want to support.
35 * gpsmon basically sits in a loop reading packets, using the same layer
36 * as gpsd to dispatch on packet type to select an active device driver.
37 * Your monitor object will become the handler for incoming packets whenever
38 * the driver your object points at is selected.
40 * A comment following the method descriptions explains some available
44 extern const struct gps_type_t PROTO_binary;
46 static bool PROTO_initialize(void)
49 * This function is called when your monitor object is activated.
51 * When you enter it, two windows will be accessible to you; (1)
52 * devicewin, just below the status and command line at top of
53 * screen, and (2) packetwin, taking up the rest of the screen below
54 * it; packetwin will be enabled for scrolling. Note, however,
55 * that you cannot necessarily update packetwin safely, as it may be NULL
56 * if the screen has no lines left over after allocating devicewin;
57 * you'll need to check this in your code.
59 * Use this method to paint windowframes and legends on the
60 * freshly initialized device window. You can also use this
61 * method to send probes to the device, e.g. to elicit a response
62 * telling you firmware rev levels or whatever.
65 /* return false if the window allocation failed; gpsmon will abort */
69 static void PROTO_update(void)
72 * Called on each packet received. The packet will be accessible in
73 * session.packet.outbuffer and the length in session.packet.outbuflen.
74 * If the device is NMEA, session.driver.nmea.fields[] will contain the
75 * array of unconverted field strings, including the tag in slot zero
76 * but not including the checksum or trailing \r\n.
78 * Use this function to update devicewin. The packet will be echoed to
79 * packetwin immediately after this function is called; you can use this
80 * function to write a prefix on the line.
84 static int PROTO_command(char line[])
87 * Interpret a command line. Whatever characters the user types will
88 * be echoed in the command buffer at the top right of the display. When
89 * he/she presses enter the command line will be passed to this function
90 * for interpretation. Note: packet receipt is suspended while this
91 * function is executing.
93 * This method is optional. If you set the command method pointer to
94 * NULL, gpsmon will behave sanely, accepting no device-specific commands.
96 * It is a useful convention to use uppercase letters for
97 * driver-specific commands and leave lowercase ones for the
98 * generic gpsmon ones.
102 * Return COMMAND_UNKNOWN to tell gpsmon you can't interpret the line, and
103 * it will be passed to the generic command interpreter to be handled there.
104 * You can alse return COMMAND_MATCH to tell it you handled the command,
105 * or COMMAND_TERMINATE to tell gpsmon you handled it and gpsmon should
108 return COMMAND_UNKNOWN;
111 static void PROTO_wrap(void)
114 * Deinitialize any windows you created in PROTO_initialize.
115 * This will be called when gpsmon switches drivers due to seeing
121 * Use mmt = monitor method table as a suffix for naming these things
122 * Yours will need to be added to the monitor_objects table in gpsmon.c,
123 * then of course you need to link your module into gpsmon.
125 const struct monitor_object_t PROTO_mmt = {
126 .initialize = PROTO_initialize,
127 .update = PROTO_update,
128 .command = PROTO_command,
130 .min_y = 23, .min_x = 80, /* size of the device window */
132 * The gpsd driver type for your device. gpsmon will use the mode_switcher
133 * method for 'n', the speed_switcher for 's', and the control_send method
134 * for 'c'. Additionally, the driver type name will be displayed before
135 * the '>' command prompt in the top line of the display.
137 .driver = &PROTO_binary,
143 * bool monitor_control_send(unsigned char *buf, size_t len)
144 * Ship a packet payload to the device. Calls the driver send_control()
145 * method to add headers/trailers/checksum; also dumps the sent
146 * packet to the packet window, if the send_control() is playing
147 * nice by using session.msgbuf to assemble the message.
149 * void monitor_log(const char *fmt, ...)
150 * Write a message to the packet window. Safe if the packet window
153 * void monitor_complain(const char *fmt, ...)
154 * Post an error message to the command window, wait till user presses a key.
155 * You get to make sure the message will fit.
157 * void monitor_fixframe(WINDOW *win)
158 * Fix the frame of win to the right of the current location by redrawing
159 * ACS_VLINE there. Useful after doing wclrtoeol() and writing on the
162 * The libgpsd session object is accessible as the global variable 'session'.