From f45ade999f0874e20811bad3ae3d022e6abe8b13 Mon Sep 17 00:00:00 2001 From: Guy Harris Date: Thu, 29 Sep 2011 22:40:32 +0000 Subject: Update README.developer to take into account the disappearance of FT_EBCDIC and the addition of support for character encodings. svn path=/trunk/; revision=39190 --- doc/README.developer | 80 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 49 insertions(+), 31 deletions(-) (limited to 'doc') diff --git a/doc/README.developer b/doc/README.developer index 2295af5e77..e17b0e2d86 100644 --- a/doc/README.developer +++ b/doc/README.developer @@ -1127,7 +1127,7 @@ FIELDABBREV The abbreviated name for the header field. (NO SPACES) FIELDTYPE FT_NONE, FT_BOOLEAN, FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, FT_UINT64, FT_INT8, FT_INT16, FT_INT24, FT_INT32, FT_INT64, FT_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME, - FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_EBCDIC, FT_EUI64 + FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_EUI64, FT_UINT_STRING, FT_ETHER, FT_BYTES, FT_UINT_BYTES, FT_IPv4, FT_IPv6, FT_IPXNET, FT_FRAMENUM, FT_PROTOCOL, FT_GUID, FT_OID FIELDDISPLAY For FT_UINT{8,16,24,32,64} and FT_INT{8,16,24,32,64): @@ -1730,23 +1730,6 @@ The type of value this field holds. The current field types are: displayed as the date, followed by the time, as hours, minutes, and seconds with 9 digits after the decimal point. - - Two absolute time encodings may be specified - with proto_tree_add_item(): - - ENC_TIME_TIMESPEC: Seconds (4 bytes) and - nanoseconds (4 bytes) of time since January 1, - 1970, midnight UTC. - - ENC_TIME_NTP: NTP timestamps are represented as - a 64-bit unsigned fixed-point number, in seconds - relative to 0h on 1 January 1900. The integer - part is in the first 32 bits and the fraction - part in the last 32 bits. - - The encoding must be logically ORed with - ENC_BIG_ENDIAN or ENC_LITTLE_ENDIAN as - appropriate. FT_RELATIVE_TIME Seconds (4 bytes) and nanoseconds (4 bytes) of time relative to an arbitrary time. displayed as seconds and 9 digits @@ -1762,10 +1745,6 @@ The type of value this field holds. The current field types are: However if the length given in the call is -1, then the length used is that returned by calling tvb_strsize(). - FT_EBCDIC A string of characters, not necessarily - NUL-terminated, but possibly NUL-padded. - The data from the packet is converted from - EBCDIC to ASCII before displaying to the user. FT_UINT_STRING A counted string of characters, consisting of a count (represented as an integral value, of width given in the proto_tree_add_item() @@ -2354,13 +2333,52 @@ proto_tree_add_item is used when you wish to do no special formatting. The item added to the GUI tree will contain the name (as passed in the proto_register_*() function) and a value. The value will be fetched from the tvbuff by proto_tree_add_item(), based on the type of the field -and, for integral and Boolean fields, the byte order of the value; the -byte order, for items for which that's relevant, is specified by the -'encoding' argument, which is ENC_LITTLE_ENDIAN if the value is -little-endian and ENC_BIG_ENDIAN if it is big-endian. If the byte order -is not relevant, use ENC_NA (Not Applicable). For some field types, -additional encoding information, such as the character encoding for -character strings, are supported. +and the encoding of the value as specified by the "encoding" argument. + +For protocols, FT_NONE fields, FT_BYTES fields, FT_EUI64 fields, FT_IPv6 +fields, FT_IPXNET fields, and FT_OID fields, the encoding is not +relevant; the 'encoding' argument should be ENC_NA (Not Applicable). + +For integral, floating-point, Boolean, and FT_GUID fields, the encoding +specifies the byte order of the value; the 'encoding' argument should be +is ENC_LITTLE_ENDIAN if the value is little-endian and ENC_BIG_ENDIAN if +it is big-endian. + +For FT_IPv4 fields, the encoding also specifies the byte order of the +value. In almost all cases, the encoding is in network byte order, +hence big-endian, but in at least one protocol dissected by Wireshark, +at least one IPv4 address is byte-swapped, so it's in little-endian +order. + +For string fields, the encoding specifies the character set used for the +string and the way individual code points in that character set are +encoded. For FT_UINT_STRING fields, the byte order of the count must be +specified; when support for UTF-16 encoding is added, the byte order of +the encoding will also have to be specified. In other cases, either +ENC_NA, ENC_BIG_ENDIAN, or ENC_LITTLE_ENDIAN can be specified. The +character encodings that are currently supported are: + + ENC_UTF_8 - UTF-8 + ENC_ASCII - ASCII (currently treated as UTF-8; in the future, + all bytes with the 8th bit set will be treated as + errors) + ENC_EBCDIC - EBCDIC + +Other encodings will be added in the future. + +For FT_ABSOLUTE_TIME fields, the encoding specifies the form in which +the time stamp is specified, as well as its byte order. The time stamp +encodings that are curretly supported are: + + ENC_TIME_TIMESPEC - seconds (4 bytes) and nanoseconds (4 bytes) + of time since January 1, 1970, midnight UTC. + + ENC_TIME_NTP - an NTP timestamp, represented as a 64-bit + unsigned fixed-point number, in seconds relative to 0h + on 1 January 1900. The integer part is in the first 32 + bits and the fraction part in the last 32 bits. + +For other types, there is no support for proto_tree_add_item(). Now that definitions of fields have detailed information about bitfield fields, you can use proto_tree_add_item() with no extra processing to @@ -3856,7 +3874,7 @@ static hf_register_info hf[] = { }; /** -* Dissect a buffer containing C strings. +* Dissect a buffer containing ASCII C strings. * * @param tvb The buffer to dissect. * @param pinfo Packet Info. @@ -3882,7 +3900,7 @@ static void dissect_cstr(tvbuff_t * tvb, packet_info * pinfo, proto_tree * tree) if (tree) { proto_tree_add_item(tree, hf_cstring, tvb, offset, len, - ENC_NA); + ENC_ASCII|ENC_NA); } offset += (guint)len; } -- cgit v1.2.3