packet-dcerpc: nca_s_fault_sec_pkg_error
[metze/wireshark/wip.git] / wiretap / wtap_opttypes.h
1 /* wtap_opttypes.h
2  *
3  * Wireshark - Network traffic analyzer
4  * By Gerald Combs <gerald@wireshark.org>
5  * Copyright 2001 Gerald Combs
6  *
7  * This program is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License
9  * as published by the Free Software Foundation; either version 2
10  * of the License, or (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
20  */
21
22 #ifndef WTAP_OPT_TYPES_H
23 #define WTAP_OPT_TYPES_H
24
25 #include "ws_symbol_export.h"
26
27 #include <wsutil/inet_ipv6.h>
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif /* __cplusplus */
32
33 /*
34  * We use the pcapng option codes for option type values.
35  */
36
37 /* Options for all blocks */
38 #define OPT_EOFOPT           0     /**< Appears in pcapng files, but not in blocks. */
39 #define OPT_COMMENT          1     /**< A UTF-8 string containing a human-readable comment. */
40
41 /* Section Header block (SHB) */
42 #define OPT_SHB_HARDWARE     2     /**< A UTF-8 string containing the description of the
43                                      *     hardware used to create this section.
44                                      */
45 #define OPT_SHB_OS           3     /**< A UTF-8 string containing the
46                                      *     name of the operating system used to create this section.
47                                      */
48 #define OPT_SHB_USERAPPL     4     /**< A UTF-8 string containing the
49                                      *     name of the application used to create this section.
50                                      */
51
52 /* Interface Description block (IDB) */
53 #define OPT_IDB_NAME         2     /**< A UTF-8 string containing the name
54                                      *     of the device used to capture data.
55                                      *     "eth0" / "\Device\NPF_{AD1CE675-96D0-47C5-ADD0-2504B9126B68}"
56                                      */
57 #define OPT_IDB_DESCR        3     /**< A UTF-8 string containing the description
58                                      *     of the device used to capture data.
59                                      *     "Broadcom NetXtreme" / "First Ethernet Interface"
60                                      */
61 #define OPT_IDB_IP4ADDR      4     /**< XXX: if_IPv4addr Interface network address and netmask.
62                                      *     This option can be repeated multiple times within the same Interface Description Block
63                                      *     when multiple IPv4 addresses are assigned to the interface.
64                                      *     192 168 1 1 255 255 255 0
65                                      */
66 #define OPT_IDB_IP6ADDR      5     /* XXX: if_IPv6addr Interface network address and prefix length (stored in the last byte).
67                                      *     This option can be repeated multiple times within the same Interface
68                                      *     Description Block when multiple IPv6 addresses are assigned to the interface.
69                                      *     2001:0db8:85a3:08d3:1319:8a2e:0370:7344/64 is written (in hex) as
70                                      *     "20 01 0d b8 85 a3 08 d3 13 19 8a 2e 03 70 73 44 40"*/
71 #define OPT_IDB_MACADDR      6     /* XXX: if_MACaddr  Interface Hardware MAC address (48 bits).                             */
72 #define OPT_IDB_EUIADDR      7     /* XXX: if_EUIaddr  Interface Hardware EUI address (64 bits)                              */
73 #define OPT_IDB_SPEED        8     /**< Interface speed (in bps). 100000000 for 100Mbps
74                                      */
75 #define OPT_IDB_TSRESOL      9     /**< Resolution of timestamps. If the Most Significant Bit is equal to zero,
76                                      *     the remaining bits indicates the resolution of the timestamp as as a
77                                      *     negative power of 10 (e.g. 6 means microsecond resolution, timestamps
78                                      *     are the number of microseconds since 1/1/1970). If the Most Significant Bit
79                                      *     is equal to one, the remaining bits indicates the resolution has a
80                                      *     negative power of 2 (e.g. 10 means 1/1024 of second).
81                                      *     If this option is not present, a resolution of 10^-6 is assumed
82                                      *     (i.e. timestamps have the same resolution of the standard 'libpcap' timestamps).
83                                      */
84 #define OPT_IDB_TZONE        10    /* XXX: if_tzone    Time zone for GMT support (TODO: specify better). */
85 #define OPT_IDB_FILTER       11    /**< The filter (e.g. "capture only TCP traffic") used to capture traffic.
86                                      *     The first byte of the Option Data keeps a code of the filter used
87                                      *     (e.g. if this is a libpcap string, or BPF bytecode, and more).
88                                      *     More details about this format will be presented in Appendix XXX (TODO).
89                                      *     (TODO: better use different options for different fields?
90                                      *     e.g. if_filter_pcap, if_filter_bpf, ...) 00 "tcp port 23 and host 10.0.0.5"
91                                      */
92 #define OPT_IDB_OS           12    /**< A UTF-8 string containing the name of the operating system of the
93                                      *     machine in which this interface is installed.
94                                      *     This can be different from the same information that can be
95                                      *     contained by the Section Header Block
96                                      *     (Section 3.1 (Section Header Block (mandatory))) because
97                                      *     the capture can have been done on a remote machine.
98                                      *     "Windows XP SP2" / "openSUSE 10.2"
99                                      */
100 #define OPT_IDB_FCSLEN       13    /**< An integer value that specified the length of the
101                                      *     Frame Check Sequence (in bits) for this interface.
102                                      *     For link layers whose FCS length can change during time,
103                                      *     the Packet Block Flags Word can be used (see Appendix A (Packet Block Flags Word))
104                                      */
105 #define OPT_IDB_TSOFFSET     14    /**< XXX: A 64 bits integer value that specifies an offset (in seconds)
106                                      *     that must be added to the timestamp of each packet to obtain
107                                      *     the absolute timestamp of a packet. If the option is missing,
108                                      *     the timestamps stored in the packet must be considered absolute
109                                      *     timestamps. The time zone of the offset can be specified with the
110                                      *     option if_tzone. TODO: won't a if_tsoffset_low for fractional
111                                      *     second offsets be useful for highly syncronized capture systems?
112                                      */
113
114 #define OPT_NS_DNSNAME       2
115 #define OPT_NS_DNSIP4ADDR    3
116 #define OPT_NS_DNSIP6ADDR    4
117
118 #define OPT_ISB_STARTTIME    2
119 #define OPT_ISB_ENDTIME      3
120 #define OPT_ISB_IFRECV       4
121 #define OPT_ISB_IFDROP       5
122 #define OPT_ISB_FILTERACCEPT 6
123 #define OPT_ISB_OSDROP       7
124 #define OPT_ISB_USRDELIV     8
125
126 struct wtap_block;
127 typedef struct wtap_block *wtap_block_t;
128
129 /*
130  * Currently supported blocks; these are not the pcapng block type values
131  * for them, they're identifiers used internally.
132  */
133 typedef enum {
134     WTAP_BLOCK_NG_SECTION = 0,
135     WTAP_BLOCK_IF_DESCR,
136     WTAP_BLOCK_NG_NRB,
137     WTAP_BLOCK_IF_STATS,
138     WTAP_BLOCK_END_OF_LIST
139 } wtap_block_type_t;
140
141 /* Currently supported option types */
142 typedef enum {
143     WTAP_OPTTYPE_UINT8,
144     WTAP_OPTTYPE_UINT64,
145     WTAP_OPTTYPE_STRING,
146     WTAP_OPTTYPE_IPv4,
147     WTAP_OPTTYPE_IPv6,
148     WTAP_OPTTYPE_CUSTOM
149 } wtap_opttype_e;
150
151 typedef enum {
152     WTAP_OPTTYPE_SUCCESS = 0,
153     WTAP_OPTTYPE_NO_SUCH_OPTION = -1,
154     WTAP_OPTTYPE_NOT_FOUND = -2,
155     WTAP_OPTTYPE_TYPE_MISMATCH = -3,
156     WTAP_OPTTYPE_NUMBER_MISMATCH = -4,
157     WTAP_OPTTYPE_ALREADY_EXISTS = -5,
158 } wtap_opttype_return_val;
159
160 struct wtap_opttype_custom
161 {
162     void* data;
163     guint size;
164 };
165
166 /*
167  * Structure describing a value of an option.
168  */
169 typedef union {
170     guint8 uint8val;
171     guint64 uint64val;
172     guint32 ipv4val;    /* network byte order */
173     struct e_in6_addr ipv6val;
174     char *stringval;
175     struct wtap_opttype_custom customval;
176 } wtap_optval_t;
177
178 /*
179  * Structure describing an option in a block.
180  */
181 typedef struct {
182     guint option_id;     /**< option code for the option */
183     wtap_optval_t value; /**< value */
184 } wtap_option_t;
185
186 struct wtap_dumper;
187
188 typedef void (*wtap_block_create_func)(wtap_block_t block);
189 typedef void (*wtap_mand_free_func)(wtap_block_t block);
190 typedef void (*wtap_mand_copy_func)(wtap_block_t dest_block, wtap_block_t src_block);
191
192 /** Initialize block types.
193  *
194  * This is currently just a placeholder as nothing needs to be
195  * initialized yet.  Should handle "registration" when code is
196  * refactored to do so.
197  */
198 WS_DLL_PUBLIC void wtap_opttypes_initialize(void);
199
200 /** Create a block by type
201  *
202  * Return a newly allocated block with default options provided
203  *
204  * @param[in] block_type Block type to be created
205  * @return Newly allocated block
206  */
207 WS_DLL_PUBLIC wtap_block_t wtap_block_create(wtap_block_type_t block_type);
208
209 /** Free a block
210  *
211  * Needs to be called to clean up any allocated block
212  *
213  * @param[in] block Block to be freed
214  */
215 WS_DLL_PUBLIC void wtap_block_free(wtap_block_t block);
216
217 /** Free an array of blocks
218  *
219  * Needs to be called to clean up blocks allocated
220  * through GArray (for multiple blocks of same type)
221  * Includes freeing the GArray
222  *
223  * @param[in] block_array Array of blocks to be freed
224  */
225 WS_DLL_PUBLIC void wtap_block_array_free(GArray* block_array);
226
227 /** Provide mandatory data of a block
228  *
229  * @param[in] block Block from which to retrieve mandatory data
230  * @return Block mandatory data.  Structure varies based on block type
231  */
232 WS_DLL_PUBLIC void* wtap_block_get_mandatory_data(wtap_block_t block);
233
234 /** Add UINT8 option value to a block
235  *
236  * @param[in] block Block to which to add the option
237  * @param[in] option_id Identifier value for option
238  * @param[in] value Value of option
239  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
240  * error code otherwise
241  */
242 WS_DLL_PUBLIC wtap_opttype_return_val
243 wtap_block_add_uint8_option(wtap_block_t block, guint option_id, guint8 value);
244
245 /** Set UINT8 option value in a block
246  *
247  * @param[in] block Block in which to set the option value
248  * @param[in] option_id Identifier value for option
249  * @param[in] value New value of option
250  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
251  * error code otherwise
252  */
253 WS_DLL_PUBLIC wtap_opttype_return_val
254 wtap_block_set_uint8_option_value(wtap_block_t block, guint option_id, guint8 value);
255
256 /** Get UINT8 option value from a block
257  *
258  * @param[in] block Block from which to get the option value
259  * @param[in] option_id Identifier value for option
260  * @param[out] value Returned value of option
261  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
262  * error code otherwise
263  */
264 WS_DLL_PUBLIC wtap_opttype_return_val
265 wtap_block_get_uint8_option_value(wtap_block_t block, guint option_id, guint8* value) G_GNUC_WARN_UNUSED_RESULT;
266
267 /** Add UINT64 option value to a block
268  *
269  * @param[in] block Block to which to add the option
270  * @param[in] option_id Identifier value for option
271  * @param[in] value Value of option
272  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
273  * error code otherwise
274  */
275 WS_DLL_PUBLIC wtap_opttype_return_val
276 wtap_block_add_uint64_option(wtap_block_t block, guint option_id, guint64 value);
277
278 /** Set UINT64 option value in a block
279  *
280  * @param[in] block Block in which to set the option value
281  * @param[in] option_id Identifier value for option
282  * @param[in] value New value of option
283  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
284  * error code otherwise
285  */
286 WS_DLL_PUBLIC wtap_opttype_return_val
287 wtap_block_set_uint64_option_value(wtap_block_t block, guint option_id, guint64 value);
288
289 /** Get UINT64 option value from a block
290  *
291  * @param[in] block Block from which to get the option value
292  * @param[in] option_id Identifier value for option
293  * @param[out] value Returned value of option
294  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
295  * error code otherwise
296  */
297 WS_DLL_PUBLIC wtap_opttype_return_val
298 wtap_block_get_uint64_option_value(wtap_block_t block, guint option_id, guint64* value) G_GNUC_WARN_UNUSED_RESULT;
299
300 /** Add IPv4 address option value to a block
301  *
302  * @param[in] block Block to which to add the option
303  * @param[in] option_id Identifier value for option
304  * @param[in] value Value of option
305  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
306  * error code otherwise
307  */
308 WS_DLL_PUBLIC wtap_opttype_return_val
309 wtap_block_add_ipv4_option(wtap_block_t block, guint option_id, guint32 value);
310
311 /** Set IPv4 option value in a block
312  *
313  * @param[in] block Block in which to set the option value
314  * @param[in] option_id Identifier value for option
315  * @param[in] value New value of option
316  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
317  * error code otherwise
318  */
319 WS_DLL_PUBLIC wtap_opttype_return_val
320 wtap_block_set_ipv4_option_value(wtap_block_t block, guint option_id, guint32 value);
321
322 /** Get IPv4 option value from a block
323  *
324  * @param[in] block Block from which to get the option value
325  * @param[in] option_id Identifier value for option
326  * @param[out] value Returned value of option
327  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
328  * error code otherwise
329  */
330 WS_DLL_PUBLIC wtap_opttype_return_val
331 wtap_block_get_ipv4_option_value(wtap_block_t block, guint option_id, guint32* value) G_GNUC_WARN_UNUSED_RESULT;
332
333 /** Add IPv6 address option value to a block
334  *
335  * @param[in] block Block to which to add the option
336  * @param[in] option_id Identifier value for option
337  * @param[in] value Value of option
338  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
339  * error code otherwise
340  */
341 WS_DLL_PUBLIC wtap_opttype_return_val
342 wtap_block_add_ipv6_option(wtap_block_t block, guint option_id, struct e_in6_addr *value);
343
344 /** Set IPv6 option value in a block
345  *
346  * @param[in] block Block in which to set the option value
347  * @param[in] option_id Identifier value for option
348  * @param[in] value New value of option
349  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
350  * error code otherwise
351  */
352 WS_DLL_PUBLIC wtap_opttype_return_val
353 wtap_block_set_ipv6_option_value(wtap_block_t block, guint option_id, struct e_in6_addr *value);
354
355 /** Get IPv6 option value from a block
356  *
357  * @param[in] block Block from which to get the option value
358  * @param[in] option_id Identifier value for option
359  * @param[out] value Returned value of option
360  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
361  * error code otherwise
362  */
363 WS_DLL_PUBLIC wtap_opttype_return_val
364 wtap_block_get_ipv6_option_value(wtap_block_t block, guint option_id, struct e_in6_addr* value) G_GNUC_WARN_UNUSED_RESULT;
365
366 /** Add a string option to a block
367  *
368  * @param[in] block Block to which to add the option
369  * @param[in] option_id Identifier value for option
370  * @param[in] value Value of option
371  * @param[in] value_length Maximum length of string to copy.
372  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
373  * error code otherwise
374  */
375 WS_DLL_PUBLIC wtap_opttype_return_val
376 wtap_block_add_string_option(wtap_block_t block, guint option_id, const char *value, gsize value_length);
377
378 /** Add a string option to a block witha printf-formatted string as its value
379  *
380  * @param[in] block Block to which to add the option
381  * @param[in] option_id Identifier value for option
382  * @param[in] format printf-like format string
383  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
384  * error code otherwise
385  */
386 WS_DLL_PUBLIC wtap_opttype_return_val
387 wtap_block_add_string_option_format(wtap_block_t block, guint option_id, const char *format, ...)
388                                     G_GNUC_PRINTF(3,4);
389
390 /** Set string option value in a block
391  *
392  * @param[in] block Block in which to set the option value
393  * @param[in] option_id Identifier value for option
394  * @param[in] value New value of option
395  * @param[in] value_length Maximum length of string to copy.
396  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
397  * error code otherwise
398  */
399 WS_DLL_PUBLIC wtap_opttype_return_val
400 wtap_block_set_string_option_value(wtap_block_t block, guint option_id, const char* value, gsize value_length);
401
402 /** Set string option value for nth instance of a particular option in a block
403  *
404  * @param[in] block Block in which to set the option value
405  * @param[in] option_id Identifier value for option
406  * @param[in] idx Instance number of option with that ID
407  * @param[in] value New value of option
408  * @param[in] value_length Maximum length of string to copy.
409  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
410  * error code otherwise
411  */
412 WS_DLL_PUBLIC wtap_opttype_return_val
413 wtap_block_set_nth_string_option_value(wtap_block_t block, guint option_id, guint idx, const char* value, gsize value_length);
414
415 /** Set string option value in a block to a printf-formatted string
416  *
417  * @param[in] block Block in which to set the option value
418  * @param[in] option_id Identifier value for option
419  * @param[in] format printf-like format string
420  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
421  * error code otherwise
422  */
423 WS_DLL_PUBLIC wtap_opttype_return_val
424 wtap_block_set_string_option_value_format(wtap_block_t block, guint option_id, const char *format, ...)
425                                           G_GNUC_PRINTF(3,4);
426
427 /** Get string option value from a block
428  *
429  * @param[in] block Block from which to get the option value
430  * @param[in] option_id Identifier value for option
431  * @param[out] value Returned value of option
432  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
433  * error code otherwise
434  */
435 WS_DLL_PUBLIC wtap_opttype_return_val
436 wtap_block_get_string_option_value(wtap_block_t block, guint option_id, char** value) G_GNUC_WARN_UNUSED_RESULT;
437
438 /** Get string option value for nth instance of a particular option in a block
439  *
440  * @param[in] block Block from which to get the option value
441  * @param[in] option_id Identifier value for option
442  * @param[in] idx Instance number of option with that ID
443  * @param[out] value Returned value of option
444  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
445  * error code otherwise
446  */
447 WS_DLL_PUBLIC wtap_opttype_return_val
448 wtap_block_get_nth_string_option_value(wtap_block_t block, guint option_id, guint idx, char** value) G_GNUC_WARN_UNUSED_RESULT;
449
450 /** Add a "custom" option value to a block
451  *
452  * @param[in] block Block to which to add the option
453  * @param[in] option_id Identifier value for option
454  * @param[in] value Value of option
455  * @param[in] value_size Size of value
456  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
457  * error code otherwise
458  */
459 WS_DLL_PUBLIC wtap_opttype_return_val
460 wtap_block_add_custom_option(wtap_block_t block, guint option_id, void* value, size_t value_size);
461
462 /** Set a "custom" option value in a block
463  *
464  * @param[in] block Block in which to set the option value
465  * @param[in] option_id Identifier value for option
466  * @param[in] value New value of option
467  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
468  * error code otherwise
469  */
470 WS_DLL_PUBLIC wtap_opttype_return_val
471 wtap_block_set_custom_option_value(wtap_block_t block, guint option_id, void* value);
472
473 /** Get a "custom" option value from a block
474  *
475  * @param[in] block Block from which to get the option value
476  * @param[in] option_id Identifier value for option
477  * @param[out] value Returned value of option
478  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
479  * error code otherwise
480  */
481 WS_DLL_PUBLIC wtap_opttype_return_val
482 wtap_block_get_custom_option_value(wtap_block_t block, guint option_id, void** value) G_GNUC_WARN_UNUSED_RESULT;
483
484 /** Remove an option from a block
485  *
486  * @param[in] block Block from which to remove the option
487  * @param[in] option_id Identifier value for option
488  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
489  * error code otherwise
490  */
491 WS_DLL_PUBLIC wtap_opttype_return_val
492 wtap_block_remove_option(wtap_block_t block, guint option_id);
493
494 /** Remove the nth instance of an option from a block
495  *
496  * @param[in] block Block from which to remove the option instance
497  * @param[in] option_id Identifier value for option
498  * @param[in] idx Instance number of option with that ID
499  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
500  * error code otherwise
501  */
502 WS_DLL_PUBLIC wtap_opttype_return_val
503 wtap_block_remove_nth_option_instance(wtap_block_t block, guint option_id,
504                                       guint idx);
505
506 /** Copy a block to another.
507  *
508  * Any options that are in the destination but not the source are not removed.
509  * Options that are just in source will be added to destination
510  *
511  * @param[in] dest_block Block to be copied to
512  * @param[in] src_block Block to be copied from
513  */
514 WS_DLL_PUBLIC void wtap_block_copy(wtap_block_t dest_block, wtap_block_t src_block);
515
516
517 typedef void (*wtap_block_foreach_func)(wtap_block_t block, guint option_id, wtap_opttype_e option_type, wtap_optval_t *option, void *user_data);
518 WS_DLL_PUBLIC void wtap_block_foreach_option(wtap_block_t block, wtap_block_foreach_func func, void* user_data);
519
520 WS_DLL_PUBLIC int wtap_opttype_register_custom_block_type(const char* name, const char* description, wtap_block_create_func create,
521                                                 wtap_mand_free_func free_mand, wtap_mand_copy_func copy_mand);
522
523 #ifdef __cplusplus
524 }
525 #endif /* __cplusplus */
526
527 #endif /* WTAP_OPT_TYPES_H */
528