Explain the BoundsError and ReportedBoundsError errors a bit more, as
[obnox/wireshark/wip.git] / epan / exceptions.h
1 #ifndef __EXCEPTIONS_H__
2 #define __EXCEPTIONS_H__
3
4 #ifndef XCEPT_H
5 #include "except.h"
6 #endif
7
8 /* Ethereal has only one exception group, to make these macros simple */
9 #define XCEPT_GROUP_ETHEREAL 1
10
11 /* Ethereal's exceptions */
12
13 /**
14     Index is out of range.
15     An attempt was made to read past the end of a buffer.
16     This generally means that the capture was done with a "slice"
17     length or "snapshot" length less than the maximum packet size,
18     and a link-layer packet was cut short by that, so not all of the
19     data in the link-layer packet was available.
20 **/
21 #define BoundsError             1       
22
23 /**
24     Index is beyond reported length (not cap_len) 
25     An attempt was made to read past the logical end of a buffer. This
26     differs from a BoundsError in that the parent protocol established a
27     limit past which this dissector should not process in the buffer and that
28     limit was execeeded.
29     This generally means that the packet is invalid, i.e. whatever
30     code constructed the packet and put it on the wire didn't put enough
31     data into it.  It is therefore currently reported as a "Malformed
32     packet".
33     However, it also happens in some cases where the packet was fragmented
34     and the fragments weren't reassembled.  We need to add another length
35     field to a tvbuff, so that "length of the packet from the link layer"
36     and "length of the packet were it fully reassembled" are different,
37     and going past the first of those without going past the second would
38     throw a different exception, which would be reported as an "Unreassembled
39     packet" rather than a "Malformed packet".
40 **/
41 #define ReportedBoundsError     2
42
43 /**
44     During dfilter parsing 
45 **/
46 #define TypeError               3
47
48 /**
49     A bug was detected in a dissector 
50 **/
51 #define DissectorError          4       
52
53 /* Usage:
54  *
55  * TRY {
56  *      code;
57  * }
58  *
59  * CATCH(exception) {
60  *      code;
61  * }
62  *
63  * CATCH2(exception1, exception2) {
64  *      code;
65  * }
66  *
67  * CATCH_ALL {
68  *      code;
69  * }
70  *
71  * FINALLY {
72  *      code;
73  * }
74  *
75  * ENDTRY;
76  *
77  * ********* Never use 'goto' or 'return' inside the TRY, CATCH, CATCH_ALL,
78  * ********* or FINALLY blocks. Execution must proceed through ENDTRY before
79  * ********* branching out.
80  *
81  * This is really something like:
82  *
83  * {
84  *      x = setjmp()
85  *      if (x == 0) {
86  *              <TRY code>
87  *      }
88  *      else if (x == 1) {
89  *              <CATCH(1) code>
90  *      }
91  *      else if (x == 2) {
92  *              <CATCH(2) code>
93  *      }
94  *      else if (x == 3 || x == 4) {
95  *              <CATCH2(3,4) code>
96  *      }
97  *      else {
98  *              <CATCH_ALL code> {
99  *      }
100  *      <FINALLY code>
101  * }<ENDTRY tag>
102  *
103  * All CATCH's must precede a CATCH_ALL.
104  * FINALLY must occur after any CATCH or CATCH_ALL.
105  * ENDTRY marks the end of the TRY code.
106  * TRY and ENDTRY are the mandatory parts of a TRY block.
107  * CATCH, CATCH_ALL, and FINALLY are all optional (although
108  * you'll probably use at least one, otherwise why "TRY"?)
109  *
110  * GET_MESSAGE  returns string ptr to exception message
111  *              when exception is thrown via THROW_MESSAGE()
112  *
113  * To throw/raise an exception.
114  *
115  * THROW(exception)
116  * RETHROW                              rethrow the caught exception
117  *
118  * A cleanup callback is a function called in case an exception occurs
119  * and is not caught. It should be used to free any dynamically-allocated data.
120  * A pop or call_and_pop should occur at the same statement-nesting level
121  * as the push.
122  *
123  * CLEANUP_CB_PUSH(func, data)
124  * CLEANUP_CB_POP
125  * CLEANUP_CB_CALL_AND_POP
126  */
127
128
129
130 #define TRY \
131 {\
132         except_t *exc; \
133         static const except_id_t catch_spec[] = { \
134                 { XCEPT_GROUP_ETHEREAL, XCEPT_CODE_ANY } }; \
135         except_try_push(catch_spec, 1, &exc); \
136         if (exc == 0) { \
137                 /* user's code goes here */
138
139 #define ENDTRY \
140         } \
141         except_try_pop();\
142 }
143
144 #define CATCH(x) \
145         } \
146         else if (exc->except_id.except_code == (x)) { \
147                 /* user's code goes here */
148
149 #define CATCH2(x,y) \
150         } \
151         else if (exc->except_id.except_code == (x) || exc->except_id.except_code == (y)) { \
152                 /* user's code goes here */
153
154 #define CATCH_ALL \
155         } \
156         else { \
157                 /* user's code goes here */
158
159 #define FINALLY \
160         } \
161         { \
162                 /* user's code goes here */
163
164 #define THROW(x) \
165         except_throw(XCEPT_GROUP_ETHEREAL, (x), "XCEPT_GROUP_ETHEREAL")
166
167 #define THROW_MESSAGE(x, y) \
168         except_throw(XCEPT_GROUP_ETHEREAL, (x), (y))
169
170 #define GET_MESSAGE                     except_message(exc)
171
172 #define RETHROW                         except_rethrow(exc)
173
174 #define EXCEPT_CODE                     except_code(exc)
175
176 /* Register cleanup functions in case an exception is thrown and not caught.
177  * From the Kazlib documentation, with modifications for use with the
178  * Ethereal-specific macros:
179  *
180  * CLEANUP_PUSH(func, arg)
181  *
182  *  The call to CLEANUP_PUSH shall be matched with a call to
183  *  CLEANUP_CALL_AND_POP or CLEANUP_POP which must occur in the same
184  *  statement block at the same level of nesting. This requirement allows
185  *  an implementation to provide a CLEANUP_PUSH macro which opens up a
186  *  statement block and a CLEANUP_POP which closes the statement block.
187  *  The space for the registered pointers can then be efficiently
188  *  allocated from automatic storage.
189  *
190  *  The CLEANUP_PUSH macro registers a cleanup handler that will be
191  *  called if an exception subsequently occurs before the matching
192  *  CLEANUP_[CALL_AND_]POP is executed, and is not intercepted and
193  *  handled by a try-catch region that is nested between the two.
194  *
195  *  The first argument to CLEANUP_PUSH is a pointer to the cleanup
196  *  handler, a function that returns nothing and takes a single
197  *  argument of type void*. The second argument is a void* value that
198  *  is registered along with the handler.  This value is what is passed
199  *  to the registered handler, should it be called.
200  *
201  *  Cleanup handlers are called in the reverse order of their nesting:
202  *  inner handlers are called before outer handlers.
203  *
204  *  The program shall not leave the cleanup region between
205  *  the call to the macro CLEANUP_PUSH and the matching call to
206  *  CLEANUP_[CALL_AND_]POP by means other than throwing an exception,
207  *  or calling CLEANUP_[CALL_AND_]POP.
208  *
209  *  Within the call to the cleanup handler, it is possible that new
210  *  exceptions may happen.  Such exceptions must be handled before the
211  *  cleanup handler terminates. If the call to the cleanup handler is
212  *  terminated by an exception, the behavior is undefined. The exception
213  *  which triggered the cleanup is not yet caught; thus the program
214  *  would be effectively trying to replace an exception with one that
215  *  isn't in a well-defined state.
216  *
217  *
218  * CLEANUP_POP and CLEANUP_CALL_AND_POP
219  *
220  *  A call to the CLEANUP_POP or CLEANUP_CALL_AND_POP macro shall match
221  *  each call to CLEANUP_PUSH which shall be in the same statement block
222  *  at the same nesting level.  It shall match the most recent such a
223  *  call that is not matched by a previous CLEANUP_[CALL_AND_]POP at
224  *  the same level.
225  *
226  *  These macros causes the registered cleanup handler to be removed. If
227  *  CLEANUP_CALL_AND_POP is called, the cleanup handler is called.
228  *  In that case, the registered context pointer is passed to the cleanup
229  *  handler. If CLEANUP_POP is called, the cleanup handler is not called.
230  *
231  *  The program shall not leave the region between the call to the
232  *  macro CLEANUP_PUSH and the matching call to CLEANUP_[CALL_AND_]POP
233  *  other than by throwing an exception, or by executing the
234  *  CLEANUP_CALL_AND_POP.
235  *
236  */
237
238
239 #define CLEANUP_PUSH(f,a)               except_cleanup_push((f),(a))
240 #define CLEANUP_POP                     except_cleanup_pop(0)
241 #define CLEANUP_CALL_AND_POP            except_cleanup_pop(1)
242
243 #endif /* __EXCEPTIONS_H__ */