epan/conversation.h

   1 /* conversation.h
   2  * Routines for building lists of packets that are part of a "conversation"
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11 #ifndef __CONVERSATION_H__
  12 #define __CONVERSATION_H__
  13
  14 #include "ws_symbol_export.h"
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif /* __cplusplus */
  19
  20 /**
  21  *@file
  22  */
  23 /*
  24  * Flags to pass to "conversation_new()" to indicate that the address 2
  25  * and/or port 2 values for the conversation should be wildcards.
  26  * The CONVERSATION_TEMPLATE option tells that any of the other supplied
  27  * port and / or address wildcards will be used to match an infinite number
  28  * of new connections to the conversation(s) that have the CONVERSATION_-
  29  * TEMPLATE flag set. Any conversation created without the CONVERSATION_-
  30  * TEMPLATE flag will be altered once the first connections (connection
  31  * oriented protocols only) to include the newly found information which
  32  * matched the wildcard options.
  33  */
  34 #define NO_ADDR2 0x01
  35 #define NO_PORT2 0x02
  36 #define NO_PORT2_FORCE 0x04
  37 #define CONVERSATION_TEMPLATE 0x08
  38
  39 /*
  40  * Flags to pass to "find_conversation()" to indicate that the address B
  41  * and/or port B search arguments are wildcards.
  42  */
  43 #define NO_ADDR_B 0x01
  44 #define NO_PORT_B 0x02
  45
  46 /* Flags to handle endpoints */
  47 #define USE_LAST_ENDPOINT 0x08      /* Use last endpoint created, regardless of type */
  48
  49 #include "packet.h"             /* for conversation dissector type */
  50
  51 /* Types of port numbers Wireshark knows about. */
  52 typedef enum {
  53         ENDPOINT_NONE,                  /* no endpoint */
  54         ENDPOINT_SCTP,                  /* SCTP */
  55         ENDPOINT_TCP,                   /* TCP */
  56         ENDPOINT_UDP,                   /* UDP */
  57         ENDPOINT_DCCP,                  /* DCCP */
  58         ENDPOINT_IPX,                   /* IPX sockets */
  59         ENDPOINT_NCP,                   /* NCP connection */
  60         ENDPOINT_EXCHG,                 /* Fibre Channel exchange */
  61         ENDPOINT_DDP,                   /* DDP AppleTalk connection */
  62         ENDPOINT_SBCCS,                 /* FICON */
  63         ENDPOINT_IDP,                   /* XNS IDP sockets */
  64         ENDPOINT_TIPC,                  /* TIPC PORT */
  65         ENDPOINT_USB,                   /* USB endpoint 0xffff means the host */
  66         ENDPOINT_I2C,
  67         ENDPOINT_IBQP,                  /* Infiniband QP number */
  68         ENDPOINT_BLUETOOTH,
  69         ENDPOINT_TDMOP,
  70         ENDPOINT_DVBCI,
  71         ENDPOINT_ISO14443,
  72         ENDPOINT_ISDN,                  /* ISDN channel number */
  73         ENDPOINT_H223,                  /* H.223 logical channel number */
  74         ENDPOINT_X25,                   /* X.25 logical channel number */
  75         ENDPOINT_IAX2,                  /* IAX2 call id */
  76         ENDPOINT_DLCI,                  /* Frame Relay DLCI */
  77         ENDPOINT_ISUP,                  /* ISDN User Part CIC */
  78         ENDPOINT_BICC,                  /* BICC Circuit identifier */
  79         ENDPOINT_GSMTAP,
  80         ENDPOINT_IUUP
  81 } endpoint_type;
  82
  83 /**
  84  * Data structure representing a conversation.
  85  */
  86 struct conversation_key;
  87 typedef struct conversation_key* conversation_key_t;
  88
  89 typedef struct conversation {
  90         struct conversation *next;      /** pointer to next conversation on hash chain */
  91         struct conversation *last;      /** pointer to the last conversation on hash chain */
  92         struct conversation *latest_found;
  93                                                                 /** pointer to the last conversation on hash chain */
  94         guint32 conv_index;                             /** unique ID for conversation */
  95         guint32 setup_frame;            /** frame number that setup this conversation */
  96         /* Assume that setup_frame is also the lowest frame number for now. */
  97         guint32 last_frame;             /** highest frame number in this conversation */
  98         wmem_tree_t *data_list;                 /** list of data associated with conversation */
  99         wmem_tree_t *dissector_tree;
 100                                                                 /** tree containing protocol dissector client associated with conversation */
 101         guint   options;                        /** wildcard flags */
 102         conversation_key_t key_ptr;     /** pointer to the key for this conversation */
 103 } conversation_t;
 104
 105
 106 struct endpoint;
 107 typedef struct endpoint* endpoint_t;
 108
 109 WS_DLL_PUBLIC address* conversation_key_addr1(const conversation_key_t key);
 110 WS_DLL_PUBLIC address* conversation_key_addr2(const conversation_key_t key);
 111 WS_DLL_PUBLIC guint32 conversation_key_port1(const conversation_key_t key);
 112 WS_DLL_PUBLIC guint32 conversation_key_port2(const conversation_key_t key);
 113
 114 /**
 115  * Create a new hash tables for conversations.
 116  */
 117 extern void conversation_init(void);
 118
 119 /**
 120  * Initialize some variables every time a file is loaded or re-loaded.
 121  */
 122 extern void conversation_epan_reset(void);
 123
 124 /*
 125  * Given two address/port pairs for a packet, create a new conversation
 126  * to contain packets between those address/port pairs.
 127  *
 128  * The options field is used to specify whether the address 2 value
 129  * and/or port 2 value are not given and any value is acceptable
 130  * when searching for this conversation.
 131  */
 132 WS_DLL_PUBLIC conversation_t *conversation_new(const guint32 setup_frame, const address *addr1, const address *addr2,
 133     const endpoint_type etype, const guint32 port1, const guint32 port2, const guint options);
 134
 135 WS_DLL_PUBLIC conversation_t *conversation_new_by_id(const guint32 setup_frame, const endpoint_type etype, const guint32 id, const guint options);
 136
 137 /**
 138  * Given two address/port pairs for a packet, search for a conversation
 139  * containing packets between those address/port pairs.  Returns NULL if
 140  * not found.
 141  *
 142  * We try to find the most exact match that we can, and then proceed to
 143  * try wildcard matches on the "addr_b" and/or "port_b" argument if a more
 144  * exact match failed.
 145  *
 146  * Either or both of the "addr_b" and "port_b" arguments may be specified as
 147  * a wildcard by setting the NO_ADDR_B or NO_PORT_B flags in the "options"
 148  * argument.  We do only wildcard matches on addresses and ports specified
 149  * as wildcards.
 150  *
 151  * I.e.:
 152  *
 153  *      if neither "addr_b" nor "port_b" were specified as wildcards, we
 154  *      do an exact match (addr_a/port_a and addr_b/port_b) and, if that
 155  *      succeeds, we return a pointer to the matched conversation;
 156  *
 157  *      otherwise, if "port_b" wasn't specified as a wildcard, we try to
 158  *      match any address 2 with the specified port 2 (addr_a/port_a and
 159  *      {any}/addr_b) and, if that succeeds, we return a pointer to the
 160  *      matched conversation;
 161  *
 162  *      otherwise, if "addr_b" wasn't specified as a wildcard, we try to
 163  *      match any port 2 with the specified address 2 (addr_a/port_a and
 164  *      addr_b/{any}) and, if that succeeds, we return a pointer to the
 165  *      matched conversation;
 166  *
 167  *      otherwise, we try to match any address 2 and any port 2
 168  *      (addr_a/port_a and {any}/{any}) and, if that succeeds, we return
 169  *      a pointer to the matched conversation;
 170  *
 171  *      otherwise, we found no matching conversation, and return NULL.
 172  */
 173 WS_DLL_PUBLIC conversation_t *find_conversation(const guint32 frame_num, const address *addr_a, const address *addr_b,
 174     const endpoint_type etype, const guint32 port_a, const guint32 port_b, const guint options);
 175
 176 WS_DLL_PUBLIC conversation_t *find_conversation_by_id(const guint32 frame, const endpoint_type etype, const guint32 id, const guint options);
 177
 178 /**  A helper function that calls find_conversation() using data from pinfo
 179  *  The frame number and addresses are taken from pinfo.
 180  */
 181 WS_DLL_PUBLIC conversation_t *find_conversation_pinfo(packet_info *pinfo, const guint options);
 182
 183 /**  A helper function that calls find_conversation() and, if a conversation is
 184  *  not found, calls conversation_new().
 185  *  The frame number and addresses are taken from pinfo.
 186  *  No options are used, though we could extend this API to include an options
 187  *  parameter.
 188  */
 189 WS_DLL_PUBLIC conversation_t *find_or_create_conversation(packet_info *pinfo);
 190
 191 /**  A helper function that calls find_conversation_by_id() and, if a
 192  *  conversation is not found, calls conversation_new_by_id().
 193  *  The frame number is taken from pinfo.
 194  */
 195 WS_DLL_PUBLIC conversation_t *find_or_create_conversation_by_id(packet_info *pinfo, const endpoint_type etype, const guint32 id);
 196
 197 WS_DLL_PUBLIC void conversation_add_proto_data(conversation_t *conv, const int proto,
 198     void *proto_data);
 199 WS_DLL_PUBLIC void *conversation_get_proto_data(const conversation_t *conv, const int proto);
 200 WS_DLL_PUBLIC void conversation_delete_proto_data(conversation_t *conv, const int proto);
 201
 202 WS_DLL_PUBLIC void conversation_set_dissector(conversation_t *conversation,
 203     const dissector_handle_t handle);
 204
 205 WS_DLL_PUBLIC void conversation_set_dissector_from_frame_number(conversation_t *conversation,
 206     const guint32 starting_frame_num, const dissector_handle_t handle);
 207
 208 WS_DLL_PUBLIC dissector_handle_t conversation_get_dissector(conversation_t *conversation,
 209     const guint32 frame_num);
 210
 211 WS_DLL_PUBLIC void conversation_create_endpoint(struct _packet_info *pinfo, address* addr1, address* addr2,
 212     endpoint_type etype, guint32 port1, guint32 port2, const guint options);
 213
 214 WS_DLL_PUBLIC void conversation_create_endpoint_by_id(struct _packet_info *pinfo,
 215     endpoint_type etype, guint32 id, const guint options);
 216
 217 WS_DLL_PUBLIC guint32 conversation_get_endpoint_by_id(struct _packet_info *pinfo,
 218     endpoint_type etype, const guint options);
 219
 220 /**
 221  * Given two address/port pairs for a packet, search for a matching
 222  * conversation and, if found and it has a conversation dissector,
 223  * call that dissector and return TRUE, otherwise return FALSE.
 224  *
 225  * This helper uses call_dissector_only which will NOT call the default
 226  * "data" dissector if the packet was rejected.
 227  * Our caller is responsible to call the data dissector explicitly in case
 228  * this function returns FALSE.
 229  */
 230 WS_DLL_PUBLIC gboolean
 231 try_conversation_dissector(const address *addr_a, const address *addr_b, const endpoint_type etype,
 232     const guint32 port_a, const guint32 port_b, tvbuff_t *tvb, packet_info *pinfo,
 233     proto_tree *tree, void* data, const guint options);
 234
 235 WS_DLL_PUBLIC gboolean
 236 try_conversation_dissector_by_id(const endpoint_type etype, const guint32 id, tvbuff_t *tvb,
 237     packet_info *pinfo, proto_tree *tree, void* data);
 238
 239 /* These routines are used to set undefined values for a conversation */
 240
 241 WS_DLL_PUBLIC
 242 void conversation_set_port2(conversation_t *conv, const guint32 port);
 243 WS_DLL_PUBLIC
 244 void conversation_set_addr2(conversation_t *conv, const address *addr);
 245
 246 WS_DLL_PUBLIC
 247 wmem_map_t *get_conversation_hashtable_exact(void);
 248
 249 WS_DLL_PUBLIC
 250 wmem_map_t *get_conversation_hashtable_no_addr2(void);
 251
 252 WS_DLL_PUBLIC
 253 wmem_map_t * get_conversation_hashtable_no_port2(void);
 254
 255 WS_DLL_PUBLIC
 256 wmem_map_t *get_conversation_hashtable_no_addr2_or_port2(void);
 257
 258 /* Temporary function to handle port_type to endpoint_type conversion
 259    For now it's a 1-1 mapping, but the intention is to remove
 260    many of the port_type instances in favor of endpoint_type
 261 */
 262 WS_DLL_PUBLIC
 263 endpoint_type conversation_pt_to_endpoint_type(port_type pt);
 264
 265 WS_DLL_PUBLIC guint
 266 conversation_hash_exact(gconstpointer v);
 267
 268 /* Provide a wmem_alloced (NULL scope) hash string using HTML tags */
 269 WS_DLL_PUBLIC gchar*
 270 conversation_get_html_hash(const conversation_key_t key);
 271
 272 #ifdef __cplusplus
 273 }
 274 #endif /* __cplusplus */
 275
 276 #endif /* conversation.h */