epan/conversation.h

   1 /* conversation.h
   2  * Routines for building lists of packets that are part of a "conversation"
   3  *
   4  * $Id$
   5  *
   6  * Wireshark - Network traffic analyzer
   7  * By Gerald Combs <gerald@wireshark.org>
   8  * Copyright 1998 Gerald Combs
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU General Public License
  12  * as published by the Free Software Foundation; either version 2
  13  * of the License, or (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  23  */
  24
  25 #ifndef __CONVERSATION_H__
  26 #define __CONVERSATION_H__
  27
  28 #include "ws_symbol_export.h"
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif /* __cplusplus */
  33
  34 /**
  35  *@file
  36  */
  37 /*
  38  * Flags to pass to "conversation_new()" to indicate that the address 2
  39  * and/or port 2 values for the conversation should be wildcards.
  40  * The CONVERSATION_TEMPLATE option tells that any of the other supplied
  41  * port and / or address wildcards will be used to match an infinite number
  42  * of new connections to the conversation(s) that have the CONVERSATION_-
  43  * TEMPLATE flag set. Any conversation created without the CONVERSATION_-
  44  * TEMPLATE flag will be altered once the first connections (connection
  45  * oriented protocols only) to include the newly found information which
  46  * matched the wildcard options.
  47  */
  48 #define NO_ADDR2 0x01
  49 #define NO_PORT2 0x02
  50 #define NO_PORT2_FORCE 0x04
  51 #define CONVERSATION_TEMPLATE 0x08
  52
  53 /*
  54  * Flags to pass to "find_conversation()" to indicate that the address B
  55  * and/or port B search arguments are wildcards.
  56  */
  57 #define NO_ADDR_B 0x01
  58 #define NO_PORT_B 0x02
  59
  60 #include "packet.h"             /* for conversation dissector type */
  61
  62 /**
  63  * Data structure representing a conversation.
  64  */
  65 typedef struct conversation_key {
  66         struct conversation_key *next;
  67         address addr1;
  68         address addr2;
  69         port_type ptype;
  70         guint32 port1;
  71         guint32 port2;
  72 } conversation_key;
  73
  74 typedef struct conversation {
  75         struct conversation *next;      /** pointer to next conversation on hash chain */
  76         struct conversation *last;      /** pointer to the last conversation on hash chain */
  77         struct conversation *latest_found;
  78                                                                 /** pointer to the last conversation on hash chain */
  79         guint32 index;                          /** unique ID for conversation */
  80         guint32 setup_frame;            /** frame number that setup this conversation */
  81         /* Assume that setup_frame is also the lowest frame number for now. */
  82         guint32 last_frame;             /** highest frame number in this conversation */
  83         GSList *data_list;                      /** list of data associated with conversation */
  84         dissector_handle_t dissector_handle;
  85                                                                 /** handle for protocol dissector client associated with conversation */
  86         guint   options;                        /** wildcard flags */
  87         conversation_key *key_ptr;      /** pointer to the key for this conversation */
  88 } conversation_t;
  89
  90 /**
  91  * Destroy all existing conversations
  92  */
  93 extern void conversation_cleanup(void);
  94
  95 /**
  96  * Initialize some variables every time a file is loaded or re-loaded.
  97  * Create a new hash table for the conversations in the new file.
  98  */
  99 extern void conversation_init(void);
 100
 101 /*
 102  * Given two address/port pairs for a packet, create a new conversation
 103  * to contain packets between those address/port pairs.
 104  *
 105  * The options field is used to specify whether the address 2 value
 106  * and/or port 2 value are not given and any value is acceptable
 107  * when searching for this conversation.
 108  */
 109 WS_DLL_PUBLIC conversation_t *conversation_new(const guint32 setup_frame, const address *addr1, const address *addr2,
 110     const port_type ptype, const guint32 port1, const guint32 port2, const guint options);
 111
 112 /**
 113  * Given two address/port pairs for a packet, search for a conversation
 114  * containing packets between those address/port pairs.  Returns NULL if
 115  * not found.
 116  *
 117  * We try to find the most exact match that we can, and then proceed to
 118  * try wildcard matches on the "addr_b" and/or "port_b" argument if a more
 119  * exact match failed.
 120  *
 121  * Either or both of the "addr_b" and "port_b" arguments may be specified as
 122  * a wildcard by setting the NO_ADDR_B or NO_PORT_B flags in the "options"
 123  * argument.  We do only wildcard matches on addresses and ports specified
 124  * as wildcards.
 125  *
 126  * I.e.:
 127  *
 128  *      if neither "addr_b" nor "port_b" were specified as wildcards, we
 129  *      do an exact match (addr_a/port_a and addr_b/port_b) and, if that
 130  *      succeeds, we return a pointer to the matched conversation;
 131  *
 132  *      otherwise, if "port_b" wasn't specified as a wildcard, we try to
 133  *      match any address 2 with the specified port 2 (addr_a/port_a and
 134  *      {any}/addr_b) and, if that succeeds, we return a pointer to the
 135  *      matched conversation;
 136  *
 137  *      otherwise, if "addr_b" wasn't specified as a wildcard, we try to
 138  *      match any port 2 with the specified address 2 (addr_a/port_a and
 139  *      addr_b/{any}) and, if that succeeds, we return a pointer to the
 140  *      matched conversation;
 141  *
 142  *      otherwise, we try to match any address 2 and any port 2
 143  *      (addr_a/port_a and {any}/{any}) and, if that succeeds, we return
 144  *      a pointer to the matched conversation;
 145  *
 146  *      otherwise, we found no matching conversation, and return NULL.
 147  */
 148 WS_DLL_PUBLIC conversation_t *find_conversation(const guint32 frame_num, const address *addr_a, const address *addr_b,
 149     const port_type ptype, const guint32 port_a, const guint32 port_b, const guint options);
 150
 151 /**  A helper function that calls find_conversation() and, if a conversation is
 152  *  not found, calls conversation_new().
 153  *  The frame number and addresses are taken from pinfo.
 154  *  No options are used, though we could extend this API to include an options
 155  *  parameter.
 156  */
 157 WS_DLL_PUBLIC conversation_t *find_or_create_conversation(packet_info *pinfo);
 158
 159 WS_DLL_PUBLIC void conversation_add_proto_data(conversation_t *conv, const int proto,
 160     void *proto_data);
 161 WS_DLL_PUBLIC void *conversation_get_proto_data(const conversation_t *conv, const int proto);
 162 WS_DLL_PUBLIC void conversation_delete_proto_data(conversation_t *conv, const int proto);
 163
 164 WS_DLL_PUBLIC void conversation_set_dissector(conversation_t *conversation,
 165     const dissector_handle_t handle);
 166 /**
 167  * Given two address/port pairs for a packet, search for a matching
 168  * conversation and, if found and it has a conversation dissector,
 169  * call that dissector and return TRUE, otherwise return FALSE.
 170  *
 171  * This helper uses call_dissector_only which will NOT call the default
 172  * "data" dissector if the packet was rejected.
 173  * Our caller is responsible to call the data dissector explicitely in case
 174  * this function returns FALSE.
 175  */
 176 extern gboolean
 177 try_conversation_dissector(const address *addr_a, const address *addr_b, const port_type ptype,
 178     const guint32 port_a, const guint32 port_b, tvbuff_t *tvb, packet_info *pinfo,
 179     proto_tree *tree, void* data);
 180
 181 /* These routines are used to set undefined values for a conversation */
 182
 183 extern void conversation_set_port2(conversation_t *conv, const guint32 port);
 184 extern void conversation_set_addr2(conversation_t *conv, const address *addr);
 185
 186 WS_DLL_PUBLIC
 187 GHashTable *get_conversation_hashtable_exact(void);
 188
 189 WS_DLL_PUBLIC
 190 GHashTable *get_conversation_hashtable_no_addr2(void);
 191
 192 WS_DLL_PUBLIC
 193 GHashTable * get_conversation_hashtable_no_port2(void);
 194
 195 WS_DLL_PUBLIC
 196 GHashTable *get_conversation_hashtable_no_addr2_or_port2(void);
 197
 198
 199 #ifdef __cplusplus
 200 }
 201 #endif /* __cplusplus */
 202
 203 #endif /* conversation.h */