Update README.developer to take into account the disappearance of
authorguy <guy@f5534014-38df-0310-8fa8-9805f1628bb7>
Thu, 29 Sep 2011 22:40:32 +0000 (22:40 +0000)
committerguy <guy@f5534014-38df-0310-8fa8-9805f1628bb7>
Thu, 29 Sep 2011 22:40:32 +0000 (22:40 +0000)
FT_EBCDIC and the addition of support for character encodings.

git-svn-id: http://anonsvn.wireshark.org/wireshark/trunk@39190 f5534014-38df-0310-8fa8-9805f1628bb7

doc/README.developer

index 2295af5..e17b0e2 100644 (file)
@@ -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;
     }