epan/follow.h

   1 /** @file
   2  *
   3  * Copyright 1998 Mike Hall <mlh@io.com>
   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
  13 #ifndef __FOLLOW_H__
  14 #define __FOLLOW_H__
  15
  16 #include <epan/epan.h>
  17 #include <epan/packet.h>
  18 #include <wsutil/inet_cidr.h>
  19 #include <epan/tap.h>
  20 #include <epan/wmem_scopes.h>
  21 #include "ws_symbol_export.h"
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif /* __cplusplus */
  26
  27 /* Show Stream */
  28 typedef enum {
  29     FROM_CLIENT,
  30     FROM_SERVER,
  31     BOTH_HOSTS
  32 } show_stream_t;
  33
  34 typedef union _stream_addr {
  35   uint32_t ipv4;
  36   ws_in6_addr ipv6;
  37 } stream_addr;
  38
  39 struct _follow_info;
  40
  41 #define SUBSTREAM_UNUSED        UINT64_C(0xFFFFFFFFFFFFFFFF)
  42
  43 typedef struct {
  44     bool is_server;
  45     uint32_t packet_num;
  46     uint32_t seq; /* TCP only */
  47     nstime_t abs_ts; /**< Packet absolute time stamp */
  48     GByteArray *data;
  49 } follow_record_t;
  50
  51 typedef struct _follow_info {
  52     show_stream_t   show_stream;
  53     char            *filter_out_filter;
  54     GList           *payload;   /* "follow_record_t" entries, in reverse order. */
  55     unsigned        bytes_written[2]; /* Index with FROM_CLIENT or FROM_SERVER for readability. */
  56     uint32_t        seq[2]; /* TCP only */
  57     GList           *fragments[2]; /* TCP only */
  58     unsigned        client_port;
  59     unsigned        server_port;
  60     address         client_ip;
  61     address         server_ip;
  62     void*           gui_data;
  63     uint64_t        substream_id;  /**< Sub-stream; used only by HTTP2 and QUIC */
  64 } follow_info_t;
  65
  66 struct register_follow;
  67 typedef struct register_follow register_follow_t;
  68
  69 typedef char* (*follow_conv_filter_func)(epan_dissect_t *edt, packet_info *pinfo, unsigned *stream, unsigned *sub_stream);
  70 typedef char* (*follow_index_filter_func)(unsigned stream, unsigned sub_stream);
  71 typedef char* (*follow_address_filter_func)(address* src_addr, address* dst_addr, int src_port, int dst_port);
  72 typedef char* (*follow_port_to_display_func)(wmem_allocator_t *allocator, unsigned port);
  73 typedef uint32_t (*follow_stream_count_func)(void);
  74 typedef bool (*follow_sub_stream_id_func)(unsigned stream, unsigned sub_stream, bool le, unsigned *sub_stream_out);
  75
  76 WS_DLL_PUBLIC
  77 void register_follow_stream(const int proto_id, const char* tap_listener,
  78                             follow_conv_filter_func conv_filter, follow_index_filter_func index_filter, follow_address_filter_func address_filter,
  79                             follow_port_to_display_func port_to_display, tap_packet_cb tap_handler,
  80                             follow_stream_count_func stream_count, follow_sub_stream_id_func sub_stream_id);
  81
  82 /** Get protocol ID from registered follower
  83  *
  84  * @param follower Registered follower
  85  * @return protocol id of follower
  86  */
  87 WS_DLL_PUBLIC int get_follow_proto_id(register_follow_t* follower);
  88
  89 /** Get tap name string from registered follower (used for register_tap_listener)
  90  *
  91  * @param follower Registered follower
  92  * @return tap name string of follower
  93  */
  94 WS_DLL_PUBLIC const char* get_follow_tap_string(register_follow_t* follower);
  95
  96 /** Get a registered follower by protocol short name
  97  *
  98  * @param proto_short_name Protocol short name
  99  * @return tap registered follower if match, otherwise NULL
 100  */
 101 WS_DLL_PUBLIC register_follow_t* get_follow_by_name(const char* proto_short_name);
 102
 103 /** Get a registered follower by protocol id
 104  *
 105  * @param proto_id Protocol Id
 106  * @return tap registered follower if match, otherwise NULL
 107  */
 108 WS_DLL_PUBLIC register_follow_t* get_follow_by_proto_id(const int proto_id);
 109
 110 /** Provide function that builds a follow filter based on the current packet's conversation.
 111  *
 112  * @param follower [in] Registered follower
 113  * @return A filter function handler
 114  */
 115 WS_DLL_PUBLIC follow_conv_filter_func get_follow_conv_func(register_follow_t* follower);
 116
 117 /** Provide function that builds a follow filter based on stream.
 118  *
 119  * @param follower [in] Registered follower
 120  * @return A filter function handler
 121  */
 122 WS_DLL_PUBLIC follow_index_filter_func get_follow_index_func(register_follow_t* follower);
 123
 124 /** Provide function that builds a follow filter based on address/port pairs.
 125  *
 126  * @param follower [in] Registered follower
 127  * @return A filter function handler
 128  */
 129 WS_DLL_PUBLIC follow_address_filter_func get_follow_address_func(register_follow_t* follower);
 130
 131 /** Provide function that resolves port number to name based on follower.
 132  *
 133  * @param follower [in] Registered follower
 134  * @return A port resolver function handler
 135  */
 136 WS_DLL_PUBLIC follow_port_to_display_func get_follow_port_to_display(register_follow_t* follower);
 137
 138 /** Provide function that handles tap data (tap_packet_cb parameter of register_tap_listener)
 139  *
 140  * @param follower [in] Registered follower
 141  * @return A tap packet handler
 142  */
 143 WS_DLL_PUBLIC tap_packet_cb get_follow_tap_handler(register_follow_t* follower);
 144
 145 /** Provide function that gets the total number of streams for a registered follower
 146  * The function can be NULL if the follower does not count the number of streams
 147  *
 148  * @param follower [in] Registered follower
 149  * @return A stream count handler
 150  */
 151 WS_DLL_PUBLIC follow_stream_count_func get_follow_stream_count_func(register_follow_t* follower);
 152
 153 /** Provide function that, for given stream and sub stream ids, searches for
 154  * the first sub stream id less than or equal (or greater than or equal) the
 155  * given sub stream id present on the given stream id. Returns true and the
 156  * sub stream id found, or false.
 157  * This is used by the GUI to select valid sub stream numbers, e.g. when
 158  * incrementing or decrementing the sub stream ID widget.
 159  * This function should be NULL if the follower does not have sub streams.
 160  *
 161  * @param follower [in] Registered follower
 162  * @return A sub stream id function handler
 163  */
 164 WS_DLL_PUBLIC follow_sub_stream_id_func get_follow_sub_stream_id_func(register_follow_t* follower);
 165
 166 /** Tap function handler when dissector's tap provides follow data as a tvb.
 167  * Used by TCP, UDP and HTTP followers
 168  */
 169 WS_DLL_PUBLIC tap_packet_status
 170 follow_tvb_tap_listener(void *tapdata, packet_info *pinfo, epan_dissect_t *edt _U_, const void *data, tap_flags_t flags);
 171
 172 /** Interator to walk all registered followers and execute func
 173  *
 174  * @param func action to be performed on all conversation tables
 175  * @param user_data any data needed to help perform function
 176  */
 177 WS_DLL_PUBLIC void follow_iterate_followers(wmem_foreach_func func, void *user_data);
 178
 179 /** Generate -z stat (tap) name for a follower
 180  * Currently used only by TShark
 181  *
 182  * @param follower [in] Registered follower
 183  * @return A tap data handler
 184  */
 185 WS_DLL_PUBLIC char* follow_get_stat_tap_string(register_follow_t* follower);
 186
 187 /** Clear payload, fragments, counters, addresses, and ports of follow_info_t
 188  * for retapping. (Does not clear substream_id, which is used for selecting
 189  * which tvbs are tapped.)
 190  * Free everything except the GUI element and the follow_info_t structure
 191  * itself
 192  *
 193  * @param info [in] follower info
 194  */
 195 WS_DLL_PUBLIC void follow_reset_stream(follow_info_t* info);
 196
 197 /** Free follow_info_t structure
 198  * Free everything except the GUI element
 199  *
 200  * @param follow_info [in] follower info
 201  */
 202 WS_DLL_PUBLIC void follow_info_free(follow_info_t* follow_info);
 203
 204 #ifdef __cplusplus
 205 }
 206 #endif /* __cplusplus */
 207
 208 #endif