Adding upstream version 4.2.2.upstream/4.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 88 insertions, 0 deletions

diff --git a/wiretap/README.developer b/wiretap/README.developer
new file mode 100644
index 00000000..6552ad18
--- /dev/null
+++ b/wiretap/README.developer
@@ -0,0 +1,88 @@
+This is a very quick and very dirty guide to adding support for new
+capture file formats.  If you see any errors or have any improvements,
+submit patches - free software is a community effort....
+
+To add the ability to read a new capture file format, you have to:
+
+	write an "open" routine that can read the beginning of the
+	capture file and figure out if it's in that format or not,
+	either by looking at a magic number at the beginning or by using
+	some form of heuristic to determine if it's a file of that type
+	(if the file format has a magic number, that's what should be
+	used);
+
+	write a "read" routine that can read a packet from the file and
+	supply the packet length, captured data length, time stamp, and
+	packet pseudo-header (if any) and data, and have the "open"
+	routine set the "subtype_read" member of the "wtap" structure
+	supplied to it to point to that routine;
+
+	write a "seek and read" routine that can seek to a specified
+	location in the file for a packet and supply the packet
+	pseudo-header (if any) and data, and have the "open" routine set
+	the "subtype_seek_read" member of the "wtap" structure to point
+	to that routine;
+
+	write a "close" routine, if necessary (if, for example, the
+	"open" routine allocates any memory), and set the
+	"subtype_close" member of the "wtap" structure to point to it,
+	otherwise leave it set to NULL;
+
+	add an entry for that file type in the "open_info_base[]" table
+	in "wiretap/file_access.c", giving a pointer to the "open" routine,
+	a name to use in file open dialogs, whether the file type uses a
+	magic number or a heuristic, and if it uses a heuristic, file
+	extensions for which the heuristic should be tried first. More
+	discriminating and faster heuristics should be put before less
+	accurate and slower heuristics;
+
+	add a registration routine passing a "file_type_subtype_info" struct
+	to wtap_register_file_type_subtypes(), giving a descriptive name, a
+	short name that's convenient to type on a command line (no blanks or
+	capital letters, please), common file extensions to open and save,
+	any block types supported, and pointers to the "can_write_encap" and
+	"dump_open" routines if writing that file is supported (see below),
+	otherwise just null pointers.
+
+Wiretap applications typically first perform sequential reads through
+the capture file and may later do "seek and read" for individual frames.
+The "read" routine should set the variable data_offset to the byte
+offset within the capture file from which the "seek and read" routine
+will read.  If the capture records consist of:
+
+	capture record header
+	pseudo-header (e.g., for ATM)
+	frame data
+
+then data_offset should point to the pseudo-header.  The first
+sequential read pass will process and store the capture record header
+data, but it will not store the pseudo-header.  Note that the
+seek_and_read routine should work with the "random_fh" file handle
+of the passed in wtap struct, instead of the "fh" file handle used
+in the normal read routine.
+
+To add the ability to write a new capture file format, you have to:
+
+	add a "can_write_encap" routine that returns an indication of
+	whether a given packet encapsulation format is supported by the
+	new capture file format;
+
+	add a "dump_open" routine that starts writing a file (writing
+	headers, allocating data structures, etc.);
+
+	add a "dump" routine to write a packet to a file, and have the
+	"dump_open" routine set the "subtype_write" member of the
+	"wtap_dumper" structure passed to it to point to it;
+
+	add a "dump_close" routine, if necessary (if, for example, the
+	"dump_open" routine allocates any memory, or if some of the file
+	header can be written only after all the packets have been
+	written), and have the "dump_open" routine set the
+	"subtype_close" member of the "wtap_dumper" structure to point
+	to it;
+
+	put pointers to the "can_write_encap" and "dump_open" routines
+	in the "file_type_subtype_info" struct passed to
+	wtap_register_file_type_subtypes().
+
+In the wiretap directory, add your source file to CMakelists.txt.