GetHostNameW 함수(winsock2.h)

아티클
08/27/2023

GetHostNameW 함수는 로컬 컴퓨터의 표준 호스트 이름을 유니코드 문자열로 검색합니다.

구문

int WSAAPI GetHostNameW(
  [out] PWSTR name,
  [in]  int   namelen
);

매개 변수

[out] name

로컬 호스트 이름을 null로 종료된 유니코드 문자열로 수신하는 버퍼에 대한 포인터입니다.

[in] namelen

이름 매개 변수가 가리키는 버퍼의 길이(와이드 문자)입니다.

반환 값

오류가 발생하지 않으면 GetHostNameW 는 0을 반환합니다. 그렇지 않으면 SOCKET_ERROR 반환하고 WSAGetLastError를 호출하여 특정 오류 코드를 검색할 수 있습니다.

오류 코드	의미
WSAEFAULT	name 매개 변수는 NULL 포인터이거나 사용자 주소 공간의 유효한 부분이 아닙니다. namelen 매개 변수로 지정된 버퍼 크기가 너무 작아서 전체 호스트 이름을 보유하지 않은 경우에도 이 오류가 반환됩니다.
WSANOTINITIALISED	이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다.
WSAENETDOWN	네트워크 하위 시스템이 실패했습니다.

설명

GetHostNameW 함수는 로컬 호스트의 이름을 유니코드(UTF-16)의 name 매개 변수로 지정된 버퍼에 반환합니다. 호스트 이름은 null로 종료된 유니코드 문자열로 반환됩니다. 호스트 이름의 형식은 Windows 소켓 공급자에 따라 달라집니다. 간단한 호스트 이름이거나 정규화된 도메인 이름이 될 수 있습니다. 그러나 반환된 이름은 GetAddrInfoW에서 성공적으로 구문 분석됩니다.

인터넷이 증가함에 따라 ASCII 문자 집합으로 표현되지 않는 다른 언어의 인터넷 호스트 이름을 식별해야 하는 필요성이 증가하고 있습니다. 이러한 요구 사항을 용이하게 하고 비 ASCII 문자(유니코드)를 특수 ASCII 문자 문자열(Punycode)으로 나타낼 수 있도록 하는 식별자를 IDN(Internationalized Domain Names)으로 알려져 있습니다. IDNA(애플리케이션에서 도메인 이름 국제화)라는 메커니즘은 표준 방식으로 IDN을 처리하는 데 사용됩니다. GetHostNameW 함수는 로컬 호스트 이름을 Punycode와 유니코드 간에 변환하지 않습니다. GetAddrInfoW 함수는 IDN(Internationalized Domain Name) 구문 분석을 지원하고 Punycode/IDN 인코딩 및 변환을 수행합니다.

GetHostNameW 함수가 Windows Server 2012의 클러스터 리소스에서 사용되고 CLUSTER_NETWORK_NAME 환경 변수가 정의된 경우 이 환경 변수의 값은 실제 호스트 이름을 재정의하고 반환됩니다. 클러스터 리소스에서 CLUSTER_NETWORK_NAME 환경 변수에는 클러스터 이름이 포함됩니다.

GetHostNameW 함수는 네임스페이스 공급자를 쿼리하여 Svgguid.h 헤더 파일에 정의된 SVCID_HOSTNAME GUID를 사용하여 로컬 호스트 이름을 확인합니다. 네임스페이스 공급자가 응답하지 않으면 GetHostNameW 함수는 유니코드에 있는 로컬 컴퓨터의 NetBIOS 이름을 반환합니다.

이름 매개 변수가 가리키는 버퍼에서 반환된 문자열의 최대 길이(와이드 문자)는 네임스페이스 공급자에 따라 달라지지만 이 문자열은 256자 이하여야 합니다. 따라서 256개 와이드 문자의 버퍼가 name 매개 변수에 전달되고 namelen 매개 변수가 256으로 설정된 경우 버퍼 크기는 항상 적절합니다.

참고 로컬 호스트 이름이 구성되지 않은 경우 GetHostNameW가 성공하고 GetAddrInfoW에서 resolve 수 있는 토큰 호스트 이름을 반환해야 합니다.

Windows Phone 8: 이 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에서 지원됩니다.

Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상의 Windows 스토어 앱에서 지원됩니다.

요구 사항


지원되는 최소 클라이언트	Windows 8.1, Windows 8 [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2012 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	winsock2.h
라이브러리	Ws2_32.lib
DLL	Ws2_32.dll

추가 정보

GetHostNameW 함수(winsock2.h)

구문

매개 변수

반환 값

설명

요구 사항

추가 정보

피드백

피드백

추가 리소스