AdjustTokenGroups 函式 (securitybaseapi.h)
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 |