wiretap/README.developer

   1 This is a very quick and very dirty guide to adding support for new
   2 capture file formats.  If you see any errors or have any improvements,
   3 submit patches - free software is a community effort....
   4
   5 To add the ability to read a new capture file format, you have to:
   6
   7         write an "open" routine that can read the beginning of the
   8         capture file and figure out if it's in that format or not,
   9         either by looking at a magic number at the beginning or by using
  10         some form of heuristic to determine if it's a file of that type
  11         (if the file format has a magic number, that's what should be
  12         used);
  13
  14         write a "read" routine that can read a packet from the file and
  15         supply the packet length, captured data length, time stamp, and
  16         packet pseudo-header (if any) and data, and have the "open"
  17         routine set the "subtype_read" member of the "wtap" structure
  18         supplied to it to point to that routine;
  19
  20         write a "seek and read" routine that can seek to a specified
  21         location in the file for a packet and supply the packet
  22         pseudo-header (if any) and data, and have the "open" routine set
  23         the "subtype_seek_read" member of the "wtap" structure to point
  24         to that routine;
  25
  26         write a "close" routine, if necessary (if, for example, the
  27         "open" routine allocates any memory), and set the
  28         "subtype_close" member of the "wtap" structure to point to it,
  29         otherwise leave it set to NULL;
  30
  31         add an entry for that file type in the "open_info_base[]" table
  32         in "wiretap/file_access.c", giving a pointer to the "open" routine,
  33         a name to use in file open dialogs, whether the file type uses a
  34         magic number or a heuristic, and if it uses a heuristic, file
  35         extensions for which the heuristic should be tried first. More
  36         discriminating and faster heuristics should be put before less
  37         accurate and slower heuristics;
  38
  39         add a registration routine passing a "file_type_subtype_info" struct
  40         to wtap_register_file_type_subtypes(), giving a descriptive name, a
  41         short name that's convenient to type on a command line (no blanks or
  42         capital letters, please), common file extensions to open and save,
  43         any block types supported, and pointers to the "can_write_encap" and
  44         "dump_open" routines if writing that file is supported (see below),
  45         otherwise just null pointers.
  46
  47 Wiretap applications typically first perform sequential reads through
  48 the capture file and may later do "seek and read" for individual frames.
  49 The "read" routine should set the variable data_offset to the byte
  50 offset within the capture file from which the "seek and read" routine
  51 will read.  If the capture records consist of:
  52
  53         capture record header
  54         pseudo-header (e.g., for ATM)
  55         frame data
  56
  57 then data_offset should point to the pseudo-header.  The first
  58 sequential read pass will process and store the capture record header
  59 data, but it will not store the pseudo-header.  Note that the
  60 seek_and_read routine should work with the "random_fh" file handle
  61 of the passed in wtap struct, instead of the "fh" file handle used
  62 in the normal read routine.
  63
  64 To add the ability to write a new capture file format, you have to:
  65
  66         add a "can_write_encap" routine that returns an indication of
  67         whether a given packet encapsulation format is supported by the
  68         new capture file format;
  69
  70         add a "dump_open" routine that starts writing a file (writing
  71         headers, allocating data structures, etc.);
  72
  73         add a "dump" routine to write a packet to a file, and have the
  74         "dump_open" routine set the "subtype_write" member of the
  75         "wtap_dumper" structure passed to it to point to it;
  76
  77         add a "dump_close" routine, if necessary (if, for example, the
  78         "dump_open" routine allocates any memory, or if some of the file
  79         header can be written only after all the packets have been
  80         written), and have the "dump_open" routine set the
  81         "subtype_close" member of the "wtap_dumper" structure to point
  82         to it;
  83
  84         put pointers to the "can_write_encap" and "dump_open" routines
  85         in the "file_type_subtype_info" struct passed to
  86         wtap_register_file_type_subtypes().
  87
  88 In the wiretap directory, add your source file to CMakeLists.txt.