DsGetDcNameA 함수(dsgetdc.h)
DsGetDcName 함수는 지정된 도메인에 있는 도메인 컨트롤러의 이름을 반환합니다. 이 함수는 특정 특성을 가진 도메인 컨트롤러에 대한 기본 설정을 나타내기 위해 추가 도메인 컨트롤러 선택 조건을 허용합니다.
구문
DSGETDCAPI DWORD DsGetDcNameA(
[in] LPCSTR ComputerName,
[in] LPCSTR DomainName,
[in] GUID *DomainGuid,
[in] LPCSTR SiteName,
[in] ULONG Flags,
[out] PDOMAIN_CONTROLLER_INFOA *DomainControllerInfo
);
매개 변수
[in] ComputerName
이 함수를 처리할 서버의 이름을 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 일반적으로 이 매개 변수는 로컬 컴퓨터가 사용됨을 나타내는 NULL입니다.
[in] DomainName
쿼리할 도메인 또는 애플리케이션 파티션의 이름을 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 이 이름은 DNS 스타일 이름(예: fabrikam.com 또는 플랫 스타일 이름(예: Fabrikam)일 수 있습니다. DNS 스타일 이름을 지정하는 경우 후행 기간의 유의 여부에 관계없이 이름을 지정할 수 있습니다.
Flags 매개 변수에 DS_GC_SERVER_REQUIRED 플래그가 포함된 경우 DomainName은 포리스트의 이름이어야 합니다. 이 경우 DomainName이 포리스트 루트가 아닌 이름을 지정하면 DsGetDcName이 실패합니다.
Flags 매개 변수에 DS_GC_SERVER_REQUIRED 플래그가 포함되어 있고 DomainName이 NULL인 경우 DsGetDcName은 ComputerName으로 식별된 컴퓨터의 포리스트에서 전역 카탈로그를 찾으려고 시도합니다. ComputerName이 NULL인 경우 로컬 컴퓨터입니다.
DomainName이 NULL이고 Flags 매개 변수에 DS_GC_SERVER_REQUIRED 플래그가 없는 경우 ComputerName은 ComputerName으로 식별된 컴퓨터의 기본 도메인 이름으로 설정됩니다.
[in] DomainGuid
쿼리된 도메인의 GUID 를 지정하는 GUID 구조체에 대한 포인터입니다. DomainGuid가 NULL이 아니고 DomainName 또는 ComputerName으로 지정된 도메인을 찾을 수 없는 경우 DsGetDcName은 DomainGuid에서 지정한 GUID가 있는 도메인에서 도메인 컨트롤러를 찾으려고 시도합니다.
[in] SiteName
반환된 도메인 컨트롤러가 물리적으로 존재해야 하는 사이트의 이름을 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 이 매개 변수가 NULL인 경우 DsGetDcName 은 ComputerName으로 지정된 컴퓨터의 사이트에 가장 가까운 사이트의 도메인 컨트롤러를 반환하려고 시도합니다. 이 매개 변수는 기본적으로 NULL이어야 합니다.
[in] Flags
요청을 처리하는 데 사용되는 추가 데이터를 제공하는 플래그 집합을 포함합니다. 이 매개 변수는 다음 값의 조합일 수 있습니다.
DS_AVOID_SELF
도메인 컨트롤러에서 호출되는 경우 반환된 도메인 컨트롤러 이름이 현재 컴퓨터가 아니어야 하므로 지정합니다. 현재 컴퓨터가 도메인 컨트롤러가 아니면 이 플래그는 무시됩니다. 이 플래그를 사용하여 도메인에 있는 다른 도메인 컨트롤러의 이름을 가져올 수 있습니다.
DS_BACKGROUND_ONLY
DS_FORCE_REDISCOVERY 플래그를 지정하지 않으면 이 함수는 캐시된 도메인 컨트롤러 데이터를 사용합니다. 캐시된 데이터가 15분 이상 오래된 경우 도메인 컨트롤러를 ping하여 캐시를 새로 고칩니다. 이 플래그를 지정하면 캐시된 데이터가 만료되더라도 이 새로 고침은 방지됩니다. DsGetDcName 함수를 주기적으로 호출하는 경우 이 플래그를 사용해야 합니다.
DS_DIRECTORY_SERVICE_PREFERRED
DsGetDcName 은 디렉터리 서비스 함수를 지원하는 도메인 컨트롤러를 찾으려고 시도합니다. 디렉터리 서비스를 지원하는 도메인 컨트롤러를 사용할 수 없는 경우 DsGetDcName 은 디렉터리가 아닌 서비스 도메인 컨트롤러의 이름을 반환합니다. 그러나 DsGetDcName 은 디렉터리 서비스 도메인 컨트롤러를 찾으려는 시도가 시간 초과된 후에만 비 디렉터리 서비스 도메인 컨트롤러를 반환합니다.
DS_DIRECTORY_SERVICE_REQUIRED
반환된 도메인 컨트롤러가 디렉터리 서비스를 지원해야 합니다.
DS_DIRECTORY_SERVICE_6_REQUIRED
반환된 도메인 컨트롤러가 Windows Server 2008 이상을 실행해야 합니다.
DS_DIRECTORY_SERVICE_8_REQUIRED
반환된 도메인 컨트롤러가 Windows Server 2012 이상을 실행해야 합니다.
DS_FORCE_REDISCOVERY
캐시된 도메인 컨트롤러 데이터를 강제로 무시합니다. DS_FORCE_REDISCOVERY 플래그를 지정하지 않으면 DsGetDcName에서 캐시된 도메인 컨트롤러 데이터를 반환할 수 있습니다. 이 플래그를 지정하면 DsGetDcName 은 캐시된 정보(있는 경우)를 사용하지 않고 대신 새 도메인 컨트롤러 검색을 수행합니다.
캐시된 도메인 컨트롤러 정보를 사용하면 성능 특성이 향상되고 모든 애플리케이션에서 동일한 도메인 컨트롤러를 일관되게 사용할 수 있으므로 이 플래그는 정상적인 조건에서 사용하면 안 됩니다. 이 플래그는 애플리케이션이 DsGetDcName 에서 반환된 도메인 컨트롤러(이 플래그 없이 호출될 때)에 액세스할 수 없다고 판단한 후에만 사용해야 합니다. 이 경우 애플리케이션은 이 플래그를 사용하여 DsGetDcName 호출을 반복하여 사용하지 않는 캐시된 정보(있는 경우)가 무시되고 연결 가능한 도메인 컨트롤러가 검색되도록 해야 합니다.
DS_GC_SERVER_REQUIRED
반환된 도메인 컨트롤러가 이 도메인이 루트로 포함된 도메인의 포리스트에 대한 글로벌 카탈로그 서버여야 합니다. 이 플래그가 설정되고 DomainName 매개 변수가 NULL이 아닌 경우 DomainName 은 포리스트 이름을 지정해야 합니다. 이 플래그는 DS_PDC_REQUIRED 또는 DS_KDC_REQUIRED 플래그와 결합할 수 없습니다.
DS_GOOD_TIMESERV_PREFERRED
DsGetDcName 은 신뢰할 수 있는 시간 서버인 도메인 컨트롤러를 찾으려고 시도합니다. 하나 이상의 도메인 컨트롤러를 신뢰할 수 있는 시간 서버로 선언하도록 Windows 시간 서비스를 구성할 수 있습니다. 자세한 내용은 Windows 시간 서비스 설명서를 참조하세요. 이 플래그는 Windows 시간 서비스에서만 사용됩니다.
DS_IP_REQUIRED
이 매개 변수는 도메인 컨트롤러에 IP 주소가 있어야 했음을 나타냅니다. 이 경우 DsGetDcName은 도메인 컨트롤러의 인터넷 프로토콜 주소를 DomainControllerInfo의 DomainControllerAddress 멤버에 배치합니다.
DS_IS_DNS_NAME
DomainName 매개 변수가 DNS 이름임을 지정합니다. 이 플래그는 DS_IS_FLAT_NAME 플래그와 결합할 수 없습니다.
DS_IS_DNS_NAME 또는 DS_IS_FLAT_NAME 지정합니다. 두 플래그를 모두 지정하지 않으면 DNS 스타일과 플랫 이름을 모두 검색해야 할 수 있으므로 도메인 컨트롤러를 찾는 데 DsGetDcName 이 더 오래 걸릴 수 있습니다.
DS_IS_FLAT_NAME
DomainName 매개 변수가 플랫 이름임을 지정합니다. 이 플래그는 DS_IS_DNS_NAME 플래그와 결합할 수 없습니다.
DS_KDC_REQUIRED
반환된 도메인 컨트롤러가 Kerberos Key Distribution Center 서비스를 현재 실행하고 있어야 합니다. 이 플래그는 DS_PDC_REQUIRED 또는 DS_GC_SERVER_REQUIRED 플래그와 결합할 수 없습니다.
DS_ONLY_LDAP_NEEDED
반환되는 서버가 LDAP 서버이도록 지정합니다. 반환된 서버가 반드시 도메인 컨트롤러일 필요는 없습니다. 다른 서비스는 서버에 있는 것을 암시하지 않습니다. 반환된 서버에 반드시 쓰기 가능한 구성 컨테이너나 쓰기 가능한 스키마 컨테이너가 있는 것은 아닙니다. 반환된 서버를 반드시 보안 원칙을 만들거나 수정하는 데 사용할 필요는 없습니다. 이 플래그는 DS_GC_SERVER_REQUIRED 플래그와 함께 사용하여 글로벌 카탈로그 서버를 호스트하는 LDAP 서버를 반환할 수 있습니다. 반환된 글로벌 카탈로그 서버가 반드시 도메인 컨트롤러가 아닌 것은 아닙니다. 다른 서비스는 서버에 있는 것을 암시하지 않습니다. 이 플래그를 지정하면 DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIRED 및 DS_KDC_REQUIRED 플래그가 무시됩니다.
DS_PDC_REQUIRED
반환된 도메인 컨트롤러가 도메인의 기본 도메인 컨트롤러여야 합니다. 이 플래그는 DS_KDC_REQUIRED 또는 DS_GC_SERVER_REQUIRED 플래그와 결합할 수 없습니다.
DS_RETURN_DNS_NAME
DomainControllerName 및 DomainControllerInfo의 DomainName 멤버에 반환된 이름이 DNS 이름이 되도록 지정합니다. DNS 이름을 사용할 수 없는 경우 오류가 반환됩니다. 이 플래그는 DS_RETURN_FLAT_NAME 플래그로 지정할 수 없습니다. 이 플래그는 DS_IP_REQUIRED 플래그를 의미합니다.
DS_RETURN_FLAT_NAME
DomainControllerName 및 DomainControllerInfo의 DomainName 멤버에 반환된 이름이 플랫 이름이 되도록 지정합니다. 플랫 이름을 사용할 수 없는 경우 오류가 반환됩니다. 이 플래그는 DS_RETURN_DNS_NAME 플래그로 지정할 수 없습니다.
DS_TIMESERV_REQUIRED
반환된 도메인 컨트롤러가 Windows Time Service를 현재 실행하고 있어야 합니다.
DS_TRY_NEXTCLOSEST_SITE
이 플래그를 지정하면 DsGetDcName 은 호출자와 동일한 사이트에서 도메인 컨트롤러를 찾으려고 시도합니다. 이러한 도메인 컨트롤러를 찾을 수 없는 경우 토폴로지 정보를 제공하고 DsBindToISTG 를 호출하여 바인딩 핸들을 가져온 다음 UDP를 통해 DsQuerySitesByCost 를 호출하여 "다음으로 가장 가까운 사이트"를 확인하고 마지막으로 찾은 사이트의 이름을 캐시할 수 있는 도메인 컨트롤러를 찾습니다. 해당 사이트에서 도메인 컨트롤러를 찾을 수 없는 경우 DsGetDcName 은 도메인 컨트롤러를 찾는 기본 방법을 대체합니다.
이 플래그가 입력 매개 변수 SiteName에서 NULL이 아닌 값과 함께 사용되는 경우 ERROR_INVALID_FLAGS throw됩니다.
또한 DS_TRY_NEXT_CLOSEST_SITE 사용하는 검색 종류는 사이트별이므로 DS_PDC_REQUIRED 함께 사용하는 경우 이 플래그는 무시됩니다. 마지막으로 netBIOS를 사용하여 이름을 resolve 때문에 DS_RETURN_FLAT_NAME 함께 사용할 때 DS_TRY_NEXTCLOSEST_SITE 무시되지만, 찾은 도메인 컨트롤러의 도메인이 클라이언트가 조인된 도메인과 반드시 일치하지는 않습니다.
DS_WRITABLE_REQUIRED
반환된 도메인 컨트롤러를 쓸 수 있어야 합니다. 즉, 디렉터리 서비스의 쓰기 가능한 복사본을 호스트합니다.
DS_WEB_SERVICE_REQUIRED
반환된 도메인 컨트롤러가 현재 Active Directory 웹 서비스를 실행해야 합니다.
[out] DomainControllerInfo
선택한 도메인 컨트롤러에 대한 데이터가 포함된 DOMAIN_CONTROLLER_INFO 구조체에 대한 포인터를 수신하는 PDOMAIN_CONTROLLER_INFO 값에 대한 포인터입니다. 이 구조체는 DsGetDcName에 의해 할당됩니다. 호출자는 더 이상 필요하지 않은 경우 NetApiBufferFree 함수를 사용하여 구조를 해제해야 합니다.
반환 값
함수가 도메인 컨트롤러 데이터를 반환하는 경우 반환 값은 ERROR_SUCCESS.
함수가 실패하면 반환 값은 다음 오류 코드 중 하나일 수 있습니다.
설명
DsGetDcName 함수는 ComputerName으로 지정된 원격 컴퓨터의 Netlogon 서비스로 전송됩니다. ComputerName이 NULL이면 함수가 로컬 컴퓨터에서 처리됩니다.
DsGetDcName 은 반환된 도메인 컨트롤러 이름이 실제 도메인 컨트롤러 또는 글로벌 카탈로그의 이름인지 확인하지 않습니다. 상호 인증이 필요한 경우 호출자는 인증을 수행해야 합니다.
DsGetDcName 은 지정된 도메인에 대한 특정 액세스 권한이 필요하지 않습니다. 기본적으로 이 함수는 반환된 도메인 컨트롤러를 현재 사용할 수 있도록 보장하지 않습니다. 대신 호출자는 반환된 도메인 컨트롤러를 사용하려고 시도해야 합니다. 도메인 컨트롤러를 사용할 수 없는 경우 호출자는 DsGetDcName 함수를 다시 호출하고 DS_FORCE_REDISCOVERY 플래그를 지정해야 합니다.
응답 시간
DsGetDcName을 사용하는 경우 다음 타이밍 세부 정보를 알고 있어야 합니다.- DsGetDcName 은 네트워크 호출을 수행하며 네트워크 트래픽, 토폴로지, DC 로드 등에 따라 몇 초에서 1분까지 걸릴 수 있습니다.
- UI 또는 다른 타이밍 중요 스레드에서 DsGetDcName 을 호출하지 않는 것이 좋습니다.
- DC 로케이터는 최적화된 논리를 사용하여 가능한 한 빨리 DC 정보를 제공합니다. 또한 사이트에서 캐시된 정보를 사용하여 가장 가까운 DC에 연결합니다.
도메인 컨트롤러 고정에 대한 참고 사항
Active Directory Domain Services 도메인 컨트롤러 로케이터 함수는 클라이언트가 기본 도메인 컨트롤러를 찾으면 해당 도메인 컨트롤러가 응답을 중지하거나 클라이언트가 다시 시작되지 않는 한 클라이언트가 다른 도메인 컨트롤러를 찾지 않도록 설계되었습니다. 이를 "도메인 컨트롤러 고정"이라고 합니다. 워크스테이션은 일반적으로 문제 또는 다시 시작 없이 몇 달 동안 작동하기 때문에 이 동작의 의도하지 않은 결과 중 하나는 특정 도메인 컨트롤러가 유지 관리를 위해 중단되면 연결된 모든 클라이언트가 다른 도메인 컨트롤러로 연결을 이동한다는 것입니다. 그러나 도메인 컨트롤러가 백업되면 클라이언트가 자주 다시 시작되지 않으므로 클라이언트가 다시 연결되지 않습니다. 이로 인해 부하 분산 문제가 발생할 수 있습니다.이전에는 이 문제에 대한 가장 일반적인 해결 방법은 플래그를 사용하여 DsGetDcName 을 주기적으로 호출하는 각 클라이언트 컴퓨터에 스크립트를 배포하는 DS_FORCE_REDISCOVERY 것이었습니다. 이는 다소 번거로운 솔루션이므로 Windows Server 2008 및 Windows Vista는 도메인 컨트롤러 고정 문제를 일으키는 새로운 메커니즘을 도입했습니다.
DsGetDcName은 캐시에서 도메인 컨트롤러 이름을 검색할 때마다 캐시된 항목이 만료되었는지 확인하고, 만료된 경우 해당 도메인 컨트롤러 이름을 삭제하고 도메인 컨트롤러 이름을 다시 검색하려고 시도합니다. 캐시된 항목의 수명은 다음 레지스트리 키의 값에 의해 제어됩니다.
Hkey_local_machine\시스템\CurrentControlSet\서비스\Netlogon\매개 변수\ForceRediscoveryInterval
및
Hkey_local_machine\소프트웨어\정책\Microsoft\Netlogon\매개 변수\ForceRediscoveryInterval
이러한 레지스트리 키의 값은 REG_DWORD 형식입니다. DsGetDcName이 도메인 컨트롤러 이름을 다시 검색하기 전에 길이를 초 단위로 지정합니다. 기본값은 43200초(12시간)입니다. ForceRediscoveryInterval 레지스트리 항목의 값이 0으로 설정된 경우 클라이언트는 항상 다시 검색을 수행합니다. 값이 4294967295 설정되면 캐시가 만료되지 않으며 캐시된 도메인 컨트롤러가 계속 사용됩니다. ForceRediscoveryInterval 레지스트리 항목을 3600초(60분) 미만의 값으로 설정하지 않는 것이 좋습니다.
DsGetDcName의 ETW 추적
DsGetDcName에 대한 ETW 추적을 켜려면 다음 레지스트리 키를 만듭니다.Hkey_local_machine\시스템\CurrentControlSet\서비스\DCLocator\추적
키에는 다음과 같은 구조가 있습니다.
String ProcessName
DWORD PID <optional>
ProcessName 은 추적 정보를 가져올 프로세스의 확장을 포함하여 전체 이름이어야 합니다. PID 는 이름이 같은 여러 프로세스가 있는 경우에만 필요합니다. 정의된 경우 해당 PID를 사용하는 프로세스만 추적에 사용하도록 설정됩니다. 이름이 같은 3개 이상의 프로세스 중 2개만 추적할 수 없습니다. 하나의 instance 또는 모든 인스턴스를 사용하도록 설정할 수 있습니다(동일한 프로세스 이름을 가진 여러 인스턴스가 있고 PID가 지정되지 않은 경우 모든 인스턴스가 추적에 사용하도록 설정됨).
예를 들어 이는 App1.exe 및 App2.exe 모든 인스턴스를 추적하지만 PID가 999인 App3.exe instance 추적합니다.
App1.exe
App2.exe
App3.exe
PID 999
다음 명령을 실행하여 추적 세션을 시작합니다.
tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>
sessionname 은 추적 세션에 지정된 이름입니다. DCLocator 추적 공급자의 GUID 는 "cfaa5446-c6c4-4f5c-866f-31c9b55b962d"입니다. filename 은 이벤트가 기록되는 로그 파일의 이름입니다. traceFlags 는 추적할 영역을 나타내는 다음 플래그 중 하나 이상입니다.
| 플래그 | 16진수 값 | Description |
|---|---|---|
| DCLOCATOR_MISC | 0x00000002 | 기타 디버깅 |
| DCLOCATOR_MAILSLOT | 0x00000010 | Mailslot 메시지 |
| DCLOCATOR_SITE | 0x00000020 | 사이트 |
| DCLOCATOR_CRITICAL | 0x00000100 | 중요한 오류 |
| DCLOCATOR_SESSION_SETUP | 0x00000200 | 신뢰할 수 있는 도메인 유지 관리 |
| DCLOCATOR_DNS | 0x00004000 | 이름 등록 |
| DCLOCATOR_DNS_MORE | 0x00020000 | 자세한 정보 표시 이름 등록 |
| DCLOCATOR_MAILBOX_TEXT | 0x02000000 | 사서함 메시지 세부 정보 표시 |
| DCLOCATOR_SITE_MORE | 0x08000000 | 자세한 정보 표시 사이트 |
다음 명령을 실행하여 추적 세션을 중지합니다.
tracelog.exe -stop <세션 이름>
sessionname 은 세션을 시작할 때 사용한 이름과 동일한 이름입니다.
참고
dsgetdc.h 헤더는 DsGetDcName을 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows Vista |
| 지원되는 최소 서버 | Windows Server 2008 |
| 대상 플랫폼 | Windows |
| 헤더 | dsgetdc.h |
| 라이브러리 | NetApi32.lib |
| DLL | NetApi32.dll |