Squelch warnings.
[metze/wireshark/wip.git] / doc / packet-PROTOABBREV.c
1 /* packet-PROTOABBREV.c
2  * Routines for PROTONAME dissection
3  * Copyright 201x, YOUR_NAME <YOUR_EMAIL_ADDRESS>
4  *
5  * Wireshark - Network traffic analyzer
6  * By Gerald Combs <gerald@wireshark.org>
7  * Copyright 1998 Gerald Combs
8  *
9  * This program is free software; you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation; either version 2 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License along
20  * with this program; if not, write to the Free Software Foundation, Inc.,
21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22  */
23
24 /*
25  * (A short description of the protocol including links to specifications,
26  *  detailed documentation, etc.)
27  */
28
29 #include <config.h>
30
31 #if 0
32 /* "System" includes used only as needed */
33 #include <stdio.h>
34 #include <stdlib.h>
35 #include <string.h>
36 ...
37 #endif
38
39 #include <epan/packet.h>   /* Should be first Wireshark include (other than config.h) */
40 #include <epan/expert.h>   /* Include only as needed */
41 #include <epan/prefs.h>    /* Include only as needed */
42
43 #if 0
44 /* IF AND ONLY IF your protocol dissector exposes code to other dissectors
45  * (which most dissectors don't need to do) then the 'public' prototypes and
46  * data structures can go in the header file packet-PROTOABBREV.h. If not, then
47  * a header file is not needed at all and this #include statement can be
48  * removed. */
49 #include "packet-PROTOABBREV.h"
50 #endif
51
52 /* Prototypes */
53 /* (Required to prevent [-Wmissing-prototypes] warnings */
54 void proto_reg_handoff_PROTOABBREV(void);
55 void proto_register_PROTOABBREV(void);
56
57 /* Initialize the protocol and registered fields */
58 static int proto_PROTOABBREV = -1;
59 static int hf_PROTOABBREV_FIELDABBREV = -1;
60 static expert_field ei_PROTOABBREV_EXPERTABBREV = EI_INIT;
61
62 /* Global sample preference ("controls" display of numbers) */
63 static gboolean pref_hex = FALSE;
64 /* Global sample port preference - real port preferences should generally
65  * default to 0 unless there is an IANA-registered (or equivalent) port for your
66  * protocol. */
67 #define PROTOABBREV_TCP_PORT 1234
68 static guint tcp_port_pref = PROTOABBREV_TCP_PORT;
69
70 /* Initialize the subtree pointers */
71 static gint ett_PROTOABBREV = -1;
72
73 /* A sample #define of the minimum length (in bytes) of the protocol data.
74  * If data is received with fewer than this many bytes it is rejected by
75  * the current dissector. */
76 #define PROTOABBREV_MIN_LENGTH 8
77
78 /* Code to actually dissect the packets */
79 static int
80 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree,
81         void *data _U_)
82 {
83     /* Set up structures needed to add the protocol subtree and manage it */
84     proto_item *ti, *expert_ti;
85     proto_tree *PROTOABBREV_tree;
86     /* Other misc. local variables. */
87     guint       offset = 0;
88     int         len    = 0;
89
90     /*** HEURISTICS ***/
91
92     /* First, if at all possible, do some heuristics to check if the packet
93      * cannot possibly belong to your protocol.  This is especially important
94      * for protocols directly on top of TCP or UDP where port collisions are
95      * common place (e.g., even though your protocol uses a well known port,
96      * someone else may set up, for example, a web server on that port which,
97      * if someone analyzed that web server's traffic in Wireshark, would result
98      * in Wireshark handing an HTTP packet to your dissector).
99      *
100      * For example:
101      */
102
103     /* Check that the packet is long enough for it to belong to us. */
104     if (tvb_reported_length(tvb) < PROTOABBREV_MIN_LENGTH)
105         return 0;
106
107     /* Check that there's enough data present to run the heuristics. If there
108      * isn't, reject the packet; it will probably be dissected as data and if
109      * the user wants it dissected despite it being short they can use the
110      * "Decode-As" functionality. If your heuristic needs to look very deep into
111      * the packet you may not want to require *all* data to be present, but you
112      * should ensure that the heuristic does not access beyond the captured
113      * length of the packet regardless. */
114     if (tvb_captured_length(tvb) < MAX_NEEDED_FOR_HEURISTICS)
115         return 0;
116
117     /* Fetch some values from the packet header using tvb_get_*(). If these
118      * values are not valid/possible in your protocol then return 0 to give
119      * some other dissector a chance to dissect it. */
120     if ( TEST_HEURISTICS_FAIL )
121         return 0;
122
123     /*** COLUMN DATA ***/
124
125     /* There are two normal columns to fill in: the 'Protocol' column which
126      * is narrow and generally just contains the constant string 'PROTOABBREV',
127      * and the 'Info' column which can be much wider and contain misc. summary
128      * information (for example, the port number for TCP packets).
129      *
130      * If you are setting the column to a constant string, use "col_set_str()",
131      * as it's more efficient than the other "col_set_XXX()" calls.
132      *
133      * If
134      * - you may be appending to the column later OR
135      * - you have constructed the string locally OR
136      * - the string was returned from a call to val_to_str()
137      * then use "col_add_str()" instead, as that takes a copy of the string.
138      *
139      * The function "col_add_fstr()" can be used instead of "col_add_str()"; it
140      * takes "printf()"-like arguments. Don't use "col_add_fstr()" with a format
141      * string of "%s" - just use "col_add_str()" or "col_set_str()", as it's
142      * more efficient than "col_add_fstr()".
143      *
144      * For full details see section 1.4 of README.dissector.
145      */
146
147     /* Set the Protocol column to the constant string of PROTOABBREV */
148     col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
149
150 #if 0
151     /* If you will be fetching any data from the packet before filling in
152      * the Info column, clear that column first in case the calls to fetch
153      * data from the packet throw an exception so that the Info column doesn't
154      * contain data left over from the previous dissector: */
155     col_clear(pinfo->cinfo, COL_INFO);
156 #endif
157
158     col_set_str(pinfo->cinfo, COL_INFO, "XXX Request");
159
160     /*** PROTOCOL TREE ***/
161
162     /* Now we will create a sub-tree for our protocol and start adding fields
163      * to display under that sub-tree. Most of the time the only functions you
164      * will need are proto_tree_add_item() and proto_item_add_subtree().
165      *
166      * NOTE: The offset and length values in the call to proto_tree_add_item()
167      * define what data bytes to highlight in the hex display window when the
168      * line in the protocol tree display corresponding to that item is selected.
169      *
170      * Supplying a length of -1 tells Wireshark to highlight all data from the
171      * offset to the end of the packet.
172      */
173
174     /* create display subtree for the protocol */
175     ti = proto_tree_add_item(tree, proto_PROTOABBREV, tvb, 0, -1, ENC_NA);
176
177     PROTOABBREV_tree = proto_item_add_subtree(ti, ett_PROTOABBREV);
178
179     /* Add an item to the subtree, see section 1.5 of README.dissector for more
180      * information. */
181     expert_ti = proto_tree_add_item(PROTOABBREV_tree, hf_PROTOABBREV_FIELDABBREV, tvb,
182             offset, len, ENC_xxx);
183     offset += len;
184     /* Some fields or situations may require "expert" analysis that can be
185      * specifically highlighted. */
186     if ( TEST_EXPERT_condition )
187         /* value of hf_PROTOABBREV_FIELDABBREV isn't what's expected */
188         expert_add_info(pinfo, expert_ti, &ei_PROTOABBREV_EXPERTABBREV);
189
190     /* Continue adding tree items to process the packet here... */
191
192     /* If this protocol has a sub-dissector call it here, see section 1.8 of
193      * README.dissector for more information. */
194
195     /* Return the amount of data this dissector was able to dissect (which may
196      * or may not be the total captured packet as we return here). */
197     return tvb_captured_length(tvb);
198 }
199
200 /* Register the protocol with Wireshark.
201  *
202  * This format is require because a script is used to build the C function that
203  * calls all the protocol registration.
204  */
205 void
206 proto_register_PROTOABBREV(void)
207 {
208     module_t        *PROTOABBREV_module;
209     expert_module_t *expert_PROTOABBREV;
210
211     /* Setup list of header fields  See Section 1.5 of README.dissector for
212      * details. */
213     static hf_register_info hf[] = {
214         { &hf_PROTOABBREV_FIELDABBREV,
215           { "FIELDNAME", "PROTOABBREV.FIELDABBREV",
216             FT_FIELDTYPE, FIELDDISPLAY, FIELDCONVERT, BITMASK,
217             "FIELDDESCR", HFILL }
218         }
219     };
220
221     /* Setup protocol subtree array */
222     static gint *ett[] = {
223         &ett_PROTOABBREV
224     };
225
226     /* Setup protocol expert items */
227     static ei_register_info ei[] = {
228         { &ei_PROTOABBREV_EXPERTABBREV,
229           { "PROTOABBREV.EXPERTABBREV", PI_SEVERITY, PI_GROUP,
230             "EXPERTDESCR", EXPFILL }
231         }
232     };
233
234     /* Register the protocol name and description */
235     proto_PROTOABBREV = proto_register_protocol("PROTONAME",
236             "PROTOSHORTNAME", "PROTOABBREV");
237
238     /* Required function calls to register the header fields and subtrees */
239     proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf));
240     proto_register_subtree_array(ett, array_length(ett));
241
242     /* Required function calls to register expert items */
243     expert_PROTOABBREV = expert_register_protocol(proto_PROTOABBREV);
244     expert_register_field_array(expert_PROTOABBREV, ei, array_length(ei));
245
246     /* Register a preferences module (see section 2.6 of README.dissector
247      * for more details). Registration of a prefs callback is not required
248      * if there are no preferences that affect protocol registration (an example
249      * of a preference that would affect registration is a port preference).
250      * If the prefs callback is not needed, use NULL instead of
251      * proto_reg_handoff_PROTOABBREV in the following.
252      */
253     PROTOABBREV_module = prefs_register_protocol(proto_PROTOABBREV,
254             proto_reg_handoff_PROTOABBREV);
255
256     /* Register a preferences module under the preferences subtree.
257      * Only use this function instead of prefs_register_protocol (above) if you
258      * want to group preferences of several protocols under one preferences
259      * subtree.
260      *
261      * Argument subtree identifies grouping tree node name, several subnodes can
262      * be specified using slash '/' (e.g. "OSI/X.500" - protocol preferences
263      * will be accessible under Protocols->OSI->X.500-><PROTOSHORTNAME>
264      * preferences node.
265      */
266     PROTOABBREV_module = prefs_register_protocol_subtree(const char *subtree,
267             proto_PROTOABBREV, proto_reg_handoff_PROTOABBREV);
268
269     /* Register a simple example preference */
270     prefs_register_bool_preference(PROTOABBREV_module, "show_hex",
271             "Display numbers in Hex",
272             "Enable to display numerical values in hexadecimal.",
273             &pref_hex);
274
275     /* Register an example port preference */
276     prefs_register_uint_preference(PROTOABBREV_module, "tcp.port", "PROTOABBREV TCP Port",
277             " PROTOABBREV TCP port if other than the default",
278             10, &tcp_port_pref);
279 }
280
281 /* If this dissector uses sub-dissector registration add a registration routine.
282  * This exact format is required because a script is used to find these
283  * routines and create the code that calls these routines.
284  *
285  * If this function is registered as a prefs callback (see
286  * prefs_register_protocol above) this function is also called by Wireshark's
287  * preferences manager whenever "Apply" or "OK" are pressed. In that case, it
288  * should accommodate being called more than once by use of the static
289  * 'initialized' variable included below.
290  *
291  * This form of the reg_handoff function is used if if you perform registration
292  * functions which are dependent upon prefs. See below this function for a
293  * simpler form which can be used if there are no prefs-dependent registration
294  * functions.
295  */
296 void
297 proto_reg_handoff_PROTOABBREV(void)
298 {
299     static gboolean initialized = FALSE;
300     static dissector_handle_t PROTOABBREV_handle;
301     static int current_port;
302
303     if (!initialized) {
304         /* Use create_dissector_handle() to indicate that
305          * dissect_PROTOABBREV() returns the number of bytes it dissected (or 0
306          * if it thinks the packet does not belong to PROTONAME).
307          */
308         PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV,
309                 proto_PROTOABBREV);
310         initialized = TRUE;
311
312     } else {
313         /* If you perform registration functions which are dependent upon
314          * prefs then you should de-register everything which was associated
315          * with the previous settings and re-register using the new prefs
316          * settings here. In general this means you need to keep track of
317          * the PROTOABBREV_handle and the value the preference had at the time
318          * you registered.  The PROTOABBREV_handle value and the value of the
319          * preference can be saved using local statics in this
320          * function (proto_reg_handoff).
321          */
322         dissector_delete_uint("tcp.port", current_port, PROTOABBREV_handle);
323     }
324
325     current_port = tcp_port_pref;
326
327     dissector_add_uint("tcp.port", current_port, PROTOABBREV_handle);
328 }
329
330 #if 0
331
332 /* Simpler form of proto_reg_handoff_PROTOABBREV which can be used if there are
333  * no prefs-dependent registration function calls. */
334 void
335 proto_reg_handoff_PROTOABBREV(void)
336 {
337     dissector_handle_t PROTOABBREV_handle;
338
339     /* Use create_dissector_handle() to indicate that dissect_PROTOABBREV()
340      * returns the number of bytes it dissected (or 0 if it thinks the packet
341      * does not belong to PROTONAME).
342      */
343     PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV,
344             proto_PROTOABBREV);
345     dissector_add_uint_with_preference("tcp.port", PROTOABBREV_TCP_PORT, PROTOABBREV_handle);
346 }
347 #endif
348
349 /*
350  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
351  *
352  * Local variables:
353  * c-basic-offset: 4
354  * tab-width: 8
355  * indent-tabs-mode: nil
356  * End:
357  *
358  * vi: set shiftwidth=4 tabstop=8 expandtab:
359  * :indentSize=4:tabSize=8:noTabs=true:
360  */