From 8d234a0d8c6c974a374e36a58cd7b3d699866464 Mon Sep 17 00:00:00 2001 From: Guy Harris Date: Sun, 23 Feb 2014 14:16:24 -0800 Subject: More tvbuff API deprecation, comment expansion, and documentation updates. Do with tvb_get_stringz() what was done with tvb_get_string(). Redo the comments for the string get routines to try to give more detail in a fashion that's a bit less hard to read. Warn, in comments, of the problems with using tvb_get_string()/tvb_get_stringz() (i.e., if your strings are non-ASCII, all bytes with the 8th bit set are going be replaced by the Unicode REPLACEMENT CHARACTER, and displayed as such). Warn, in a comment, of the problems with tvb_get_const_stringz() (i.e., it gives you raw bytes, rather than guaranteed-to-be-valid UTF-8). Update documentation and release notes appropriately. Change-Id: Ibd3efb92a203861f507ce71bc8d04d19d9d38a93 Reviewed-on: https://code.wireshark.org/review/327 Reviewed-by: Guy Harris --- doc/README.dissector | 54 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 18 deletions(-) (limited to 'doc') diff --git a/doc/README.dissector b/doc/README.dissector index 321f87288d..5f5eb789a5 100644 --- a/doc/README.dissector +++ b/doc/README.dissector @@ -256,9 +256,38 @@ data from the specified tvbuff, starting at the specified offset, and containing the specified length worth of characters. Reads data in the specified encoding and produces UTF-8 in the buffer. See below for a list of input encoding values. -guint8 *tvb_get_stringz(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, gint *lengthp); +The buffer is allocated by g_malloc() if scope is set to NULL (in that +case memory must be explicitely freed), or with the allocator lifetime +if scope is not NULL. + guint8 *tvb_get_stringz_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, gint *lengthp, const guint encoding); + +Returns a null-terminated buffer allocated from the specified scope, +containing data from the specified tvbuff, starting at the specified +offset, and containing all characters from the tvbuff up to and +including a terminating null character in the tvbuff. Reads data in the +specified encoding and produces UTF-8 in the buffer. See below for a +list of input encoding values. "*lengthp" will be set to the length of +the string, including the terminating null. + +The buffer is allocated by g_malloc() if scope is set to NULL (in that +case memory must be explicitely freed), or with the allocator lifetime +if scope is not NULL. + const guint8 *tvb_get_const_stringz(tvbuff_t *tvb, const gint offset, gint *lengthp); + +Returns a null-terminated const buffer containing data from the +specified tvbuff, starting at the specified offset, and containing all +bytes from the tvbuff up to and including a terminating null character +in the tvbuff. "*lengthp" will be set to the length of the string, +including the terminating null. + +You do not need to free() this buffer; it will happen automatically once +the next packet is dissected. This function is slightly more efficient +than the others because it does not allocate memory and copy the string, +but it does not do any mapping to UTF-8 or checks for valid octet +sequences. + gint tvb_get_nstringz(tvbuff_t *tvb, const gint offset, const guint bufsize, guint8* buffer); gint tvb_get_nstringz0(tvbuff_t *tvb, const gint offset, const guint bufsize, guint8* buffer); @@ -268,26 +297,15 @@ tvbuff up to and including a terminating null character in the tvbuff. "*lengthp" will be set to the length of the string, including the terminating null. -tvb_get_stringz() returns a buffer allocated by g_malloc() if scope is set -to NULL (in that case memory must be explicitely freed), or with the -allocator lifetime if scope is not NULL. - -tvb_get_stringz_enc() is a version of tvb_get_stringz() that takes a -string encoding as an argument. See below for a list of encoding values -for strings. - -tvb_get_const_stringz() returns a pointer to the (const) string in the tvbuff. -You do not need to free() this buffer, it will happen automatically once the -next packet is dissected. This function is slightly more efficient than the -others because it does not allocate memory and copy the string. - gchar *tvb_get_ts_23_038_7bits_string(wmem_allocator_t *scope, tvbuff_t *tvb, const gint bit_offset, gint no_of_chars); -tvb_get_ts_23_038_7bits_string() returns a string of a given number of characters -and encoded according to 3GPP TS 23.038 7 bits alphabet. The buffer allocated by -g_malloc() if scope is set to NULL (in that case memory must be explicitely freed), -or with the allocator lifetime if scope is not NULL. +tvb_get_ts_23_038_7bits_string() returns a string of a given number of +characters and encoded according to 3GPP TS 23.038 7 bits alphabet. + +The buffer is allocated by g_malloc() if scope is set to NULL (in that +case memory must be explicitely freed), or with the allocator lifetime +if scope is not NULL. Byte Array Accessors: -- cgit v1.2.3