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 #include "packet.h"                     /* for conversation dissector type */
  17 #include <epan/wmem_scopes.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif /* __cplusplus */
  22
  23 /**
  24  * @file
  25  * The conversation API lets you correlate packets based on values in a
  26  * packet, typically address+port tuples. You can search for conversations
  27  * based on their value tuples and attach data to them.
  28  */
  29
  30 /**
  31  * Flags to pass to "conversation_new()" to indicate that the address 2
  32  * and/or port 2 values for the conversation should be wildcards.
  33  * The CONVERSATION_TEMPLATE option tells that any of the other supplied
  34  * port and / or address wildcards will be used to match an infinite number
  35  * of new connections to the conversation(s) that have the CONVERSATION_-
  36  * TEMPLATE flag set. Any conversation created without the CONVERSATION_-
  37  * TEMPLATE flag will be altered once the first connections (connection
  38  * oriented protocols only) to include the newly found information which
  39  * matched the wildcard options.
  40  */
  41 #define NO_ADDR2 0x01
  42 #define NO_PORT2 0x02
  43 #define NO_PORT2_FORCE 0x04
  44 #define CONVERSATION_TEMPLATE 0x08
  45 #define NO_PORTS 0x010
  46
  47 /**
  48  * Flags to pass to "find_conversation()" to indicate that the address B
  49  * and/or port B search arguments are wildcards.
  50  */
  51 #define NO_MASK_B 0xFFFF0000
  52 #define NO_ADDR_B 0x00010000
  53 #define NO_PORT_B 0x00020000
  54 #define NO_PORT_X 0x00040000
  55 #define NO_ANC    0x00080000
  56
  57 /** Flags to handle endpoints */
  58 #define USE_LAST_ENDPOINT 0x08          /**< Use last endpoint created, regardless of type */
  59
  60 /* Types of conversations Wireshark knows about. */
  61 /* XXX: There should be a way to register conversation types used only
  62  * within one dissector, similar to address types, instead of changing
  63  * the global typedef.
  64  */
  65 typedef enum {
  66     CONVERSATION_NONE,          /* no conversation key */
  67     CONVERSATION_SCTP,          /* SCTP */
  68     CONVERSATION_TCP,           /* TCP address/port pairs */
  69     CONVERSATION_UDP,           /* UDP address/port pairs */
  70     CONVERSATION_DCCP,          /* DCCP */
  71     CONVERSATION_IPX,           /* IPX sockets */
  72     CONVERSATION_NCP,           /* NCP connection */
  73     CONVERSATION_EXCHG,         /* Fibre Channel exchange */
  74     CONVERSATION_DDP,           /* DDP AppleTalk address/port pair */
  75     CONVERSATION_SBCCS,         /* FICON */
  76     CONVERSATION_IDP,           /* XNS IDP sockets */
  77     CONVERSATION_TIPC,          /* TIPC PORT */
  78     CONVERSATION_USB,           /* USB endpoint 0xffff means the host */
  79     CONVERSATION_I2C,
  80     CONVERSATION_IBQP,          /* Infiniband QP number */
  81     CONVERSATION_BLUETOOTH,
  82     CONVERSATION_TDMOP,
  83     CONVERSATION_DVBCI,
  84     CONVERSATION_ISO14443,
  85     CONVERSATION_ISDN,          /* ISDN channel number */
  86     CONVERSATION_H223,          /* H.223 logical channel number */
  87     CONVERSATION_X25,           /* X.25 logical channel number */
  88     CONVERSATION_IAX2,          /* IAX2 call id */
  89     CONVERSATION_DLCI,          /* Frame Relay DLCI */
  90     CONVERSATION_ISUP,          /* ISDN User Part CIC */
  91     CONVERSATION_BICC,          /* BICC Circuit identifier */
  92     CONVERSATION_GSMTAP,
  93     CONVERSATION_IUUP,
  94     CONVERSATION_DVBBBF,        /* DVB Base Band Frame ISI/PLP_ID */
  95     CONVERSATION_IWARP_MPA,     /* iWarp MPA */
  96     CONVERSATION_BT_UTP,        /* BitTorrent uTP Connection ID */
  97     CONVERSATION_LOG,           /* Logging source */
  98     CONVERSATION_LTP,           /* LTP Engine ID and Session Number */
  99     CONVERSATION_MCTP,
 100     CONVERSATION_NVME_MI,       /* NVMe management interface */
 101     CONVERSATION_BP,            /* Bundle Protocol endpoint IDs */
 102     CONVERSATION_SNMP,          /* SNMP */
 103     CONVERSATION_QUIC,          /* QUIC */
 104     CONVERSATION_IDN,
 105     CONVERSATION_IP,            /* IP */
 106     CONVERSATION_IPV6,          /* IPv6 */
 107     CONVERSATION_ETH,           /* ETHERNET classic */
 108     CONVERSATION_ETH_NN,        /* ETHERNET deinterlaced Interface:N VLAN:N */
 109     CONVERSATION_ETH_NV,        /* ETHERNET deinterlaced Interface:N VLAN:Y */
 110     CONVERSATION_ETH_IN,        /* ETHERNET deinterlaced Interface:Y VLAN:N */
 111     CONVERSATION_ETH_IV,        /* ETHERNET deinterlaced Interface:Y VLAN:Y */
 112     CONVERSATION_VSPC_VMOTION,  /* VMware vSPC vMotion (Telnet) */
 113     CONVERSATION_OPENVPN,
 114     CONVERSATION_PROXY,
 115     CONVERSATION_DNP3
 116 } conversation_type;
 117
 118 /*
 119  * XXX - for now, we just #define these to be the same as the
 120  * corresponding CONVERSATION_ values, for backwards source
 121  * compatibility.
 122  *
 123  * In the long term, we should make this into a separate enum,
 124  * with elements corresponding to conversation types that do
 125  * not have known endpoints removed.
 126  */
 127 /* Types of conversation endpoints Wireshark knows about. */
 128 #define ENDPOINT_NONE           CONVERSATION_NONE
 129 #define ENDPOINT_SCTP           CONVERSATION_SCTP
 130 #define ENDPOINT_TCP            CONVERSATION_TCP
 131 #define ENDPOINT_UDP            CONVERSATION_UDP
 132 #define ENDPOINT_DCCP           CONVERSATION_DCCP
 133 #define ENDPOINT_IPX            CONVERSATION_IPX
 134 #define ENDPOINT_NCP            CONVERSATION_NCP
 135 #define ENDPOINT_EXCHG          CONVERSATION_EXCHG
 136 #define ENDPOINT_DDP            CONVERSATION_DDP
 137 #define ENDPOINT_SBCCS          CONVERSATION_SBCCS
 138 #define ENDPOINT_IDP            CONVERSATION_IDP
 139 #define ENDPOINT_TIPC           CONVERSATION_TIPC
 140 #define ENDPOINT_USB            CONVERSATION_USB
 141 #define ENDPOINT_I2C            CONVERSATION_I2C
 142 #define ENDPOINT_IBQP           CONVERSATION_IBQP
 143 #define ENDPOINT_BLUETOOTH      CONVERSATION_BLUETOOTH
 144 #define ENDPOINT_TDMOP          CONVERSATION_TDMOP
 145 #define ENDPOINT_DVBCI          CONVERSATION_DVBCI
 146 #define ENDPOINT_ISO14443       CONVERSATION_ISO14443
 147 #define ENDPOINT_ISDN           CONVERSATION_ISDN
 148 #define ENDPOINT_H223           CONVERSATION_H223
 149 #define ENDPOINT_X25            CONVERSATION_X25
 150 #define ENDPOINT_IAX2           CONVERSATION_IAX2
 151 #define ENDPOINT_DLCI           CONVERSATION_DLCI
 152 #define ENDPOINT_ISUP           CONVERSATION_ISUP
 153 #define ENDPOINT_BICC           CONVERSATION_BICC
 154 #define ENDPOINT_GSMTAP         CONVERSATION_GSMTAP
 155 #define ENDPOINT_IUUP           CONVERSATION_IUUP
 156 #define ENDPOINT_DVBBBF         CONVERSATION_DVBBBF
 157 #define ENDPOINT_IWARP_MPA      CONVERSATION_IWARP_MPA
 158 #define ENDPOINT_BT_UTP         CONVERSATION_BT_UTP
 159 #define ENDPOINT_LOG            CONVERSATION_LOG
 160 #define ENDPOINT_MCTP           CONVERSATION_MCTP
 161 #define ENDPOINT_NVME_MI        CONVERSATION_NVME_MI
 162 #define ENDPOINT_SNMP           CONVERSATION_SNMP
 163
 164 typedef conversation_type endpoint_type;
 165
 166 /**
 167  * Conversation element type.
 168  */
 169 typedef enum {
 170     CE_CONVERSATION_TYPE,   /* CONVERSATION_ value */
 171     CE_ADDRESS,             /* address */
 172     CE_PORT,                /* unsigned integer representing a port */
 173     CE_STRING,              /* string */
 174     CE_UINT,                /* unsigned integer not representing a port */
 175     CE_UINT64,              /* 64-bit unsigned integer */
 176     CE_INT,                 /* signed integer */
 177     CE_INT64,               /* signed integer */
 178     CE_BLOB,                /* arbitrary binary data */
 179 } conversation_element_type;
 180
 181 /**
 182  * Elements used to identify conversations for *_full routines and
 183  * pinfo->conv_elements.
 184  * Arrays must be terminated with an element .type set to CE_CONVERSATION_TYPE.
 185  *
 186  * This is currently set only by conversation_set_elements_by_id(); it
 187  * is not set for conversations identified by address/port endpoints.
 188  *
 189  * In find_conversation_pinfo() and find_or_create_conversation(), if
 190  * any dissector has set this, then, unless some dissector has set the
 191  * pair of address/port endpoints (see below), the array of elements
 192  * is used to look up or create the conversation.  Otherwise, the
 193  * current addresses and ports in the packet_info structure are used.
 194  *
 195  * XXX - is there any reason why we shouldn't use an array of conversation
 196  * elements, with the appropriate addresses and ports, and set it for
 197  * all protocols that use conversations specified by a pair of address/port
 198  * endpoints?  That might simplify find_conversation_pinfo() by having
 199  * them always use the array of elements if it's present, and just fail if
 200  * it's not.
 201  */
 202 typedef struct conversation_element {
 203     conversation_element_type type;
 204     union {
 205         conversation_type conversation_type_val;
 206         address addr_val;
 207         unsigned int port_val;
 208         const char *str_val;
 209         unsigned int uint_val;
 210         uint64_t uint64_val;
 211         int int_val;
 212         int64_t int64_val;
 213         struct {
 214             const uint8_t *val;
 215             size_t len;
 216         } blob;
 217     };
 218 } conversation_element_t;
 219
 220 /**
 221  * Data structure representing a conversation.
 222  */
 223 typedef struct conversation {
 224     struct conversation *next;  /** pointer to next conversation on hash chain */
 225     struct conversation *last;  /** pointer to the last conversation on hash chain */
 226     struct conversation *latest_found; /** pointer to the last conversation on hash chain */
 227     uint32_t    conv_index;             /** unique ID for conversation */
 228     uint32_t setup_frame;               /** frame number that setup this conversation */
 229     /* Assume that setup_frame is also the lowest frame number for now. */
 230     uint32_t last_frame;                /** highest frame number in this conversation */
 231     wmem_tree_t *data_list;             /** list of data associated with conversation */
 232     wmem_tree_t *dissector_tree;        /** tree containing protocol dissector client associated with conversation */
 233     unsigned    options;                /** wildcard flags */
 234     conversation_element_t *key_ptr;    /** Keys are conversation element arrays terminated with a CE_CONVERSATION_TYPE */
 235 } conversation_t;
 236
 237 /*
 238  * For some protocols, we store, in the packet_info structure, a pair
 239  * of address/port endpoints, for use by code that might want to
 240  * construct a conversation for that protocol.
 241  *
 242  * This appears to have been done in order to allow protocols to save
 243  * that information *without* overwriting the addresses or ports in the
 244  * packet_info structure, so that the other code that uses those values,
 245  * such as the code that fills in the address and port columns in the
 246  * packet summary, will pick up the values put there by protocols such
 247  * as IP and UDP, rather than the values put there by protocols such as
 248  * TDMoP, FCIP, TIPC, and DVB Dynamic Mode Adaptation. See commit
 249  * 66b441f3d63e21949530d672bf1406dea94ed254 and issue #11340.
 250  *
 251  * That is set by conversation_set_conv_addr_port_endpoints().
 252  *
 253  * In find_conversation_pinfo() and find_or_create_conversation(), if
 254  * any dissector has set this, that address/port endpoint pair is used
 255  * to look up or create the conversation.
 256  *
 257  * Prior to 4.0, conversations identified by a single integer value
 258  * (such as a circuit ID) were handled by creating a pair of address/port
 259  * endpoints with null addresses, the first port equal to the integer
 260  * value, the second port missing, and a port type being an ENDPOINT_
 261  * type specifying the protocol for the conversation.  Now we use an
 262  * array of elements, with a CE_UINT value for the integer followed
 263  * by a CE_CONVERSATION_TYPE value specifying the protocol for the
 264  * conversation.
 265  *
 266  * XXX - is there any reason why we shouldn't use an array of conversation
 267  * elements, with the appropriate addresses and ports, instead of this
 268  * structure?  It would at least simplify find_conversation_pinfo() and
 269  * find_or_create_conversation().
 270  */
 271 struct conversation_addr_port_endpoints;
 272 typedef struct conversation_addr_port_endpoints* conversation_addr_port_endpoints_t;
 273
 274 WS_DLL_PUBLIC const address* conversation_key_addr1(const conversation_element_t *key);
 275 WS_DLL_PUBLIC uint32_t conversation_key_port1(const conversation_element_t *key);
 276 WS_DLL_PUBLIC const address* conversation_key_addr2(const conversation_element_t *key);
 277 WS_DLL_PUBLIC uint32_t conversation_key_port2(const conversation_element_t *key);
 278
 279 /**
 280  * Create a new hash tables for conversations.
 281  */
 282 extern void conversation_init(void);
 283
 284 /**
 285  * Initialize some variables every time a file is loaded or re-loaded.
 286  */
 287 extern void conversation_epan_reset(void);
 288
 289 /**
 290  * Create a new conversation identified by a list of elements.
 291  * @param setup_frame The first frame in the conversation.
 292  * @param elements An array of element types and values. Must not be NULL. Must be terminated with a CE_CONVERSATION_TYPE element.
 293  * @return The new conversation.
 294  */
 295 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_full(const uint32_t setup_frame, conversation_element_t *elements);
 296
 297 /**
 298  * Given two address/port pairs for a packet, create a new conversation
 299  * identified by address/port pairs.
 300  *
 301  * The options field is used to specify whether the address 2 value
 302  * and/or port 2 value are not given and any value is acceptable
 303  * when searching for this conversation. Null address values will
 304  * be replaced with empty (AT_NONE) addresses.
 305  *
 306  * @param setup_frame The first frame in the conversation.
 307  * @param addr1 The first address in the identifying tuple.
 308  * @param addr2 The second address in the identifying tuple.
 309  * @param ctype The conversation type.
 310  * @param port1 The first port in the identifying tuple.
 311  * @param port2 The second port in the identifying tuple.
 312  * @param options NO_ADDR2, NO_PORT2, NO_PORT2_FORCE, or CONVERSATION_TEMPLATE.
 313  *        Options except for NO_PORT2 and NO_PORT2_FORCE can be ORed.
 314  * @return The new conversation.
 315  */
 316 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new(const uint32_t setup_frame, const address *addr1, const address *addr2,
 317     const conversation_type ctype, const uint32_t port1, const uint32_t port2, const unsigned options);
 318
 319 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_by_id(const uint32_t setup_frame, const conversation_type ctype, const uint32_t id);
 320
 321 /**
 322  *
 323  */
 324 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_deinterlaced(const uint32_t setup_frame, const address *addr1, const address *addr2,
 325     const conversation_type ctype, const uint32_t port1, const uint32_t port2, const uint32_t anchor, const unsigned options);
 326
 327 /**
 328  * Create a deinterlacer conversation, based on two addresses,
 329  * a type, and several keys (VLAN, Mac, Interface).
 330  *
 331  * @param setup_frame The first frame in the conversation.
 332  * @param addr1 The first address in the identifying tuple.
 333  * @param addr2 The second address in the identifying tuple.
 334  * @param ctype The conversation type.
 335  * @param key1  The first key in the identifying tuple.
 336  * @param key2  The second key in the identifying tuple.
 337  * @param key3  The third key in the identifying tuple.
 338  * @return The new conversation.
 339  */
 340 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_deinterlacer(const uint32_t setup_frame, const address *addr1, const address *addr2,
 341     const conversation_type ctype, const uint32_t key1, const uint32_t key2, const uint32_t key3);
 342
 343 /**
 344  * A helper function for creating conversations according to the runtime deinterlacing strategy,
 345  * which means the returned conversation is either a classic (historical) object, or a deinterlaced one.
 346  *
 347  * @param pinfo Packet info.
 348  * @param ctype The conversation type.
 349  * @param options NO_ADDR2, NO_PORT2, NO_PORT2_FORCE, or CONVERSATION_TEMPLATE.
 350  *        Options except for NO_PORT2 and NO_PORT2_FORCE can be ORed.
 351  * @return The new conversation.
 352  */
 353 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_strat(packet_info *pinfo, const conversation_type ctype, const unsigned options);
 354
 355 /**
 356  * Search for a conversation based on the structure and values of an element list.
 357  * @param frame_num Frame number. Must be greater than or equal to the conversation's initial frame number.
 358  * @param elements An array of element types and values. Must not be NULL. Must be terminated with a CE_CONVERSATION_TYPE element.
 359  * @return The matching conversation if found, otherwise NULL.
 360  */
 361 WS_DLL_PUBLIC conversation_t *find_conversation_full(const uint32_t frame_num, conversation_element_t *elements);
 362
 363 /**
 364  * Given two address/port pairs for a packet, search for a conversation
 365  * containing packets between those address/port pairs.  Returns NULL if
 366  * not found.
 367  *
 368  * We try to find the most exact match that we can, and then proceed to
 369  * try wildcard matches on the "addr_b" and/or "port_b" argument if a more
 370  * exact match failed.
 371  *
 372  * Either or both of the "addr_b" and "port_b" arguments may be specified as
 373  * a wildcard by setting the NO_ADDR_B or NO_PORT_B flags in the "options"
 374  * argument.  We do only wildcard matches on addresses and ports specified
 375  * as wildcards.
 376  *
 377  * I.e.:
 378  *
 379  *      if neither "addr_b" nor "port_b" were specified as wildcards, we
 380  *      do an exact match (addr_a/port_a and addr_b/port_b) and, if that
 381  *      succeeds, we return a pointer to the matched conversation;
 382  *
 383  *      otherwise, if "port_b" wasn't specified as a wildcard, we try to
 384  *      match any address 2 with the specified port 2 (addr_a/port_a and
 385  *      {any}/addr_b) and, if that succeeds, we return a pointer to the
 386  *      matched conversation;
 387  *
 388  *      otherwise, if "addr_b" wasn't specified as a wildcard, we try to
 389  *      match any port 2 with the specified address 2 (addr_a/port_a and
 390  *      addr_b/{any}) and, if that succeeds, we return a pointer to the
 391  *      matched conversation;
 392  *
 393  *      otherwise, we try to match any address 2 and any port 2
 394  *      (addr_a/port_a and {any}/{any}) and, if that succeeds, we return
 395  *      a pointer to the matched conversation;
 396  *
 397  *      otherwise, we found no matching conversation, and return NULL.
 398  *
 399  * Null address values will be replaced with empty (AT_NONE) addresses.
 400  *
 401  * @param frame_num Frame number. Must be greater than or equal to the conversation's initial frame number.
 402  * @param addr_a The first address in the identifying tuple.
 403  * @param addr_b The second address in the identifying tuple.
 404  * @param ctype The conversation type.
 405  * @param port_a The first port in the identifying tuple.
 406  * @param port_b The second port in the identifying tuple.
 407  * @param options Wildcard options as described above.
 408  * @return The matching conversation if found, otherwise NULL.
 409  */
 410 WS_DLL_PUBLIC conversation_t *find_conversation(const uint32_t frame_num, const address *addr_a, const address *addr_b,
 411     const conversation_type ctype, const uint32_t port_a, const uint32_t port_b, const unsigned options);
 412
 413 WS_DLL_PUBLIC conversation_t *find_conversation_deinterlaced(const uint32_t frame_num, const address *addr_a, const address *addr_b,
 414     const conversation_type ctype, const uint32_t port_a, const uint32_t port_b, const uint32_t anchor, const unsigned options);
 415
 416 WS_DLL_PUBLIC conversation_t *find_conversation_deinterlacer(const uint32_t frame_num, const address *addr_a, const address *addr_b,
 417     const conversation_type ctype, const uint32_t key_a, const uint32_t key_b, const uint32_t key_c);
 418
 419 /**  A wrapper function of find_conversation_deinterlacer() using data from pinfo,
 420  *  which evaluates the execution context first (user preference, VLAN, interface,..),
 421  *  and then calls find_conversation_deinterlacer().
 422  *  The frame number and addresses are taken from pinfo.
 423  */
 424 WS_DLL_PUBLIC conversation_t *find_conversation_deinterlacer_pinfo(const packet_info *pinfo);
 425
 426 WS_DLL_PUBLIC conversation_t *find_conversation_by_id(const uint32_t frame, const conversation_type ctype, const uint32_t id);
 427
 428 /**  A helper function that calls find_conversation() using data from pinfo,
 429  *  and returns a conversation according to the runtime deinterlacing strategy.
 430  *  The frame number and addresses are taken from pinfo.
 431  */
 432 WS_DLL_PUBLIC conversation_t *find_conversation_strat(const packet_info *pinfo, const conversation_type ctype, const unsigned options);
 433
 434 /**  A helper function that calls find_conversation() using data from pinfo
 435  *  The frame number and addresses are taken from pinfo.
 436  */
 437 WS_DLL_PUBLIC conversation_t *find_conversation_pinfo(const packet_info *pinfo, const unsigned options);
 438
 439 /**  A helper function that calls find_conversation() using data from pinfo.
 440  *  It's a simplified version of find_conversation_pinfo() to avoid
 441  *  unnecessary checks and be limited to read-only, which is the minimal
 442  *  need for displaying packets in packet_list.
 443  *  The frame number and addresses are taken from pinfo.
 444  */
 445 WS_DLL_PUBLIC conversation_t *find_conversation_pinfo_ro(const packet_info *pinfo, const unsigned options);
 446
 447 /**
 448  * A helper function that calls find_conversation() and, if a conversation is
 449  * not found, calls conversation_new().
 450  * The frame number and addresses are taken from pinfo.
 451  * No options are used, though we could extend this API to include an options
 452  * parameter.
 453  *
 454  * @param pinfo Packet info.
 455  * @return The existing or new conversation.
 456  */
 457 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *find_or_create_conversation(packet_info *pinfo);
 458
 459 /**  A helper function that calls find_conversation_by_id() and, if a
 460  *  conversation is not found, calls conversation_new_by_id().
 461  *  The frame number is taken from pinfo.
 462  */
 463 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *find_or_create_conversation_by_id(packet_info *pinfo, const conversation_type ctype, const uint32_t id);
 464
 465 /** Associate data with a conversation.
 466  * @param conv Conversation. Must not be NULL.
 467  * @param proto Protocol ID.
 468  * @param proto_data Pointer to the data to associate.
 469  */
 470 WS_DLL_PUBLIC void conversation_add_proto_data(conversation_t *conv, const int proto, void *proto_data);
 471
 472 /** Fetch data associated with a conversation.
 473  * @param conv Conversation. Must not be NULL.
 474  * @param proto Protocol ID.
 475  * @return The data previously set with conversation_add_proto_data, otherwise NULL.
 476  */
 477 WS_DLL_PUBLIC void *conversation_get_proto_data(const conversation_t *conv, const int proto);
 478
 479 /** Remove data associated with a conversation.
 480  * @param conv Conversation. Must not be NULL.
 481  * @param proto Protocol ID.
 482  */
 483 WS_DLL_PUBLIC void conversation_delete_proto_data(conversation_t *conv, const int proto);
 484
 485 WS_DLL_PUBLIC void conversation_set_dissector(conversation_t *conversation, const dissector_handle_t handle);
 486
 487 WS_DLL_PUBLIC void conversation_set_dissector_from_frame_number(conversation_t *conversation,
 488     const uint32_t starting_frame_num, const dissector_handle_t handle);
 489
 490 WS_DLL_PUBLIC dissector_handle_t conversation_get_dissector(conversation_t *conversation, const uint32_t frame_num);
 491
 492 /**
 493  * Save address+port information in the current packet info; it can be matched
 494  * by find_conversation_pinfo or find_conversation.
 495  * Supports wildcarding.
 496  * @param pinfo Packet info.
 497  * @param addr1 The first address in the identifying tuple.
 498  * @param addr2 The second address in the identifying tuple.
 499  * @param ctype The conversation type.
 500  * @param port1 The first port in the identifying tuple.
 501  * @param port2 The second port in the identifying tuple.
 502  */
 503 WS_DLL_PUBLIC void conversation_set_conv_addr_port_endpoints(struct _packet_info *pinfo, address* addr1, address* addr2,
 504     conversation_type ctype, uint32_t port1, uint32_t port2);
 505
 506 /**
 507  * Save conversation elements including ID information in the current
 508  * packet info which can be matched by conversation_get_id_from_elements.
 509  * Does not support wildcarding.
 510  * @param pinfo Packet info.
 511  * @param ctype The conversation type.
 512  * @param id A unique ID.
 513  */
 514 WS_DLL_PUBLIC void conversation_set_elements_by_id(struct _packet_info *pinfo,
 515     conversation_type ctype, uint32_t id);
 516
 517 /**
 518  * @brief Get the ID value from the conversation elements in the packet info.
 519  * @param pinfo Packet info.
 520  * @param ctype The conversation type.
 521  * @param options USE_LAST_ENDPOINT or 0.
 522  * @return The ID value from the elements if successful, or 0
 523  *   on failure.
 524  */
 525 WS_DLL_PUBLIC uint32_t conversation_get_id_from_elements(struct _packet_info *pinfo,
 526     conversation_type ctype, const unsigned options);
 527
 528 /**
 529  * Given two address/port pairs for a packet, search for a matching
 530  * conversation and, if found and it has a conversation dissector,
 531  * call that dissector and return true, otherwise return false.
 532  *
 533  * This helper uses call_dissector_only which will NOT call the default
 534  * "data" dissector if the packet was rejected.
 535  * Our caller is responsible to call the data dissector explicitly in case
 536  * this function returns false.
 537  */
 538 WS_DLL_PUBLIC bool try_conversation_dissector(const address *addr_a, const address *addr_b, const conversation_type ctype,
 539     const uint32_t port_a, const uint32_t port_b, tvbuff_t *tvb, packet_info *pinfo,
 540     proto_tree *tree, void* data, const unsigned options);
 541
 542 WS_DLL_PUBLIC bool try_conversation_dissector_by_id(const conversation_type ctype, const uint32_t id, tvbuff_t *tvb,
 543     packet_info *pinfo, proto_tree *tree, void* data);
 544
 545 /* These routines are used to set undefined values for a conversation */
 546
 547 /**
 548  * Set the second port in a conversation created with conversation_new.
 549  * @param conv Conversation. Must be created with conversation_new.
 550  * @param port The second port to set.
 551  */
 552 WS_DLL_PUBLIC void conversation_set_port2(conversation_t *conv, const uint32_t port);
 553
 554 /**
 555  * Set the second address in a conversation created with conversation_new.
 556  * @param conv Conversation. Must be created with conversation_new.
 557  * @param addr The second address to set.
 558  */
 559 WS_DLL_PUBLIC void conversation_set_addr2(conversation_t *conv, const address *addr);
 560
 561 /**
 562  * @brief Get a hash table of conversation hash table.
 563  *
 564  * @return A wmem_map_t * of (const char *: wmem_map_t *).
 565  * Each value is a wmem_map_t * of (const conversation_element_t *: void *).
 566  */
 567 WS_DLL_PUBLIC wmem_map_t *get_conversation_hashtables(void);
 568
 569 /* Temporary function to handle port_type to conversation_type conversion
 570    For now it's a 1-1 mapping, but the intention is to remove
 571    many of the port_type instances in favor of conversation_type
 572  */
 573 WS_DLL_PUBLIC conversation_type conversation_pt_to_conversation_type(port_type pt);
 574
 575 /* Temporary function to handle port_type to endpoint_type conversion
 576    For now it's a 1-1 mapping, but the intention is to remove
 577    many of the port_type instances in favor of endpoint_type
 578  */
 579 WS_DLL_PUBLIC endpoint_type conversation_pt_to_endpoint_type(port_type pt);
 580
 581 #ifdef __cplusplus
 582 }
 583 #endif /* __cplusplus */
 584
 585 #endif /* conversation.h */