Wireshark  4.3.0
The Wireshark network protocol analyzer
conversation.h
Go to the documentation of this file.
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 
41 #define NO_ADDR2 0x01
42 #define NO_PORT2 0x02
43 #define NO_PORT2_FORCE 0x04
44 #define CONVERSATION_TEMPLATE 0x08
45 
50 #define NO_MASK_B 0xFFFF0000
51 #define NO_ADDR_B 0x00010000
52 #define NO_PORT_B 0x00020000
53 
55 #define USE_LAST_ENDPOINT 0x08
57 /* Types of conversations Wireshark knows about. */
58 /* XXX: There should be a way to register conversation types used only
59  * within one dissector, similar to address types, instead of changing
60  * the global typedef.
61  */
62 typedef enum {
63  CONVERSATION_NONE, /* no conversation key */
64  CONVERSATION_SCTP, /* SCTP */
65  CONVERSATION_TCP, /* TCP address/port pairs */
66  CONVERSATION_UDP, /* UDP address/port pairs */
67  CONVERSATION_DCCP, /* DCCP */
68  CONVERSATION_IPX, /* IPX sockets */
69  CONVERSATION_NCP, /* NCP connection */
70  CONVERSATION_EXCHG, /* Fibre Channel exchange */
71  CONVERSATION_DDP, /* DDP AppleTalk address/port pair */
72  CONVERSATION_SBCCS, /* FICON */
73  CONVERSATION_IDP, /* XNS IDP sockets */
74  CONVERSATION_TIPC, /* TIPC PORT */
75  CONVERSATION_USB, /* USB endpoint 0xffff means the host */
76  CONVERSATION_I2C,
77  CONVERSATION_IBQP, /* Infiniband QP number */
78  CONVERSATION_BLUETOOTH,
79  CONVERSATION_TDMOP,
80  CONVERSATION_DVBCI,
81  CONVERSATION_ISO14443,
82  CONVERSATION_ISDN, /* ISDN channel number */
83  CONVERSATION_H223, /* H.223 logical channel number */
84  CONVERSATION_X25, /* X.25 logical channel number */
85  CONVERSATION_IAX2, /* IAX2 call id */
86  CONVERSATION_DLCI, /* Frame Relay DLCI */
87  CONVERSATION_ISUP, /* ISDN User Part CIC */
88  CONVERSATION_BICC, /* BICC Circuit identifier */
89  CONVERSATION_GSMTAP,
90  CONVERSATION_IUUP,
91  CONVERSATION_DVBBBF, /* DVB Base Band Frame ISI/PLP_ID */
92  CONVERSATION_IWARP_MPA, /* iWarp MPA */
93  CONVERSATION_BT_UTP, /* BitTorrent uTP Connection ID */
94  CONVERSATION_LOG, /* Logging source */
95  CONVERSATION_LTP, /* LTP Engine ID and Session Number */
96  CONVERSATION_MCTP,
97  CONVERSATION_NVME_MI, /* NVMe management interface */
98  CONVERSATION_BP, /* Bundle Protocol endpoint IDs */
99  CONVERSATION_SNMP, /* SNMP */
100  CONVERSATION_QUIC, /* QUIC */
101  CONVERSATION_IDN,
102 } conversation_type;
103 
104 /*
105  * XXX - for now, we just #define these to be the same as the
106  * corresponding CONVERSATION_ values, for backwards source
107  * compatibility.
108  *
109  * In the long term, we should make this into a separate enum,
110  * with elements corresponding to conversation types that do
111  * not have known endpoints removed.
112  */
113 /* Types of conversation endpoints Wireshark knows about. */
114 #define ENDPOINT_NONE CONVERSATION_NONE
115 #define ENDPOINT_SCTP CONVERSATION_SCTP
116 #define ENDPOINT_TCP CONVERSATION_TCP
117 #define ENDPOINT_UDP CONVERSATION_UDP
118 #define ENDPOINT_DCCP CONVERSATION_DCCP
119 #define ENDPOINT_IPX CONVERSATION_IPX
120 #define ENDPOINT_NCP CONVERSATION_NCP
121 #define ENDPOINT_EXCHG CONVERSATION_EXCHG
122 #define ENDPOINT_DDP CONVERSATION_DDP
123 #define ENDPOINT_SBCCS CONVERSATION_SBCCS
124 #define ENDPOINT_IDP CONVERSATION_IDP
125 #define ENDPOINT_TIPC CONVERSATION_TIPC
126 #define ENDPOINT_USB CONVERSATION_USB
127 #define ENDPOINT_I2C CONVERSATION_I2C
128 #define ENDPOINT_IBQP CONVERSATION_IBQP
129 #define ENDPOINT_BLUETOOTH CONVERSATION_BLUETOOTH
130 #define ENDPOINT_TDMOP CONVERSATION_TDMOP
131 #define ENDPOINT_DVBCI CONVERSATION_DVBCI
132 #define ENDPOINT_ISO14443 CONVERSATION_ISO14443
133 #define ENDPOINT_ISDN CONVERSATION_ISDN
134 #define ENDPOINT_H223 CONVERSATION_H223
135 #define ENDPOINT_X25 CONVERSATION_X25
136 #define ENDPOINT_IAX2 CONVERSATION_IAX2
137 #define ENDPOINT_DLCI CONVERSATION_DLCI
138 #define ENDPOINT_ISUP CONVERSATION_ISUP
139 #define ENDPOINT_BICC CONVERSATION_BICC
140 #define ENDPOINT_GSMTAP CONVERSATION_GSMTAP
141 #define ENDPOINT_IUUP CONVERSATION_IUUP
142 #define ENDPOINT_DVBBBF CONVERSATION_DVBBBF
143 #define ENDPOINT_IWARP_MPA CONVERSATION_IWARP_MPA
144 #define ENDPOINT_BT_UTP CONVERSATION_BT_UTP
145 #define ENDPOINT_LOG CONVERSATION_LOG
146 #define ENDPOINT_MCTP CONVERSATION_MCTP
147 #define ENDPOINT_NVME_MI CONVERSATION_NVME_MI
148 #define ENDPOINT_SNMP CONVERSATION_SNMP
149 
150 typedef conversation_type endpoint_type;
151 
155 typedef enum {
156  CE_CONVERSATION_TYPE, /* CONVERSATION_ value */
157  CE_ADDRESS, /* address */
158  CE_PORT, /* unsigned integer representing a port */
159  CE_STRING, /* string */
160  CE_UINT, /* unsigned integer not representing a port */
161  CE_UINT64, /* 64-bit unsigned integer */
162  CE_INT, /* signed integer */
164 
186 typedef struct conversation_element {
188  union {
189  conversation_type conversation_type_val;
190  address addr_val;
191  unsigned int port_val;
192  const char *str_val;
193  unsigned int uint_val;
194  uint64_t uint64_val;
195  int int_val;
196  };
198 
202 typedef struct conversation {
203  struct conversation *next;
204  struct conversation *last;
206  guint32 conv_index;
207  guint32 setup_frame;
208  /* Assume that setup_frame is also the lowest frame number for now. */
209  guint32 last_frame;
212  guint options;
215 
216 /*
217  * For some protocols, we store, in the packet_info structure, a pair
218  * of address/port endpoints, for use by code that might want to
219  * construct a conversation for that protocol.
220  *
221  * This appears to have been done in order to allow protocols to save
222  * that information *without* overwriting the addresses or ports in the
223  * packet_info structure, so that the other code that uses those values,
224  * such as the code that fills in the address and port columns in the
225  * packet summary, will pick up the values put there by protocols such
226  * as IP and UDP, rather than the values put there by protocols such as
227  * TDMoP, FCIP, TIPC, and DVB Dynamic Mode Adaptation. See commit
228  * 66b441f3d63e21949530d672bf1406dea94ed254 and issue #11340.
229  *
230  * That is set by conversation_set_conv_addr_port_endpoints().
231  *
232  * In find_conversation_pinfo() and find_or_create_conversation(), if
233  * any dissector has set this, that address/port endpoint pair is used
234  * to look up or create the conversation.
235  *
236  * Prior to 4.0, conversations identified by a single integer value
237  * (such as a circuit ID) were handled by creating a pair of address/port
238  * endpoints with null addresses, the first port equal to the integer
239  * value, the second port missing, and a port type being an ENDPOINT_
240  * type specifying the protocol for the conversation. Now we use an
241  * array of elements, with a CE_UINT value for the integer followed
242  * by a CE_CONVERSATION_TYPE value specifying the protocol for the
243  * converation.
244  *
245  * XXX - is there any reason why we shouldn't use an array of conversation
246  * elements, with the appropriate addresses and ports, instead of this
247  * structure? It would at least simplify find_conversation_pinfo() and
248  * find_or_create_conversation().
249  */
252 
253 WS_DLL_PUBLIC const address* conversation_key_addr1(const conversation_element_t *key);
254 WS_DLL_PUBLIC guint32 conversation_key_port1(const conversation_element_t *key);
255 WS_DLL_PUBLIC const address* conversation_key_addr2(const conversation_element_t *key);
256 WS_DLL_PUBLIC guint32 conversation_key_port2(const conversation_element_t *key);
257 
261 extern void conversation_init(void);
262 
266 extern void conversation_epan_reset(void);
267 
274 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_full(const guint32 setup_frame, conversation_element_t *elements);
275 
295 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new(const guint32 setup_frame, const address *addr1, const address *addr2,
296  const conversation_type ctype, const guint32 port1, const guint32 port2, const guint options);
297 
298 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *conversation_new_by_id(const guint32 setup_frame, const conversation_type ctype, const guint32 id);
299 
306 WS_DLL_PUBLIC conversation_t *find_conversation_full(const guint32 frame_num, conversation_element_t *elements);
307 
355 WS_DLL_PUBLIC conversation_t *find_conversation(const guint32 frame_num, const address *addr_a, const address *addr_b,
356  const conversation_type ctype, const guint32 port_a, const guint32 port_b, const guint options);
357 
358 WS_DLL_PUBLIC conversation_t *find_conversation_by_id(const guint32 frame, const conversation_type ctype, const guint32 id);
359 
363 WS_DLL_PUBLIC conversation_t *find_conversation_pinfo(packet_info *pinfo, const guint options);
364 
375 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *find_or_create_conversation(packet_info *pinfo);
376 
381 WS_DLL_PUBLIC WS_RETNONNULL conversation_t *find_or_create_conversation_by_id(packet_info *pinfo, const conversation_type ctype, const guint32 id);
382 
388 WS_DLL_PUBLIC void conversation_add_proto_data(conversation_t *conv, const int proto, void *proto_data);
389 
395 WS_DLL_PUBLIC void *conversation_get_proto_data(const conversation_t *conv, const int proto);
396 
401 WS_DLL_PUBLIC void conversation_delete_proto_data(conversation_t *conv, const int proto);
402 
403 WS_DLL_PUBLIC void conversation_set_dissector(conversation_t *conversation, const dissector_handle_t handle);
404 
405 WS_DLL_PUBLIC void conversation_set_dissector_from_frame_number(conversation_t *conversation,
406  const guint32 starting_frame_num, const dissector_handle_t handle);
407 
408 WS_DLL_PUBLIC dissector_handle_t conversation_get_dissector(conversation_t *conversation, const guint32 frame_num);
409 
421 WS_DLL_PUBLIC void conversation_set_conv_addr_port_endpoints(struct _packet_info *pinfo, address* addr1, address* addr2,
422  conversation_type ctype, guint32 port1, guint32 port2);
423 
432 WS_DLL_PUBLIC void conversation_set_elements_by_id(struct _packet_info *pinfo,
433  conversation_type ctype, guint32 id);
434 
443 WS_DLL_PUBLIC guint32 conversation_get_id_from_elements(struct _packet_info *pinfo,
444  conversation_type ctype, const guint options);
445 
456 WS_DLL_PUBLIC gboolean try_conversation_dissector(const address *addr_a, const address *addr_b, const conversation_type ctype,
457  const guint32 port_a, const guint32 port_b, tvbuff_t *tvb, packet_info *pinfo,
458  proto_tree *tree, void* data, const guint options);
459 
460 WS_DLL_PUBLIC gboolean try_conversation_dissector_by_id(const conversation_type ctype, const guint32 id, tvbuff_t *tvb,
461  packet_info *pinfo, proto_tree *tree, void* data);
462 
463 /* These routines are used to set undefined values for a conversation */
464 
470 WS_DLL_PUBLIC void conversation_set_port2(conversation_t *conv, const guint32 port);
471 
477 WS_DLL_PUBLIC void conversation_set_addr2(conversation_t *conv, const address *addr);
478 
485 WS_DLL_PUBLIC wmem_map_t *get_conversation_hashtables(void);
486 
487 /* Temporary function to handle port_type to conversation_type conversion
488  For now it's a 1-1 mapping, but the intention is to remove
489  many of the port_type instances in favor of conversation_type
490  */
491 WS_DLL_PUBLIC conversation_type conversation_pt_to_conversation_type(port_type pt);
492 
493 /* Temporary function to handle port_type to endpoint_type conversion
494  For now it's a 1-1 mapping, but the intention is to remove
495  many of the port_type instances in favor of endpoint_type
496  */
497 WS_DLL_PUBLIC endpoint_type conversation_pt_to_endpoint_type(port_type pt);
498 
499 #ifdef __cplusplus
500 }
501 #endif /* __cplusplus */
502 
503 #endif /* conversation.h */
void conversation_epan_reset(void)
Definition: conversation.c:543
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * find_or_create_conversation(packet_info *pinfo)
Definition: conversation.c:1752
WS_DLL_PUBLIC void conversation_set_port2(conversation_t *conv, const guint32 port)
Definition: conversation.c:912
struct conversation conversation_t
WS_DLL_PUBLIC wmem_map_t * get_conversation_hashtables(void)
Get a hash table of conversation hash table.
Definition: conversation.c:1846
WS_DLL_PUBLIC void conversation_set_addr2(conversation_t *conv, const address *addr)
Definition: conversation.c:956
WS_DLL_PUBLIC conversation_t * find_conversation(const guint32 frame_num, const address *addr_a, const address *addr_b, const conversation_type ctype, const guint32 port_a, const guint32 port_b, const guint options)
Definition: conversation.c:1147
WS_DLL_PUBLIC gboolean try_conversation_dissector(const address *addr_a, const address *addr_b, const conversation_type ctype, const guint32 port_a, const guint32 port_b, tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data, const guint options)
Definition: conversation.c:1612
WS_DLL_PUBLIC void * conversation_get_proto_data(const conversation_t *conv, const int proto)
Definition: conversation.c:1530
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * conversation_new_full(const guint32 setup_frame, conversation_element_t *elements)
Definition: conversation.c:670
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * conversation_new(const guint32 setup_frame, const address *addr1, const address *addr2, const conversation_type ctype, const guint32 port1, const guint32 port2, const guint options)
Definition: conversation.c:712
WS_DLL_PUBLIC conversation_t * find_conversation_full(const guint32 frame_num, conversation_element_t *elements)
Definition: conversation.c:1030
WS_DLL_PUBLIC void conversation_delete_proto_data(conversation_t *conv, const int proto)
Definition: conversation.c:1544
struct conversation_element conversation_element_t
WS_DLL_PUBLIC guint32 conversation_get_id_from_elements(struct _packet_info *pinfo, conversation_type ctype, const guint options)
Get the ID value from the conversation elements in the packet info.
Definition: conversation.c:1828
void conversation_init(void)
Definition: conversation.c:463
WS_DLL_PUBLIC WS_RETNONNULL conversation_t * find_or_create_conversation_by_id(packet_info *pinfo, const conversation_type ctype, const guint32 id)
Definition: conversation.c:1780
WS_DLL_PUBLIC void conversation_set_elements_by_id(struct _packet_info *pinfo, conversation_type ctype, guint32 id)
Definition: conversation.c:1818
conversation_element_type
Definition: conversation.h:155
WS_DLL_PUBLIC conversation_t * find_conversation_pinfo(packet_info *pinfo, const guint options)
Definition: conversation.c:1695
WS_DLL_PUBLIC void conversation_add_proto_data(conversation_t *conv, const int proto, void *proto_data)
Definition: conversation.c:1517
WS_DLL_PUBLIC void conversation_set_conv_addr_port_endpoints(struct _packet_info *pinfo, address *addr1, address *addr2, conversation_type ctype, guint32 port1, guint32 port2)
Definition: conversation.c:1798
Definition: address.h:55
Definition: packet_info.h:44
Definition: proto.h:897
Definition: wmem_map.c:44
Definition: wmem_tree-int.h:48
Definition: conversation.c:46
Definition: conversation.h:186
Definition: conversation.h:202
wmem_tree_t * dissector_tree
Definition: conversation.h:211
guint32 setup_frame
Definition: conversation.h:207
struct conversation * last
Definition: conversation.h:204
struct conversation * latest_found
Definition: conversation.h:205
guint32 last_frame
Definition: conversation.h:209
guint options
Definition: conversation.h:212
guint32 conv_index
Definition: conversation.h:206
wmem_tree_t * data_list
Definition: conversation.h:210
conversation_element_t * key_ptr
Definition: conversation.h:213
Definition: packet.c:762
Definition: tvbuff-int.h:35