rename ep_tvb_fake_unicode() to tvb_get_ephemeral_faked_unicode() and update the README file.

svn path=/trunk/; revision=15271

doc/README.developer

@@ -360,10 +360,10 @@ the buffer.
 
 If you're fetching into such a chunk of memory a 2-byte Unicode string
 from the buffer, and the string has a specified size, you can use
-"tvb_fake_unicode()", which will check whether the entire string is
+"tvb_get_ephemeral_faked_unicode()", which will check whether the entire 
-present before allocating a buffer for the string, and will also put a
+string is present before allocating a buffer for the string, and will also 
-trailing '\0' at the end of the buffer.  The resulting string will be a
+put a trailing '\0' at the end of the buffer.  The resulting string will be 
-sequence of single-byte characters; the only Unicode characters that
+a sequence of single-byte characters; the only Unicode characters that
 will be handled correctly are those in the ASCII range.  (Ethereal's
 ability to handle non-ASCII strings is limited; it needs to be
 improved.)
@@ -896,7 +896,7 @@ tvbuff, starting at the specified offset, and containing the specified
 length worth of characters (the length of the buffer will be length+1,
 as it includes a null character to terminate the string).
 
-tvb_get_string() returns a bugger allocated by g_malloc() so you must
+tvb_get_string() returns a buffer allocated by g_malloc() so you must
 g_free() it when you are finished with the string. Failure to g_free() this
 buffer will lead to memory leaks.
 tvb_get_ephemeral_string() returns a buffer allocated from a special heap
@@ -913,6 +913,25 @@ specified offset, and containing all characters 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.
 
+
+guint8 *tvb_fake_unicode(tvbuff_t*, gint offset, gint length);
+guint8 *tvb_get_ephemeral_faked_unicode(tvbuff_t*, gint offset, gint length);
+
+Converts a 2-byte unicode string to an ASCII string.
+Returns a null-terminated buffer containing data from the specified
+tvbuff, starting at the specified offset, and containing the specified
+length worth of characters (the length of the buffer will be length+1,
+as it includes a null character to terminate the string).
+
+tvb_fake_unicode() returns a buffer allocated by g_malloc() so you must
+g_free() it when you are finished with the string. Failure to g_free() this
+buffer will lead to memory leaks.
+tvb_get_ephemeral_faked_unicode() returns a buffer allocated from a special 
+heap with a lifetime until the next packet is dissected. You do not need to
+free() this buffer, it will happen automatically once the next packet is 
+dissected.
+
+
 Copying memory:
 guint8* tvb_memcpy(tvbuff_t*, guint8* target, gint offset, gint length);
 

epan/dissectors/packet-tds.c

@@ -683,7 +683,7 @@ dissect_tds_query_packet(tvbuff_t *tvb, packet_info *pinfo _U_, proto_tree *tree
 		is_unicode = FALSE;
 	
 	if (is_unicode)
-		msg = ep_tvb_fake_unicode(tvb, offset, len/2, TRUE);
+		msg = tvb_get_ephemeral_faked_unicode(tvb, offset, len/2, TRUE);
 	else
 		msg = tvb_get_ephemeral_string(tvb, offset, len);
 	
@@ -702,7 +702,7 @@ dissect_tds5_lang_token(tvbuff_t *tvb, guint offset, guint len, proto_tree *tree
     len    -= 1;
 
     if (is_unicode)
-        msg = ep_tvb_fake_unicode(tvb, offset, (len)/2, TRUE);
+        msg = tvb_get_ephemeral_faked_unicode(tvb, offset, (len)/2, TRUE);
     else
         msg = tvb_get_ephemeral_string(tvb, offset, len);
 	
@@ -866,7 +866,7 @@ dissect_tds7_login(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
 		if (len != 0) {
 			if( i != 2) {
 				if (is_unicode == TRUE) {
-					val = ep_tvb_fake_unicode(tvb, offset2, len, TRUE);
+					val = tvb_get_ephemeral_faked_unicode(tvb, offset2, len, TRUE);
 					len *= 2;
 				} else
 					val = tvb_get_ephemeral_string(tvb, offset2, len);
@@ -1163,7 +1163,7 @@ dissect_tds_env_chg(tvbuff_t *tvb, guint offset, guint token_sz,
 		if (env_type != 7) { /* if it's not 'Collation Info - which is not textual! */
 			string_offset = offset + 2;
 			if (is_unicode == TRUE) {
-				new_val = ep_tvb_fake_unicode(tvb, string_offset,
+				new_val = tvb_get_ephemeral_faked_unicode(tvb, string_offset,
 					new_len, TRUE);
 				new_len *= 2;
 			} else
@@ -1190,7 +1190,7 @@ dissect_tds_env_chg(tvbuff_t *tvb, guint offset, guint token_sz,
 	if (old_len) {
 		string_offset = old_len_offset + 1;
 		if (is_unicode == TRUE) {
-			old_val = ep_tvb_fake_unicode(tvb, string_offset,
+			old_val = tvb_get_ephemeral_faked_unicode(tvb, string_offset,
 			    old_len, TRUE);
 			old_len *= 2;
 		} else
@@ -1223,7 +1223,7 @@ dissect_tds_err_token(tvbuff_t *tvb, guint offset, guint token_sz _U_, proto_tre
 		is_unicode = TRUE;
 
 	if(is_unicode) {
-		msg = ep_tvb_fake_unicode(tvb, offset, msg_len, TRUE);
+		msg = tvb_get_ephemeral_faked_unicode(tvb, offset, msg_len, TRUE);
 		msg_len *= 2;
 	} else {
 		msg = tvb_get_ephemeral_string(tvb, offset, msg_len);
@@ -1237,7 +1237,7 @@ dissect_tds_err_token(tvbuff_t *tvb, guint offset, guint token_sz _U_, proto_tre
 	offset +=1;
 	if(srvr_len) {
 		if (is_unicode) {
-			msg = ep_tvb_fake_unicode(tvb, offset, srvr_len, TRUE);
+			msg = tvb_get_ephemeral_faked_unicode(tvb, offset, srvr_len, TRUE);
 			srvr_len *=2;
 		} else {
 			msg = tvb_get_ephemeral_string(tvb, offset, srvr_len);
@@ -1252,7 +1252,7 @@ dissect_tds_err_token(tvbuff_t *tvb, guint offset, guint token_sz _U_, proto_tre
 	offset +=1;
 	if(proc_len) {
 		if (is_unicode) {
-			msg = ep_tvb_fake_unicode(tvb, offset, proc_len, TRUE);
+			msg = tvb_get_ephemeral_faked_unicode(tvb, offset, proc_len, TRUE);
 			proc_len *=2;
 		} else {
 			msg = tvb_get_ephemeral_string(tvb, offset, proc_len);
@@ -1288,7 +1288,7 @@ dissect_tds_login_ack_token(tvbuff_t *tvb, guint offset, guint token_sz, proto_t
 		is_unicode = TRUE;
 	proto_tree_add_text(tree, tvb, offset, 0, "msg_len: %d, token_sz: %d, total: %d",msg_len, token_sz, msg_len + 6U + 3U);
 	if(is_unicode) {
-		msg = ep_tvb_fake_unicode(tvb, offset, msg_len, TRUE);
+		msg = tvb_get_ephemeral_faked_unicode(tvb, offset, msg_len, TRUE);
 		msg_len *= 2;
 	} else {
 		msg = tvb_get_ephemeral_string(tvb, offset, msg_len);
@@ -1341,7 +1341,7 @@ dissect_tds7_results_token(tvbuff_t *tvb, guint offset, proto_tree *tree)
 			table_len = tvb_get_letohs(tvb, offset);
 			offset +=2;
 			if(table_len != 0) {
-				msg = ep_tvb_fake_unicode(tvb, offset, table_len, TRUE);
+				msg = tvb_get_ephemeral_faked_unicode(tvb, offset, table_len, TRUE);
 				proto_tree_add_text(tree, tvb, offset, table_len*2, "Table name: %s", msg);
 				offset += table_len*2;
 			}
@@ -1367,7 +1367,7 @@ dissect_tds7_results_token(tvbuff_t *tvb, guint offset, proto_tree *tree)
 		proto_tree_add_text(tree, tvb, offset, 1, "message length: %d",msg_len);
 		offset += 1;
 		if(msg_len != 0) {
-			msg = ep_tvb_fake_unicode(tvb, offset, msg_len, TRUE);
+			msg = tvb_get_ephemeral_faked_unicode(tvb, offset, msg_len, TRUE);
 			proto_tree_add_text(tree, tvb, offset, msg_len*2, "Text: %s", msg);
 			offset += msg_len*2;
 		}
@@ -1421,7 +1421,7 @@ dissect_tds_rpc(tvbuff_t *tvb, packet_info *pinfo _U_, proto_tree *tree)
 				offset += 2;
 			}
 			else if (len != 0) {
-				val = ep_tvb_fake_unicode(tvb, offset, len, TRUE);
+				val = tvb_get_ephemeral_faked_unicode(tvb, offset, len, TRUE);
 				len *= 2;
 				proto_tree_add_text(tree, tvb, offset, len, "RPC Name: %s", val);
 				offset += len;

epan/tvbuff.c

@@ -1684,18 +1684,15 @@ tvb_fake_unicode(tvbuff_t *tvb, int offset, int len, gboolean little_endian)
 }
 
 /* Convert a string from Unicode to ASCII.  At the moment we fake it by
- * replacing all non-ASCII characters with a '.' )-:  The caller must
+ * replacing all non-ASCII characters with a '.' )-:   The len parameter is 
- * free the result returned.  The len parameter is the number of guint16's
+ * the number of guint16's to convert from Unicode.
- * to convert from Unicode.
  *
  * This function allocates memory from a buffer with packet lifetime.
  * You do not have to free this buffer, it will be automatically freed
  * when ethereal starts decoding the next packet.
- * Do not use this function if you want the allocated memory to be persistent
- * after the current packet has been dissected.
  */
 char *
-ep_tvb_fake_unicode(tvbuff_t *tvb, int offset, int len, gboolean little_endian)
+tvb_get_ephemeral_faked_unicode(tvbuff_t *tvb, int offset, int len, gboolean little_endian)
 {
 	char *buffer;
 	int i;

epan/tvbuff.h

@@ -390,16 +390,19 @@ extern guint tvb_strsize(tvbuff_t *tvb, gint offset);
 extern gint tvb_strnlen(tvbuff_t*, gint offset, guint maxlength);
 
 /** Convert a string from Unicode to ASCII.  At the moment we fake it by
- * assuming all characters are ASCII  )-:  The caller must free the
+ * assuming all characters are ASCII  )-:  The len parameter is the number 
- * result returned.  The len parameter is the number of guint16's to
+ * of guint16's to convert from Unicode. 
- * convert from Unicode. */
+ *
+ * tvb_fake_unicode() returns a buffer allocated by g_malloc() and must
+ *                    be g_free() by the caller.
+ * tvb_get_ephemeral_faked_unicode() returns a buffer that does not need
+ *                    to be explicitely freed. Instead this buffer is
+ *                    automatically freed when ethereal starts dissecting
+ *                    the next packet.
+ */
 extern char *tvb_fake_unicode(tvbuff_t *tvb, int offset, int len,
                               gboolean little_endian);
-/* Same as above but the buffer returned from this function does not have to
+extern char *tvb_get_ephemeral_faked_unicode(tvbuff_t *tvb, int offset, int len,
- * be freed. It will be automatically freed after the packet is dissected.
- * Buffers allocated by this function are NOT persistent.
- */
-extern char *ep_tvb_fake_unicode(tvbuff_t *tvb, int offset, int len,
                               gboolean little_endian);
 
 /**