From 22149c5523a77e642ec13d12064b2ccef29e51fb Mon Sep 17 00:00:00 2001 From: Evan Huus Date: Sat, 22 Feb 2014 08:39:57 -0500 Subject: TVB API deprecations and cleanup - rename tvb_length and similar to tvb_captured_length and similar; leave #defines in place for backwards-compat, but mark them clearly as deprecated in code comments and in checkAPI - remove tvb_get_string as C code and just leave a #define in place for backwards-compat; mark it clearly as deprecated in code comment and checkAPI - update READMEs and sample dissector for all of the above - while in the neighbourhood, make checkAPI skip (and warn) for missing files instead of bailing on the whole check, so subsequent files still get checked Change-Id: I32fc437896ca86ca73e9b49d5f50400adf8ec5ad Reviewed-on: https://code.wireshark.org/review/311 Reviewed-by: Evan Huus --- epan/tvbuff.c | 30 ++++++++++-------------------- epan/tvbuff.h | 42 +++++++++++++++++++++++++----------------- 2 files changed, 35 insertions(+), 37 deletions(-) (limited to 'epan') diff --git a/epan/tvbuff.c b/epan/tvbuff.c index a0371a7423..123e7ec473 100644 --- a/epan/tvbuff.c +++ b/epan/tvbuff.c @@ -304,7 +304,7 @@ tvb_new_octet_aligned(tvbuff_t *tvb, guint32 bit_offset, gint32 no_of_bits) right = 8 - left; /* for right-shifting */ if (no_of_bits == -1) { - datalen = tvb_length_remaining(tvb, byte_offset); + datalen = tvb_captured_length_remaining(tvb, byte_offset); remaining_bits = 0; } else { datalen = no_of_bits >> 3; @@ -326,7 +326,7 @@ tvb_new_octet_aligned(tvbuff_t *tvb, guint32 bit_offset, gint32 no_of_bits) * if non extra byte is available, the last shifted byte requires * special treatment */ - if (tvb_length_remaining(tvb, byte_offset) > datalen) { + if (tvb_captured_length_remaining(tvb, byte_offset) > datalen) { data = tvb_get_ptr(tvb, byte_offset, datalen + 1); /* Do this allocation AFTER tvb_get_ptr() (which could throw an exception) */ @@ -390,7 +390,7 @@ tvb_clone(tvbuff_t *tvb) } guint -tvb_length(const tvbuff_t *tvb) +tvb_captured_length(const tvbuff_t *tvb) { DISSECTOR_ASSERT(tvb && tvb->initialized); @@ -398,7 +398,7 @@ tvb_length(const tvbuff_t *tvb) } gint -tvb_length_remaining(const tvbuff_t *tvb, const gint offset) +tvb_captured_length_remaining(const tvbuff_t *tvb, const gint offset) { guint abs_offset, rem_length; int exception; @@ -413,7 +413,7 @@ tvb_length_remaining(const tvbuff_t *tvb, const gint offset) } guint -tvb_ensure_length_remaining(const tvbuff_t *tvb, const gint offset) +tvb_ensure_captured_length_remaining(const tvbuff_t *tvb, const gint offset) { guint abs_offset, rem_length; int exception; @@ -2474,16 +2474,6 @@ tvb_get_string_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, return strbuf; } -/* - * Get an ASCII string; this should not be used in new code. - */ -guint8 * -tvb_get_string(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, - const gint length) -{ - return tvb_get_ascii_string(scope, tvb, offset, length); -} - /* * These routines are like the above routines, except that they handle * null-terminated strings. They find the length of that string (and @@ -2949,7 +2939,7 @@ tvb_find_line_end(tvbuff_t *tvb, const gint offset, int len, gint *next_offset, guchar found_needle = 0; if (len == -1) - len = tvb_length_remaining(tvb, offset); + len = tvb_captured_length_remaining(tvb, offset); /* * XXX - what if "len" is still -1, meaning "offset is past the * end of the tvbuff"? @@ -3065,7 +3055,7 @@ tvb_find_line_end_unquoted(tvbuff_t *tvb, const gint offset, int len, gint *next int linelen; if (len == -1) - len = tvb_length_remaining(tvb, offset); + len = tvb_captured_length_remaining(tvb, offset); /* * XXX - what if "len" is still -1, meaning "offset is past the * end of the tvbuff"? @@ -3203,7 +3193,7 @@ tvb_skip_wsp(tvbuff_t *tvb, const gint offset, const gint maxlength) guint8 tempchar; /* Get the length remaining */ - tvb_len = tvb_length(tvb); + tvb_len = tvb_captured_length(tvb); end = offset + maxlength; if (end >= tvb_len) { @@ -3238,7 +3228,7 @@ tvb_skip_guint8(tvbuff_t *tvb, int offset, const int maxlength, const guint8 ch) int end, tvb_len; /* Get the length remaining */ - tvb_len = tvb_length(tvb); + tvb_len = tvb_captured_length(tvb); end = offset + maxlength; if (end >= tvb_len) end = tvb_len; @@ -3294,7 +3284,7 @@ tvb_bcd_dig_to_wmem_packet_str(tvbuff_t *tvb, const gint offset, const gint len, dgt = &Dgt1_9_bcd; if (len == -1) { - length = tvb_length(tvb); + length = tvb_captured_length(tvb); if (length < offset) { return ""; } diff --git a/epan/tvbuff.h b/epan/tvbuff.h index be7db043f3..9e15612105 100644 --- a/epan/tvbuff.h +++ b/epan/tvbuff.h @@ -221,18 +221,29 @@ WS_DLL_PUBLIC tvbuff_t *tvb_new_composite(void); WS_DLL_PUBLIC void tvb_composite_finalize(tvbuff_t *tvb); -/* Get total length of buffer */ -WS_DLL_PUBLIC guint tvb_length(const tvbuff_t *tvb); +/* Get amount of captured data in the buffer (which is *NOT* necessarily the + * length of the packet). You probably want tvb_reported_length instead. */ +WS_DLL_PUBLIC guint tvb_captured_length(const tvbuff_t *tvb); + +/* DEPRECATED, do not use in new code, call tvb_captured_length directly! */ +#define tvb_length tvb_captured_length /** Computes bytes to end of buffer, from offset (which can be negative, * to indicate bytes from end of buffer). Function returns 0 if offset is - * either at the end of the buffer or out of bounds. No exception is thrown. */ -WS_DLL_PUBLIC gint tvb_length_remaining(const tvbuff_t *tvb, const gint offset); + * either at the end of the buffer or out of bounds. No exception is thrown. + * You probably want tvb_reported_length_remaining instead. */ +WS_DLL_PUBLIC gint tvb_captured_length_remaining(const tvbuff_t *tvb, const gint offset); + +/* DEPRECATED, do not use in new code, call tvb_captured_length_remaining directly! */ +#define tvb_length_remaining tvb_captured_length_remaining /** Same as above, but throws an exception if the offset is out of bounds. */ -WS_DLL_PUBLIC guint tvb_ensure_length_remaining(const tvbuff_t *tvb, +WS_DLL_PUBLIC guint tvb_ensure_captured_length_remaining(const tvbuff_t *tvb, const gint offset); +/* DEPRECATED, do not use in new code, call tvb_ensure_captured_length_remaining directly! */ +#define tvb_ensure_length_remaining tvb_ensure_captured_length_remaining + /* Checks (w/o throwing exception) that the bytes referred to by * 'offset'/'length' actually exist in the buffer */ WS_DLL_PUBLIC gboolean tvb_bytes_exist(const tvbuff_t *tvb, const gint offset, @@ -472,23 +483,20 @@ extern gchar *tvb_format_stringzpad_wsp(tvbuff_t *tvb, const gint offset, * * Throws an exception if the tvbuff ends before the string does. * - * tvb_get_string() handles 7-bit ASCII strings, with characters - * with the 8th bit set are converted to the - * Unicode REPLACEMENT CHARACTER. + * Takes a string encoding as well, and converts to UTF-8 from the encoding, + * possibly mapping some characters to the Unicode REPLACEMENT CHARACTER. * - * tvb_get_string_enc() takes a string encoding as well, and converts to UTF-8 - * from the encoding, possibly mapping some characters - * to the REPLACEMENT CHARACTER. - * - * If scope is set to NULL it is the user's responsibility to g_free() - * the memory allocated by tvb_memdup(). Otherwise memory is - * automatically freed when the scope lifetime is reached. + * If scope is set to NULL it is the user's responsibility to wmem_free() + * the memory allocated. Otherwise memory is automatically freed when the scope + * lifetime is reached. */ -WS_DLL_PUBLIC guint8 *tvb_get_string(wmem_allocator_t *scope, tvbuff_t *tvb, - const gint offset, const gint length); WS_DLL_PUBLIC guint8 *tvb_get_string_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, const gint length, const guint encoding); +/* DEPRECATED, do not use in new code, call tvb_get_string_enc directly! */ +#define tvb_get_string(SCOPE, TVB, OFFSET, LENGTH) \ + tvb_get_string_enc(SCOPE, TVB, OFFSET, LENGTH, ENC_ASCII) + /** * Given a tvbuff, a bit offset, and a number of characters, allocate * a buffer big enough to hold a non-null-terminated string of no_of_chars -- cgit v1.2.3