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
);

參數

[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)
程式庫	Advapi32.lib
Dll	Advapi32.dll