[cifs-protocol] Bitfields

[Andrew Bartlett]

On Sun, 2008-08-31 at 22:06 -0700, Ron Schnell wrote:
> The Technical Committee was formed to help enforce the Microsoft anti-trust Final Judgment entered by the
> US Courts in 2002 (see http://www.thetc.org).  The TC has been involved in reviewing and commenting on
> much of the recently posted technical documentation and is interested in hearing about your experiences using
> these documents for product development or enhancement, either by posting your feedback to this mailing list,
> or by contacting the TC on a strictly confidential basis by sending e-mail to docfeedback at thetc.org

The other documentation issue that I have regards bitfields.  Many of
the protocols I work on are based on DCE/RPC or LDAP.  This provides a
clear standard for the presentation of integers into wire formats. 

However, in all the Microsoft documents, whenever a bitfield is
displayed, the bits are described not in terms of numerical constants
(preferably in hexadecimal), but in terms of useless bitfield tables.  I
say useless because I personally go to extreme lengths to avoid having
to try and decode them - often hoping that an existing piece of source
code already has this particular constant defined.

Presented apparently with the sole intention of increasing programmer
frustration, they are labled in inverse order - high order bits appear
first, but are numbered lowest.  This makes even the mental arithmetic a
challenge, and frequently incorrect. 

In both cases, there is no value in providing information on the bit
order - the wire protocols define which order the bits will appear in
(negotiable in DCE/RPC), so these constants *must* be described in
source code in terms of natural numbers.  However, the programmer much
decipher the documentation first.

Any assistance you could provide in this area will greatly reduce the
effort required to produce interoperable implementations here. 

Andrew Bartlett

-- 
Andrew Bartlett
http://samba.org/~abartlet/
Authentication Developer, Samba Team           http://samba.org
Samba Developer, Red Hat Inc.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.samba.org/archive/cifs-protocol/attachments/20081104/770e2fb6/attachment.bin