Replace ancient notes about modifying libpcap with a link to a newer doc.
authorGuy Harris <guy@alum.mit.edu>
Sun, 6 Jan 2019 03:06:10 +0000 (19:06 -0800)
committerGuy Harris <guy@alum.mit.edu>
Sun, 6 Jan 2019 03:34:58 +0000 (03:34 +0000)
Instead of giving horribly out-of-date instructions on how to add a new
module to libpcap, just point to the document that I started whipping up
earlier today (it definitely needs work - it's incomplete - but I'll be
getting back to it).

While we're at it, update the notes on adding support for new LINKTYPE_
values to libwiretap, and note that it's only necessary if you had to
add a new DLT_ *and* there isn't already a WTAP_ENCAP_ value that would
correspond to that DLT_.

Change-Id: I3882d0a57b29e98f73c074317bc6df7458fcc677
Reviewed-on: https://code.wireshark.org/review/31397
Petri-Dish: Guy Harris <guy@alum.mit.edu>
Tested-by: Petri Dish Buildbot
Reviewed-by: Guy Harris <guy@alum.mit.edu>
docbook/wsdg_src/WSDG_chapter_capture.asciidoc

index 4e6c55a36b48a9f8e659214db3a47f1a3e2064d8..db6505fe8d33caada728b0d0a0db499279315377 100644 (file)
@@ -16,60 +16,28 @@ This chapter needs to be reviewed and extended.
 
 === How To Add A New Capture Type To Libpcap
 
-The following is an updated excerpt from a developer mailing list mail about
-adding ISO 9141 and 14230 (simple serial line card diagnostics) to Wireshark:
-
-For libpcap, the first thing you’d need to do would be to get `{dlt-glob}` values
-for all the link-layer protocols you’d need. If ISO 9141 and 14230 use the same
-link-layer protocol, they might be able to share a `{dlt-glob}` value, unless the
-only way to know what protocols are running above the link layer is to know
-which link-layer protocol is being used, in which case you might want separate
-`{dlt-glob}` values.
-
-For the rest of the libpcap discussion, I'll assume you're working with libpcap
-1.0 or later and that this is on a UN*X platform. You probably don't want to
-work with a version older than 1.0, even if whatever OS you're using happens to
-include libpcap - older versions are not as friendly towards adding support for
-devices other than standard network interfaces.
-
-Then you’d probably add to the `pcap_open_live()` routine, for whatever
-platform or platforms this code should work, something such as a check
-for device names that look like serial port names and, if the check
-succeeds, a call to a routine to open the serial port.
-
-See, for example, the `#ifdef HAVE_DAG_API` code in _pcap-linux.c_ and
-_pcap-bpf.c_.
-
-The serial port open routine would open the serial port device, set the baud
-rate and do anything else needed to open the device. It’d allocate a `pcap_t`,
-set its `fd` member to the file descriptor for the serial device, set the
-`snapshot` member to the argument passed to the open routine, set the `linktype`
-member to one of the `{dlt-glob}` values, and set the `selectable_fd` member to
-the same value as the `fd` member. It should also set the `dlt_count` member to
-the number of `{dlt-glob}` values to support, and allocate an array of
-`dlt_count` `u_int`s, assign it to the `dlt_list` member, and fill in that list
-with all the `{dlt-glob}` values.
-
-You’d then set the various `_*_op` fields to routines to handle the operations in
-question. `read_op` is the routine that’d read packets from the device. `inject_op`
-would be for sending packets; if you don't care about that, you’d set it to a
-routine that returns an error indication. `setfilter_op` can probably just be set
-to `install_bpf_program`. `set_datalink` would just set the `linktype` member to the
-specified value if it’s one of the values for OBD, otherwise it should return an
-error. `getnonblock_op` can probably be set to `pcap_getnonblock_fd`. `setnonblock_op`
-can probably be set to `pcap_setnonblock_fd`. `stats_op` would be set to a routine
-that reports statistics. `close_op` can probably be set to `pcap_close_common`.
-
-If there’s more than one `{dlt-glob}` value, you definitely want a `set_datalink`
-routine so that the user can select the appropriate link-layer type.
-
-For Wireshark, you’d add support for those `{dlt-glob}` values to
-_wiretap/libpcap.c_, which might mean adding one or more _WTAP_ENCAP_ types to
-_wtap.h_ and to the `encap_table[]` table in _wiretap/wtap.c_. You’d then
-have to write a dissector or dissectors for the link-layer protocols or
-protocols and have them register themselves with the `wtap_encap` dissector
-table, with the appropriate _WTAP_ENCAP_ values by calling
-`dissector_add_uint()`.
+For this discussion, I'll assume you're working with libpcap 1.0 or
+later.  You probably don't want to work with a version older than 1.0,
+even if whatever OS you're using happens to include libpcap - older
+versions are not as friendly towards adding support for devices other
+than standard network interfaces.
+
+First, read 
+
+link:https://github.com/the-tcpdump-group/libpcap/blob/master/doc/README.capture-module:[the
+libpcap documentation on writing a new libpcap module]
+
+(It's currently incomplete, but I'll be finishing it up over time.  If
+you have contributions, feel free to submit pull requests for it.)
+
+If you had to introduce one or more new `{dlt-glob}` values, you will
+also have to add support in Wireshark for those `{dlt-glob}` values to
+_wiretap/pcap-common.c_, which might mean adding one or more
+_WTAP_ENCAP_ types to _wtap.h_ and to the `encap_table[]` table in
+_wiretap/wtap.c_. You’d thehave to write a dissector or dissectors for
+the link-layer protocols or protocols and have them register themselves
+with the `wtap_encap` dissector table, with the appropriate _WTAP_ENCAP_
+values by calling `dissector_add_uint()`.
 
 [[ChCaptureExtcap]]