From a96e6b2047cce1c671f476ae26c81ee8afb7ca12 Mon Sep 17 00:00:00 2001 From: Anders Broman Date: Sat, 28 Aug 2010 19:27:19 +0000 Subject: Doxygen changes. svn path=/trunk/; revision=33981 --- epan/conversation.h | 87 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 79 insertions(+), 8 deletions(-) (limited to 'epan/conversation.h') diff --git a/epan/conversation.h b/epan/conversation.h index 2329b261b4..c330ce7fb9 100644 --- a/epan/conversation.h +++ b/epan/conversation.h @@ -29,6 +29,9 @@ extern "C" { #endif /* __cplusplus */ +/** + *@file + */ /* * Flags to pass to "conversation_new()" to indicate that the address 2 * and/or port 2 values for the conversation should be wildcards. @@ -54,7 +57,7 @@ extern "C" { #include "packet.h" /* for conversation dissector type */ -/* +/** * Data structure representing a conversation. */ typedef struct conversation_key { @@ -67,25 +70,83 @@ typedef struct conversation_key { } conversation_key; typedef struct conversation { - struct conversation *next; /* pointer to next conversation on hash chain */ - guint32 index; /* unique ID for conversation */ - guint32 setup_frame; /* frame number that setup this conversation */ - GSList *data_list; /* list of data associated with conversation */ + struct conversation *next; /** pointer to next conversation on hash chain */ + guint32 index; /** unique ID for conversation */ + guint32 setup_frame; /** frame number that setup this conversation */ + GSList *data_list; /** list of data associated with conversation */ dissector_handle_t dissector_handle; - /* handle for protocol dissector client associated with conversation */ - guint options; /* wildcard flags */ - conversation_key *key_ptr; /* pointer to the key for this conversation */ + /** handle for protocol dissector client associated with conversation */ + guint options; /** wildcard flags */ + conversation_key *key_ptr; /** pointer to the key for this conversation */ } conversation_t; +/** + * Destroy all existing conversations + */ extern void conversation_cleanup(void); + +/** + * Initialize some variables every time a file is loaded or re-loaded. + * Create a new hash table for the conversations in the new file. + */ extern void conversation_init(void); +/* + * Given two address/port pairs for a packet, create a new conversation + * to contain packets between those address/port pairs. + * + * The options field is used to specify whether the address 2 value + * and/or port 2 value are not given and any value is acceptable + * when searching for this conversation. + */ extern conversation_t *conversation_new(const guint32 setup_frame, const address *addr1, const address *addr2, const port_type ptype, const guint32 port1, const guint32 port2, const guint options); +/** + * Given two address/port pairs for a packet, search for a conversation + * containing packets between those address/port pairs. Returns NULL if + * not found. + * + * We try to find the most exact match that we can, and then proceed to + * try wildcard matches on the "addr_b" and/or "port_b" argument if a more + * exact match failed. + * + * Either or both of the "addr_b" and "port_b" arguments may be specified as + * a wildcard by setting the NO_ADDR_B or NO_PORT_B flags in the "options" + * argument. We do only wildcard matches on addresses and ports specified + * as wildcards. + * + * I.e.: + * + * if neither "addr_b" nor "port_b" were specified as wildcards, we + * do an exact match (addr_a/port_a and addr_b/port_b) and, if that + * succeeds, we return a pointer to the matched conversation; + * + * otherwise, if "port_b" wasn't specified as a wildcard, we try to + * match any address 2 with the specified port 2 (addr_a/port_a and + * {any}/addr_b) and, if that succeeds, we return a pointer to the + * matched conversation; + * + * otherwise, if "addr_b" wasn't specified as a wildcard, we try to + * match any port 2 with the specified address 2 (addr_a/port_a and + * addr_b/{any}) and, if that succeeds, we return a pointer to the + * matched conversation; + * + * otherwise, we try to match any address 2 and any port 2 + * (addr_a/port_a and {any}/{any}) and, if that succeeds, we return + * a pointer to the matched conversation; + * + * otherwise, we found no matching conversation, and return NULL. + */ extern conversation_t *find_conversation(const guint32 frame_num, const address *addr_a, const address *addr_b, const port_type ptype, const guint32 port_a, const guint32 port_b, const guint options); +/** A helper function that calls find_conversation() and, if a conversation is + * not found, calls conversation_new(). + * The frame number and addresses are taken from pinfo. + * No options are used, though we could extend this API to include an options + * parameter. + */ extern conversation_t *find_or_create_conversation(packet_info *pinfo); extern void conversation_add_proto_data(conversation_t *conv, const int proto, @@ -95,6 +156,16 @@ extern void conversation_delete_proto_data(conversation_t *conv, const int proto extern void conversation_set_dissector(conversation_t *conversation, const dissector_handle_t handle); +/** + * Given two address/port pairs for a packet, search for a matching + * conversation and, if found and it has a conversation dissector, + * call that dissector and return TRUE, otherwise return FALSE. + * + * This helper uses call_dissector_only which will NOT call the default + * "data" dissector if the packet was rejected. + * Our caller is responsible to call the data dissector explicitely in case + * this function returns FALSE. + */ extern gboolean try_conversation_dissector(const address *addr_a, const address *addr_b, const port_type ptype, const guint32 port_a, const guint32 port_b, tvbuff_t *tvb, packet_info *pinfo, -- cgit v1.2.3