GetNameInfoW 함수(ws2tcpip.h)
GetNameInfoW 함수는 주소에서 유니코드 호스트 이름으로, 포트 번호에서 유니코드 서비스 이름으로 프로토콜 독립적 이름 확인을 제공합니다.
구문
INT WSAAPI GetNameInfoW(
[in] const SOCKADDR *pSockaddr,
[in] socklen_t SockaddrLength,
[out] PWCHAR pNodeBuffer,
[in] DWORD NodeBufferSize,
[out] PWCHAR pServiceBuffer,
[in] DWORD ServiceBufferSize,
[in] INT Flags
);
매개 변수
[in] pSockaddr
소켓의 IP 주소 및 포트 번호를 포함하는 소켓 주소 구조에 대한 포인터입니다. IPv4의 경우 pSockaddr 매개 변수는 sockaddr_in 구조를 가리킵니다. IPv6의 경우 pSockaddr 매개 변수는 sockaddr_in6 구조를 가리킵니다.
[in] SockaddrLength
pSockaddr 매개 변수가 가리키는 구조체의 길이(바이트)입니다.
[out] pNodeBuffer
호스트 이름을 저장할 유니코드 문자열에 대한 포인터입니다. 성공하면 유니코드 호스트 이름에 대한 포인터가 기본적으로 FQDN(정규화된 도메인 이름)으로 반환됩니다. pNodeBuffer 매개 변수가 NULL인 경우 호출자가 호스트 이름 문자열을 수신하지 않음을 나타냅니다.
[in] NodeBufferSize
pNodeBuffer 매개 변수가 가리키는 버퍼의 WCHAR 문자 수입니다. 호출자는 종료 되는 NULL 문자를 포함하여 유니코드 호스트 이름을 보유할 수 있을 만큼 큰 버퍼를 제공해야 합니다.
[out] pServiceBuffer
서비스 이름을 저장할 유니코드 문자열에 대한 포인터입니다. 성공하면 포트 번호와 연결된 서비스 이름을 나타내는 유니코드 문자열에 포인터가 반환됩니다. pServiceBuffer 매개 변수가 NULL인 경우 호출자가 서비스 이름 문자열을 수신하지 않음을 나타냅니다.
[in] ServiceBufferSize
pServiceBuffer 매개 변수가 가리키는 버퍼의 WCHAR 문자 수입니다. 호출자는 종료 되는 NULL 문자를 포함하여 유니코드 서비스 이름을 보유할 수 있을 만큼 큰 버퍼를 제공해야 합니다.
[in] Flags
GetNameInfoW 함수의 처리를 사용자 지정하는 데 사용되는 값입니다. 주의 섹션을 참조하십시오.
반환 값
성공하면 GetNameInfoW 는 0을 반환합니다. 0이 아닌 반환 값은 실패를 나타내며 WSAGetLastError를 호출하여 특정 오류 코드를 검색할 수 있습니다.
GetNameInfoW 함수에서 반환된 0이 아닌 오류 코드는 IETF(인터넷 엔지니어링 태스크 포스) 권장 사항에 설명된 오류 집합에도 매핑됩니다. 다음 표에서는 이러한 오류 코드와 해당 WSA에 해당하는 코드를 보여 줍니다. Winsock 프로그래머에게 친숙하고 포괄적인 오류 정보를 제공하므로 WSA 오류 코드를 사용하는 것이 좋습니다.
| 오류 값 | WSA 동등 | Description |
|---|---|---|
| EAI_AGAIN | WSATRY_AGAIN | 이름 확인에 일시적인 오류가 발생했습니다. |
| EAI_BADFLAGS | WSAEINVAL | 하나 이상의 잘못된 매개 변수가 GetNameInfoW 함수에 전달되었습니다. 호스트 이름이 요청되었지만 NodeBufferSize 매개 변수가 0이거나 서비스 이름이 요청되었지만 ServiceBufferSize 매개 변수가 0인 경우 이 오류가 반환됩니다. |
| EAI_FAIL | WSANO_RECOVERY | 이름 확인에서 복구할 수 없는 오류가 발생했습니다. |
| EAI_FAMILY | WSAEAFNOSUPPORT | pSockaddr 매개 변수가 가리키는 소켓 주소 구조의 sa_family 멤버는 지원되지 않습니다. |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | 메모리 할당 오류가 발생했습니다. |
| EAI_NONAME | WSAHOST_NOT_FOUND | 서비스 이름이 요청되었지만 pSockaddr 매개 변수가 가리키는 구조에서 포트 번호를 찾을 수 없거나 포트 번호와 일치하는 서비스 이름을 찾을 수 없습니다. NI_NAMEREQD 설정되고 호스트 이름을 배치할 수 없거나 pNodeBuffer 및 pServiceBuffer 매개 변수가 모두 NULL이었습니다. |
gai_strerror 함수를 사용하여 GetNameInfoW 함수에서 반환된 EAI 코드를 기반으로 오류 메시지를 인쇄할 수 있습니다. gai_strerror 함수는 IETF 권장 사항을 준수하기 위해 제공되지만 스레드로부터 안전하지는 않습니다. 따라서 WSAGetLastError 와 같은 기존 Windows 소켓 함수를 사용하는 것이 좋습니다.
또한 다음 오류 코드를 반환할 수 있습니다.
| 오류 코드 | 의미 |
|---|---|
| pSockaddr 매개 변수가 NULL이거나 SockaddrLength 매개 변수가 IPv4의 sockaddr_in 구조체 크기 또는 IPv6의 sockaddr_in6 구조에 필요한 길이보다 작은 경우 이 오류가 반환됩니다. |
설명
GetNameInfoW 함수는 프로토콜 독립적 이름 확인을 제공하는 함수의 유니코드 버전입니다. GetNameInfoW 함수는 소켓 주소 구조의 내용을 노드 이름 및/또는 서비스 이름으로 변환하는 데 사용됩니다.
IPv6 및 IPv4 프로토콜의 경우 이름 확인은 DNS(Domain Name System), 로컬 호스트 파일 또는 다른 명명 메커니즘을 통해 확인할 수 있습니다. 이 함수를 사용하여 IPv4 또는 IPv6 주소의 호스트 이름, 역방향 DNS 조회를 확인하거나 포트 번호의 서비스 이름을 확인할 수 있습니다. GetNameInfoW 함수를 사용하여 SOCKADDR 구조체의 IP 주소 또는 포트 번호를 유니코드 문자열로 변환할 수도 있습니다. 이 함수를 사용하여 호스트 이름의 IP 주소를 확인할 수도 있습니다.
이 함수의 ANSI 버전은 getnameinfo입니다.
Winsock 헤더 파일의 매크로는 애플리케이션이 WINDOWS XP SP2(서비스 팩 2) 이상(_WIN32_WINNT = 0x0502>)을 대상으로 할 때 사용할 수 있는 GetNameInfo의 혼합 사례 함수 이름을 정의합니다. 이 GetNameInfo 함수는 TCHAR 형식의 포인터에 대한 pNodeBuffer 및 pServiceBuffer 매개 변수를 사용하여 호출해야 합니다. UNICODE 또는 _UNICODE 정의되면 GetNameInfo가 유니코드 버전에 정의되고 GetNameInfoW는 char 형식의 포인터의 호스트 및 serv 매개 변수를 사용하여 호출됩니다. UNICODE 또는 _UNICODE 정의되지 않은 경우 GetNameInfo는 ANSI 버전에 정의되고 getnameinfo는 PWCHAR 형식의 포인터에 대한 pNodeBuffer 및 pServiceBuffer 매개 변수를 사용하여 호출됩니다.
pNodeBuffer 및 pServiceBuffer 매개 변수에 대한 버퍼 요구 사항 확인을 간소화하기 위해 최대 호스트 이름 길이 및 최대 서비스 이름에 대한 다음 값은 Ws2tcpip.h 헤더 파일에 정의됩니다.
#include <windows.h>
#define NI_MAXSERV 32
#define NI_MAXHOST 1025
Flags 매개 변수를 사용하여 GetNameInfoW 함수의 처리를 사용자 지정할 수 있습니다. 사용할 수 있는 플래그는 다음과 같습니다.
- NI_NOFQDN
- NI_NUMERICHOST
- NI_NAMEREQD
- NI_NUMERICSERV
- NI_DGRAM
NI_NAMEREQD 플래그가 설정되면 DNS에서 확인할 수 없는 호스트 이름에 오류가 발생합니다.
NI_NOFQDN 플래그를 설정하면 로컬 호스트가 pNodeBuffer 매개 변수에 반환된 RDN(상대 고유 이름)만 반환됩니다.
NI_NUMERICHOST 플래그를 설정하면 해당 이름 대신 호스트 이름의 숫자 형식이 반환됩니다. 호스트 이름을 DNS에서 확인할 수 없는 경우에도 호스트 이름의 숫자 형식이 반환됩니다.
NI_NUMERICSERV 플래그를 설정하면 이름 대신 서비스의 포트 번호가 반환됩니다. 또한 IP 주소(예: 127.0.0.2)의 호스트 이름을 찾을 수 없는 경우 호스트 이름이 IP 주소로 반환됩니다.
Windows Vista 이상에서는 flags 매개 변수에 NI_NUMERICSERV 지정되지 않고 sa 매개 변수가 가리키는 sockaddr 구조에 포함된 포트 번호가 잘 알려진 서비스에 resolve 않으면 GetNameInfoW 함수는 서비스 주소(포트 번호)의 숫자 형식을 숫자 문자열로 반환합니다. NI_NUMERICSERV 지정하면 포트 번호가 숫자 문자열로 반환됩니다. 이 동작은 RFC 3493의 섹션 6.2에서 지정됩니다. 자세한 내용은 www.ietf.org/rfc/rfc3493.txt
Windows Server 2003 이하에서는 flags 매개 변수에 NI_NUMERICSERV 지정되지 않고 sa 매개 변수가 가리키는 sockaddr 구조에 포함된 포트 번호가 잘 알려진 서비스에 resolve 않으면 GetNameInfoW 함수가 실패합니다. NI_NUMERICSERV 지정하면 포트 번호가 숫자 문자열로 반환됩니다.
NI_DGRAM 플래그를 설정하면 서비스가 데이터그램 서비스임을 나타냅니다. 이 플래그는 UDP 및 TCP 서비스에 대해 서로 다른 포트 번호를 제공하는 몇 가지 서비스에 필요합니다.
Windows Phone 8: 이 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에서 지원됩니다.
Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상에서 Windows 스토어 앱에서 지원됩니다.
예제 코드
다음 예제에서는 GetNameInfoW 함수를 사용하는 방법을 보여 줍니다.#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
DWORD dwRetval;
struct sockaddr_in saGNI;
WCHAR hostname[NI_MAXHOST];
WCHAR servInfo[NI_MAXSERV];
u_short port = 27015;
// Validate the parameters
if (argc != 2) {
wprintf(L"usage: %s IPv4 address\n", argv[0]);
wprintf(L" to return hostname\n");
wprintf(L" %s 127.0.0.1\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
wprintf(L"WSAStartup failed: %d\n", iResult);
return 1;
}
//-----------------------------------------
// Set up sockaddr_in structure which is passed
// to the getnameinfo function
saGNI.sin_family = AF_INET;
saGNI.sin_addr.s_addr = inet_addr(argv[1]);
saGNI.sin_port = htons(port);
//-----------------------------------------
// Call GetNameInfoW
dwRetval = GetNameInfoW((struct sockaddr *) &saGNI,
sizeof (struct sockaddr),
hostname,
NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);
if (dwRetval != 0) {
wprintf(L"GetNameInfoW failed with error # %ld\n", WSAGetLastError());
return 1;
} else {
wprintf(L"GetNameInfoW returned hostname = %ws\n", hostname);
return 0;
}
}
참고
ws2tcpip.h 헤더는 GETNameInfo를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8.1, Windows Vista [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | ws2tcpip.h |
| 라이브러리 | Ws2_32.lib |
| DLL | Ws2_32.dll |