From 9bdc911c29796729dbd27d9fc5f614fa830f94ce Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Sat, 13 Jul 2013 15:07:15 +0000 Subject: [PATCH] From Dominic Spill via https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=8921 Update the README to reflect the value_string name changes in r48645. From me: reorganize a bit to promote the use of val_to_str over try_val_to_str in most cases. svn path=/trunk/; revision=50557 --- doc/README.dissector | 71 ++++++++++++++++---------------------------- 1 file changed, 26 insertions(+), 45 deletions(-) diff --git a/doc/README.dissector b/doc/README.dissector index 03bd3fd673..e5082da767 100644 --- a/doc/README.dissector +++ b/doc/README.dissector @@ -1907,29 +1907,14 @@ clicks as well, launching the configured browser with this URL as parameter. 1.6 Utility routines. -1.6.1 match_strval, match_strval_ext, val_to_str and val_to_str_ext. +1.6.1 val_to_str, val_to_str_const, try_val_to_str and try_val_to_str_idx A dissector may need to convert a value to a string, using a 'value_string' structure, by hand, rather than by declaring a field with an associated 'value_string' structure; this might be used, for example, to generate a COL_INFO line for a frame. -'match_strval()' will do that: - - gchar* - match_strval(guint32 val, const value_string *vs) - -It will look up the value 'val' in the 'value_string' table pointed to -by 'vs', and return either the corresponding string, or NULL if the -value could not be found in the table. Note that, unless 'val' is -guaranteed to be a value in the 'value_string' table ("guaranteed" as in -"the code has already checked that it's one of those values" or "the -table handles all possible values of the size of 'val'", not "the -protocol spec says it has to be" - protocol specs do not prevent invalid -packets from being put onto a network or into a purported packet capture -file), you must check whether 'match_strval()' returns NULL, and arrange -that its return value not be dereferenced if it's NULL. 'val_to_str()' -can be used to generate a string for values not found in the table: +val_to_str() handles the most common case: gchar* val_to_str(guint32 val, const value_string *vs, const char *fmt) @@ -1942,43 +1927,39 @@ You can use it in a call to generate a COL_INFO line for a frame such as col_add_fstr(COL_INFO, ", %s", val_to_str(val, table, "Unknown %d")); -The match_strval_ext and val_to_str_ext functions are "extended" versions -of match_strval and val_to_str. They should be used for large value-string -arrays which contain many entries. They implement value to string conversions -which will do either a direct access or a binary search of the -value string array if possible. See "Extended Value Strings" under -section 1.6 "Constructing the protocol tree" for more information. +If you don't need to display 'val' in your fmt string, you can use +val_to_str_const() which just takes a string constant instead and returns it +unmodified when 'val' isn't found. + +If you need to handle the failure case in some custom way, try_val_to_str() +will return NULL if val isn't found: + + gchar* + try_val_to_str(guint32 val, const value_string *vs) + +Note that, you must check whether 'try_val_to_str()' returns NULL, and arrange +that its return value not be dereferenced if it's NULL. 'try_val_to_str_idx()' +behaves similarly, except it also returns an index into the value_string array, +or -1 if 'val' was not found. + +The *_ext functions are "extended" versions of those already described. They +should be used for large value-string arrays which contain many entries. They +implement value to string conversions which will do either a direct access or +a binary search of the value string array if possible. See +"Extended Value Strings" under section 1.6 "Constructing the protocol tree" for +more information. See epan/value_string.h for detailed information on the various value_string functions. - -1.6.2 match_strrval and rval_to_str. +1.6.2 rval_to_str, try_rval_to_str and try_rval_to_str_idx A dissector may need to convert a range of values to a string, using a 'range_string' structure. -'match_strrval()' will do that: +Most of the same functions exist as with regular value_strings (see section +1.6.1) except with the names 'rval' instead of 'val'. - gchar* - match_strrval(guint32 val, const range_string *rs) - -It will look up the value 'val' in the 'range_string' table pointed to -by 'rs', and return either the corresponding string, or NULL if the -value could not be found in the table. Please note that its base -behavior is inherited from match_strval(). - -'rval_to_str()' can be used to generate a string for values not found in -the table: - - gchar* - rval_to_str(guint32 val, const range_string *rs, const char *fmt) - -If the value 'val' is found in the 'range_string' table pointed to by -'rs', 'rval_to_str' will return the corresponding string; otherwise, it -will use 'fmt' as an 'sprintf'-style format, with 'val' as an argument, -to generate a string, and will return a pointer to that string. Please -note that its base behavior is inherited from match_strval(). 1.7 Calling Other Dissectors.