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