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 #ifdef __cplusplus
  28 extern "C" {
  29 #endif /* __cplusplus */
  30
  31 /*
  32  * We use the pcapng option codes for option type values.
  33  */
  34 #define OPT_EOFOPT           0x0000 /**< Appears in pcapng files, but not in option blocks. */
  35 #define OPT_COMMENT          0x0001 /**< NULL if not available */
  36
  37 /* Section Header block (SHB) */
  38 #define OPT_SHB_HARDWARE     0x0002 /**< NULL if not available
  39                                      *     UTF-8 string containing the description of the
  40                                      *     hardware used to create this section.
  41                                      */
  42 #define OPT_SHB_OS           0x0003 /**< NULL if not available, UTF-8 string containing the
  43                                      *     name of the operating system used to create this section.
  44                                      */
  45 #define OPT_SHB_USERAPPL     0x0004 /**< NULL if not available, UTF-8 string containing the
  46                                      *     name of the application used to create this section.
  47                                      */
  48
  49 /* Interface Description block (IDB) */
  50 #define OPT_IDB_NAME         0x0002 /**< NULL if not available, A UTF-8 string containing the name
  51                                      *     of the device used to capture data.
  52                                      *     "eth0" / "\Device\NPF_{AD1CE675-96D0-47C5-ADD0-2504B9126B68}"
  53                                      */
  54 #define OPT_IDB_DESCR        0x0003 /**< NULL if not available, A UTF-8 string containing the description
  55                                      *     of the device used to capture data.
  56                                      *     "Broadcom NetXtreme" / "First Ethernet Interface"
  57                                      */
  58 #define OPT_IDB_IP4ADDR      0x0004 /**< XXX: if_IPv4addr Interface network address and netmask.
  59                                      *     This option can be repeated multiple times within the same Interface Description Block
  60                                      *     when multiple IPv4 addresses are assigned to the interface.
  61                                      *     192 168 1 1 255 255 255 0
  62                                      */
  63 #define OPT_IDB_IP6ADDR      0x0005 /* XXX: if_IPv6addr Interface network address and prefix length (stored in the last byte).
  64                                      *     This option can be repeated multiple times within the same Interface
  65                                      *     Description Block when multiple IPv6 addresses are assigned to the interface.
  66                                      *     2001:0db8:85a3:08d3:1319:8a2e:0370:7344/64 is written (in hex) as
  67                                      *     "20 01 0d b8 85 a3 08 d3 13 19 8a 2e 03 70 73 44 40"*/
  68 #define OPT_IDB_MACADDR      0x0006 /* XXX: if_MACaddr  Interface Hardware MAC address (48 bits).                             */
  69 #define OPT_IDB_EUIADDR      0x0007 /* XXX: if_EUIaddr  Interface Hardware EUI address (64 bits)                              */
  70 #define OPT_IDB_SPEED        0x0008 /**< 0xFFFFFFFF if unknown
  71                                      *     Interface speed (in bps). 100000000 for 100Mbps
  72                                      */
  73 #define OPT_IDB_TSRESOL      0x0009 /**< Resolution of timestamps. If the Most Significant Bit is equal to zero,
  74                                      *     the remaining bits indicates the resolution of the timestamp as as a
  75                                      *     negative power of 10 (e.g. 6 means microsecond resolution, timestamps
  76                                      *     are the number of microseconds since 1/1/1970). If the Most Significant Bit
  77                                      *     is equal to one, the remaining bits indicates the resolution has a
  78                                      *     negative power of 2 (e.g. 10 means 1/1024 of second).
  79                                      *     If this option is not present, a resolution of 10^-6 is assumed
  80                                      *     (i.e. timestamps have the same resolution of the standard 'libpcap' timestamps).
  81                                      */
  82 #define OPT_IDB_TZONE        0x000A /* XXX: if_tzone    Time zone for GMT support (TODO: specify better). */
  83 #define OPT_IDB_FILTER       0x000B /**< The filter (e.g. "capture only TCP traffic") used to capture traffic.
  84                                      *     The first byte of the Option Data keeps a code of the filter used
  85                                      *     (e.g. if this is a libpcap string, or BPF bytecode, and more).
  86                                      *     More details about this format will be presented in Appendix XXX (TODO).
  87                                      *     (TODO: better use different options for different fields?
  88                                      *     e.g. if_filter_pcap, if_filter_bpf, ...) 00 "tcp port 23 and host 10.0.0.5"
  89                                      */
  90 #define OPT_IDB_OS           0x000C /**< NULL if not available, A UTF-8 string containing the name of the operating system of the
  91                                      *     machine in which this interface is installed.
  92                                      *     This can be different from the same information that can be
  93                                      *     contained by the Section Header Block
  94                                      *     (Section 3.1 (Section Header Block (mandatory))) because
  95                                      *     the capture can have been done on a remote machine.
  96                                      *     "Windows XP SP2" / "openSUSE 10.2"
  97                                      */
  98 #define OPT_IDB_FCSLEN       0x000D /**< An integer value that specified the length of the
  99                                      *     Frame Check Sequence (in bits) for this interface.
 100                                      *     For link layers whose FCS length can change during time,
 101                                      *     the Packet Block Flags Word can be used (see Appendix A (Packet Block Flags Word))
 102                                      */
 103 #define OPT_IDB_TSOFFSET     0x000E /**< XXX: A 64 bits integer value that specifies an offset (in seconds)
 104                                      *                     that must be added to the timestamp of each packet to obtain
 105                                      *                     the absolute timestamp of a packet. If the option is missing,
 106                                      *                     the timestamps stored in the packet must be considered absolute
 107                                      *                     timestamps. The time zone of the offset can be specified with the
 108                                      *                     option if_tzone. TODO: won't a if_tsoffset_low for fractional
 109                                      *                     second offsets be useful for highly syncronized capture systems?
 110                                      */
 111
 112 #define OPT_ISB_STARTTIME    0x0002
 113 #define OPT_ISB_ENDTIME      0x0003
 114 #define OPT_ISB_IFRECV       0x0004
 115 #define OPT_ISB_IFDROP       0x0005
 116 #define OPT_ISB_FILTERACCEPT 0x0006
 117 #define OPT_ISB_OSDROP       0x0007
 118 #define OPT_ISB_USRDELIV     0x0008
 119
 120 struct wtap_optionblock;
 121 typedef struct wtap_optionblock *wtap_optionblock_t;
 122
 123 /* Currently supported option blocks */
 124 typedef enum {
 125     WTAP_OPTION_BLOCK_IF_DESCR = 0,
 126     WTAP_OPTION_BLOCK_IF_STATS,
 127     WTAP_OPTION_BLOCK_NG_SECTION,
 128     WTAP_OPTION_BLOCK_NG_NRB,
 129     WTAP_OPTION_BLOCK_END_OF_LIST
 130 } wtap_optionblock_type_t;
 131
 132 /* Currently supported option types */
 133 typedef enum {
 134     WTAP_OPTTYPE_UINT8,
 135     WTAP_OPTTYPE_UINT64,
 136     WTAP_OPTTYPE_STRING,
 137     WTAP_OPTTYPE_CUSTOM
 138 } wtap_opttype_e;
 139
 140 typedef enum {
 141     WTAP_OPTTYPE_SUCCESS = 0,
 142     WTAP_OPTTYPE_NOT_FOUND = -1,
 143     WTAP_OPTTYPE_TYPE_MISMATCH = -2,
 144     WTAP_OPTTYPE_ALREADY_EXISTS = -3
 145 } wtap_opttype_return_val;
 146
 147 typedef void (*wtap_opttype_free_custom_func)(void* data);
 148
 149 struct wtap_opttype_custom
 150 {
 151     void* data;
 152     guint size;
 153     wtap_opttype_free_custom_func free_func;
 154 };
 155
 156 typedef union {
 157     guint8 uint8val;
 158     guint64 uint64val;
 159     char *stringval;
 160     struct wtap_opttype_custom customval;
 161 } wtap_option_type;
 162
 163 struct wtap_dumper;
 164
 165 typedef void (*wtap_block_create_func)(wtap_optionblock_t block);
 166 typedef void (*wtap_mand_free_func)(wtap_optionblock_t block);
 167 typedef void (*wtap_mand_copy_func)(wtap_optionblock_t dest_block, wtap_optionblock_t src_block);
 168
 169 typedef struct wtap_optblock_reg {
 170     const char *name;                /**< name of option */
 171     const char *description;         /**< human-readable description of option */
 172     wtap_opttype_e type;             /**< type of that option */
 173     wtap_option_type option;         /**< pointer to variable storing the value */
 174     wtap_option_type default_val;    /**< the default value of the option */
 175 } wtap_optblock_reg_t;
 176
 177 /** Initialize option block types.
 178  *
 179  * This is currently just a placeholder as nothing needs to be
 180  * initialized yet.  Should handle "registration" when code is
 181  * refactored to do so.
 182  */
 183 void wtap_opttypes_initialize(void);
 184
 185 /** Create an option block by type
 186  *
 187  * Return a newly allocated option block with default options provided
 188  *
 189  * @param[in] block_type Option block type to be created
 190  * @return Newly allocated option block
 191  */
 192 WS_DLL_PUBLIC wtap_optionblock_t wtap_optionblock_create(int block_type);
 193
 194 /** Free an option block
 195  *
 196  * Needs to be called to clean up any allocated option block
 197  *
 198  * @param[in] block Block to be freed
 199  */
 200 WS_DLL_PUBLIC void wtap_optionblock_free(wtap_optionblock_t block);
 201
 202 /** Free an array of option blocks
 203  *
 204  * Needs to be called to clean up option blocks allocated
 205  * through GArray (for multiple blocks of same type)
 206  * Includes freeing the GArray
 207  *
 208  * @param[in] block_array Array of blocks to be freed
 209  */
 210 WS_DLL_PUBLIC void wtap_optionblock_array_free(GArray* block_array);
 211
 212 /** Provide mandatory data of an option block
 213  *
 214  * @param[in] block Block from which to retrieve mandatory data
 215  * @return Option block mandatory data.  Structure varies based on option block type
 216  */
 217 WS_DLL_PUBLIC void* wtap_optionblock_get_mandatory_data(wtap_optionblock_t block);
 218
 219 /** Add an option to the option block
 220  *
 221  * @param[in] block Block to which to add option
 222  * @param[in] option_id Identifier value for option
 223  * @param[in] option structure explaining it
 224  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 225  * error code otherwise
 226  */
 227 WS_DLL_PUBLIC wtap_opttype_return_val
 228 wtap_optionblock_add_option(wtap_optionblock_t block, guint option_id, wtap_optblock_reg_t* option);
 229
 230 /** Set string option value in an option block
 231  *
 232  * @param[in] block Block in which to set the option value
 233  * @param[in] option_id Identifier value for option
 234  * @param[in] value New value of option
 235  * @param[in] value_length Maximum length of string to copy.
 236  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 237  * error code otherwise
 238  */
 239 WS_DLL_PUBLIC wtap_opttype_return_val
 240 wtap_optionblock_set_option_string(wtap_optionblock_t block, guint option_id, char* value, gsize value_length);
 241
 242 /** Set string option value in an option block to a printf-formatted string
 243  *
 244  * @param[in] block Block in which to set the option value
 245  * @param[in] option_id Identifier value for option
 246  * @param[in] format printf-like format string
 247  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 248  * error code otherwise
 249  */
 250 WS_DLL_PUBLIC wtap_opttype_return_val
 251 wtap_optionblock_set_option_string_format(wtap_optionblock_t block, guint option_id, const char *format, ...)
 252                                           G_GNUC_PRINTF(3,4);
 253
 254 /** Get string option value from an option block
 255  *
 256  * @param[in] block Block from which to get the option value
 257  * @param[in] option_id Identifier value for option
 258  * @param[out] value Returned value of option
 259  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 260  * error code otherwise
 261  */
 262 WS_DLL_PUBLIC wtap_opttype_return_val
 263 wtap_optionblock_get_option_string(wtap_optionblock_t block, guint option_id, char** value);
 264
 265 /** Get array of string option values from an option block
 266  *
 267  * @param[in] block Block from which to get option values
 268  * @param[in] option_id Identifier value for option
 269  * @param[out] value Returned GArray of option values
 270  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 271  * error code otherwise
 272  */
 273 WS_DLL_PUBLIC wtap_opttype_return_val
 274 wtap_optionblock_get_string_options(wtap_optionblock_t block, guint option_id, GArray **value);
 275
 276 /** Set UINT64 option value in an option block
 277  *
 278  * @param[in] block Block in which to set the option value
 279  * @param[in] option_id Identifier value for option
 280  * @param[in] value New value of option
 281  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 282  * error code otherwise
 283  */
 284 WS_DLL_PUBLIC wtap_opttype_return_val
 285 wtap_optionblock_set_option_uint64(wtap_optionblock_t block, guint option_id, guint64 value);
 286
 287 /** Get UINT64 option value from an option block
 288  *
 289  * @param[in] block Block from which to get the option value
 290  * @param[in] option_id Identifier value for option
 291  * @param[out] value Returned value of option
 292  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 293  * error code otherwise
 294  */
 295 WS_DLL_PUBLIC wtap_opttype_return_val
 296 wtap_optionblock_get_option_uint64(wtap_optionblock_t block, guint option_id, guint64* value);
 297
 298 /** Set UINT8 option value in an option block
 299  *
 300  * @param[in] block Block in which to set the option value
 301  * @param[in] option_id Identifier value for option
 302  * @param[in] value New value of option
 303  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 304  * error code otherwise
 305  */
 306 WS_DLL_PUBLIC wtap_opttype_return_val
 307 wtap_optionblock_set_option_uint8(wtap_optionblock_t block, guint option_id, guint8 value);
 308
 309 /** Get UINT8 option value from an option block
 310  *
 311  * @param[in] block Block from which to get the option value
 312  * @param[in] option_id Identifier value for option
 313  * @param[out] value Returned value of option
 314  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 315  * error code otherwise
 316  */
 317 WS_DLL_PUBLIC wtap_opttype_return_val
 318 wtap_optionblock_get_option_uint8(wtap_optionblock_t block, guint option_id, guint8* value);
 319
 320 /** Set a "custom" option value in an option block
 321  *
 322  * @param[in] block Block in which to set the option value
 323  * @param[in] option_id Identifier value for option
 324  * @param[in] value New value of option
 325  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 326  * error code otherwise
 327  */
 328 WS_DLL_PUBLIC wtap_opttype_return_val
 329 wtap_optionblock_set_option_custom(wtap_optionblock_t block, guint option_id, void* value);
 330
 331 /** Get a "custom" option value from an option block
 332  *
 333  * @param[in] block Block from which to get the option value
 334  * @param[in] option_id Identifier value for option
 335  * @param[out] value Returned value of option
 336  * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful,
 337  * error code otherwise
 338  */
 339 WS_DLL_PUBLIC wtap_opttype_return_val
 340 wtap_optionblock_get_option_custom(wtap_optionblock_t block, guint option_id, void** value);
 341
 342 /** Copy an option block to another.
 343  *
 344  * Any options that are in the destination but not the source are not removed.
 345  * Options that are just in source will be added to destination
 346  *
 347  * @param[in] dest_block Block to be copied to
 348  * @param[in] src_block Block to be copied from
 349  */
 350 void wtap_optionblock_copy_options(wtap_optionblock_t dest_block, wtap_optionblock_t src_block);
 351
 352
 353 typedef void (*wtap_optionblock_foreach_func)(wtap_optionblock_t block, guint option_id, wtap_opttype_e option_type, wtap_option_type* option, void* user_data);
 354 WS_DLL_PUBLIC void wtap_optionblock_foreach_option(wtap_optionblock_t block, wtap_optionblock_foreach_func func, void* user_data);
 355
 356 WS_DLL_PUBLIC int wtap_opttype_register_custom_block_type(const char* name, const char* description, wtap_block_create_func create,
 357                                                 wtap_mand_free_func free_mand, wtap_mand_copy_func copy_mand);
 358
 359 #ifdef __cplusplus
 360 }
 361 #endif /* __cplusplus */
 362
 363 #endif /* WTAP_OPT_TYPES_H */
 364