PFNPROCESSGROUPPOLICYEX 콜백 함수(userenv.h)

아티클
08/26/2023

ProcessGroupPolicyEx 함수는 정책을 적용할 때 사용되는 애플리케이션 정의 콜백 함수입니다. 이 확장 함수는 RSoP(결과 정책 집합) 데이터의 로깅도 지원합니다. PFNPROCESSGROUPPOLICYEX 형식은 이 콜백 함수에 대한 포인터를 정의합니다. ProcessGroupPolicyEx 는 애플리케이션 정의 함수 이름의 자리 표시자입니다.

구문

PFNPROCESSGROUPPOLICYEX Pfnprocessgrouppolicyex;

DWORD Pfnprocessgrouppolicyex(
  [in]  DWORD dwFlags,
  [in]  HANDLE hToken,
  [in]  HKEY hKeyRoot,
  [in]  PGROUP_POLICY_OBJECT pDeletedGPOList,
  [in]  PGROUP_POLICY_OBJECT pChangedGPOList,
  [in]  ASYNCCOMPLETIONHANDLE pHandle,
  [in]  BOOL *pbAbort,
  [in]  PFNSTATUSMESSAGECALLBACK pStatusCallback,
  [in]  IWbemServices *pWbemServices,
  [out] HRESULT *pRsopStatus
)
{...}

매개 변수

[in] dwFlags

이 매개 변수는 다음 플래그 중 하나 이상일 수 있습니다.

GPO_INFO_FLAG_MACHINE

사용자 정책이 아닌 컴퓨터 정책을 적용합니다.

GPO_INFO_FLAG_BACKGROUND

정책의 백그라운드 새로 고침을 수행합니다. 자세한 내용은 이 목록 다음 텍스트를 참조하세요.

GPO_INFO_FLAG_ASYNC_FOREGROUND

정책의 비동기 포그라운드 새로 고침을 수행합니다. 자세한 내용은 이 목록 다음 텍스트를 참조하세요. 포그라운드 정책 애플리케이션에 대한 자세한 내용은 그룹 정책 초기 처리를 참조하세요.

GPO_INFO_FLAG_SLOWLINK

정책이 느린 링크에 적용되고 있습니다.

GPO_INFO_FLAG_VERBOSE

자세한 정보 표시 출력을 이벤트 로그에 씁니다.

GPO_INFO_FLAG_NOCHANGES

GPO에 대한 변경 내용이 검색되지 않았습니다.

GPO_INFO_FLAG_LINKTRANSITION

정책 애플리케이션 간에 링크 속도의 변경이 감지되었습니다.

GPO_INFO_FLAG_LOGRSOP_TRANSITION

이전 정책의 애플리케이션과 현재 정책의 애플리케이션 간에 RSoP 로깅의 변경 내용이 검색되었습니다.

GPO_INFO_FLAG_FORCED_REFRESH

강제 정책 새로 고침이 적용되고 있습니다.

GPO_INFO_FLAG_SAFEMODE_BOOT

안전 모드 플래그입니다.

GPO_INFO_FLAG_BACKGROUND 플래그와 GPO_INFO_FLAG_ASYNC_FOREGROUND 플래그를 모두 설정할 수 있습니다. 정책은 백그라운드 새로 고침 중에 항상 비동기적으로 적용되므로 대부분의 확장은 백그라운드 새로 고침을 처리하는 것과 동일한 방식으로 비동기 포그라운드 새로 고침을 처리합니다. 따라서 GPO_INFO_FLAG_ASYNC_FOREGROUND 플래그에 대해 검사 필요가 없습니다. 확장이 정책의 백그라운드 새로 고침과 정책의 비동기 포그라운드 새로 고침을 구분해야 하는 경우 확장은 GPO_INFO_FLAG_ASYNC_FOREGROUND 플래그에 대해 검사 수 있습니다.

[in] hToken

LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken 또는 OpenThreadToken 함수에서 반환된 사용자 또는 컴퓨터에 대한 토큰입니다. 이 토큰에는 TOKEN_IMPERSONATE 및 TOKEN_QUERY 액세스 권한이 있어야 합니다. 자세한 내용은 Access-Token 개체 및 클라이언트 가장 에 대한 액세스 권한을 참조하세요.

[in] hKeyRoot

HKEY_LOCAL_MACHINE 또는 HKEY_CURRENT_USER 레지스트리 키에 대한 핸들입니다.

[in] pDeletedGPOList

삭제된 GPO 구조 목록을 수신하는 포인터입니다. 자세한 내용은 GROUP_POLICY_OBJECT 참조하세요.

[in] pChangedGPOList

변경된 GPO 구조 목록을 수신하는 포인터입니다. 자세한 내용은 GROUP_POLICY_OBJECT 참조하세요.

[in] pHandle

비동기 완료 핸들입니다. 콜백 함수가 비동기 처리를 지원하지 않는 경우 이 핸들은 0입니다.

[in] pbAbort

GPO 처리를 계속할지 여부를 지정합니다. 이 매개 변수가 TRUE이면 GPO 처리가 중단됩니다. 이 매개 변수가 FALSE이면 GPO 처리가 계속됩니다.

[in] pStatusCallback

상태 메시지를 표시하는 StatusMessageCallback 콜백 함수에 대한 포인터입니다. 이 매개 변수는 특정 경우에 NULL 일 수 있습니다. 예를 들어 시스템이 백그라운드에서 정책을 적용하는 경우 상태 사용자 인터페이스가 없고 애플리케이션이 표시할 상태 메시지를 보낼 수 없습니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[in] pWbemServices

정책 데이터를 작성해야 하는 RSoP 네임스페이스에 대한 WMI 서비스 포인터를 지정합니다. 이 매개 변수는 RSoP 로깅을 사용하지 않도록 설정하면 확장에서 RSoP 데이터를 기록해서는 안 됨을 나타내는 NULL 입니다.

[out] pRsopStatus

RSoP 로깅이 성공했는지 여부를 나타내는 HRESULT 반환 코드에 대한 포인터입니다.

반환 값

정책이 성공적으로 적용된 경우 ERROR_SUCCESS 반환합니다. GPO 목록에 변경 내용이 없고 확장을 다시 호출할 경우 ERROR_OVERRIDE_NOCHANGES 반환합니다. ERROR_OVERRIDE_NOCHANGES 반환하면 NoGPOListChanges 레지스트리 값이 설정된 경우에도 확장이 다시 호출됩니다. (이 레지스트리 값에 대한 자세한 내용은 비고를 참조하세요.)

비동기 포그라운드 새로 고침을 위해 함수가 호출되었지만 비동기 새로 고침 중에 정책을 적용할 수 없는 경우 ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED 반환합니다. ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED 반환하면 정책의 동기 전경 새로 고침을 위해 함수를 다시 호출해야 했음을 나타냅니다.

그렇지 않으면 시스템 오류 코드를 반환합니다.

설명

자세한 내용은 그룹 정책 클라이언트 쪽 확장 구현을 참조하세요.

시스템은 로컬 컴퓨터에 대한 광범위한 권한이 있는 LocalSystem 계정의 컨텍스트에서 이 함수를 호출합니다. 네트워크 리소스를 사용하려면 hToken 매개 변수에 제공된 토큰을 사용하여 사용자 또는 컴퓨터를 가장해야 합니다.

이 콜백 함수를 등록하려면 다음 레지스트리 키 아래에 하위 키를 만듭니다.

Hkey_local_machine\소프트웨어\Microsoft\\ Windows NT CurrentVersion\Winlogon\GPExtensions\ClientExtensionGuid

하위 키는 고유하게 GUID여야 합니다. 다음 값이 포함되어야 합니다.

정책을 동기적으로 적용하는 경우에만 상태 메시지를 업데이트해야 합니다. 이렇게 하면 긴 정책 애플리케이션 중에 피드백과 진단 제공할 수 있습니다. 상태 메시지 콜백 함수를 사용하려면 pStatusCallback이 NULL이 아닌지 확인해야 합니다. 그런 다음 메시지 문자열 리소스를 로드합니다. 상태 함수를 호출할 때 문자열이 자세한지 여부를 나타내야 합니다. 문자열이 자세한 정보 표시인 경우 콜백 함수는 컴퓨터가 자세한 정보 표시 모드인지 확인하고 메시지를 표시합니다. 자세한 내용은 StatusMessageCallback을 참조하세요.

경고 백그라운드 스레드에서 pStatusCallback 함수를 호출하지 않거나 다른 스레드의 상태 메시지를 덮어쓸 수 있습니다.