Adding upstream version 4.2.2.upstream/4.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 144 insertions, 0 deletions

diff --git a/doc/README.idl2wrs b/doc/README.idl2wrs
new file mode 100644
index 0000000..77596cb
--- /dev/null
+++ b/doc/README.idl2wrs
@@ -0,0 +1,144 @@
+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
+   https://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 file to include the packet-test-idl.c
+
+   cp packet-test-idl.c /dir/where/wireshark/lives/epan/dissectors/
+   cp /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt.example \
+     /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt
+   nano /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt
+
+
+6. Run CMake
+
+   cmake /dir/where/wireshark/lives
+
+
+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.
+