Add some info about extended value string to section 1.7.1
[obnox/wireshark/wip.git] / doc / idl2wrs.pod
1
2 =head1 NAME
3
4 idl2wrs - CORBA IDL to Wireshark Plugin Generator
5
6 =head1 SYNOPSIS
7
8 B<idl2wrs> filename
9
10 =head1 DESCRIPTION
11
12 B<idl2wrs> is a program that takes a user specified B<CORBA IDL> 
13 file and generates B<"C"> source code for a B<Wireshark> "plugin".
14
15 This resulting file can be compiled as a B<Wireshark> plugin, and
16 used to monitor B<GIOP/IIOP> traffic that is using this IDL.
17
18 B<idl2wrs> is actually a shell script wrapper for two B<Python> programs.
19
20 These programs are:
21
22 =over 4
23
24 B<wireshark_be.py>  - Contains the main IDL Visitor Class
25
26 B<wireshark_gen.py> - Contains the Source Code Generator Class 
27
28 =back
29
30 B<idl2wrs> supports heuristic dissection of GIOP/IIOP traffic,
31 and some experimental code for explicit dissection, based on
32 Object Key <-> Repository Id mapping.
33 However, code for heuristic based plugins is
34 generated by default, and users should consider this the preferred
35 method unless you have some namespace collisions.
36
37
38 =head1 OPTIONS
39
40 Currently there are no options. B<idl2wrs> can be invoked as follows.
41
42 1.  To write the C code to stdout.  
43
44     idl2wrs  <your_file.idl>
45
46     eg: idl2wrs echo.idl
47
48
49 2. To write to a file, just redirect the output.
50
51     idl2wrs echo.idl > packet-test.c
52
53
54
55
56 =head1 ENVIRONMENT
57
58 B<idl2wrs> will look for B<wireshark_be.py> and B<wireshark_gen.py> in
59 B<$PYTHONPATH/site-packages/> and if not found, will try the current
60 directory B<./>
61
62 The B<-p> option passed to omniidl (inside B<idl2wrs>) indicates where
63 B<wireshark_be.py> and B<wireshark_gen.py> will be searched.  This may
64 need tweaking if you place these files somewhere else.
65
66 If it complains about being unable to find some modules (eg tempfile.py), 
67 you may want to check if PYTHONPATH is set correctly.
68
69 eg:  PYTHONPATH=/usr/lib/python1.5/ 
70
71
72 =head1 SEE ALSO
73
74 wireshark(1), tshark(1)
75
76
77 =head1 NOTES
78
79 B<idl2wrs> (including B<wireshark_be.py> and B<wireshark_gen.py>) are part of 
80 the B<Wireshark> distribution.  The latest version of B<Wireshark> can 
81 be found at L<http://www.wireshark.org>.
82
83 B<idl2wrs> uses B<omniidl>, an IDL parser, and can be found at
84 L<http://omniorb.sourceforge.net/>
85
86 =head1 TODO
87
88 Some of the more important things to do are:
89
90 =over 4
91
92 =item *
93 Improve Explicit dissection code.
94
95 =item *
96 Improve command line options.
97
98 =item *
99 Improve decode algorithm when we have operation name collision.
100
101 =back
102
103 =head1 AUTHORS
104
105   Original Author
106   -------- ------
107   Frank Singleton             <frank.singleton[AT]ericsson.com>
108
109
110   Contributors
111   ------------
112