3 This is a very quick and very dirty guide to adding support for new
4 capture file formats. If you see any errors or have any improvements,
5 submit patches - free software is a community effort....
7 To add the ability to read a new capture file format, you have to:
9 add a new WTAP_FILE_ value for the file type to
12 write an "open" routine that can read the beginning of the
13 capture file and figure out if it's in that format or not,
14 either by looking at a magic number at the beginning or by using
15 some form of heuristic to determine if it's a file of that type
16 (if the file format has a magic number, that's what should be
19 write a "read" routine that can read a packet from the file and
20 supply the packet length, captured data length, time stamp, and
21 packet pseudo-header (if any) and data, and have the "open"
22 routine set the "subtype_read" member of the "wtap" structure
23 supplied to it to point to that routine;
25 write a "seek and read" routine that can seek to a specified
26 location in the file for a packet and supply the packet
27 pseudo-header (if any) and data, and have the "open" routine set
28 the "subtype_seek_read" member of the "wtap" structure to point
31 write a "close" routine, if necessary (if, for example, the
32 "open" routine allocates any memory), and set the
33 "subtype_close" member of the "wtap" structure to point to it,
34 otherwise leave it set to NULL;
36 add a pointer to the "open" routine to the "open_routines_base[]"
37 table in "wiretap/file_access.c" - if it uses a magic number, put
38 it in the first section of that list, and, if it uses a heuristic,
39 put it in the second section, preferably putting the heuristic
40 routines for binary files before the heuristic routines for text
43 add an entry for that file type in the "dump_open_table_base[]" in
44 "wiretap/file_access.c", giving a descriptive name, a short name
45 that's convenient to type on a command line (no blanks or capital
46 letters, please), common file extensions to open and save, a flag
47 if it can be compressed with gzip (currently unused) and pointers
48 to the "can_write_encap" and "dump_open" routines if writing that
49 file is supported (see below), otherwise just null pointers.
51 Wiretap applications typically first perform sequential reads through
52 the capture file and may later do "seek and read" for individual frames.
53 The "read" routine should set the variable data_offset to the byte
54 offset within the capture file from which the "seek and read" routine
55 will read. If the capture records consist of:
58 pseudo-header (e.g., for ATM)
61 then data_offset should point to the pseudo-header. The first
62 sequential read pass will process and store the capture record header
63 data, but it will not store the pseudo-header.
65 To add the ability to write a new capture file format, you have to:
67 add a "can_write_encap" routine that returns an indication of
68 whether a given packet encapsulation format is supported by the
69 new capture file format;
71 add a "dump_open" routine that starts writing a file (writing
72 headers, allocating data structures, etc.);
74 add a "dump" routine to write a packet to a file, and have the
75 "dump_open" routine set the "subtype_write" member of the
76 "wtap_dumper" structure passed to it to point to it;
78 add a "dump_close" routine, if necessary (if, for example, the
79 "dump_open" routine allocates any memory, or if some of the file
80 header can be written only after all the packets have been
81 written), and have the "dump_open" routine set the
82 "subtype_close" member of the "wtap_dumper" structure to point
85 put pointers to the "can_write_encap" and "dump_open" routines
86 in the "dump_open_table_base[]" entry for that file type.