doc/README.idl2wrs

   1 Copyright (C) 2001 Frank Singleton <frank.singleton@ericsson.com>
   2
   3
   4 What is it ?
   5 ============
   6
   7 As you have probably guessed from the name, "idl2wrs" takes a
   8 user specified IDL file and attempts to build a dissector that
   9 can decode the IDL traffic over GIOP. The resulting file is
  10 "C" code that should compile okay as a Wireshark dissector.
  11
  12 idl2wrs basically parses the data struct given to it by
  13 the omniidl compiler, and using the GIOP API available in packet-giop.[ch],
  14 generates get_CDR_xxx calls to decode the CORBA traffic on the wire.
  15
  16 It consists of 4 main files.
  17
  18 README.idl2wrs     - This document
  19 wireshark_be.py    - The main compiler backend
  20 wireshark_gen.py   - A helper class that generates the C code.
  21 idl2wrs            - A simple shell script wrapper that the end user should
  22                      use to generate the dissector from the IDL file(s).
  23
  24 Why did you do this ?
  25 =====================
  26
  27 It is important to understand how CORBA traffic looks
  28 like over GIOP/IIOP, and to help build a tool that can assist
  29 in troubleshooting CORBA interworking. This was especially the
  30 case after seeing a lot of discussions about how particular
  31 IDL types are represented inside an octet stream.
  32
  33 I have also had comments/feedback that this tool would be good for say
  34 a CORBA class when teaching students how CORBA traffic looks like
  35 "on the wire".
  36
  37 It is also COOL to work on a great Open Source project such as
  38 the case with "Wireshark" (https://www.wireshark.org)
  39
  40
  41 How to use idl2wrs
  42 ==================
  43
  44 To use the idl2wrs to generate Wireshark dissectors, you
  45 need the following.
  46
  47
  48 1. Python must be installed
  49    https://python.org/
  50
  51 2. omniidl from the omniORB package must be available.
  52    http://omniorb.sourceforge.net/
  53
  54 3. Of course you need Wireshark installed to compile the
  55    code and tweak it if required. idl2wrs is part of the
  56    standard Wireshark distribution.
  57
  58
  59 Procedure
  60 =========
  61
  62 1.  To write the C code to stdout.
  63
  64     idl2wrs  <your_file.idl>
  65
  66     eg: idl2wrs echo.idl
  67
  68
  69 2. To write to a file, just redirect the output.
  70
  71     idl2wrs echo.idl > packet-test-idl.c
  72
  73    You may wish to comment out the register_giop_user_module() code
  74    and that will leave you with heuristic dissection.
  75
  76
  77 If you don't want to use the shell script wrapper, then try
  78 steps 3 or 4 instead.
  79
  80 3.  To write the C code to stdout.
  81
  82     Usage: omniidl  -p ./ -b wireshark_be <your_file.idl>
  83
  84     eg: omniidl  -p ./ -b wireshark_be echo.idl
  85
  86
  87 4. To write to a file, just redirect the output.
  88
  89     omniidl  -p ./ -b wireshark_be echo.idl > packet-test-idl.c
  90
  91    You may wish to comment out the register_giop_user_module() code
  92    and that will leave you with heuristic dissection.
  93
  94
  95 5. Copy the resulting C code to your Wireshark src directory, edit the
  96    following file to include the packet-test-idl.c
  97
  98    cp packet-test-idl.c /dir/where/wireshark/lives/epan/dissectors/
  99    cp /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt.example \
 100      /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt
 101    nano /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt
 102
 103
 104 6. Run CMake
 105
 106    cmake /dir/where/wireshark/lives
 107
 108
 109 7. Compile the code
 110
 111    make
 112
 113
 114 8. Good Luck !!
 115
 116
 117 TODO
 118 ====
 119
 120 1. Exception code not generated  (yet), but can be added manually.
 121 2. Enums not converted to symbolic values (yet), but can be added manually.
 122 3. Add command line options, etc.
 123 4. More I am sure :-)
 124
 125
 126 Limitations
 127 ===========
 128
 129 See TODO list inside packet-giop.c
 130
 131
 132 Notes
 133 =====
 134
 135 1. The "-p ./" option passed to omniidl indicates that the wireshark_be.py
 136    and wireshark_gen.py are residing in the current directory. This may need
 137    tweaking if you place these files somewhere else.
 138
 139 2. If it complains about being unable to find some modules (eg tempfile.py),
 140    you may want to check if PYTHONPATH is set correctly.
 141    On my Linux box, it is  PYTHONPATH=/usr/lib/python1.5/
 142
 143 Frank Singleton.
 144