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