docbook/wsdg_src/WSDG_chapter_capture.xml

   1 <!-- WSDG Chapter Capture -->
   2 <!-- $Id$ -->
   3
   4 <chapter id="ChapterCapture">
   5   <title>Packet capturing</title>
   6
   7   <para>
   8   XXX - this chapter has to be reviewed and extended!
   9   </para>
  10
  11   <section id="ChCaptureAddLibpcap">
  12         <title>How to add a new capture type to libpcap</title>
  13         <para>
  14         The following is an excerpt from a developer mailing list mail, about
  15         adding ISO 9141 and 14230 (simple serial line card diagnostics) to
  16         Wireshark:
  17         </para>
  18         <para>
  19         For libpcap, the first thing you'd need to do would be to get DLT_ values
  20         for all the link-layer protocols you'd need.  If ISO 9141 and 14230 use
  21         the same link-layer protocol, they might be able to share a DLT_ value,
  22         unless the only way to know what protocols are running above the link
  23         layer is to know which link-layer protocol is being used, in which case
  24         you might want separate DLT_ values.
  25         </para>
  26         <para>
  27         For the rest of the libpcap discussion, I'll assume you're working with
  28         the current top-of-tree CVS version of libpcap, and that this is on a
  29         UN*X platform.  You probably don't want to work with a version older than
  30         0.8, even if whatever OS you're using happens to include libpcap - older
  31         versions are not as friendly towards adding support for devices other than
  32         standard network interfaces.
  33         </para>
  34         <para>
  35         Then you'd probably add to the "pcap_open_live()" routine, for whatever
  36         platform or platforms this code should work, something such as a check
  37         for device names that look like serial port names and, if the check
  38         succeeds, a call to a routine to open the serial port.
  39         </para>
  40         <para>
  41         See, for example, the "#ifdef HAVE_DAG_API" code in pcap-linux.c and
  42         pcap-bpf.c.
  43         </para>
  44         <para>
  45         The serial port open routine would open the serial port device, set the
  46         baud rate and do anything else needed to open the device.  It'd allocate
  47         a pcap_t, set its "fd" member to the file descriptor for the serial
  48         device, set the "snapshot" member to the argument passed to the open
  49         routine, set the "linktype" member to one of the DLT_ values, and set the
  50         "selectable_fd" member to the same value as the "fd" member.  It should
  51         also set the "dlt_count" member to the number of DLT_ values to support,
  52         and allocate an array of "dlt_count" "u_int"s, assign it to the "dlt_list"
  53         member, and fill in that list with all the DLT_ values.
  54         </para>
  55         <para>
  56         You'd then set the various _op fields to routines to handle the
  57         operations in question.  read_op is the routine that'd read packets from
  58         the device.  inject_op would be for sending packets; if you don't care
  59         about that, you'd set it to a routine that returns an error indication.
  60         setfilter_op can probably just be set to install_bpf_program. set_datalink
  61         would just set the "linktype" member to the specified value if it's one
  62         of the values for OBD, otherwise it should return an error. getnonblock_op
  63         can probably be set to pcap_getnonblock_fd; setnonblock_op can probably be
  64         set to pcap_setnonblock_fd.  stats_op would be set to a routine that
  65         reports statistics.  close_op can probably be set to pcap_close_common.
  66         </para>
  67         <para>
  68         If there's more than one DLT_ value, you definitely want a set_datalink
  69         routine, so that the user can select the appropriate link-layer type.
  70         </para>
  71         <para>
  72         For Wireshark, you'd add support for those DLT_ values to wiretap/libpcap.c,
  73         which might mean adding one or more WTAP_ENCAP types to wtap.h and to the
  74         encap_table[] table in wiretap/wtap.c.  You'd then have to write a
  75         dissector or dissectors for the link-layer protocols or protocols and have
  76         them register themselves with the "wtap_encap" dissector table, with the
  77         appropriate WTAP_ENCAP values, by calling "dissector_add_uint()".
  78         </para>
  79   </section>
  80
  81 </chapter>
  82 <!-- End of EDG Chapter Dissection -->