From a96e6b2047cce1c671f476ae26c81ee8afb7ca12 Mon Sep 17 00:00:00 2001 From: Anders Broman Date: Sat, 28 Aug 2010 19:27:19 +0000 Subject: [PATCH] Doxygen changes. svn path=/trunk/; revision=33981 --- epan/circuit.h | 46 +++++++++++++++----- epan/conversation.h | 87 ++++++++++++++++++++++++++++++++++---- epan/crypt/crypt-md5.h | 2 +- epan/dissector_filters.h | 8 ++-- epan/except.h | 4 +- epan/frame_data.h | 56 ++++++++++++------------ epan/ipv6-utils.h | 6 +-- epan/oids.h | 8 ++-- epan/prefs-int.h | 76 ++++++++++++++++++++------------- epan/proto.h | 37 ++++++++-------- epan/range.h | 61 +++++++++++++++++++++++--- epan/tcap-persistentdata.h | 37 +++++++++++++--- epan/wslua/init_wslua.h | 7 ++- epan/wslua/wslua.h | 16 ++++--- 14 files changed, 330 insertions(+), 121 deletions(-) diff --git a/epan/circuit.h b/epan/circuit.h index cd262b1318..a937aa437a 100644 --- a/epan/circuit.h +++ b/epan/circuit.h @@ -31,7 +31,7 @@ extern "C" { #endif /* __cplusplus */ -/* +/** * Data structure representing a circuit. */ typedef struct circuit_key { @@ -40,26 +40,46 @@ typedef struct circuit_key { } circuit_key; typedef struct circuit { - struct circuit *next; /* pointer to next circuit with given circuit ID */ - guint32 first_frame; /* # of first frame for that circuit */ - guint32 last_frame; /* # of last frame for that circuit */ - guint32 index; /* unique ID for circuit */ - GSList *data_list; /* list of data associated with circuit */ - dissector_handle_t dissector_handle; - /* handle for protocol dissector client associated with circuit */ - guint options; /* wildcard flags */ - circuit_key *key_ptr; /* pointer to the key for this circuit */ + struct circuit *next; /**< pointer to next circuit with given circuit ID */ + guint32 first_frame; /**< # of first frame for that circuit */ + guint32 last_frame; /**< # of last frame for that circuit */ + guint32 index; /**< unique ID for circuit */ + GSList *data_list; /**< list of data associated with circuit */ + dissector_handle_t dissector_handle; /**< handle for protocol dissector client associated with circuit */ + guint options; /**< wildcard flags */ + circuit_key *key_ptr; /**< pointer to the key for this circuit */ } circuit_t; +/** + * Destroy all existing circuits. + */ extern void circuit_cleanup(void); + +/** + * Initialize some variables every time a file is loaded or re-loaded. + * Create a new hash table for the circuits in the new file. + */ extern void circuit_init(void); +/** + * Given a circuit type and circuit ID for a packet, create a new circuit + * to contain packets for that circuit. + */ extern circuit_t *circuit_new(circuit_type ctype, guint32 circuit_id, guint32 first_frame); +/** + * Given a circuit type and ID, and a frame number, search for a circuit with + * that type and ID whose range of frames includes that frame number. + * Returns NULL if not found. + */ extern circuit_t *find_circuit(circuit_type ctype, guint32 circuit_id, guint32 frame); +/** + * Set the last frame of a circuit, if it's not already known, + * "closing" the circuit. + */ extern void close_circuit(circuit_t *circuit, guint32 last_frame); extern void circuit_add_proto_data(circuit_t *conv, int proto, @@ -70,6 +90,12 @@ extern void circuit_delete_proto_data(circuit_t *conv, int proto); extern void circuit_set_dissector(circuit_t *circuit, dissector_handle_t handle); extern dissector_handle_t circuit_get_dissector(circuit_t *circuit); + +/** + * Given a circuit type and ID for a packet, search for a matching + * circuit and, if found and it has a circuit dissector, + * call that dissector and return TRUE, otherwise return FALSE. + */ extern gboolean try_circuit_dissector(circuit_type ctype, guint32 circuit_id, guint32 frame, tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree); 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, diff --git a/epan/crypt/crypt-md5.h b/epan/crypt/crypt-md5.h index 342a1bdda5..f10da7e707 100644 --- a/epan/crypt/crypt-md5.h +++ b/epan/crypt/crypt-md5.h @@ -18,7 +18,7 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -#ifndef __MD5_H__ /* Should this be _CRYPT_MD5_H__ ?*/ +#ifndef __MD5_H__ /**@todo Should this be _CRYPT_MD5_H__ ?*/ #define __MD5_H__ /** diff --git a/epan/dissector_filters.h b/epan/dissector_filters.h index b19a8135cc..12807627fd 100644 --- a/epan/dissector_filters.h +++ b/epan/dissector_filters.h @@ -30,15 +30,17 @@ extern "C" { #endif /* __cplusplus */ +/** @file + */ -/* callback function definition: is a filter available for this packet? */ +/** callback function definition: is a filter available for this packet? */ typedef gboolean (*is_filter_valid_func)(packet_info *pinfo); -/* callback function definition: return the available filter for this packet or NULL if no filter is available */ +/** callback function definition: return the available filter for this packet or NULL if no filter is available */ typedef const gchar* (*build_filter_string_func)(packet_info *pinfo); -/* register a dissector filter */ +/** register a dissector filter */ extern void register_dissector_filter(const char *name, is_filter_valid_func is_filter_valid, build_filter_string_func build_filter_string); diff --git a/epan/except.h b/epan/except.h index 363589417d..cacd7cbae2 100644 --- a/epan/except.h +++ b/epan/except.h @@ -18,7 +18,9 @@ * $Name: $ */ -/* +/** + * @file + * Portable Exception Handling for ANSI C.
* Modified to support throwing an exception with a null message pointer, * and to have the message not be const (as we generate messages with * "g_strdup_sprintf()", which means they need to be freed; using diff --git a/epan/frame_data.h b/epan/frame_data.h index 85161e7d70..950b90de0a 100644 --- a/epan/frame_data.h +++ b/epan/frame_data.h @@ -36,43 +36,43 @@ should we keep that stuff in the "packet_info" structure, instead, to save memory? */ -/* The frame number is the ordinal number of the frame in the capture, so +/** The frame number is the ordinal number of the frame in the capture, so it's 1-origin. In various contexts, 0 as a frame number means "frame number unknown". */ typedef struct _frame_data { - struct _frame_data *next; /* Next element in list */ - struct _frame_data *prev; /* Previous element in list */ - GSList *pfd; /* Per frame proto data */ - guint32 num; /* Frame number */ - guint32 pkt_len; /* Packet length */ - guint32 cap_len; /* Amount actually captured */ - guint32 cum_bytes; /* Cumulative bytes into the capture */ - gint64 file_off; /* File offset */ - guint16 subnum; /* subframe number, for protocols that require this */ - gint16 lnk_t; /* Per-packet encapsulation/data-link type */ + struct _frame_data *next; /** Next element in list */ + struct _frame_data *prev; /** Previous element in list */ + GSList *pfd; /** Per frame proto data */ + guint32 num; /** Frame number */ + guint32 pkt_len; /** Packet length */ + guint32 cap_len; /** Amount actually captured */ + guint32 cum_bytes; /** Cumulative bytes into the capture */ + gint64 file_off; /** File offset */ + guint16 subnum; /** subframe number, for protocols that require this */ + gint16 lnk_t; /** Per-packet encapsulation/data-link type */ struct { - unsigned int passed_dfilter : 1; /* 1 = display, 0 = no display */ - unsigned int encoding : 2; /* Character encoding (ASCII, EBCDIC...) */ - unsigned int visited : 1; /* Has this packet been visited yet? 1=Yes,0=No*/ - unsigned int marked : 1; /* 1 = marked by user, 0 = normal */ - unsigned int ref_time : 1; /* 1 = marked as a reference time frame, 0 = normal */ - unsigned int ignored : 1; /* 1 = ignore this frame, 0 = normal */ + unsigned int passed_dfilter : 1; /** 1 = display, 0 = no display */ + unsigned int encoding : 2; /** Character encoding (ASCII, EBCDIC...) */ + unsigned int visited : 1; /** Has this packet been visited yet? 1=Yes,0=No*/ + unsigned int marked : 1; /** 1 = marked by user, 0 = normal */ + unsigned int ref_time : 1; /** 1 = marked as a reference time frame, 0 = normal */ + unsigned int ignored : 1; /** 1 = ignore this frame, 0 = normal */ } flags; - const void *color_filter; /* Per-packet matching color_filter_t object */ + const void *color_filter; /** Per-packet matching color_filter_t object */ - nstime_t abs_ts; /* Absolute timestamp */ - nstime_t rel_ts; /* Relative timestamp (yes, it can be negative) */ - nstime_t del_dis_ts; /* Delta timestamp to previous displayed frame (yes, it can be negative) */ - nstime_t del_cap_ts; /* Delta timestamp to previous captured frame (yes, it can be negative) */ + nstime_t abs_ts; /** Absolute timestamp */ + nstime_t rel_ts; /** Relative timestamp (yes, it can be negative) */ + nstime_t del_dis_ts; /** Delta timestamp to previous displayed frame (yes, it can be negative) */ + nstime_t del_cap_ts; /** Delta timestamp to previous captured frame (yes, it can be negative) */ #ifdef NEW_PACKET_LIST - gchar **col_text; /* The column text for some columns, see colum_utils */ - guint *col_text_len; /* The length of the column text strings in 'col_text' */ + gchar **col_text; /** The column text for some columns, see colum_utils */ + guint *col_text_len; /** The length of the column text strings in 'col_text' */ #endif } frame_data; -/* +/** * A data source. * Has a tvbuff and a name. */ @@ -88,7 +88,7 @@ extern void p_add_proto_data(frame_data *fd, int proto, void *proto_data); extern void *p_get_proto_data(frame_data *fd, int proto); extern void p_remove_proto_data(frame_data *fd, int proto); -/* compare two frame_datas */ +/** compare two frame_datas */ extern gint frame_data_compare(const frame_data *fdata1, const frame_data *fdata2, int field); extern void frame_data_cleanup(frame_data *fdata); @@ -96,7 +96,9 @@ extern void frame_data_cleanup(frame_data *fdata); extern void frame_data_init(frame_data *fdata, guint32 num, const struct wtap_pkthdr *phdr, gint64 offset, guint32 cum_bytes); - +/** + * Sets the frame data struct values before dissection. + */ extern void frame_data_set_before_dissect(frame_data *fdata, nstime_t *elapsed_time, nstime_t *first_ts, diff --git a/epan/ipv6-utils.h b/epan/ipv6-utils.h index 85012102b0..b1d300d9a7 100644 --- a/epan/ipv6-utils.h +++ b/epan/ipv6-utils.h @@ -29,10 +29,10 @@ #define __IPV6_UTILS_H__ struct e_in6_addr { - guint8 bytes[16]; /* 128 bit IP6 address */ + guint8 bytes[16]; /** 128 bit IP6 address */ }; -/* +/** * Unicast Scope * Note that we must check topmost 10 bits only, not 16 bits (see RFC2373). */ @@ -41,7 +41,7 @@ struct e_in6_addr { #define E_IN6_IS_ADDR_SITELOCAL(a) \ (((a)->bytes[0] == 0xfe) && (((a)->bytes[1] & 0xc0) == 0xc0)) -/* +/** * Multicast */ #define E_IN6_IS_ADDR_MULTICAST(a) ((a)->bytes[0] == 0xff) diff --git a/epan/oids.h b/epan/oids.h index 328cd813f8..285a3a5537 100644 --- a/epan/oids.h +++ b/epan/oids.h @@ -28,7 +28,9 @@ #define __OIDS_H__ #include - +/** + *@file + */ #define BER_TAG_ANY -1 struct _oid_bit_t { @@ -102,10 +104,10 @@ typedef struct _oid_info_t { struct _oid_info_t* parent; } oid_info_t; -/* init funcion called from epan.h */ +/** init funcion called from epan.h */ extern void oids_init(void); -/* init funcion called from epan.h */ +/** init funcion called from epan.h */ extern void oids_cleanup(void); /* diff --git a/epan/prefs-int.h b/epan/prefs-int.h index 10c491d10e..199c480c2e 100644 --- a/epan/prefs-int.h +++ b/epan/prefs-int.h @@ -28,26 +28,31 @@ #include +/** + *@file + */ + struct pref_module { - const char *name; /* name of module */ - const char *title; /* title of module (displayed in preferences list) */ - const char *description;/* Description of module (displayed in preferences notebook) */ - void (*apply_cb)(void); /* routine to call when preferences applied */ - GList *prefs; /* list of its preferences */ - emem_tree_t *submodules;/* list of its submodules */ - int numprefs; /* number of non-obsolete preferences */ - gboolean prefs_changed; /* if TRUE, a preference has changed since we last checked */ - gboolean obsolete; /* if TRUE, this is a module that used to - exist but no longer does */ + const char *name; /** name of module */ + const char *title; /** title of module (displayed in preferences list) */ + const char *description; /** Description of module (displayed in preferences notebook) */ + void (*apply_cb)(void); /** routine to call when preferences applied */ + GList *prefs; /** list of its preferences */ + emem_tree_t *submodules; /** list of its submodules */ + int numprefs; /** number of non-obsolete preferences */ + gboolean prefs_changed; /** if TRUE, a preference has changed since we last checked */ + gboolean obsolete; /** if TRUE, this is a module that used to + * exist but no longer does + */ }; -/* +/** * Module used for protocol preferences. * With MSVC and a libwireshark.dll, we need a special declaration. */ WS_VAR_IMPORT module_t *protocols_module; -/* +/** * PREF_OBSOLETE is used for preferences that a module used to support * but no longer supports; we give different error messages for them. */ @@ -62,12 +67,13 @@ typedef enum { PREF_OBSOLETE } pref_type_t; +/** Struct to hold preference data */ struct preference { - const char *name; /* name of preference */ - const char *title; /* title to use in GUI */ - const char *description; /* human-readable description of preference */ - int ordinal; /* ordinal number of this preference */ - pref_type_t type; /* type of that preference */ + const char *name; /** name of preference */ + const char *title; /** title to use in GUI */ + const char *description; /** human-readable description of preference */ + int ordinal; /** ordinal number of this preference */ + pref_type_t type; /** type of that preference */ union { guint *uint; gboolean *boolp; @@ -75,39 +81,49 @@ struct preference { const char **string; range_t **range; void* uat; - } varp; /* pointer to variable storing the value */ + } varp; /** pointer to variable storing the value */ union { guint uint; gboolean boolval; gint enumval; char *string; range_t *range; - } saved_val; /* original value, when editing from the GUI */ + } saved_val; /** original value, when editing from the GUI */ union { guint uint; gboolean boolval; gint enumval; char *string; range_t *range; - } default_val; /* the default value of the preference */ + } default_val; /** the default value of the preference */ union { - guint base; /* input/output base, for PREF_UINT */ - guint32 max_value; /* maximum value of a range */ + guint base; /** input/output base, for PREF_UINT */ + guint32 max_value; /** maximum value of a range */ struct { - const enum_val_t *enumvals; /* list of name & values */ - gboolean radio_buttons; /* TRUE if it should be shown as - radio buttons rather than as an - option menu or combo box in - the preferences tab */ - } enum_info; /* for PREF_ENUM */ - } info; /* display/text file information */ - void *control; /* handle for GUI control for this preference */ + const enum_val_t *enumvals; /** list of name & values */ + gboolean radio_buttons; /** TRUE if it should be shown as + radio buttons rather than as an + option menu or combo box in + the preferences tab */ + } enum_info; /** for PREF_ENUM */ + } info; /** display/text file information */ + void *control; /** handle for GUI control for this preference */ }; /* read_prefs_file: read in a generic config file and do a callback to */ /* pref_set_pair_fct() for every key/value pair found */ +/** + * Given a string of the form ":", as might appear + * as an argument to a "-o" option, parse it and set the preference in + * question. + * @return an indication of whether it succeeded or failed + * in some fashion. + */ typedef prefs_set_pref_e (*pref_set_pair_cb) (gchar *key, gchar *value, void *private_data); +/** read the preferences file (or similiar) and call the callback + * function to set each key/value pair found + */ int read_prefs_file(const char *pf_path, FILE *pf, pref_set_pair_cb pref_set_pair_fct, void *private_data); diff --git a/epan/proto.h b/epan/proto.h index f49f17866c..98465ba2cf 100644 --- a/epan/proto.h +++ b/epan/proto.h @@ -204,7 +204,7 @@ typedef struct _protocol protocol_t; /* For integral types, the display format is a base_display_e value * possibly ORed with BASE_RANGE_STRING. */ -/* BASE_DISPLAY_E_MASK selects the base_display_e value. Its current +/** BASE_DISPLAY_E_MASK selects the base_display_e value. Its current * value means that we may have at most 16 base_display_e values. */ #define BASE_DISPLAY_E_MASK 0x0F @@ -224,7 +224,7 @@ typedef enum { #define BASE_RANGE_STRING 0x10 #define BASE_EXT_STRING 0x20 -/* BASE_ values that cause the field value to be displayed twice */ +/** BASE_ values that cause the field value to be displayed twice */ #define IS_BASE_DUAL(b) ((b)==BASE_DEC_HEX||(b)==BASE_HEX_DEC) /* For FT_ABSOLUTE_TIME, the display format is an absolute_time_display_e @@ -245,7 +245,7 @@ struct _header_field_info { const char *name; /**< full name of this field */ const char *abbrev; /**< abbreviated name of this field */ enum ftenum type; /**< field type, one of FT_ (from ftypes.h) */ - int display; /**< one of BASE_, or field bit-width if FT_BOOLEAN and non-zero bitmask */ + int display; /**< one of BASE_, or field bit-width if FT_BOOLEAN and non-zero bitmask */ const void *strings; /**< value_string, range_string or true_false_string, typically converted by VALS(), RVALS() or TFS(). If this is an FT_PROTOCOL then it points to the @@ -254,10 +254,10 @@ struct _header_field_info { const char *blurb; /**< Brief description of field */ /* ------- set by proto routines (prefilled by HFILL macro, see below) ------ */ - int id; /**< Field ID */ - int parent; /**< parent protocol tree */ - hf_ref_type ref_type; /**< is this field referenced by a filter */ - int bitshift; /**< bits to shift */ + int id; /**< Field ID */ + int parent; /**< parent protocol tree */ + hf_ref_type ref_type; /**< is this field referenced by a filter */ + int bitshift; /**< bits to shift */ header_field_info *same_name_next; /**< Link to next hfinfo with same abbrev */ header_field_info *same_name_prev; /**< Link to previous hfinfo with same abbrev */ }; @@ -271,8 +271,8 @@ struct _header_field_info { /** Used when registering many fields at once, using proto_register_field_array() */ typedef struct hf_register_info { - int *p_id; /**< written to by register() function */ - header_field_info hfinfo; /**< the field info to be registered */ + int *p_id; /**< written to by register() function */ + header_field_info hfinfo; /**< the field info to be registered */ } hf_register_info; @@ -287,15 +287,15 @@ typedef struct _item_label_t { /** Contains the field information for the proto_item. */ typedef struct field_info { header_field_info *hfinfo; /**< pointer to registered field information */ - gint start; /**< current start of data in field_info.ds_tvb */ - gint length; /**< current data length of item in field_info.ds_tvb */ - gint appendix_start; /**< start of appendix data */ - gint appendix_length; /**< length of appendix data */ - gint tree_type; /**< one of ETT_ or -1 */ + gint start; /**< current start of data in field_info.ds_tvb */ + gint length; /**< current data length of item in field_info.ds_tvb */ + gint appendix_start; /**< start of appendix data */ + gint appendix_length; /**< length of appendix data */ + gint tree_type; /**< one of ETT_ or -1 */ item_label_t *rep; /**< string for GUI tree */ - guint32 flags; /**< bitfield like FI_GENERATED, ... */ - tvbuff_t *ds_tvb; /**< data source tvbuff */ - fvalue_t value; + guint32 flags; /**< bitfield like FI_GENERATED, ... */ + tvbuff_t *ds_tvb; /**< data source tvbuff */ + fvalue_t value; } field_info; @@ -306,7 +306,7 @@ typedef struct field_info { /** The protocol field should not be shown in the tree (it's used for filtering only), * used in field_info.flags. */ -/* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! +/** HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! A user cannot tell by looking at the packet detail that the field exists and that they can filter on its value. */ #define FI_HIDDEN 0x00000001 @@ -442,6 +442,7 @@ typedef gboolean (*proto_tree_traverse_func)(proto_node *, gpointer); extern gboolean proto_tree_traverse_post_order(proto_tree *tree, proto_tree_traverse_func func, gpointer data); + extern void proto_tree_children_foreach(proto_tree *tree, proto_tree_foreach_func func, gpointer data); diff --git a/epan/range.h b/epan/range.h index 1d10801bd8..1022e7b321 100644 --- a/epan/range.h +++ b/epan/range.h @@ -30,7 +30,11 @@ #include -/* XXX where's the best place for these? */ +/** @file + * Range strings a variant of value_strings + */ + +/**@todo where's the best place for these? */ #define MAX_SCTP_PORT 65535 #define MAX_TCP_PORT 65535 #define MAX_UDP_PORT 65535 @@ -41,13 +45,13 @@ typedef struct range_admin_tag { guint32 high; } range_admin_t; +/** user specified range(s) */ typedef struct range { - /* user specified range(s) */ - guint nranges; /* number of entries in ranges */ - range_admin_t ranges[1]; /* variable-length array */ + guint nranges; /**< number of entries in ranges */ + range_admin_t ranges[1]; /**< variable-length array */ } range_t; -/* +/** * Return value from range_convert_str(). */ typedef enum { @@ -58,17 +62,64 @@ typedef enum { extern range_t *range_empty(void); + +/*** Converts a range string to a fast comparable array of ranges. + * This function allocates a range_t large enough to hold the number + * of ranges specified, and fills the array range->ranges containing + * low and high values with the number of ranges being range->nranges. + * After having called this function, the function value_is_in_range() + * determines whether a given number is within the range or not.
+ * In case of a single number, we make a range where low is equal to high. + * We take care on wrongly entered ranges; opposite order will be taken + * care of. + * + * The following syntax is accepted : + * + * 1-20,30-40 Range from 1 to 20, and packets 30 to 40 + * -20,30 Range from 1 to 20, and packet 30 + * 20,30,40- 20, 30, and the range from 40 to the end + * 20-10,30-25 Range from 10 to 20, and from 25 to 30 + * - All values + * @param range the range + * @param es points to the string to be converted. + * @param max_value' specifies the maximum value in a range. + * @return + */ extern convert_ret_t range_convert_str(range_t **range, const gchar *es, guint32 max_value); +/** This function returns TRUE if a given value is within one of the ranges + * stored in the ranges array. + * @param range the range + * @param val the value to check + * @return TRUE if the value is in range + */ extern gboolean value_is_in_range(range_t *range, guint32 val); +/** This function returns TRUE if the two given range_t's are equal. + * @param a first range + * @param b second range + * @return TRUE if the value is in range + */ extern gboolean ranges_are_equal(range_t *a, range_t *b); +/** This function calls the provided callback function for each value in + * in the range. + * @param range the range + * @param val value + */ extern void range_foreach(range_t *range, void (*callback)(guint32 val)); +/** + * This function converts a range_t to a (ep_alloc()-allocated) string. + */ extern char *range_convert_range(range_t *range); +/** + * Create a copy of a range. + * @param src the range to copy + * @return ep allocated copy of the range + */ extern range_t *range_copy(range_t *src); #endif /* __RANGE_H__ */ diff --git a/epan/tcap-persistentdata.h b/epan/tcap-persistentdata.h index b55cf21d22..42c58b4e64 100644 --- a/epan/tcap-persistentdata.h +++ b/epan/tcap-persistentdata.h @@ -31,6 +31,10 @@ #include #include #include +/** @file + * lists and hash tables used in wireshark's tcap dissector + * for calculation of delays in tcap-calls + */ #define LENGTH_OID 23 struct tcaphash_context_t { @@ -38,9 +42,9 @@ struct tcaphash_context_t { guint32 session_id; guint32 first_frame; guint32 last_frame; - nstime_t begin_time; /* time of arrival of TC_BEGIN */ - nstime_t end_time; /* time of closing message */ - gboolean responded; /* true, if request has been responded */ + nstime_t begin_time; /**< time of arrival of TC_BEGIN */ + nstime_t end_time; /**< time of closing message */ + gboolean responded; /**< true, if request has been responded */ gboolean closed; gboolean upper_dissector; gboolean oid_present; @@ -86,7 +90,7 @@ struct tcaphash_ansicall_t { struct tcaphash_ansicall_t * previous_ansicall; }; -/* The Key for the hash table is the TCAP origine transaction identifier +/** The Key for the hash table is the TCAP origine transaction identifier of the TC_BEGIN containing the InitialDP */ struct tcaphash_context_key_t { @@ -123,7 +127,7 @@ struct tcaphash_ansi_info_key_t { }; -/* List of infos to store for the analyse */ +/** List of infos to store for the analyse */ struct tcapsrt_info_t { guint32 tcap_session_id; guint32 src_tid; @@ -131,13 +135,36 @@ struct tcapsrt_info_t { guint8 ope; }; +/** + * Routine called when the TAP is initialized. + * so hash table are (re)created + */ void tcapsrt_init_routine(void); +/** + * Initialize the Message Info used by the main dissector + * Data are linked to a TCAP transaction + */ struct tcapsrt_info_t * tcapsrt_razinfo(void); void tcapsrt_close(struct tcaphash_context_t * p_tcaphash_context, packet_info * pinfo _U_); +/** + * Service Response Time analyze + * Called just after dissector call + * Associate a TCAP context to a tcap session and display session related infomations + * like the first frame, the last, the session duration, + * and a uniq session identifier for the filtering + * + * For ETSI tcap, the TCAP context can be reached through three keys + * - a key (BEGIN) identifying the session according to the tcap source identifier + * - a key (CONT) identifying the established session (src_id and dst_id) + * - a key (END) identifying the session according to the tcap destination identifier + * + * For ANSI tcap, the TCAP context is reached through a uniq key + * - a key (ANSI) identifying the session according to the tcap identifier +*/ struct tcaphash_context_t * tcapsrt_call_matching(tvbuff_t *tvb, packet_info * pinfo _U_, proto_tree *tree, diff --git a/epan/wslua/init_wslua.h b/epan/wslua/init_wslua.h index d77becfd78..060a26f0d8 100644 --- a/epan/wslua/init_wslua.h +++ b/epan/wslua/init_wslua.h @@ -26,7 +26,12 @@ #define __INIT_WSLUA_H__ #include - +/** @defgroup wslua_group Wireshark LUA + * + */ +/** @file + * @ingroup wslua_group + */ typedef struct _wslua_plugin { gchar *name; /* plugin name */ gchar *version; /* plugin version */ diff --git a/epan/wslua/wslua.h b/epan/wslua/wslua.h index 629869b955..86004656b0 100644 --- a/epan/wslua/wslua.h +++ b/epan/wslua/wslua.h @@ -58,6 +58,10 @@ #include "declare_wslua.h" +/** @file + * @ingroup wslua_group + */ + #define WSLUA_INIT_ROUTINES "init_routines" #define LOG_DOMAIN_LUA "wslua" @@ -94,7 +98,7 @@ typedef struct _wslua_field_t { guint32 mask; } wslua_field_t; -/* +/** * PREF_OBSOLETE is used for preferences that a module used to support * but no longer supports; we give different error messages for them. */ @@ -122,15 +126,15 @@ typedef struct _wslua_pref_t { void* p; } value; union { - guint32 max_value; /* maximum value of a range */ + guint32 max_value; /**< maximum value of a range */ struct { - const enum_val_t *enumvals; /* list of name & values */ - gboolean radio_buttons; /* TRUE if it should be shown as + const enum_val_t *enumvals; /**< list of name & values */ + gboolean radio_buttons; /**< TRUE if it should be shown as radio buttons rather than as an option menu or combo box in the preferences tab */ - } enum_info; /* for PREF_ENUM */ - } info; /* display/text file information */ + } enum_info; /**< for PREF_ENUM */ + } info; /**< display/text file information */ struct _wslua_pref_t* next; struct _wslua_proto_t* proto;