2 * Routines for building lists of packets that are part of a "conversation"
4 * Wireshark - Network traffic analyzer
5 * By Gerald Combs <gerald@wireshark.org>
6 * Copyright 1998 Gerald Combs
8 * SPDX-License-Identifier: GPL-2.0-or-later
11 #ifndef __CONVERSATION_H__
12 #define __CONVERSATION_H__
14 #include "ws_symbol_export.h"
18 #endif /* __cplusplus */
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.
36 #define NO_PORT2_FORCE 0x04
37 #define CONVERSATION_TEMPLATE 0x08
40 * Flags to pass to "find_conversation()" to indicate that the address B
41 * and/or port B search arguments are wildcards.
43 #define NO_ADDR_B 0x01
44 #define NO_PORT_B 0x02
46 /* Flags to handle endpoints */
47 #define USE_LAST_ENDPOINT 0x08 /* Use last endpoint created, regardless of type */
49 #include "packet.h" /* for conversation dissector type */
51 /* Types of port numbers Wireshark knows about. */
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 */
67 ENDPOINT_IBQP, /* Infiniband QP number */
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 */
84 * Data structure representing a conversation.
86 struct conversation_key;
87 typedef struct conversation_key* conversation_key_t;
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 */
107 typedef struct endpoint* endpoint_t;
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);
115 * Create a new hash tables for conversations.
117 extern void conversation_init(void);
120 * Initialize some variables every time a file is loaded or re-loaded.
122 extern void conversation_epan_reset(void);
125 * Given two address/port pairs for a packet, create a new conversation
126 * to contain packets between those address/port pairs.
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.
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);
135 WS_DLL_PUBLIC conversation_t *conversation_new_by_id(const guint32 setup_frame, const endpoint_type etype, const guint32 id, const guint options);
138 * Given two address/port pairs for a packet, search for a conversation
139 * containing packets between those address/port pairs. Returns NULL if
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.
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
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;
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;
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;
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;
171 * otherwise, we found no matching conversation, and return NULL.
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);
176 WS_DLL_PUBLIC conversation_t *find_conversation_by_id(const guint32 frame, const endpoint_type etype, const guint32 id, const guint options);
178 /** A helper function that calls find_conversation() using data from pinfo
179 * The frame number and addresses are taken from pinfo.
181 WS_DLL_PUBLIC conversation_t *find_conversation_pinfo(packet_info *pinfo, const guint options);
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
189 WS_DLL_PUBLIC conversation_t *find_or_create_conversation(packet_info *pinfo);
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.
195 WS_DLL_PUBLIC conversation_t *find_or_create_conversation_by_id(packet_info *pinfo, const endpoint_type etype, const guint32 id);
197 WS_DLL_PUBLIC void conversation_add_proto_data(conversation_t *conv, const int proto,
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);
202 WS_DLL_PUBLIC void conversation_set_dissector(conversation_t *conversation,
203 const dissector_handle_t handle);
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);
208 WS_DLL_PUBLIC dissector_handle_t conversation_get_dissector(conversation_t *conversation,
209 const guint32 frame_num);
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);
214 WS_DLL_PUBLIC void conversation_create_endpoint_by_id(struct _packet_info *pinfo,
215 endpoint_type etype, guint32 id, const guint options);
217 WS_DLL_PUBLIC guint32 conversation_get_endpoint_by_id(struct _packet_info *pinfo,
218 endpoint_type etype, const guint options);
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.
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.
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);
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);
239 /* These routines are used to set undefined values for a conversation */
242 void conversation_set_port2(conversation_t *conv, const guint32 port);
244 void conversation_set_addr2(conversation_t *conv, const address *addr);
247 wmem_map_t *get_conversation_hashtable_exact(void);
250 wmem_map_t *get_conversation_hashtable_no_addr2(void);
253 wmem_map_t * get_conversation_hashtable_no_port2(void);
256 wmem_map_t *get_conversation_hashtable_no_addr2_or_port2(void);
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
263 endpoint_type conversation_pt_to_endpoint_type(port_type pt);
266 conversation_hash_exact(gconstpointer v);
268 /* Provide a wmem_alloced (NULL scope) hash string using HTML tags */
270 conversation_get_html_hash(const conversation_key_t key);
274 #endif /* __cplusplus */
276 #endif /* conversation.h */