AdjustTokenGroups

	BOOL AdjustTokenGroups(TokenHandle, ResetToDefault, NewState, BufferLength, PreviousState, ReturnLength)
	HANDLE TokenHandle;
	BOOL ResetToDefault;
	PTOKEN_GROUPS NewState;
	DWORD BufferLength;
	PTOKEN_GROUPS PreviousState;
	PDWORD ReturnLength;

The AdjustTokenGroups function enables and/or disables groups in the specified token. The function can optionally capture the previous state of changed groups. TOKEN_ADJUST_GROUPS access is required to enable or disable groups in a token.

The absence from the token of some of the groups listed to be changed doesn't affect the successful modification of the groups that are in the token.

Note that mandatory groups can not be disabled. An attempt to disable any mandatory groups will cause the call to fail, leaving the state of all groups unchanged.

Parameters

TokenHandle

Handle to the token whose groups the function will enable/disable.

ResetToDefault

Boolean value that, if TRUE, specifies that the function should set the groups to their default enabled/disabled states. If FALSE, the function will set the groups according to the NewState parameter.

NewState

Optional pointer to a TOKEN_GROUPS data structure that contains the groups whose states are to be enabled/disabled. If ResetToDefault is TRUE, the function ignores this parameter. If ResetToDefault is FALSE, AdjustTokenGroups sets each of the token's groups to the value of that group's Enabled flag within the TOKEN_GROUPS data structure pointed to by NewState.

The TOKEN_GROUPS data structure has the following form:

typedef struct _TOKEN_GROUPS { /* tg */

DWORD GroupCount;

SID_AND_ATTRIBUTES Groups[ANYSIZE_ARRAY];

} TOKEN_GROUPS ;

BufferLength

Optionally specifies the size in bytes of the buffer pointed to by PreviousState. A value is required if PreviousState is non-NULL.

PreviousState

Optional pointer to a buffer that the function will fill with a TOKEN_GROUPS data structure containing the pre-adjustment state of any groups the function modifies.

The TOKEN_GROUPS data structure is detailed in the discussion of the NewState parameter above.

Since the information is formatted as a TOKEN_GROUPS data structure, a pointer to the buffer can be passed as the NewState parameter in a subsequent call to this function, thus restoring the original state of the groups.

TOKEN_QUERY access is needed to use this parameter.

If this buffer does not contain enough space to receive the complete list of modified groups, then no group states are changed, and STATUS_BUFFER_TOO_SMALL is returned. In this case, the function sets the variable pointed to by the ReturnLength parameter to the actual number of bytes needed to hold the complete list of modified groups.

ReturnLength

Optional pointer to a variable that the function will set to the actual number of bytes needed to hold the previous group state information. This parameter is ignored if PreviousState is NULL.

Return Value

The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.