wiretap/README.developer

   1 $Id$
   2
   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....
   6
   7 To add the ability to read a new capture file format, you have to:
   8
   9         add a new WTAP_FILE_ value for the file type to
  10         "wiretap/wtap.h";
  11
  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
  17         used);
  18
  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;
  24
  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
  29         to that routine;
  30
  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;
  35
  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
  41         files;
  42
  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.
  50
  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:
  56
  57         capture record header
  58         pseudo-header (e.g., for ATM)
  59         frame data
  60
  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.  Note that the
  64 seek_and_read routine should work with the "random_fh" file handle
  65 of the passed in wtap struct, instead of the "fh" file habndle used
  66 in the normal read routine.
  67
  68 To add the ability to write a new capture file format, you have to:
  69
  70         add a "can_write_encap" routine that returns an indication of
  71         whether a given packet encapsulation format is supported by the
  72         new capture file format;
  73
  74         add a "dump_open" routine that starts writing a file (writing
  75         headers, allocating data structures, etc.);
  76
  77         add a "dump" routine to write a packet to a file, and have the
  78         "dump_open" routine set the "subtype_write" member of the
  79         "wtap_dumper" structure passed to it to point to it;
  80
  81         add a "dump_close" routine, if necessary (if, for example, the
  82         "dump_open" routine allocates any memory, or if some of the file
  83         header can be written only after all the packets have been
  84         written), and have the "dump_open" routine set the
  85         "subtype_close" member of the "wtap_dumper" structure to point
  86         to it;
  87
  88         put pointers to the "can_write_encap" and "dump_open" routines
  89         in the "dump_open_table_base[]" entry for that file type.
  90
  91 In the wiretap directory, add your source file to CMakelists.txt and
  92 your source and header file to Makefile.common.