Treat a successful TokenHasRestrictions query with ReturnLength == 1 as a one-byte BOOLEAN at offset 0, provided the output address is DWORD-aligned; bytes 1–3 are not part of the returned value and must not be consumed.
This is the most specific available clarification: a Microsoft win32metadata maintainer reported after internal discussion that the documentation should say BOOLEAN with a DWORD-aligned pointer, and subsequently confirmed that ReturnLength == 1, with the first byte as the result, “sounds right.” The response characterized deviations as documentation defects rather than intended implementation differences. That exchange is recorded in the linked discussion, but it has not yet been converted into a published Win32 contract or a formal version-scoped support statement.
Supported reading for the reported call
For the saved successful invocation:
- Result extent: exactly
ReturnLengthbytes—here, one byte beginning at offset 0.GetTokenInformationdefinesReturnLengthas the number of bytes needed for the result buffer.^1^ - Payload type: interpret offset 0 as
BOOLEAN, which Windows defines astypedef BYTE BOOLEAN; it is therefore eight bits.^2^ - Offsets 1–3: outside the returned payload. Their retained values are neither result data nor a partially initialized
DWORD. - Meaning: zero means false; nonzero means the token has ever been filtered. That semantic remains the currently published class-21 meaning, notwithstanding the incorrect published
DWORDtype.^3^ - Call success: remains separate from the payload.
GetTokenInformationitself returns nonzero on success.^1^
A suitable decoding pattern is:
alignas(DWORD) BYTE storage[sizeof(DWORD)]{};
DWORD returned = 0;
if (!GetTokenInformation(token, TokenHasRestrictions,
storage, sizeof(storage), &returned)) {
// Handle GetLastError(); do not consume storage.
} else if (returned != sizeof(BOOLEAN)) {
// Unsupported/unexpected contract for this implementation.
} else {
const BOOLEAN value = storage[0];
const bool hasEverBeenFiltered = (value != FALSE);
}
Continue providing four bytes of capacity rather than reducing the allocation to one byte. The maintainer clarification requires DWORD alignment, while the public page still describes a DWORD; a four-byte aligned object satisfies both. A separate reproduction also found that one byte was sufficient on its tested build, but correctly did not promote that observation to a portable contract.^4^
Nonzero values
The class documentation explicitly specifies nonzero, not “equal to 1,” as meaning that the token has ever been filtered.^3^ Therefore consumers should test:
value != FALSE
and should not require value == TRUE.
The available material does not establish that Windows will actually emit arbitrary nonzero byte values. BOOLEAN is documented as a one-byte Boolean that “should be TRUE or FALSE.”^2^ Consequently:
- preserve the raw byte if auditability requires it;
- interpret any nonzero value as true under the published class semantics;
- do not claim that values other than 0 and 1 are guaranteed to be produced.
Capacity, alignment, architecture, and servicing scope
What is established:
- Four-byte capacity at a
DWORD-aligned address is consistent with both the published interface and the maintainer clarification. - On success with
ReturnLength == 1, only one byte is returned. - The token handle requires
TOKEN_QUERYfor this information class.^1^ -
DWORDis always 32 bits in both 32-bit and 64-bit Windows applications.^5^
What is not established publicly:
- a supported minimum capacity of one byte;
- whether alignment means exactly four-byte alignment on every architecture;
- a formal architecture matrix;
- a servicing-component or file-version qualification;
- an API-owner statement explicitly naming Windows 11 25H2 build
26200.9457; - normalization of the result to exactly 0 or 1.
The maintainer expected the behavior to be consistent across versions, but an expectation is not a published version guarantee. It should not be represented as formal coverage of every Windows version or as certification of the reported DLL/kernel combination.
Documentation and escalation status
The current Learn page still says TokenHasRestrictions returns a DWORD, so the published documentation has not yet incorporated the acknowledged correction.^3^ The searched repository material shows no completed correction or merged tracking item, and issue #2397 was closed because win32metadata is not a general developer-support channel—not because the byte-level interpretation was rejected.^6^
Accordingly, the present conclusion is:
- Technical contract indicated by the maintainer response: aligned one-byte
BOOLEAN. - Nature of the discrepancy: documentation defect, not a bounded runtime exception.
- Formal build-specific support conclusion: not yet available.
- Responsible API team and applicable servicing range: not identified in the public material.
For an auditable conclusion explicitly covering build 26200.9457, a Microsoft support case must request escalation to the Windows security/token API owner and obtain a written applicability statement. A documentation issue can track correction of the DWORD entry, but it cannot by itself certify a particular servicing combination.
References
- GetTokenInformation function (securitybaseapi.h)
- Windows Data Types
- TOKEN_INFORMATION_CLASS enumeration (winnt.h)
- GetTokenInformation(TokenHasRestrictions=21) returns ReturnLength=1 despite DWORD documentation - Microsoft Q&A
- Windows Coding Conventions
- #2397 TokenHasRestrictions: clarify output type and byte validity for Windows 25H2 x64 build 26200.9457