epan/conversation_table.h

   1 /* conversation_table.h
   2  * GUI independent helper routines common to all conversations taps.
   3  * Refactored original conversations_table by Ronnie Sahlberg
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __CONVERSATION_TABLE_H__
  13 #define __CONVERSATION_TABLE_H__
  14
  15 #include "conv_id.h"
  16 #include "tap.h"
  17 #include "conversation.h"
  18 #include <epan/wmem_scopes.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif /* __cplusplus */
  23
  24 /** @file
  25  *  Conversation definitions.
  26  */
  27
  28 typedef enum {
  29     CONV_FT_SRC_ADDRESS,
  30     CONV_FT_DST_ADDRESS,
  31     CONV_FT_ANY_ADDRESS,
  32     CONV_FT_SRC_PORT,
  33     CONV_FT_DST_PORT,
  34     CONV_FT_ANY_PORT
  35 } conv_filter_type_e;
  36
  37 /* Filter direction */
  38 typedef enum {
  39     CONV_DIR_A_TO_FROM_B,
  40     CONV_DIR_A_TO_B,
  41     CONV_DIR_A_FROM_B,
  42     CONV_DIR_A_TO_FROM_ANY,
  43     CONV_DIR_A_TO_ANY,
  44     CONV_DIR_A_FROM_ANY,
  45     CONV_DIR_ANY_TO_FROM_B,
  46     CONV_DIR_ANY_TO_B,
  47     CONV_DIR_ANY_FROM_B
  48 } conv_direction_e;
  49
  50 /** Conversation hash + value storage
  51  * Hash table keys are conv_key_t. Hash table values are indexes into conv_array.
  52  */
  53 typedef struct _conversation_hash_t {
  54     GHashTable  *hashtable;       /**< conversations hash table */
  55     GArray      *conv_array;      /**< array of conversation values */
  56     void        *user_data;       /**< "GUI" specifics (if necessary) */
  57     unsigned    flags;            /**< flags given to the tap packet */
  58 } conv_hash_t;
  59
  60 /** Key for hash lookups */
  61 typedef struct _conversation_key_t {
  62     address     addr1;
  63     address     addr2;
  64     uint32_t    port1;
  65     uint32_t    port2;
  66     conv_id_t   conv_id;
  67 } conv_key_t;
  68
  69 typedef struct {
  70     address  myaddress;
  71     uint32_t port;
  72 } endpoint_key_t;
  73
  74 /*
  75  * For backwards source compatibility.
  76  * Yes, G_DEPRECATED_FOR() has to be at the beginning, so that this
  77  * works with MSVC.
  78  */
  79 G_DEPRECATED_FOR(endpoint_key_t)
  80 typedef endpoint_key_t host_key_t;
  81
  82 struct _conversation_item_t;
  83 typedef const char* (*conv_get_filter_type)(struct _conversation_item_t* item, conv_filter_type_e filter);
  84
  85 typedef struct _ct_dissector_info {
  86     conv_get_filter_type get_filter_type;
  87 } ct_dissector_info_t;
  88
  89 struct _endpoint_item_t;
  90 typedef const char* (*endpoint_get_filter_type)(struct _endpoint_item_t* item, conv_filter_type_e filter_type);
  91
  92 typedef struct _et_dissector_info {
  93     endpoint_get_filter_type get_filter_type;
  94 } et_dissector_info_t;
  95
  96 /* For backwards source compatibiity */
  97 G_DEPRECATED_FOR(et_dissector_info_t)
  98 typedef et_dissector_info_t hostlist_dissector_info_t;
  99
 100 #define CONV_FILTER_INVALID "INVALID"
 101
 102
 103 struct register_ct;
 104 typedef void (*conv_gui_init_cb)(struct register_ct* ct, const char *filter);
 105
 106 typedef void (*endpoint_gui_init_cb)(struct register_ct* ct, const char *filter);
 107
 108 /**
 109  * Structure for information about a registered conversation table;
 110  * this information is for both the conversation table and any
 111  * endpoint table associated with it.
 112  */
 113 typedef struct register_ct register_ct_t;
 114
 115 /** Conversation extension for TCP */
 116 typedef struct _conversation_extension_tcp_t {
 117     uint64_t            flows;          /**< number of flows */
 118 } conv_extension_tcp_t;
 119
 120 /** Conversation list information */
 121 typedef struct _conversation_item_t {
 122     ct_dissector_info_t *dissector_info; /**< conversation information provided by dissector */
 123     address             src_address;    /**< source address */
 124     address             dst_address;    /**< destination address */
 125     conversation_type   ctype;          /**< conversation key_type (e.g. CONVERSATION_TCP) */
 126     uint32_t            src_port;       /**< source port */
 127     uint32_t            dst_port;       /**< destination port */
 128     conv_id_t           conv_id;        /**< conversation id */
 129
 130     uint64_t            rx_frames;      /**< number of received packets */
 131     uint64_t            tx_frames;      /**< number of transmitted packets */
 132     uint64_t            rx_bytes;       /**< number of received bytes */
 133     uint64_t            tx_bytes;       /**< number of transmitted bytes */
 134
 135     uint64_t            rx_frames_total;      /**< number of received packets total */
 136     uint64_t            tx_frames_total;      /**< number of transmitted packets total */
 137     uint64_t            rx_bytes_total;       /**< number of received bytes total */
 138     uint64_t            tx_bytes_total;       /**< number of transmitted bytes total */
 139
 140     nstime_t            start_time;     /**< relative start time for the conversation */
 141     nstime_t            stop_time;      /**< relative stop time for the conversation */
 142     nstime_t            start_abs_time; /**< absolute start time for the conversation */
 143
 144     bool filtered;                  /**< the entry contains only filtered data */
 145
 146     conv_extension_tcp_t ext_tcp;      /**< extension for optional TCP counters */
 147 } conv_item_t;
 148
 149 /** Endpoint information */
 150 typedef struct _endpoint_item_t {
 151     et_dissector_info_t *dissector_info; /**< endpoint information provided by dissector */
 152     address myaddress;      /**< address */
 153     endpoint_type etype;    /**< endpoint_type (e.g. ENDPOINT_TCP) */
 154     uint32_t port;           /**< port */
 155
 156     uint64_t rx_frames;      /**< number of received packets */
 157     uint64_t tx_frames;      /**< number of transmitted packets */
 158     uint64_t rx_bytes;       /**< number of received bytes */
 159     uint64_t tx_bytes;       /**< number of transmitted bytes */
 160
 161     uint64_t rx_frames_total;      /**< number of received packets total */
 162     uint64_t tx_frames_total;      /**< number of transmitted packets total */
 163     uint64_t rx_bytes_total;       /**< number of received bytes total */
 164     uint64_t tx_bytes_total;       /**< number of transmitted bytes total */
 165
 166     bool modified;      /**< new to redraw the row */
 167     bool filtered;      /**< the entry contains only filtered data */
 168
 169 } endpoint_item_t;
 170
 171 /* For backwards source compatibility */
 172 G_DEPRECATED_FOR(endpoint_item_t)
 173 typedef endpoint_item_t hostlist_talker_t;
 174
 175 #define ENDPOINT_TAP_PREFIX     "endpoints"
 176
 177 /** Register the conversation table for the conversation and endpoint windows.
 178  *
 179  * @param proto_id is the protocol with conversation
 180  * @param hide_ports hide the port columns
 181  * @param conv_packet_func the registered conversation tap name
 182  * @param endpoint_packet_func the registered endpoint tap name
 183  */
 184 WS_DLL_PUBLIC void register_conversation_table(const int proto_id, bool hide_ports, tap_packet_cb conv_packet_func, tap_packet_cb endpoint_packet_func);
 185
 186 /** Should port columns be hidden?
 187  *
 188  * @param ct Registered conversation table
 189  * @return true if port columns should be hidden for this conversation table.
 190  */
 191 WS_DLL_PUBLIC bool get_conversation_hide_ports(register_ct_t* ct);
 192
 193 /** Get protocol ID of a conversation table
 194  *
 195  * @param ct Registered conversation table
 196  * @return protocol id of conversation table
 197  */
 198 WS_DLL_PUBLIC int get_conversation_proto_id(register_ct_t* ct);
 199
 200 /** Get conversation tap function handler of a conversation table
 201  *
 202  * @param ct Registered conversation table
 203  * @return conversation tap function handler of conversation table
 204  */
 205 WS_DLL_PUBLIC tap_packet_cb get_conversation_packet_func(register_ct_t* ct);
 206
 207 /** Get endpoint tap function handler for a conversation table
 208  *
 209  * @param ct Registered conversation table
 210  * @return endpoint tap function handler of conversation table
 211  */
 212 WS_DLL_PUBLIC tap_packet_cb get_endpoint_packet_func(register_ct_t* ct);
 213
 214 /* For backwards source and binary compatibility */
 215 G_DEPRECATED_FOR(get_endpoint_packet_func)
 216 WS_DLL_PUBLIC tap_packet_cb get_hostlist_packet_func(register_ct_t* ct);
 217
 218
 219 /** get conversation table from protocol ID
 220  *
 221  * @param proto_id protocol ID
 222  * @return conversation table for that protocol ID
 223  */
 224 WS_DLL_PUBLIC register_ct_t* get_conversation_by_proto_id(int proto_id);
 225
 226 /** Register "initialization function" used by the GUI to create conversation
 227  * table display in GUI
 228  *
 229  * @param init_cb callback function that will be called when conversation table "display
 230  * is instantiated in GUI
 231  */
 232 WS_DLL_PUBLIC void conversation_table_set_gui_info(conv_gui_init_cb init_cb);
 233
 234 /** Register "initialization function" used by the GUI to create endpoint
 235  * table display in GUI
 236  *
 237  * @param init_cb callback function that will be called when endpoint table "display"
 238  * is instantiated in GUI
 239  */
 240 WS_DLL_PUBLIC void endpoint_table_set_gui_info(endpoint_gui_init_cb init_cb);
 241
 242 /* For backwards source and binary compatibility */
 243 G_DEPRECATED_FOR(endpoint_table_set_gui_info)
 244 WS_DLL_PUBLIC void hostlist_table_set_gui_info(endpoint_gui_init_cb init_cb);
 245
 246 /** Iterator to walk conversation tables and execute func
 247  *
 248  * @param func action to be performed on all conversation tables
 249  * @param user_data any data needed to help perform function
 250  */
 251 WS_DLL_PUBLIC void conversation_table_iterate_tables(wmem_foreach_func func, void* user_data);
 252
 253 /** Total number of conversation tables
 254  */
 255 WS_DLL_PUBLIC unsigned conversation_table_get_num(void);
 256
 257 /** Remove all entries from the conversation table.
 258  *
 259  * @param ch the table to reset
 260  */
 261 WS_DLL_PUBLIC void reset_conversation_table_data(conv_hash_t *ch);
 262
 263 /** Remove all entries from the endpoint table.
 264  *
 265  * @param ch the table to reset
 266  */
 267 WS_DLL_PUBLIC void reset_endpoint_table_data(conv_hash_t *ch);
 268
 269 /* For backwards source and binary compatibility */
 270 G_DEPRECATED_FOR(reset_endpoint_table_data)
 271 WS_DLL_PUBLIC void reset_hostlist_table_data(conv_hash_t *ch);
 272
 273 /** Initialize dissector conversation for stats and (possibly) GUI.
 274  *
 275  * @param opt_arg filter string to compare with dissector
 276  * @param userdata register_ct_t* for dissector conversation table
 277  */
 278 WS_DLL_PUBLIC void dissector_conversation_init(const char *opt_arg, void* userdata);
 279
 280 /** Initialize dissector endpoint for stats and (possibly) GUI.
 281  *
 282  * @param opt_arg filter string to compare with dissector
 283  * @param userdata register_ct_t* for dissector conversation table
 284  */
 285 WS_DLL_PUBLIC void dissector_endpoint_init(const char *opt_arg, void* userdata);
 286
 287 /* For backwards source and binary compatibility */
 288 G_DEPRECATED_FOR(dissector_endpoint_init)
 289 WS_DLL_PUBLIC void dissector_hostlist_init(const char *opt_arg, void* userdata);
 290
 291 /** Get the string representation of an address.
 292  *
 293  * @param allocator The wmem allocator to use when allocating the string
 294  * @param addr The address.
 295  * @param resolve_names Enable name resolution.
 296  * @return A string representing the address.
 297  */
 298 WS_DLL_PUBLIC char *get_conversation_address(wmem_allocator_t *allocator, address *addr, bool resolve_names);
 299
 300 /** Get the string representation of a port.
 301  *
 302  * @param allocator The wmem allocator to use when allocating the string
 303  * @param port The port number.
 304  * @param ctype The conversation type.
 305  * @param resolve_names Enable name resolution.
 306  * @return A string representing the port.
 307  *
 308  * XXX - this should really be a *port* type, as we just supply a port.
 309  */
 310 WS_DLL_PUBLIC char *get_conversation_port(wmem_allocator_t *allocator, uint32_t port, conversation_type ctype, bool resolve_names);
 311
 312 /** Get the string representation of the port for an endpoint_item_t.
 313  *
 314  * @param allocator The wmem allocator to use when allocating the string
 315  *
 316  * @param item Pointer to the endpoint_item_t
 317  * @param resolve_names Enable name resolution.
 318  * @return A string representing the port.
 319  *
 320  * XXX - this should really be a *port* type, as we just supply a port.
 321  */
 322 WS_DLL_PUBLIC char *get_endpoint_port(wmem_allocator_t *allocator, endpoint_item_t *item, bool resolve_names);
 323
 324 /** Get a display filter for the given conversation and direction.
 325  *
 326  * @param conv_item The conversation.
 327  * @param direction The desired direction.
 328  * @return An g_allocated string representing the conversation that must be freed
 329  */
 330 WS_DLL_PUBLIC char *get_conversation_filter(conv_item_t *conv_item, conv_direction_e direction);
 331
 332 /** Get a display filter for the given endpoint.
 333  *
 334  * @param endpoint_item The endpoint.
 335  * @return A string, allocated using the wmem NULL allocator,
 336  * representing the conversation.
 337  */
 338 WS_DLL_PUBLIC char *get_endpoint_filter(endpoint_item_t *endpoint_item);
 339
 340 /* For backwards source and binary compatibility */
 341 G_DEPRECATED_FOR(get_endpoint_filter)
 342 WS_DLL_PUBLIC char *get_hostlist_filter(endpoint_item_t *endpoint_item);
 343
 344 /** Add some data to the conversation table.
 345  *
 346  * @param ch the table to add the data to
 347  * @param src source address
 348  * @param dst destination address
 349  * @param src_port source port
 350  * @param dst_port destination port
 351  * @param num_frames number of packets
 352  * @param num_bytes number of bytes
 353  * @param ts timestamp
 354  * @param abs_ts absolute timestamp
 355  * @param ct_info callback handlers from the dissector
 356  * @param ctype the conversation type (e.g. CONVERSATION_TCP)
 357  */
 358 WS_DLL_PUBLIC void add_conversation_table_data(conv_hash_t *ch, const address *src, const address *dst,
 359     uint32_t src_port, uint32_t dst_port, int num_frames, int num_bytes, nstime_t *ts, nstime_t *abs_ts,
 360     ct_dissector_info_t *ct_info, conversation_type ctype);
 361
 362 /** Add some data to the conversation table, passing a value to be used in
 363  *  addition to the address and port quadruple to uniquely identify the
 364  *  conversation.
 365  *
 366  * @param ch the table to add the data to
 367  * @param src source address
 368  * @param dst destination address
 369  * @param src_port source port
 370  * @param dst_port destination port
 371  * @param num_frames number of packets
 372  * @param num_bytes number of bytes
 373  * @param ts timestamp
 374  * @param abs_ts absolute timestamp
 375  * @param ct_info callback handlers from the dissector
 376  * @param ctype the conversation type (e.g. CONVERSATION_TCP)
 377  * @param conv_id a value to help differentiate the conversation in case the address and port quadruple is not sufficiently unique
 378  */
 379 WS_DLL_PUBLIC conv_item_t *
 380 add_conversation_table_data_with_conv_id(conv_hash_t *ch, const address *src, const address *dst, uint32_t src_port,
 381     uint32_t dst_port, conv_id_t conv_id, int num_frames, int num_bytes,
 382     nstime_t *ts, nstime_t *abs_ts, ct_dissector_info_t *ct_info,
 383     conversation_type ctype);
 384
 385 /** Decorates add_conversation_table_data_with_conv_id() in order to be
 386  *  able to add protocol dependent additional statistics.
 387  *
 388  */
 389 WS_DLL_PUBLIC void
 390 add_conversation_table_data_extended(conv_hash_t *ch, const address *src, const address *dst, uint32_t src_port,
 391     uint32_t dst_port, conv_id_t conv_id, int num_frames, int num_bytes,
 392     nstime_t *ts, nstime_t *abs_ts, ct_dissector_info_t *ct_info,
 393     conversation_type ctype, uint32_t frameid, int (*proto_conv_cb)(conversation_t *));
 394
 395 /** Encapsulates add_conversation_table_data_with_conv_id() for the IPv4 specific case
 396  *  when the subnet aggregation user preference is true.
 397  *
 398  */
 399 WS_DLL_PUBLIC void
 400 add_conversation_table_data_ipv4_subnet(conv_hash_t *ch, const address *src, const address *dst, uint32_t src_port,
 401     uint32_t dst_port, conv_id_t conv_id, int num_frames, int num_bytes,
 402     nstime_t *ts, nstime_t *abs_ts, ct_dissector_info_t *ct_info,
 403     conversation_type ctype);
 404
 405 /** Add some data to the endpoint table.
 406  *
 407  * @param ch the table hash to add the data to
 408  * @param addr address
 409  * @param port port
 410  * @param sender true, if this is a sender
 411  * @param num_frames number of packets
 412  * @param num_bytes number of bytes
 413  * @param et_info endpoint information provided by dissector
 414  * @param etype the endpoint type (e.g. ENDPOINT_TCP)
 415  */
 416 WS_DLL_PUBLIC void add_endpoint_table_data(conv_hash_t *ch, const address *addr,
 417     uint32_t port, bool sender, int num_frames, int num_bytes, et_dissector_info_t *et_info, endpoint_type etype);
 418
 419 /** Encapsulates add_endpoint_table_data() for the IPv4 specific case
 420  *  when the subnet aggregation user preference is true.
 421  *
 422  */
 423 WS_DLL_PUBLIC void add_endpoint_table_data_ipv4_subnet(conv_hash_t *ch, const address *addr,
 424     uint32_t port, bool sender, int num_frames, int num_bytes, et_dissector_info_t *et_info, endpoint_type etype);
 425
 426 /* For backwards source and binary compatibility */
 427 G_DEPRECATED_FOR(add_endpoint_table_data)
 428 WS_DLL_PUBLIC void add_hostlist_table_data(conv_hash_t *ch, const address *addr,
 429     uint32_t port, bool sender, int num_frames, int num_bytes, et_dissector_info_t *et_info, endpoint_type etype);
 430
 431 #ifdef __cplusplus
 432 }
 433 #endif /* __cplusplus */
 434
 435 #endif /* __CONVERSATION_TABLE_H__ */
 436
 437 /*
 438  * Editor modelines
 439  *
 440  * Local Variables:
 441  * c-basic-offset: 4
 442  * tab-width: 8
 443  * indent-tabs-mode: nil
 444  * End:
 445  *
 446  * ex: set shiftwidth=4 tabstop=8 expandtab:
 447  * :indentSize=4:tabSize=8:noTabs=true:
 448  */