3 * Wireshark - Network traffic analyzer
4 * By Gerald Combs <gerald@wireshark.org>
5 * Copyright 2001 Gerald Combs
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.
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.
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.
22 #ifndef WTAP_OPT_TYPES_H
23 #define WTAP_OPT_TYPES_H
25 #include "ws_symbol_export.h"
27 #include <wsutil/inet_ipv6.h>
31 #endif /* __cplusplus */
34 * We use the pcapng option codes for option type values.
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. */
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.
45 #define OPT_SHB_OS 3 /**< A UTF-8 string containing the
46 * name of the operating system used to create this section.
48 #define OPT_SHB_USERAPPL 4 /**< A UTF-8 string containing the
49 * name of the application used to create this section.
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}"
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"
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
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
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).
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"
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"
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))
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?
114 #define OPT_NS_DNSNAME 2
115 #define OPT_NS_DNSIP4ADDR 3
116 #define OPT_NS_DNSIP6ADDR 4
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
127 typedef struct wtap_block *wtap_block_t;
130 * Currently supported blocks; these are not the pcapng block type values
131 * for them, they're identifiers used internally.
134 WTAP_BLOCK_NG_SECTION = 0,
138 WTAP_BLOCK_END_OF_LIST
141 /* Currently supported option types */
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;
160 struct wtap_opttype_custom
167 * Structure describing a value of an option.
172 guint32 ipv4val; /* network byte order */
173 struct e_in6_addr ipv6val;
175 struct wtap_opttype_custom customval;
179 * Structure describing an option in a block.
182 guint option_id; /**< option code for the option */
183 wtap_optval_t value; /**< value */
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);
192 /** Initialize block types.
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.
198 WS_DLL_PUBLIC void wtap_opttypes_initialize(void);
200 /** Create a block by type
202 * Return a newly allocated block with default options provided
204 * @param[in] block_type Block type to be created
205 * @return Newly allocated block
207 WS_DLL_PUBLIC wtap_block_t wtap_block_create(wtap_block_type_t block_type);
211 * Needs to be called to clean up any allocated block
213 * @param[in] block Block to be freed
215 WS_DLL_PUBLIC void wtap_block_free(wtap_block_t block);
217 /** Free an array of blocks
219 * Needs to be called to clean up blocks allocated
220 * through GArray (for multiple blocks of same type)
221 * Includes freeing the GArray
223 * @param[in] block_array Array of blocks to be freed
225 WS_DLL_PUBLIC void wtap_block_array_free(GArray* block_array);
227 /** Provide mandatory data of a block
229 * @param[in] block Block from which to retrieve mandatory data
230 * @return Block mandatory data. Structure varies based on block type
232 WS_DLL_PUBLIC void* wtap_block_get_mandatory_data(wtap_block_t block);
234 /** Add UINT8 option value to a block
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
242 WS_DLL_PUBLIC wtap_opttype_return_val
243 wtap_block_add_uint8_option(wtap_block_t block, guint option_id, guint8 value);
245 /** Set UINT8 option value in a block
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
253 WS_DLL_PUBLIC wtap_opttype_return_val
254 wtap_block_set_uint8_option_value(wtap_block_t block, guint option_id, guint8 value);
256 /** Get UINT8 option value from a block
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
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;
267 /** Add UINT64 option value to a block
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
275 WS_DLL_PUBLIC wtap_opttype_return_val
276 wtap_block_add_uint64_option(wtap_block_t block, guint option_id, guint64 value);
278 /** Set UINT64 option value in a block
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
286 WS_DLL_PUBLIC wtap_opttype_return_val
287 wtap_block_set_uint64_option_value(wtap_block_t block, guint option_id, guint64 value);
289 /** Get UINT64 option value from a block
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
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;
300 /** Add IPv4 address option value to a block
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
308 WS_DLL_PUBLIC wtap_opttype_return_val
309 wtap_block_add_ipv4_option(wtap_block_t block, guint option_id, guint32 value);
311 /** Set IPv4 option value in a block
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
319 WS_DLL_PUBLIC wtap_opttype_return_val
320 wtap_block_set_ipv4_option_value(wtap_block_t block, guint option_id, guint32 value);
322 /** Get IPv4 option value from a block
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
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;
333 /** Add IPv6 address option value to a block
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
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);
344 /** Set IPv6 option value in a block
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
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);
355 /** Get IPv6 option value from a block
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
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;
366 /** Add a string option to a block
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
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);
378 /** Add a string option to a block witha printf-formatted string as its value
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
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, ...)
390 /** Set string option value in a block
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
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);
402 /** Set string option value for nth instance of a particular option in a block
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
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);
415 /** Set string option value in a block to a printf-formatted string
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
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, ...)
427 /** Get string option value from a block
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
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;
438 /** Get string option value for nth instance of a particular option in a block
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
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;
450 /** Add a "custom" option value to a block
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
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);
462 /** Set a "custom" option value in a block
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
470 WS_DLL_PUBLIC wtap_opttype_return_val
471 wtap_block_set_custom_option_value(wtap_block_t block, guint option_id, void* value);
473 /** Get a "custom" option value from a block
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
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;
484 /** Remove an option from a block
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
491 WS_DLL_PUBLIC wtap_opttype_return_val
492 wtap_block_remove_option(wtap_block_t block, guint option_id);
494 /** Remove the nth instance of an option from a block
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
502 WS_DLL_PUBLIC wtap_opttype_return_val
503 wtap_block_remove_nth_option_instance(wtap_block_t block, guint option_id,
506 /** Copy a block to another.
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
511 * @param[in] dest_block Block to be copied to
512 * @param[in] src_block Block to be copied from
514 WS_DLL_PUBLIC void wtap_block_copy(wtap_block_t dest_block, wtap_block_t src_block);
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);
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);
525 #endif /* __cplusplus */
527 #endif /* WTAP_OPT_TYPES_H */