共用方式為


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 屬性值。 如果 ResetToDefaultTRUE,則會忽略此參數。

[in] BufferLength

PreviousState參數所指向之緩衝區的大小,以位元組為單位。 如果 PreviousState 參數為 Null,這個參數可以是零。

[out, optional] PreviousState

緩衝區的指標,接收包含函式所修改之任何群組先前狀態的 TOKEN_GROUPS 結構。 也就是說,如果此函式已修改群組,則群組及其先前的狀態會包含在PreviousState所參考的TOKEN_GROUPS結構中。 如果TOKEN_GROUPSGroupCount成員為零,則此函式不會變更任何群組。 此參數可以是 Null

如果已指定緩衝區,但未包含足夠的空間來接收已修改群組的完整清單,則不會變更任何群組狀態,且函式會失敗。 在此情況下,函式會將 ReturnLength 參數指向的變數設定為保存修改群組完整清單所需的位元組數目。

[out, optional] ReturnLength

變數的指標,可接收 PreviousState 參數所指向之緩衝區所需的實際位元組數目。 此參數可以是 Null ,如果 PreviousStateNull,則會忽略。

傳回值

如果函式成功,則傳回非零的值。

如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 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

另請參閱

存取控制概觀

AdjustTokenPrivileges

基本存取控制函式

CreateRestrictedToken

GetTokenInformation

OpenProcessToken

OpenThreadToken

SetTokenInformation

TOKEN_GROUPS