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 函式根據 privilege 屬性所採取的動作。

值	意義
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，這會在函式成功時傳回下列其中一個值：

傳回碼	Description
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)
程式庫	Advapi32.lib
Dll	Advapi32.dll