Add a new README.developer file for wiretap; it's currently just some

stuff I sent out in a mail message to somebody asking how to add support
for a new file format, but hopefully it'll get improved by various
contributors over time (hint hint).

svn path=/trunk/; revision=7397

1 files changed, 68 insertions, 0 deletions

diff --git a/wiretap/README.developer b/wiretap/README.developer
new file mode 100644
index 0000000000..81d9dfeb8b
--- /dev/null
+++ b/wiretap/README.developer
@@ -0,0 +1,68 @@
+$Id: README.developer,v 1.1 2003/04/02 20:21:45 guy Exp $
+
+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:
+
+	add a new WTAP_FILE_ value for the file type to
+	"wiretap/wtap.h", and increase WTAP_NUM_FILE_TYPES by 1;
+
+	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, and time stamp,
+	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, if necessary, and have the
+	"open" routine set the "subtype_seek_read" member of the "wtap"
+	structure to point to that routine, otherwise set it to
+	"wtap_def_seek_read";
+
+	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 a pointer to the "open" routine to the "open_routines[]"
+	table in "file.c" - if it uses a magic number, put it in the
+	first section of that list, and, if it uses a heuristic, put it
+	in the second section, preferably putting the heuristic routines
+	for binary files before the heuristic routines for text files;
+
+	add an entry for that file type in the "dump_open_table[]" in
+	"file.c", giving a descriptive name, a short name that's
+	convenient to type on a command line (no blanks or capital
+	letters, please), and pointers to the "can_write_encap" and
+	"dump_open" routines if writing that file is supported (see
+	below), otherwise just null pointers.
+
+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 "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 "dump_open_table[]" entry for that file type.