libethereal -> libwireshark. idl2eth -> idl2wrs. There are a _lot_ of

changes here.  It compiles OK on OS X, but hasn't been tested anywhere else.

svn path=/trunk/; revision=18260

1 files changed, 142 insertions, 0 deletions

diff --git a/doc/README.idl2wrs b/doc/README.idl2wrs
new file mode 100644
index 0000000000..cd7392c91b
--- /dev/null
+++ b/doc/README.idl2wrs
@@ -0,0 +1,142 @@
+$Id$
+
+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 an ethereal 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
+ethereal_be.py     - The main compiler backend
+ethereal_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 "Ethereal" (http://www.ethereal.com)
+
+
+How to use idl2wrs
+==================
+
+To use the idl2wrs to generate ethereal dissectors, you
+need the following.
+
+
+1. Python must be installed
+   http://python.org/
+
+2. omniidl from the the omniORB package must be available.
+   http://omniorb.sourceforge.net/
+
+3  Of course you need ethereal installed to compile the
+   code an tweak it if required. idl2wrs is part of the 
+   standard Ethereal 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 dont 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 ethereal_be <your file.idl>
+
+    eg: omniidl  -p ./ -b ethereal_be echo.idl
+
+
+4. To write to a file, just redirect the output.
+
+    omniidl  -p ./ -b ethereal_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 ethereal src directory, edit the 2 make files
+   to include the packet-test-idl.c
+ 
+   cp packet-test-idl.c /dir/where/ethereal/lives/
+   edit Makefile.am
+   edit Makefile.nmake
+
+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 ethereal_be.py
+   and ethereal_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.
+