wiretap/README.developer

   1 $Id: README.developer,v 1.2 2003/09/24 23:53:11 guy Exp $
   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", and increase WTAP_NUM_FILE_TYPES by 1;
  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, and time stamp,
  21         and have the "open" routine set the "subtype_read" member of the
  22         "wtap" structure supplied to it to point to that routine;
  23
  24         write a "seek and read" routine, if necessary, and have the
  25         "open" routine set the "subtype_seek_read" member of the "wtap"
  26         structure to point to that routine, otherwise set it to
  27         "wtap_def_seek_read";
  28
  29         write a "close" routine, if necessary (if, for example, the
  30         "open" routine allocates any memory), and set the
  31         "subtype_close" member of the "wtap" structure to point to it,
  32         otherwise leave it set to NULL;
  33
  34         add a pointer to the "open" routine to the "open_routines[]"
  35         table in "file_access.c" - if it uses a magic number, put it in
  36         the first section of that list, and, if it uses a heuristic, put
  37         it in the second section, preferably putting the heuristic
  38         routines for binary files before the heuristic routines for text
  39         files;
  40
  41         add an entry for that file type in the "dump_open_table[]" in
  42         "file_access.c", giving a descriptive name, a short name that's
  43         convenient to type on a command line (no blanks or capital
  44         letters, please), and pointers to the "can_write_encap" and
  45         "dump_open" routines if writing that file is supported (see
  46         below), otherwise just null pointers.
  47
  48 Wiretap applications typically first perform sequential reads through
  49 the capture file and may later do "seek and read" for individual frames.
  50 The "read" routine should set the variable data_offset to the byte
  51 offset within the capture file from which the "seek and read" routine
  52 will read.  If the capture records consist of:
  53
  54         capture record header
  55         pseudo-header (e.g., for ATM)
  56         frame data
  57
  58 then data_offset should point to the pseudo-header.  The first
  59 sequential read pass will process and store the capture record header
  60 data, but it will not store the pseudo-header.
  61
  62 To add the ability to write a new capture file format, you have to:
  63
  64         add a "can_write_encap" routine that returns an indication of
  65         whether a given packet encapsulation format is supported by the
  66         new capture file format;
  67
  68         add a "dump_open" routine that starts writing a file (writing
  69         headers, allocating data structures, etc.);
  70
  71         add a "dump" routine to write a packet to a file, and have the
  72         "dump_open" routine set the "subtype_write" member of the
  73         "wtap_dumper" structure passed to it to point to it;
  74
  75         add a "close" routine, if necessary (if, for example, the
  76         "dump_open" routine allocates any memory, or if some of the file
  77         header can be written only after all the packets have been
  78         written), and have the "dump_open" routine set the
  79         "subtype_close" member of the "wtap_dumper" structure to point
  80         to it;
  81
  82         put pointers to the "can_write_encap" and "dump_open" routines
  83         in the "dump_open_table[]" entry for that file type.