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