Copyright (C) 2001 Frank Singleton <frank.singleton@ericsson.com>


What is it ?
============

As you have probably guessed from the name, "idl2wrs" takes a
user specified IDL file and attempts to build a dissector that
can decode the IDL traffic over GIOP. The resulting file is
"C" code that should compile okay as a wireshark dissector.

idl2wrs basically parses the data struct given to it by
the omniidl compiler, and using the GIOP API available in packet-giop.[ch],
generates get_CDR_xxx calls to decode the CORBA traffic on the wire.

It consists of 4 main files.

README.idl2wrs     - This document
wireshark_be.py    - The main compiler backend
wireshark_gen.py   - A helper class that generates the C code.
idl2wrs            - A simple shell script wrapper that the end user should
                     use to generate the dissector from the IDL file(s).

Why did you do this ?
=====================

It is important to understand how CORBA traffic looks
like over GIOP/IIOP, and to help build a tool that can assist
in troubleshooting CORBA interworking. This was especially the
case after seeing a lot of discussions about how particular
IDL types are represented inside an octet stream.

I have also had comments/feedback that this tool would be good for say
a CORBA class when teaching students how CORBA traffic looks like
"on the wire".

It is also COOL to work on a great Open Source project such as
the case with "Wireshark" (https://www.wireshark.org)


How to use idl2wrs
==================

To use the idl2wrs to generate wireshark dissectors, you
need the following.


1. Python must be installed
   http://python.org/

2. omniidl from the omniORB package must be available.
   http://omniorb.sourceforge.net/

3. Of course you need wireshark installed to compile the
   code and tweak it if required. idl2wrs is part of the 
   standard Wireshark distribution.


Procedure
=========

1.  To write the C code to stdout.  

    idl2wrs  <your_file.idl>

    eg: idl2wrs echo.idl


2. To write to a file, just redirect the output.

    idl2wrs echo.idl > packet-test-idl.c

   You may wish to comment out the register_giop_user_module() code
   and that will leave you with heuristic dissection.


If you don't want to use the shell script wrapper, then try
steps 3 or 4 instead.

3.  To write the C code to stdout.  

    Usage: omniidl  -p ./ -b wireshark_be <your_file.idl>

    eg: omniidl  -p ./ -b wireshark_be echo.idl


4. To write to a file, just redirect the output.

    omniidl  -p ./ -b wireshark_be echo.idl > packet-test-idl.c

   You may wish to comment out the register_giop_user_module() code
   and that will leave you with heuristic dissection.


5. Copy the resulting C code to your wireshark src directory, edit the
   following files to include the packet-test-idl.c
 
   cp packet-test-idl.c /dir/where/wireshark/lives/epan/dissectors/
   edit epan/dissectors/Makefile.am
   edit epan/dissectors/CMakeLists.txt

6. Run configure

   ./configure (or ./autogen.sh)

7. Compile the code

   make

8. Good Luck !!


TODO
====

1. Exception code not generated  (yet), but can be added manually.
2. Enums not converted to symbolic values (yet), but can be added manually.
3. Add command line options, etc.
4. More I am sure :-)


Limitations
===========

See TODO list inside packet-giop.c


Notes
=====

1. The "-p ./" option passed to omniidl indicates that the wireshark_be.py
   and wireshark_gen.py are residing in the current directory. This may need
   tweaking if you place these files somewhere else.

2. If it complains about being unable to find some modules (eg tempfile.py), 
   you may want to check if PYTHONPATH is set correctly.
   On my Linux box, it is  PYTHONPATH=/usr/lib/python1.5/ 

Frank Singleton.