GetAddrInfoW 함수(ws2tcpip.h)
GetAddrInfoW 함수는 유니코드 호스트 이름에서 주소로 프로토콜 독립적 변환을 제공합니다.
구문
INT WSAAPI GetAddrInfoW(
[in, optional] PCWSTR pNodeName,
[in, optional] PCWSTR pServiceName,
[in, optional] const ADDRINFOW *pHints,
[out] PADDRINFOW *ppResult
);
매개 변수
[in, optional] pNodeName
호스트(노드) 이름 또는 숫자 호스트 주소 문자열을 포함하는 NULL로 끝나는 유니코드 문자열에 대한 포인터입니다. 인터넷 프로토콜의 경우 숫자 호스트 주소 문자열은 점선 10진수 IPv4 주소 또는 IPv6 16진수 주소입니다.
[in, optional] pServiceName
문자열로 표시되는 서비스 이름 또는 포트 번호를 포함하는 NULL로 종료된 유니코드 문자열에 대한 포인터입니다.
서비스 이름은 포트 번호의 문자열 별칭입니다. 예를 들어 "http"는 IETF(인터넷 엔지니어링 태스크 포스)에서 HTTP 프로토콜에 대해 웹 서버에서 사용하는 기본 포트로 정의된 포트 80의 별칭입니다. 포트 번호를 지정하지 않은 경우 pServiceName 매개 변수에 대한 가능한 값은 다음 파일에 나열됩니다.
%WINDIR%\system32\drivers\etc\services
[in, optional] pHints
호출자가 지원하는 소켓 유형에 대한 힌트를 제공하는 addrinfoW 구조체에 대한 포인터입니다.
pHints 매개 변수가 가리키는 addrinfoW 구조체의 ai_addrlen,ai_canonname, ai_addr 및 ai_next 멤버는 0 또는 NULL이어야 합니다. 그렇지 않으면 GetAddrInfoEx 함수가 WSANO_RECOVERY 실패합니다.
자세한 내용은 설명을 참조하세요.
[out] ppResult
호스트에 대한 응답 정보를 포함하는 하나 이상의 addrinfoW 구조체의 연결된 목록에 대한 포인터입니다.
반환 값
Success는 0을 반환합니다. 오류는 Windows 소켓 오류 코드에 있는 것처럼 0이 아닌 Windows 소켓 오류 코드를 반환합니다.
GetAddrInfoW 함수에서 반환되는 대부분의 0이 아닌 오류 코드는 IETF(Internet Engineering Task Force) 권장 사항에 설명된 오류 집합에 매핑됩니다. 다음 표에는 이러한 오류 코드와 해당 WSA에 해당하는 코드가 나와 있습니다. Winsock 프로그래머에게 친숙하고 포괄적인 오류 정보를 제공하므로 WSA 오류 코드를 사용하는 것이 좋습니다.
| 오류 값 | WSA 등가 | Description |
|---|---|---|
| EAI_AGAIN | WSATRY_AGAIN | 이름 확인에 일시적인 오류가 발생했습니다. |
| EAI_BADFLAGS | WSAEINVAL | pHints 매개 변수의 ai_flags 멤버에 대해 잘못된 값이 제공되었습니다. |
| EAI_FAIL | WSANO_RECOVERY | 이름 확인에서 복구할 수 없는 오류가 발생했습니다. |
| EAI_FAMILY | WSAEAFNOSUPPORT | pHints 매개 변수의 ai_family 멤버는 지원되지 않습니다. |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | 메모리 할당 오류가 발생했습니다. |
| EAI_NONAME | WSAHOST_NOT_FOUND | 제공된 매개 변수에 대한 이름이 resolve 않거나 pNodeName 및 pServiceName 매개 변수가 제공되지 않았습니다. |
| EAI_SERVICE | WSATYPE_NOT_FOUND | pServiceName 매개 변수는 pHints 매개 변수의 지정된 ai_socktype 멤버에 대해 지원되지 않습니다. |
| EAI_SOCKTYPE | WSAESOCKTNOSUPPORT | pHints 매개 변수의 ai_socktype 멤버는 지원되지 않습니다. |
gai_strerror 함수를 사용하여 GetAddrInfoW 함수에서 반환된 EAI_* 코드를 기반으로 오류 메시지를 출력합니다. gai_strerror 함수는 IETF 권장 사항을 준수하기 위해 제공되지만 스레드로부터 안전하지는 않습니다. 따라서 WSAGetLastError와 같은 기존 Windows 소켓 함수를 사용하는 것이 좋습니다.
| 오류 코드 | 의미 |
|---|---|
| 작업을 수행할 메모리가 부족했습니다. | |
| 요청한 프로토콜과 호환되지 않는 주소가 사용되었습니다. 이 오류는 hints 매개 변수가 가리키는 addrinfoW 구조체의 ai_family 멤버가 지원되지 않는 경우 반환됩니다. | |
| 잘못된 인수가 지정되었습니다. hints 매개 변수가 가리키는 addrinfoW 구조체의 ai_flags 멤버에 대해 잘못된 값이 제공된 경우 이 오류가 반환됩니다. | |
| 이 주소 패밀리에서는 지정된 소켓 형식이 지원되지 않습니다. hints 매개 변수가 가리키는 addrinfoW 구조체의 ai_socktype 멤버가 지원되지 않으면 이 오류가 반환됩니다. | |
| 호스트를 확인할 수 없습니다. 이 오류는 제공된 매개 변수에 대한 이름이 resolve 않거나 pNodename 및 pServicename 매개 변수가 제공되지 않은 경우 반환됩니다. | |
| 요청한 이름은 유효하지만 요청한 형식의 데이터를 찾을 수 없습니다. | |
| 데이터베이스 조회 중에 복구할 수 없는 오류가 발생했습니다. 이름 확인에서 복구할 수 없는 오류가 발생한 경우 이 오류가 반환됩니다. | |
| 이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다. | |
| 로컬 서버가 해당 서버로부터 응답을 받지 못해 발생한 일시적인 오류입니다. 이 오류는 이름 확인에서 일시적인 오류가 발생했을 때 반환됩니다. | |
| 지정된 클래스를 찾을 수 없습니다. pServiceName 매개 변수는 hints 매개 변수가 가리키는 addrinfoW 구조체의 지정된 ai_socktype 멤버에 대해 지원되지 않습니다. |
설명
GetAddrInfoW 함수는 호스트 이름에서 주소로 프로토콜 독립적 변환을 제공하는 함수의 유니코드 버전입니다. 이 함수의 ANSI 버전은 getaddrinfo입니다.
GetAddrInfoW 함수는 NS_DNS 네임스페이스에 대한 결과를 반환합니다. 두 개 이상의 네임스페이스 공급자가 정보를 반환하는 경우 GetAddrInfoW 함수는 모든 응답을 집계합니다. IPv6 및 IPv4 프로토콜과 함께 사용할 경우 이름 확인은 DNS(Domain Name System), 로컬 호스트 파일 또는 NS_DNS 네임스페이스에 대한 다른 명명 메커니즘을 통해 확인할 수 있습니다.
Winsock 헤더 파일의 매크로는 GetAddrInfo 의 혼합 대/소문자 함수 이름과 ADDRINFOT 구조를 정의합니다. 이 GetAddrInfo 함수는 TCHAR 형식의 포인터의 pNodeName 및 pServiceName 매개 변수와 ADDRINFOT 형식의 포인터에 대한 pHints 및 ppResult 매개 변수를 사용하여 호출해야 합니다. UNICODE 또는 _UNICODE 정의되면 GetAddrInfo 는 함수의 유니코드 버전인 GetAddrInfoW로 정의되고 ADDRINFOT 는 addrinfoW 구조에 정의됩니다. UNICODE 또는 _UNICODE 정의되지 않은 경우 GetAddrInfo 는 함수의 ANSI 버전인 getaddrinfo로 정의되고 ADDRINFOT 는 addrinfo 구조에 정의됩니다.
pNodeName 또는 pServiceName 매개 변수 중 하나 또는 둘 다 NULL로 종료된 유니코드 문자열을 가리킵니다. 일반적으로 둘 다 제공됩니다.
성공하면 addrinfoW 구조체의 연결된 목록이 ppResult 매개 변수에 반환됩니다. NULL 포인터가 발생할 때까지 반환된 각 addrinfoW 구조체의 ai_next 멤버에 제공된 포인터를 따라 목록을 처리할 수 있습니다. 반환된 각 addrinfoW 구조에서 ai_family, ai_socktype 및 ai_protocol 멤버는 소켓 또는 WSASocket 함수 호출의 각 인수에 해당합니다. 또한 반환된 각 addrinfoW 구조의 ai_addr 멤버는 채워진 소켓 주소 구조를 가리키며, 그 길이는 ai_addrlen 멤버에 지정됩니다.
pNodeName 매개 변수가 컴퓨터 이름을 가리키는 경우 원본 주소로 사용할 수 있는 컴퓨터의 모든 영구 주소가 반환됩니다. Windows Vista 이상에서 이러한 주소에는 MIB_UNICASTIPADDRESS_ROW 구조에서SkipAsSource 멤버가 false로 설정된 GetUnicastIpAddressTable 또는 GetUnicastIpAddressEntry 함수에서 반환된 모든 유니캐스트 IP 주소가 포함됩니다.
pNodeName 매개 변수가 "localhost"와 같은 문자열을 가리키는 경우 로컬 컴퓨터의 모든 루프백 주소가 반환됩니다.
pNodeName 매개 변수에 빈 문자열이 포함된 경우 로컬 컴퓨터의 등록된 모든 주소가 반환됩니다.
pNodeName 매개 변수가 ".와 같은 문자열을 가리키는 경우 Windows Server 2003 이상에서. localmachine", 로컬 컴퓨터에 등록된 모든 주소가 반환됩니다.
pNodeName 매개 변수가 클러스터 가상 서버 이름을 참조하는 경우 가상 서버 주소만 반환됩니다. Windows Vista 이상에서 이러한 주소에는 MIB_UNICASTIPADDRESS_ROW 구조에서SkipAsSource 멤버가 true로 설정된 GetUnicastIpAddressTable 또는 GetUnicastIpAddressEntry 함수에서 반환된 모든 유니캐스트 IP 주소가 포함됩니다. 클러스터링 대한 자세한 내용은 Windows 클러스터링을 참조하세요.
WINDOWS 7 sp1(서비스 팩 1) 및 Windows Server 2008 R2 SP1(서비스 팩 1)은 IP 주소에서 SkipAsSource 특성을 설정하기 위한 Netsh.exe 지원을 추가합니다. 또한 MIB_UNICASTIPADDRESS_ROW 구조의 SkipAsSource 멤버가 false로 설정된 경우 IP 주소가 DNS에 등록되도록 동작이 변경됩니다. SkipAsSource 멤버가 true로 설정된 경우 IP 주소가 DNS에 등록되지 않습니다.
IP 주소에서 SkipAsSource 특성을 설정하기 위한 Netsh.exe 지원을 추가하는 Windows 7 및 Windows Server 2008 R2에 핫픽스를 사용할 수 있습니다. 또한 이 핫픽스는 MIB_UNICASTIPADDRESS_ROW 구조의 SkipAsSource 멤버가 false로 설정된 경우 IP 주소가 DNS에 등록되도록 동작을 변경합니다. SkipAsSource 멤버가 true로 설정된 경우 IP 주소가 DNS에 등록되지 않습니다. 자세한 내용은 기술 자료(KB) 2386184 참조하세요.
IP 주소에서 SkipAsSource 특성을 설정하기 위한 Netsh.exe 지원을 추가하는 SP2(서비스 팩 2) 및 Windows Server 2008 SP2(서비스 팩 2)를 사용하는 Windows Vista에서도 비슷한 핫픽스를 사용할 수 있습니다. 또한 이 핫픽스는 MIB_UNICASTIPADDRESS_ROW 구조의 SkipAsSource 멤버가 false로 설정된 경우 IP 주소가 DNS에 등록되도록 동작을 변경합니다. SkipAsSource 멤버가 true로 설정된 경우 IP 주소가 DNS에 등록되지 않습니다.
GetAddrInfoW 함수의 호출자는 pHints 매개 변수가 가리키는 addrinfoW 구조를 통해 지원되는 소켓 유형에 대한 힌트를 제공할 수 있습니다. pHints 매개 변수를 사용하는 경우 연결된 addrinfoW 구조에 다음 규칙이 적용됩니다.
- ai_family AF_UNSPEC 값은 호출자가 AF_INET 및 AF_INET6 주소 패밀리만 수락했음을 나타냅니다. AF_UNSPEC 및 PF_UNSPEC 동일합니다.
- ai_socktype 값이 0이면 호출자가 소켓 유형을 수락합니다.
- ai_protocol 값이 0이면 호출자가 모든 프로토콜을 수락합니다.
- ai_addrlen 멤버를 0으로 설정해야 합니다.
- ai_canonname 멤버를 NULL로 설정해야 합니다.
- ai_addr 멤버를 NULL로 설정해야 합니다.
- ai_next 멤버를 NULL로 설정해야 합니다.
pHints 매개 변수에 제공된 addrinfoW 구조의 다른 값은 특정 요구 사항을 나타냅니다. 예를 들어 호출자가 IPv4만 처리하고 IPv6을 처리하지 않는 경우 ai_family 멤버를 AF_INET 설정해야 합니다. 또 다른 예에서는 호출자가 TCP만 처리하고 UDP를 처리하지 않는 경우 ai_socktype 멤버를 SOCK_STREAM 설정해야 합니다.
pHints 매개 변수가 NULL 포인터인 경우 GetAddrInfoW 함수는 pHints의 addrinfoW 구조체가 ai_family 멤버를 AF_UNSPEC 로 설정하고 다른 모든 멤버가 0으로 설정된 것처럼 처리합니다.
Windows Vista 이상에서 GetAddrInfoW 가 서비스에서 호출되는 경우 작업이 서비스를 호출하는 사용자 프로세스의 결과인 경우 서비스는 사용자를 가장해야 합니다. 이는 보안을 올바르게 적용할 수 있도록 하기 위한 것입니다.
GetAddrInfoW 함수를 사용하여 IP 주소의 텍스트 문자열 표현을 IP 주소 및 기타 정보에 대한 sockaddr 구조가 포함된 addrinfoW 구조체로 변환할 수 있습니다. 이러한 방식으로 사용하려면 pNodeName 매개 변수가 가리키는 문자열에 IP 주소의 텍스트 표현이 포함되어야 하며 pHints 매개 변수가 가리키는 addrinfoW 구조체에는 ai_flags 멤버에 설정된 AI_NUMERICHOST 플래그가 있어야 합니다. pNodeName 매개 변수가 가리키는 문자열에는 IPv4 또는 IPv6 주소의 텍스트 표현이 포함될 수 있습니다. 텍스트 IP 주소는 ppResult 매개 변수가 가리키는 addrinfoW 구조체로 변환됩니다. 반환된 addrinfoW 구조체에는 IP 주소에 대한 추가 정보와 함께 IP 주소에 대한 sockaddr 구조가 포함됩니다. 이 메서드가 Windows Server 2003 및 Windows XP에서 IPv6 주소 문자열로 작동하려면 로컬 컴퓨터에 IPv6 프로토콜을 설치해야 합니다. 그렇지 않으면 WSAHOST_NOT_FOUND 오류가 반환됩니다.
동적 할당에서 주소 정보 해제
ppResult 매개 변수가 가리키는 GetAddrInfoW 함수에서 반환하는 모든 정보는 addrinfoW 구조체, 소켓 주소 구조 및 addrinfoW 구조체가 가리키는 정식 호스트 이름 문자열을 포함하여 동적으로 할당됩니다. 이 함수에 대한 성공적인 호출에 의해 할당된 메모리는 FreeAddrInfoW에 대한 후속 호출과 함께 해제되어야 합니다.예제 코드
다음 코드 예제에서는 GetAddrInfoW 함수를 사용하는 방법을 보여줍니다.#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")
// set APPVER=5.02 for WinXP SP2 and later
int __cdecl wmain(int argc, wchar_t **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
INT iRetval;
DWORD dwRetval;
int i = 1;
ADDRINFOW *result = NULL;
ADDRINFOW *ptr = NULL;
ADDRINFOW hints;
// struct sockaddr_in6 *sockaddr_ipv6;
LPSOCKADDR sockaddr_ip;
wchar_t ipstringbuffer[46];
DWORD ipbufferlength = 46;
// Validate the parameters
if (argc != 3) {
wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
wprintf(L"getaddrinfow provides protocol-independent translation\n");
wprintf(L" from an Unicode host name to an IP address\n");
wprintf(L"%ws example usage\n", argv[0]);
wprintf(L" %ws www.contoso.com 0\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;
}
//--------------------------------
// Setup the hints address info structure
// which is passed to the getaddrinfo() function
ZeroMemory( &hints, sizeof(hints) );
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
wprintf(L"Calling getaddrinfow with following parameters:\n");
wprintf(L"\tnodename = %ws\n", argv[1]);
wprintf(L"\tservname (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call GetAddrinfoW(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfow structures containing response
// information
dwRetval = GetAddrInfoW(argv[1], argv[2], &hints, &result);
if ( dwRetval != 0 ) {
wprintf(L"GetAddrInfoW failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
wprintf(L"GetAddrInfoW returned success\n");
// Retrieve each address and print out the hex bytes
for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {
wprintf(L"GetAddrInfoW response %d\n", i++);
wprintf(L"\tFlags: 0x%x\n", ptr->ai_flags);
wprintf(L"\tFamily: ");
switch (ptr->ai_family) {
case AF_UNSPEC:
wprintf(L"Unspecified\n");
break;
case AF_INET:
wprintf(L"AF_INET (IPv4)\n");
sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
// The buffer length is changed by each call to WSAAddresstoString
// So we need to set it for each iteration through the loop for safety
ipbufferlength = 46;
iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL,
ipstringbuffer, &ipbufferlength );
if (iRetval)
wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
else
wprintf(L"\tIPv4 address %ws\n", ipstringbuffer);
break;
case AF_INET6:
wprintf(L"AF_INET6 (IPv6)\n");
// the InetNtop function is available on Windows Vista and later
// sockaddr_ipv6 = (struct sockaddr_in6 *) ptr->ai_addr;
// printf("\tIPv6 address %s\n",
// InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr, ipstringbuffer, 46) );
// We use WSAAddressToString since it is supported on Windows XP and later
sockaddr_ip = (LPSOCKADDR) ptr->ai_addr;
// The buffer length is changed by each call to WSAAddresstoString
// So we need to set it for each iteration through the loop for safety
ipbufferlength = 46;
iRetval = WSAAddressToString(sockaddr_ip, (DWORD) ptr->ai_addrlen, NULL,
ipstringbuffer, &ipbufferlength );
if (iRetval)
wprintf(L"WSAAddressToString failed with %u\n", WSAGetLastError() );
else
wprintf(L"\tIPv6 address %ws\n", ipstringbuffer);
break;
default:
wprintf(L"Other %ld\n", ptr->ai_family);
break;
}
wprintf(L"\tSocket type: ");
switch (ptr->ai_socktype) {
case 0:
wprintf(L"Unspecified\n");
break;
case SOCK_STREAM:
wprintf(L"SOCK_STREAM (stream)\n");
break;
case SOCK_DGRAM:
wprintf(L"SOCK_DGRAM (datagram) \n");
break;
case SOCK_RAW:
wprintf(L"SOCK_RAW (raw) \n");
break;
case SOCK_RDM:
wprintf(L"SOCK_RDM (reliable message datagram)\n");
break;
case SOCK_SEQPACKET:
wprintf(L"SOCK_SEQPACKET (pseudo-stream packet)\n");
break;
default:
wprintf(L"Other %ld\n", ptr->ai_socktype);
break;
}
wprintf(L"\tProtocol: ");
switch (ptr->ai_protocol) {
case 0:
wprintf(L"Unspecified\n");
break;
case IPPROTO_TCP:
wprintf(L"IPPROTO_TCP (TCP)\n");
break;
case IPPROTO_UDP:
wprintf(L"IPPROTO_UDP (UDP) \n");
break;
default:
wprintf(L"Other %ld\n", ptr->ai_protocol);
break;
}
wprintf(L"\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
wprintf(L"\tCanonical name: %s\n", ptr->ai_canonname);
}
FreeAddrInfoW(result);
WSACleanup();
return 0;
}
국제화된 도메인 이름
인터넷 호스트 이름은 일반적으로 매우 제한된 문자 집합으로 구성됩니다.- 영문자의 대문자 및 소문자 ASCII 문자.
- 0~9의 숫자.
- ASCII 하이픈 문자입니다.
인터넷이 증가함에 따라 ASCII 문자 집합으로 표현되지 않는 다른 언어의 인터넷 호스트 이름을 식별해야 하는 필요성이 증가하고 있습니다. 이러한 요구 사항을 용이하게 하고 비 ASCII 문자(유니코드)를 특수 ASCII 문자 문자열로 나타낼 수 있도록 하는 식별자를 IDN(Internationalized Domain Names)으로 알려져 있습니다. IDNA(애플리케이션에서 도메인 이름 국제화)라는 메커니즘은 표준 방식으로 IDN을 처리하는 데 사용됩니다. IDN 및 IDNA 사양은 IETF(인터넷 엔지니어링 태스크 포스)에서 게시한 RFC 3490, RTF 5890 및 RFC 6365 에 설명되어 있습니다.
Windows 8 및 Windows Server 2012에서 GetAddrInfoW 함수는 pNodeName 매개 변수에 전달된 이름에 적용되는 IDN(Internationalized Domain Name) 구문 분석에 대한 지원을 제공합니다. Winsock은 Punycode/IDN 인코딩 및 변환을 수행합니다. 이 동작은 아래에 설명된 AI_DISABLE_IDN_ENCODING 플래그를 사용하여 사용하지 않도록 설정할 수 있습니다.
Windows 7 및 Windows Server 2008 R2 이하에서 GetAddrInfoW 함수는 현재 pNodeName 매개 변수에 전달된 이름에 적용되는 IDN 구문 분석에 대한 지원을 제공하지 않습니다. Winsock은 Punycode/IDN 변환을 수행하지 않습니다. GetAddrInfoW 함수는 RFC 3490에 따라 IDN을 변환하기 위해 Punycode를 사용하지 않습니다. DNS를 쿼리할 때 GetAddrInfoW 함수는 엔터프라이즈 환경의 Microsoft DNS 서버에서 사용하는 형식인 UTF-8 형식으로 유니코드 이름을 인코딩합니다.
Windows Vista 및 이후의 여러 함수는 IDN의 유니코드 레이블 간 변환을 ASCII 등가물로 지원합니다. 각 유니코드 레이블의 결과 표현은 ASCII 문자만 포함하고 유니코드 레이블에 ASCII가 아닌 문자가 포함된 경우 xn-- 접두사로 시작합니다. 일부 DNS 도구 및 서버는 ASCII 문자만 지원하므로 인터넷의 기존 DNS 서버를 지원하기 때문입니다( RFC 3490 참조).
IdnToAscii 함수는 PUNycode를 사용하여 RFC 3490에 정의된 표준 알고리즘을 사용하여 IDN을 원래 유니코드 문자열의 ASCII 표현으로 변환합니다. IdnToUnicode 함수는 IDN의 ASCII 형식을 일반 유니코드 UTF-16 인코딩 구문으로 변환합니다. 관련 초안 표준에 대한 자세한 내용 및 링크는 IDN(Internationalized Domain Name) 처리를 참조하세요.
IdnToAscii 함수를 사용하여 IDN 이름을 ASCII 양식으로 변환할 수 있습니다. 이 ASCII 양식을 GetAddrInfoW 함수에 전달하려면 MultiByteToWideChar 함수를 사용하여 CHAR 문자열을 WCHAR 문자열로 변환한 다음 pNodeName 매개 변수에서 GetAddrInfoW 함수에 전달할 수 있습니다.
hints 매개 변수에서 ai_flags 사용
pHints 매개 변수에 제공된 선택적 addrinfoW 구조체의 ai_flags 멤버의 플래그는 함수의 동작을 수정합니다.
이러한 플래그 비트는 Windows 7용 Microsoft SDK(Windows 소프트웨어 개발 키트)의 Ws2def.h 헤더 파일에 정의되어 있습니다. 이러한 플래그 비트는 Windows Server 2008 및 Windows Vista용 Windows SDK의 Ws2tcpip.h 헤더 파일에 정의되어 있습니다. 이러한 플래그 비트는 Windows Server 2003 및 Windows XP용 SDK(플랫폼 소프트웨어 개발 키트)의 Ws2tcpip.h 헤더 파일에 정의됩니다.
플래그 비트는 다음의 조합일 수 있습니다.
| 플래그 비트 | 설명 |
|---|---|
| AI_PASSIVE |
AI_PASSIVE 플래그를 설정하면 호출자가 바인딩 함수 호출에서 반환된 소켓 주소 구조를 사용하려고 했음을 나타냅니다. AI_PASSIVE 플래그가 설정되고 pNodeName이 NULL 포인터인 경우 소켓 주소 구조의 IP 주소 부분은 IPv4 주소에 대해 INADDR_ANY, IPv6 주소의 경우 IN6ADDR_ANY_INIT 설정됩니다.
AI_PASSIVE 플래그가 설정되지 않은 경우 반환된 소켓 주소 구조는 연결 지향 프로토콜에 대한 connect 함수를 호출하거나 연결 없는 프로토콜에 대한 connect, sendto 또는 send 함수를 호출할 준비가 됩니다. 이 경우 pNodeName 매개 변수가 NULL 포인터인 경우 소켓 주소 구조의 IP 주소 부분은 루프백 주소로 설정됩니다. |
| AI_CANONNAME |
AI_CANONNAME 또는 AI_NUMERICHOST 모두 사용되지 않으면 GetAddrInfoW 함수는 해결을 시도합니다. 리터럴 문자열이 전달된 경우 GetAddrInfoW는 문자열을 변환하려고 시도하고 호스트 이름이 전달되면 GetAddrInfoW 함수는 이름을 주소 또는 여러 주소로 resolve 시도합니다.
AI_CANONNAME 비트가 설정되면 pNodeName 매개 변수는 NULL일 수 없습니다. 그렇지 않으면 GetAddrInfoEx 함수가 WSANO_RECOVERY 실패합니다. AI_CANONNAME 비트가 설정되고 GetAddrInfoW 함수가 성공을 반환하면 ppResult 매개 변수의 ai_canonname 멤버는 지정된 노드의 정식 이름을 포함하는 NULL로 끝나는 문자열을 가리킵니다. 참고GetAddrInfoW 함수는 AI_CANONNAME 플래그가 설정된 경우 성공을 반환할 수 있지만 연결된 addrinfoW 구조의 ai_canonname 멤버는 NULL입니다. 따라서 AI_CANONNAME 플래그를 사용하는 것이 좋습니다. 여기에는 연결된 addrinfoW 구조의 ai_canonname 멤버가 NULL인지 여부를 테스트하는 것이 포함됩니다.
|
| AI_NUMERICHOST | AI_NUMERICHOST 비트가 설정되면 pNodeName 매개 변수에 NULL이 아닌 숫자 호스트 주소 문자열이 포함되어야 합니다. 그렇지 않으면 EAI_NONAME 오류가 반환됩니다. 이 플래그를 사용하면 이름 확인 서비스가 호출되지 않습니다. |
| AI_NUMERICSERV |
AI_NUMERICSERV 비트가 설정되면 pServiceName 매개 변수에 NULL이 아닌 숫자 포트 번호가 포함되어야 합니다. 그렇지 않으면 EAI_NONAME 오류가 반환됩니다. 이 플래그를 사용하면 이름 확인 서비스가 호출되지 않습니다.
AI_NUMERICSERV 플래그는 Windows Vista용 Windows SDK 이상에서 정의됩니다. AI_NUMERICSERV 플래그는 Microsoft 공급자에서 지원되지 않습니다. |
| AI_ALL |
AI_ALL 비트가 설정되면 AI_V4MAPPED 있는 IPv6 주소 및 IPv4 주소에 대한 요청이 이루어집니다.
AI_ALL 플래그는 Windows Vista용 Windows SDK 이상에서 정의됩니다. AI_ALL 플래그는 Windows Vista 이상에서 지원됩니다. |
| AI_ADDRCONFIG |
AI_ADDRCONFIG 비트가 설정된 경우 GetAddrInfoW는 전역 주소가 구성된 경우에만 resolve. AI_ADDRCONFIG 플래그를 지정하는 경우 IPv4 주소는 로컬 시스템에 IPv4 주소가 구성된 경우에만 반환되고 IPv6 주소는 로컬 시스템에 구성된 경우에만 반환됩니다. IPv4 또는 IPv6 루프백 주소는 유효한 전역 주소로 간주되지 않습니다.
AI_ADDRCONFIG 플래그는 Windows Vista용 Windows SDK 이상에서 정의됩니다. AI_ADDRCONFIG 플래그는 Windows Vista 이상에서 지원됩니다. |
| AI_V4MAPPED |
AI_V4MAPPED 비트가 설정되고 IPv6 주소에 대한 요청이 실패하면 IPv4 주소에 대한 이름 서비스 요청이 이루어지고 이러한 주소는 IPv4 매핑된 IPv6 주소 형식으로 변환됩니다.
AI_V4MAPPED 플래그는 Windows Vista용 Windows SDK 이상에서 정의됩니다. AI_V4MAPPED 플래그는 Windows Vista 이상에서 지원됩니다. |
| AI_NON_AUTHORITATIVE |
AI_NON_AUTHORITATIVE 비트가 설정되면 NS_EMAIL 네임스페이스 공급자는 신뢰할 수 있는 결과와 신뢰할 수 없는 결과를 모두 반환합니다. AI_NON_AUTHORITATIVE 비트가 설정되지 않은 경우 NS_EMAIL 네임스페이스 공급자는 신뢰할 수 있는 결과만 반환합니다.
AI_NON_AUTHORITATIVE 플래그는 Windows Vista용 Windows SDK 이상에서 정의됩니다. AI_NON_AUTHORITATIVE 플래그는 Windows Vista 이상에서 지원되며 NS_EMAIL 네임스페이스에만 적용됩니다. |
| AI_SECURE |
AI_SECURE 비트가 설정된 경우 NS_EMAIL 네임스페이스 공급자는 보안 강화를 통해 얻은 결과를 반환하여 스푸핑 가능성을 최소화합니다.
AI_SECURE 플래그는 Windows Vista용 Windows SDK 이상에서 정의됩니다. AI_SECURE 플래그는 Windows Vista 이상에서 지원되며 NS_EMAIL 네임스페이스에만 적용됩니다. |
| AI_RETURN_PREFERRED_NAMES |
AI_RETURN_PREFERRED_NAMES 설정된 경우 pNodeName 매개 변수에 이름을 입력하지 않아야 합니다. NS_EMAIL 네임스페이스 공급자는 게시에 대한 기본 이름을 반환합니다.
AI_RETURN_PREFERRED_NAMES 플래그는 Windows Vista용 Windows SDK 이상에서 정의됩니다. AI_RETURN_PREFERRED_NAMES 플래그는 Windows Vista 이상에서 지원되며 NS_EMAIL 네임스페이스에만 적용됩니다. |
| AI_FQDN |
AI_FQDN 설정되고 플랫 이름(단일 레이블)을 지정하면 GetAddrInfoW는 이름이 최종적으로 확인된 정규화된 도메인 이름을 반환합니다. 정규화된 도메인 이름은 연결된 addrinfoW 구조의 ai_canonname 멤버에 반환됩니다. 이는 DNS에 등록된 정식 이름을 반환하는 AI_CANONNAME 비트 플래그와 다르며, 이는 플랫 이름이 확인된 정규화된 도메인 이름과 다를 수 있습니다. AI_FQDN 및 AI_CANONNAME 비트 중 하나만 설정할 수 있습니다. 두 플래그가 모두 EAI_BADFLAGS 있으면 GetAddrInfoW 함수가 실패합니다.
AI_FQDN 비트가 설정되면 pNodeName 매개 변수는 NULL일 수 없습니다. 그렇지 않으면 GetAddrInfoEx 함수가 WSANO_RECOVERY 실패합니다. Windows 7: AI_FQDN 플래그는 Windows 7 이상용 Windows SDK에 정의되어 있습니다. AI_FQDN 플래그는 Windows 7 이상에서 지원됩니다. |
| AI_FILESERVER |
AI_FILESERVER 설정된 경우 쿼리 중인 호스트 이름이 파일 공유 시나리오에서 사용되고 있음을 네임스페이스 공급자에 대한 힌트입니다. 네임스페이스 공급자는 이 힌트를 무시할 수 있습니다.
Windows 7: AI_FILESERVER 플래그는 Windows 7 이상용 Windows SDK에 정의되어 있습니다. AI_FILESERVER 플래그는 Windows 7 이상에서 지원됩니다. |
| AI_DISABLE_IDN_ENCODING |
AI_DISABLE_IDN_ENCODING 설정된 경우 GetAddrInfoW 함수에서 호출하는 이름 확인 함수에서 Punycode를 사용하여 자동 국제 도메인 이름 인코딩을 사용하지 않도록 설정합니다.
Windows 8: AI_DISABLE_IDN_ENCODING 플래그는 Windows 8 이상용 Windows SDK에 정의되어 있습니다. AI_DISABLE_IDN_ENCODING 플래그는 Windows 8 이상에서 지원됩니다. |
Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상의 Windows 스토어 앱에서 지원됩니다.
참고
ws2tcpip.h 헤더는 GETAddrInfo를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows 8.1, Windows Vista [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | ws2tcpip.h |
| 라이브러리 | Ws2_32.lib |
| DLL | Ws2_32.dll |
참고 항목
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기