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인 경우 이 매개 변수는 0일 수 있습니다.

[out, optional] PreviousState

함수가 수정하는 그룹의 이전 상태를 포함하는 TOKEN_GROUPS 구조를 수신하는 버퍼에 대한 포인터입니다. 즉, 이 함수에서 그룹을 수정한 경우 그룹 및 이전 상태는 PreviousState에서 참조하는 TOKEN_GROUPS 구조에 포함됩니다. TOKEN_GROUPSGroupCount 멤버가 0이면 이 함수에 의해 변경된 그룹이 없습니다. 이 매개 변수는 NULL일 수 있습니다.

버퍼가 지정되었지만 수정된 그룹의 전체 목록을 받을 수 있는 충분한 공간이 없는 경우 그룹 상태가 변경되지 않고 함수가 실패합니다. 이 경우 함수는 ReturnLength 매개 변수가 가리키는 변수를 수정된 그룹의 전체 목록을 보유하는 데 필요한 바이트 수로 설정합니다.

[out, optional] ReturnLength

PreviousState 매개 변수가 가리키는 버퍼에 필요한 실제 바이트 수를 수신하는 변수에 대한 포인터입니다. 이 매개 변수는 NULL 일 수 있으며 PreviousState 가 NULL인 경우 무시됩니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 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