The GetAddrInfoW function provides protocol-independent translation from a Unicode host name to an address.

Syntax

int WSAAPI GetAddrInfoW(
  __in_opt  PCWSTR pNodeName,
  __in_opt  PCWSTR pServiceName,
  __in_opt  const ADDRINFOW *pHints,
  __out     PADDRINFOW *ppResult
);

Parameters

pNodeName [in, optional]

A pointer to a NULL-terminated Unicode string that contains a host (node) name or a numeric host address string. For the Internet protocol, the numeric host address string is a dotted-decimal IPv4 address or an IPv6 hex address.

pServiceName [in, optional]

A pointer to a NULL-terminated Unicode string that contains either a service name or port number represented as a string.

pHints [in, optional]

A pointer to an addrinfoW structure that provides hints about the type of socket the caller supports. See Remarks for more details.

ppResult [out]

A pointer to a linked list of one or more addrinfoW structures that contains response information about the host.

Return Value

Success returns zero. Failure returns a nonzero Windows Sockets error code, as found in the Windows Sockets Error Codes.

Nonzero error codes returned by the GetAddrInfoW function also map to the set of errors outlined by Internet Engineering Task Force (IETF) recommendations. The following table lists these error codes and their WSA equivalents. It is recommended that the WSA error codes be used, as they offer familiar and comprehensive error information for Winsock programmers.

Use the gai_strerror function to print error messages based on the EAI_* codes returned by the GetAddrInfoW function. The gai_strerror function is provided for compliance with IETF recommendations, but it is not thread safe. Therefore, use of a traditional Windows Sockets function, such as WSAGetLastError, is recommended.

Remarks

The GetAddrInfoW function is the Unicode version of a function that provides protocol-independent translation from host name to address. The GetAddrInfoW function aggregates all responses if more than one namespace provider returns information.

For use with the IPv6 and IPv4 protocol, name resolution can be by the Domain Name System (DNS), a local hosts file, or by other naming mechanisms.

The ANSI version of this function is getaddrinfo.

Macros in the Winsock header file define a mixed-case function name of GetAddrInfo and a ADDRINFOT structure. This GetAddrInfo function should be called with the pNodeName and pServiceName parameters of a pointer of type TCHAR and the pHints and ppResult parameters of a pointer of type ADDRINFOT. When UNICODE or _UNICODE is defined, GetAddrInfo is defined to GetAddrInfoW, the Unicode version of the function, and ADDRINFOT is defined to the addrinfoW structure. When UNICODE or _UNICODE is not defined, GetAddrInfo is defined to getaddrinfo, the ANSI version of the function, and ADDRINFOT is defined to the addrinfo structure.

One or both of the pNodeName or pServiceName parameters must point to a NULL-terminated Unicode string; generally both are provided.

Upon success, a linked list of addrinfoW structures is returned in the ppResult parameter. The list can be processed by following the pointer provided in the ai_next member of each returned addrinfoW structure until a NULL pointer is encountered. In each returned addrinfoW structure, the ai_family, ai_socktype, and ai_protocol members correspond to respective arguments in a socket or WSASocket function call. Also, the ai_addr member in each returned addrinfoW structure points to a filled-in socket address structure, the length of which is specified in its ai_addrlen member.

If pNodeName is a computer name, the permanent addresses for the computer are returned. If pNodeName contains the string "..localmachine" or "localhost", all registered addresses are returned. If pNodeName refers to a cluster virtual server name, only virtual server addresses are returned. For more information about clustering, see Windows Clustering.

Callers of the GetAddrInfoW function can provide hints about the type of socket supported through an addrinfoW structure pointed to by the pHints parameter. When the pHints parameter is used, the following rules apply to its associated addrinfoW structure:

• A value of AF_UNSPEC for ai_family indicates the caller will accept any protocol family. Be aware that AF_UNSPEC and PF_UNSPEC are the same.
• A value of zero for ai_socktype indicates the caller will accept any socket type.
• A value of zero for ai_protocol indicates the caller will accept any protocol.
• The ai_addrlen member must be set to zero.
• The ai_canonname member must be set to NULL.
• The ai_addr member must be set to NULL.
• The ai_next member must be set to NULL.

Other values in the addrinfoW structure provided in the pHints parameter indicate specific requirements. For example, if the caller handles only IPv4 and does not handle IPv6, the ai_family member should be set to AF_INET. For another example, if the caller handles only TCP and does not handle UDP, the ai_socktype member should be set to SOCK_STREAM.

If the pHints parameter is a NULL pointer, the GetAddrInfoW function handles it as if the addrinfoW structure in pHints were initialized with its ai_family member set to AF_UNSPEC and all other members set to zero.

On Windows Vista and later when GetAddrInfoW is called from a service, if the operation is the result of a user process calling the service, then the service should impersonate the user. This is to allow security to be properly enforced.

The GetAddrInfoW function can be used to convert a text string representation of an IP address to an addrinfoW structure that contains a sockaddr structure for the IP address and other information. To be used in this way, the string pointed to by the pNodeName parameter must contain a text representation of an IP address and the addrinfoW structure pointed to by the pHints parameter must have the AI_NUMERICHOST flag set in the ai_flags member. The string pointed to by the pNodeName parameter may contain a text representation of either an IPv4 or an IPv6 address. The text IP address is converted to an addrinfoW structure pointed to by the ppResult parameter. The returned addrinfoW structure contains a sockaddr structure for the IP address along with additional information about the IP address. For this method to work with an IPv6 address string on Windows Server 2003 and Windows XP, the IPv6 protocol must be installed on the local computer. Otherwise, the WSAHOST_NOT_FOUND error is returned.

Freeing Address Information from Dynamic Allocation

All information returned by the GetAddrInfoW function pointed to by the ppResult parameter is dynamically allocated, including all addrinfoW structures, socket address structures, and canonical host name strings pointed to by addrinfoW structures. Memory allocated by a successful call to this function must be released with a subsequent call to FreeAddrInfoW.

Example Code

The following code example shows how to use the GetAddrInfoW function.

#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

#define UNICODE 1

// set APPVER=5.02 for WinXP SP2 and later
// link with Ws2_32.lib

int __cdecl wmain(int argc, wchar_t **argv)
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult;

    DWORD dwRetval;

    int i = 1;
    
    WCHAR *port = L"27015";

    ADDRINFOW *result = NULL;
    ADDRINFOW *ptr = NULL;
    ADDRINFOW hints;


    // Validate the parameters
    if (argc != 2) {
        wprintf(L"usage: %ws <hostname>\n", argv[0]);
        wprintf(L"  getaddrinfow provides protocol-independent translation\n");
        wprintf(L"     from a Unicode host name to an IP address\n");
        wprintf(L"      %ws www.contoso.com\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;


//--------------------------------
// Call GetAddrinfoW(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfow structures containing response
// information
    dwRetval = GetAddrInfoW(argv[1], port, &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");
                break;
            case AF_INET6:
                wprintf(L"AF_INET6 (IPv6)\n");
                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;
}

Note  Ensure that the development environment targets the newest version of Ws2tcpip.h which includes structure and function definitions for addrinfoW and GetAddrInfoW, respectively.

International Resource Identifiers

Web addresses are typically expressed using uniform resource identifiers (URIs) that consist of a very restricted set of characters:

• Upper and lower case ASCII letters from the English alphabet.
• Digits from 0 to 9.
• A small number of other ASCII symbols.

With the growth of the Internet, there is a growing need to identify resources using languages other than English. Identifiers which facilitate this need and allow non-ASCII characters (characters in the Unicode/ISO 10646 character set) are known as International Resource Identifiers (IRIs). The specifications for IRIs are documented in RFC 3987 published by IETF. Using IRIs allows a URL to contain Unicode characters.

The existing GetAddrInfoW function does not currently provide support for IRI or Internationalized Domain Name (IDN) parsing applied to the name passed in the pNodeName parameter. Winsock does not perform any punycode/IDN conversion for any version of Windows including Windows 7. The GetAddrInfoW function queries for the Unicode name in the UTF-8 format and as per RFC 3490 and does not convert the Unicode name to Punycode.

Several functions on Windows Vista and later support the conversion between Unicode labels in a domain name that represent International Domain Names to their Punycode equivalents. Punycode names contain only ASCII characters and always start with the xn-- prefix. The reason for this is to support existing DNS servers on the Internet, since most DNS servers only support ASCII characters (see RFC 3940).

The IdnToAscii function converts an internationalized domain name or other internationalized label to a wide character representation of the ASCII string that represents the name in the Punycode transfer encoding syntax. The IdnToUnicode function converts the Punycode form of an internationalized domain name or another internationalized label to the normal Unicode UTF-16 encoding syntax. For more information and links to related draft standards, see Handling Internationalized Domain Names (IDNs).

The IdnToAscii function can be used to convert an IDN name to a wide character Punycode form that then can be passed in the pNodeName parameter to the GetAddrInfoW function. The IdnToAscii function can also be used to convert an IDN name to a Punycode form that can then be passed in the pName parameter to the GetAddrInfoEx function and the nodename parameter to the getaddrinfo when the wide chartacter versions of these functions are used (when UNICODE or _UNICODE is defined).

Use of ai_flags in the hints parameter

Flags in the ai_flags member of the optional addrinfoW structure provided in the pHints parameter modify the behavior of the function.

These flag bits are defined in the Ws2def.h header file on the Microsoft Windows Software Development Kit (SDK) for Windows 7. These flag bits are defined in the Ws2tcpip.h header file on the Windows SDK for Windows Server 2008 and Windows Vista. These flag bits are defined in the Ws2tcpip.h header file on the Platform Software Development Kit (SDK) for Windows Server 2003, and Windows XP.

The flag bits can be a combination of the following:

Requirements

See Also

addrinfo

addrinfoW

bind

connect

FreeAddrInfoW

gai_strerror

getaddrinfo

GetAddrInfoEx

IdnToAscii

IdnToUnicode

send

sendto

socket

Winsock Functions

Winsock Reference

WSAGetLastError

WSASocket

Send comments about this topic to Microsoft

Build date: 7/9/2009