Devuan fork of gpsd
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

92 lines
3.7 KiB

  1. <sect1 id="packet.c"><title><filename>packet.c</filename></title>
  2. <informaltable frame='all' pgwide='1'>
  3. <tgroup cols='2'>
  4. <colspec colname='c1'></colspec>
  5. <colspec colname='c2'></colspec>
  6. <spanspec spanname='s1' namest='c1' nameend='c2'></spanspec>
  7. <thead>
  8. <row>
  9. <entry>Functions:-</entry><entry>The packet-sniffing engine for reading data packets from GPS devices.</entry>
  10. </row>
  11. </thead>
  12. <tfoot>
  13. <row>
  14. <entry spanname='s1' align='left'>Notes based on code as of Tue Apr 6 10:17:55 2010 -0400.</entry>
  15. </row>
  16. </tfoot>
  17. <tbody>
  18. <row>
  19. <entry><function>static void nextstate(struct gps_packet_t *lexer, unsigned char c)</function></entry>
  20. <entry><para>This is the main packet-sniffer loop. It scans the character
  21. against the definitions of all the packet structures known to
  22. <application>gpsd</application> and, if possible, sets a new packet
  23. state.</para><para>If the state is <quote>xxx_RECOGNIZED</quote>,
  24. the packet_parse routine will dispatch the packet to the appropriate
  25. driver.</para></entry>
  26. </row>
  27. <row>
  28. <entry><function>static void packet_accept(struct gps_packet_t *lexer, int packet_type)</function></entry>
  29. <entry><para>This shifts a packet that has been recognized into the
  30. output buffer, provided it is not bigger than the
  31. buffer.</para></entry>
  32. </row>
  33. <row>
  34. <entry><function>static void packet_discard(struct gps_packet_t *lexer)</function></entry>
  35. <entry><para>This clears a handled packet out of the input
  36. buffer.</para></entry>
  37. </row>
  38. <row>
  39. <entry><function>static void character_discard(struct gps_packet_t *lexer)</function></entry>
  40. <entry><para>This is called if the <function>nextstate()</function>
  41. function returns <quote>GROUND_STATE</quote>.</para><para>In this
  42. case the character does not match any pattern, so to discard it, the
  43. input buffer is shifted back by one character to overwrite the
  44. <quote>bad</quote> character.</para></entry>
  45. </row>
  46. <row>
  47. <entry><function>ssize_t packet_parse(struct gps_packet_t *lexer, size_t fix)</function></entry>
  48. <entry><para>Call the <function>nextstate()</function> function to
  49. process the available data and set the recognition state
  50. correctly.</para><para>When a packet is matched to a driver, call
  51. <function>packet_accept()</function> and
  52. <function>packet_discard()</function> to handle the packet. If it is
  53. not matched, call <function>packet_discard()</function> and set the
  54. state to <quote>GROUND_STATE</quote></para><para>Return the number
  55. of characters handled.</para></entry>
  56. </row>
  57. <row>
  58. <entry><function>ssize_t packet_get(int fd, struct gps_packet_t *lexer)</function></entry>
  59. <entry><para>Reads raw data from the input port.</para><para>Returns
  60. the number of characters read (0 or more) or BAD_PACKET if there was
  61. an error in reading.</para><para>Errors
  62. <errortype>EAGAIN</errortype> and <errortype>EINTR</errortype> are
  63. not classed as failures and cause a return of 0.</para><para>In case
  64. of a good read of more than 0 characters, the return value is the
  65. output from a call to
  66. <function>packet_parse()</function>.</para></entry>
  67. </row>
  68. <row>
  69. <entry><function>void packet_reset(struct gps_packet_t *lexer)</function></entry>
  70. <entry><para>This simply resets the entire packet state machine to
  71. the ground state.</para></entry>
  72. </row>
  73. <row>
  74. <entry><function>void packet_nit(struct gps_packet_t *lexer)</function></entry>
  75. <entry><para>Zeros some counters, then resets the entire packet
  76. state machine to the ground state.</para></entry>
  77. </row>
  78. <row>
  79. <entry><function>void packet_pushback(struct gps_packet_t *lexer)</function></entry>
  80. <entry><para>This pushes back the last packet from the output buffer
  81. to the input buffer, provided doing so would not overflow the input
  82. buffer.</para></entry>
  83. </row>
  84. </tbody>
  85. </tgroup>
  86. </informaltable>
  87. </sect1>