adjustTokenPrivileges 函数 (securitybaseapi.h)

项目
03/01/2024

AdjustTokenPrivileges 函数启用或禁用指定访问令牌中的特权。启用或禁用访问令牌中的特权需要TOKEN_ADJUST_PRIVILEGES访问权限。

语法

BOOL AdjustTokenPrivileges(
  [in]            HANDLE            TokenHandle,
  [in]            BOOL              DisableAllPrivileges,
  [in, optional]  PTOKEN_PRIVILEGES NewState,
  [in]            DWORD             BufferLength,
  [out, optional] PTOKEN_PRIVILEGES PreviousState,
  [out, optional] PDWORD            ReturnLength
);

参数

[in] TokenHandle

包含要修改的权限的访问令牌的句柄。句柄必须具有TOKEN_ADJUST_PRIVILEGES令牌的访问权限。如果 PreviousState 参数不为 NULL，则句柄还必须具有TOKEN_QUERY访问权限。

[in] DisableAllPrivileges

指定函数是否禁用令牌的所有特权。如果此值为 TRUE，则函数将禁用所有特权并忽略 NewState 参数。如果为 FALSE，则函数根据 NewState 参数指向的信息修改权限。

[in, optional] NewState

指向 TOKEN_PRIVILEGES 结构的指针，该结构指定特权及其属性的数组。如果 DisableAllPrivileges 参数为 FALSE， 则 AdjustTokenPrivileges 函数将启用、禁用或删除令牌的这些特权。下表描述了 AdjustTokenPrivileges 函数基于特权属性执行的操作。

值	含义
SE_PRIVILEGE_ENABLED	函数启用特权。
SE_PRIVILEGE_REMOVED	特权将从令牌中的特权列表中删除。列表中的其他特权将重新排序，以保持连续。 SE_PRIVILEGE_REMOVED取代SE_PRIVILEGE_ENABLED。由于特权已从令牌中删除，因此尝试重新启用该特权会导致警告ERROR_NOT_ALL_ASSIGNED好像该特权从未存在过一样。尝试删除令牌中不存在的特权会导致返回ERROR_NOT_ALL_ASSIGNED。对已删除特权的特权检查会导致STATUS_PRIVILEGE_NOT_HELD。审核检查失败的权限正常发生。删除特权是不可逆的，因此在调用 AdjustTokenPrivileges 后，删除的特权的名称不包含在 PreviousState 参数中。 Windows XP SP1：函数无法删除特权。不支持此值。
无	函数禁用特权。

值

含义

SE_PRIVILEGE_ENABLED

函数启用特权。

SE_PRIVILEGE_REMOVED

特权将从令牌中的特权列表中删除。列表中的其他特权将重新排序，以保持连续。

SE_PRIVILEGE_REMOVED取代SE_PRIVILEGE_ENABLED。

由于特权已从令牌中删除，因此尝试重新启用该特权会导致警告ERROR_NOT_ALL_ASSIGNED好像该特权从未存在过一样。

尝试删除令牌中不存在的特权会导致返回ERROR_NOT_ALL_ASSIGNED。

对已删除特权的特权检查会导致STATUS_PRIVILEGE_NOT_HELD。审核检查失败的权限正常发生。

删除特权是不可逆的，因此在调用 AdjustTokenPrivileges 后，删除的特权的名称不包含在 PreviousState 参数中。

Windows XP SP1： 函数无法删除特权。不支持此值。

无

函数禁用特权。

如果 DisableAllPrivileges 为 TRUE，则函数将忽略此参数。

[in] BufferLength

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

[out, optional] PreviousState

指向缓冲区的指针，该缓冲区由函数填充TOKEN_PRIVILEGES 结构，该结构包含函数修改的任何特权的先前状态。也就是说，如果此函数修改了权限，则权限及其以前的状态包含在 PreviousState 引用的TOKEN_PRIVILEGES结构中。如果 TOKEN_PRIVILEGES 的 PrivilegeCount 成员为零，则此函数未更改任何特权。此参数可以为 NULL。

如果指定的缓冲区太小，无法接收修改的权限的完整列表，则函数将失败，并且不会调整任何特权。在这种情况下，函数将 ReturnLength 参数指向的变量设置为保存修改的权限的完整列表所需的字节数。

[out, optional] ReturnLength

指向变量的指针，该变量接收 PreviousState 参数指向的缓冲区的所需大小（以字节为单位）。如果 PreviousState 为 NULL，此参数可以为 NULL。

返回值

如果该函数成功，则返回值为非零值。若要确定函数是否调整了所有指定的特权，请调用 GetLastError，该函数在函数成功时返回以下值之一：

返回代码	说明
ERROR_SUCCESS	函数调整了所有指定的特权。
ERROR_NOT_ALL_ASSIGNED	令牌没有 NewState 参数中指定的一个或多个特权。即使未调整任何特权，函数也可能成功并显示此错误值。 PreviousState 参数指示调整的权限。

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

注解

AdjustTokenPrivileges 函数无法向访问令牌添加新特权。它只能启用或禁用令牌的现有权限。若要确定令牌的权限，请调用 GetTokenInformation 函数。

NewState 参数可以指定令牌不具有的权限，而不会导致函数失败。在这种情况下，函数调整令牌确实拥有的特权，并忽略其他特权，以便函数成功。调用 GetLastError 函数以确定该函数是否调整了所有指定的特权。 PreviousState 参数指示调整的权限。

PreviousState 参数检索包含调整的权限的原始状态的TOKEN_PRIVILEGES结构。若要还原原始状态，请在后续调用 AdjustTokenPrivileges 函数时将 PreviousState 指针作为 NewState 参数传递。

示例

有关使用此函数的示例，请参阅启用和禁用特权。

要求

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