GetGPOListW 함수(userenv.h)
GetGPOList 함수는 지정된 사용자 또는 컴퓨터에 대한 GPO 목록을 검색합니다. 이 함수는 두 가지 방법으로 호출할 수 있습니다. 첫째, 사용자 또는 컴퓨터에 토큰을 사용하거나, 두 번째로 사용자 또는 컴퓨터의 이름과 도메인 컨트롤러의 이름을 사용할 수 있습니다.
구문
USERENVAPI BOOL GetGPOListW(
[in] HANDLE hToken,
[in] LPCWSTR lpName,
[in] LPCWSTR lpHostName,
[in] LPCWSTR lpComputerName,
[in] DWORD dwFlags,
[out] PGROUP_POLICY_OBJECTW *pGPOList
);
매개 변수
[in] hToken
LogonUser, CreateRestrictedToken, DuplicateToken, OpenProcessToken 또는 OpenThreadToken 함수에서 반환된 사용자 또는 컴퓨터에 대한 토큰입니다. 이 토큰에는 TOKEN_IMPERSONATE 및 TOKEN_QUERY 액세스 권한이 있어야 합니다. 자세한 내용은 Access-Token 개체에 대한 액세스 권한 및 다음 설명 섹션을 참조하세요.
이 매개 변수가 NULL인 경우 lpName 및 lpHostName 매개 변수에 대한 값을 제공해야 합니다.
[in] lpName
정규화된 고유 이름 형식의 사용자 또는 컴퓨터 이름에 대한 포인터입니다(예: "CN=user, OU=users, DC=contoso, DC=com").
hToken 매개 변수가 NULL이 아닌 경우 이 매개 변수는 NULL이어야 합니다.
[in] lpHostName
DNS 도메인 이름(기본 설정) 또는 도메인 컨트롤러 이름입니다. 도메인 컨트롤러 이름은 DsGetDcName 함수를 사용하여 검색할 수 있으며 flags 매개 변수에 DS_DIRECTORY_SERVICE_REQUIRED 지정할 수 있습니다.
hToken 매개 변수가 NULL이 아닌 경우 이 매개 변수는 NULL이어야 합니다.
[in] lpComputerName
사이트 위치를 확인하는 데 사용되는 컴퓨터 이름에 대한 포인터입니다. 이름의 형식은 "\\computer_name"입니다. 이 매개 변수가 NULL이면 로컬 컴퓨터 이름이 사용됩니다.
[in] dwFlags
정보 검색을 제어하는 데 사용되는 추가 플래그를 지정하는 값입니다. GPO_LIST_FLAG_MACHINE 지정하면 함수는 컴퓨터에 대한 정책 정보를 검색합니다. GPO_LIST_FLAG_MACHINE 지정하지 않으면 함수는 사용자에 대한 정책 정보를 검색합니다.
GPO_LIST_FLAG_SITEONLY 지정하는 경우 함수는 컴퓨터 또는 사용자에 대한 사이트 정보만 반환합니다.
[out] pGPOList
GPO 구조 목록을 수신하는 포인터입니다. 자세한 내용은 GROUP_POLICY_OBJECT.
반환 값
함수가 성공하면 반환 값이 0이 아닙니다.
함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
설명
GetGPOList 함수는 사용자 또는 컴퓨터를 대신하여 작동하는 서비스에서 사용하기 위한 것입니다. 서비스는 이 함수를 호출하여 GPO 목록을 가져온 다음 각 GPO에서 서비스별 정책을 확인합니다.
토큰으로 이 함수를 호출하면 가장 정확한 목록이 제공됩니다. 시스템은 사용자 또는 컴퓨터에 대한 액세스 검사를 수행할 수 있습니다. 사용자 또는 컴퓨터 이름과 도메인 컨트롤러 이름을 사용하여 이 함수를 호출하는 것이 토큰을 사용하여 호출하는 것보다 빠릅니다. 그러나 토큰을 지정하지 않으면 시스템에서 호출자의 보안 액세스를 사용합니다. 즉, 목록이 의도한 사용자 또는 컴퓨터에 대해 완전히 올바르지 않을 수 있습니다.
GetGPOList를 호출할 때 컴퓨터에 대한 GPO의 가장 정확한 목록을 얻으려면 호출자는 컴퓨터 도메인의 각 OU 및 사이트에 대한 읽기 권한이 있어야 하며 해당 도메인의 사이트, 도메인 또는 OU에 연결된 모든 GPO에 대한 그룹 정책 액세스를 읽고 적용해야 합니다. 호출자의 예는 이름이 lpName 매개 변수에 지정된 컴퓨터에서 실행되는 서비스입니다. GPO 목록을 가져오는 다른 방법은 RsopPlanningModeProvider WMI 클래스의 RsopCreateSession 메서드를 호출하는 것입니다. 메서드는 가상 시나리오에서 컴퓨터 또는 사용자 계정에 대한 결과 정책 데이터를 생성할 수 있습니다.
처리를 마쳤으면 FreeGPOList 함수를 호출하여 GPO 목록을 해제합니다.
일반적으로 다음 코드 예제와 같이 사용자에 대한 GPO 목록을 검색할 때 토큰을 사용하여 GetGPOList 를 호출해야 합니다.
LPGROUP_POLICY_OBJECT pGPOList;
if (GetGPOList (hToken, NULL, NULL, NULL, 0, &pGPOList))
{
// Perform processing here.
//
// Free the GPO list when you finish processing.
FreeGPOList (pGPOList);
}
일반적으로 컴퓨터에 대한 GPO 목록을 검색하려면 다음 코드 조각에 설명된 대로 컴퓨터 이름 및 도메인 컨트롤러 이름으로 GetGPOList 를 호출할 수 있습니다.
LPGROUP_POLICY_OBJECT pGPOList;
if (GetGPOList (NULL, lpMachineName, lpHostName, lpMachineName, GPO_LIST_FLAG_MACHINE, &pGPOList))
{
// Perform processing here.
//
// Free the GPO list when you finish processing.
FreeGPOList (pGPOList);
}
특정 사용자 또는 컴퓨터 및 확장에 적용된 GPO 목록을 검색하려면 GetAppliedGPOList 함수를 호출합니다.
참고
userenv.h 헤더는 GETGPOList를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows Vista |
| 지원되는 최소 서버 | Windows Server 2008 |
| 대상 플랫폼 | Windows |
| 헤더 | userenv.h |
| 라이브러리 | Userenv.lib |
| DLL | Userenv.dll |