AdjustTokenGroups 函数 (securitybaseapi.h)

项目
08/25/2023

AdjustTokenGroups 函数启用或禁用指定访问令牌中已存在的组。若要启用或禁用访问令牌中的组，需要访问TOKEN_ADJUST_GROUPS。

语法

BOOL AdjustTokenGroups(
  [in]            HANDLE        TokenHandle,
  [in]            BOOL          ResetToDefault,
  [in, optional]  PTOKEN_GROUPS NewState,
  [in]            DWORD         BufferLength,
  [out, optional] PTOKEN_GROUPS PreviousState,
  [out, optional] PDWORD        ReturnLength
);

parameters

[in] TokenHandle

访问令牌的句柄，其中包含要启用或禁用的组。句柄必须具有对令牌TOKEN_ADJUST_GROUPS访问权限。如果 PreviousState 参数不为 NULL，则句柄还必须具有TOKEN_QUERY访问权限。

[in] ResetToDefault

指示组是否设置为默认启用和禁用状态的布尔值。如果此值为 TRUE，则组将设置为其默认状态，并忽略 NewState 参数。如果此值为 FALSE，则根据 NewState 参数指向的信息设置组。

[in, optional] NewState

指向包含要启用或禁用的组的TOKEN_GROUPS 结构的指针。如果 ResetToDefault 参数为 FALSE，则函数会将每个组设置为 TOKEN_GROUPS 结构中该组的 SE_GROUP_ENABLED 属性的值。如果 ResetToDefault 为 TRUE，则忽略此参数。

[in] BufferLength

PreviousState 参数指向的缓冲区的大小（以字节为单位）。如果 PreviousState 参数为 NULL，则此参数可以为零。

[out, optional] PreviousState

指向缓冲区的指针，该缓冲区接收包含函数修改的任何组的先前状态的 TOKEN_GROUPS 结构。也就是说，如果此函数修改了某个组，该组及其以前的状态将包含在 PreviousState 引用的TOKEN_GROUPS结构中。如果 TOKEN_GROUPS 的 GroupCount 成员为零，则此函数未更改任何组。此参数可以为 NULL。

如果指定了缓冲区，但它不包含足够的空间来接收修改组的完整列表，则不会更改任何组状态，并且函数将失败。在这种情况下，函数将 ReturnLength 参数指向的变量设置为保存修改组的完整列表所需的字节数。

[out, optional] ReturnLength

指向变量的指针，该变量接收 PreviousState 参数指向的缓冲区所需的实际字节数。此参数可以为 NULL ，如果 PreviousState 为 NULL，则忽略此参数。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

在 PreviousState 参数中检索的信息的格式设置为TOKEN_GROUPS结构。这意味着，在后续调用 AdjustTokenGroups 函数时，可以将指向缓冲区的指针作为 NewState 参数传递，从而还原组的原始状态。

NewState 参数可以列出访问令牌中不存在的要更改的组。这不会影响成功修改令牌中的组。

AdjustTokenGroups 函数不能禁用TOKEN_GROUPS结构中具有 SE_GROUP_MANDATORY 属性的组。请改用 CreateRestrictedToken 。

不能启用具有 SE_GROUP_USE_FOR_DENY_ONLY 属性的组。

要求


最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	securitybaseapi.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll