[cifs-protocol] Bitfields

[tridge at samba.org]

Hi Andrew,

The bitfield formatting is indeed frustrating! It should be easy to
fix though.

An example would be the TrustAttributes table in section 2.2.54 of
[MS-LSAD].pdf. That table is split into two parts. The first is a bit
field, and the second is a table giving a name such as 'TANT', an
expansion of the name (eg. TRUST_ATTRIBUTE_NON_TRANSITIVE), and then a
mapping to a description "Trust Attributes: Non-transitive".

An implementor needs to know what the actual values of this field
are. You might think you'd look at section 3.1.1.5, which is linked
like this:

   "TrustAttribute values are described in section 3.1.1.5."

but if you look in 3.1.1.5 you won't find them. You can find the
values in the windows behaviour section, under link <23>, which allows
you to work out that TRUST_ATTRIBUTE_NON_TRANSITIVE has value
0x00000001

That is a lot of sleuthing to work out the value of one bit! It gets
frustrating as a developer to keep having to do detective work on the
bit field values like that. I also don't see why its in "windows
behaviour"?

In the same document we can find an example where things have been
done in a much better fashion. If we look at section 2.2.11.1, we see
the definitions of the ACCESS_MASK bits. In that case we see the name
and the assocated value written above each other in the first column,
and the explanation in the second column. That makes it really easy
for developers!

So I think all that is needed is someone coming up with a script that
processes the XML of the documents to add the bit values in
hexadecimal below the names for all the fields that don't have
them. It will be a fairly tricky script, as it would need to cope with
all the different ways that the values are currently encoded in the
documents, but I think it should be possible.

Can someone from Microsoft comment on whether they think that this
would be possible?

 > Presented apparently with the sole intention of increasing programmer
 > frustration

I think 'intention' is a bit strong :-)

It certainly is done quite badly with many of the tables, but I don't
think there was any intention to make it bad, it is just that as
implementors we run across this poor layout more than the
documentation writers.

Cheers, Tridge