GetAddrInfoEx Function

The GetAddrInfoEx function provides protocol-independent name resolution with additional parameters to qualify which namespace providers should handle the request.

Syntax

int WSAAPI GetAddrInfoEx(
  __in_opt   PCTSTR pName,
  __in_opt   PCTSTR pServiceName,
  __in       DWORD dwNameSpace,
  __in_opt   LPGUID lpNspId,
  __in_opt   const ADDRINFOEX *pHints,
  __out      PADDRINFOEX *ppResult,
  __in_opt   struct timeval *timeout,
  __in_opt   LPOVERLAPPED lpOverlapped,
  __in_opt   LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
  __out_opt  LPHANDLE lpNameHandle
);

Parameter

• pName [in, optional]
  A pointer to a NULL-terminated string containing 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 an optional NULL-terminated string that contains either a service name or port number represented as a string.

  A service name is a string alias for a port number. For example, “http” is an alias for port 80 defined by the Internet Engineering Task Force (IETF) as the default port used by web servers for the HTTP protocol. Possible values for the pServiceName parameter when a port number is not specified are listed in the following file:

  %WINDIR%\system32\drivers\etc\services

• dwNameSpace [in]
  An optional namespace identifier that determines which namespace providers are queried. Passing a specific namespace identifier will result in only namespace providers that support the specified namespace being queried. Specifying NS_ALL will result in all installed and active namespace providers being queried.

  Options for the dwNameSpace parameter are listed in the Winsock2.h include file. Several namespace providers are added on Windows Vista and later. Other namespace providers can be installed, so the following possible values are only those commonly available. Many other values are possible.

  Wert	Bedeutung
  NS_ALL 0	All installed and active namespaces.
  NS_DNS 12	The domain name system (DNS) namespace.
  NS_NETBT 13	The NetBIOS over TCP/IP (NETBT) namespace.
  NS_WINS 14	The Windows Internet Naming Service (NS_WINS) namespace.
  NS_NLA 15	The network location awareness (NLA) namespace. This namespace identifier is supported on Windows XP and later.
  NS_BTH 16	The Bluetooth namespace. This namespace identifier is supported on Windows Vista and later.
  NS_NTDS 32	The Windows NT Directory Services (NS_NTDS) namespace.
  NS_EMAIL 37	The email namespace. This namespace identifier is supported on Windows Vista and later.
  NS_PNRPNAME 38	The peer-to-peer namespace for a specific peer name. This namespace identifier is supported on Windows Vista and later.
  NS_PNRPCLOUD 39	The peer-to-peer namespace for a collection of peer names. This namespace identifier is supported on Windows Vista and later.

   

• lpNspId [in, optional]
  A pointer to an optional GUID of a specific namespace provider to query in the case where multiple namespace providers are registered under a single namespace such as NS_DNS. Passing the GUID for specific namespace provider will result in only the specified namespace provider being queried. The WSAEnumNameSpaceProviders function can be called to retrieve the GUID for a namespace provider.

• pHints [in, optional]
  A pointer to an addrinfoex 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 addrinfoex structures that contains response information about the host.

• timeout [in, optional]
  An optional parameter indicating the time, in milliseconds, to wait for a response from the namespace provider before aborting the call. This parameter is currently reserved and must be set to NULL since a timeout option is not supported.

• lpOverlapped [in, optional]
  An optional pointer to an overlapped structure used for asynchronous operation. This parameter is currently reserved and must be set to NULL since asynchronous operations are not supported.

• lpCompletionRoutine [in, optional]
  An optional pointer to a function to be invoked upon successful completion for asynchronous operations. This parameter is currently reserved and must be set to NULL since asynchronous operations are not supported.

• lpNameHandle [out, optional]
  An optional pointer used only for asynchronous operations. This parameter is currently reserved and must be set to NULL since asynchronous operations are not supported.

Rückgabewert

On success, GetAddrInfoEx returns NO_ERROR (0). Failure returns a nonzero Windows Sockets error code, as found in the Windows Sockets Error Codes.

Most nonzero error codes returned by the GetAddrInfoEx function map to the set of errors outlined by Internet Engineering Task Force (IETF) recommendations. The following table shows 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 GetAddrInfoEx function. The gai_strerror function is provided for compliance with IETF recommendations, but it is not thread safe. Therefore, use of traditional Windows Sockets functions such as WSAGetLastError is recommended.

Hinweise

The GetAddrInfoEx function provides protocol-independent translation from host name to address and from service name to port number. The GetAddrInfoEx function is an enhanced version of the getaddrinfo and GetAddrInfoW functions. The GetAddrInfoEx function allows specifying the namespace provider to resolve the query.

The GetAddrInfoEx function aggregates and returns results from multiple namespace providers, unless a specific namespace provider is specified. For use with the IPv6 and IPv4 protocol, name resolution can be by the Domain Name System (DNS), a local hosts file, an email provider (the NS_EMAIL namespace), or by other naming mechanisms.

When UNICODE or _UNICODE is defined, GetAddrInfoEx is defined to GetAddrInfoExW, the Unicode version of this function. The string parameters are defined to the PWSTR data type and the ADDRINFOEXW structure is used.

When UNICODE or _UNICODE is not defined, GetAddrInfoEx is defined to GetAddrInfoExA, the ANSI version of this function. The string parameters are of the PCSTR data type and the ADDRINFOEXA structure is used.

One or both of the pName or pServiceName parameters must point to a NULL-terminated string. Generally both are provided.

Upon success, a linked list of addrinfoex 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 addrinfoex structure until a NULL pointer is encountered. In each returned addrinfoex 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 addrinfoex structure points to a filled-in socket address structure, the length of which is specified in its ai_addrlen member.

If the pName parameter points to a computer name, all permanent addresses for the computer that can be used as a source address are returned. On Windows Vista and later, these addresses would include all unicast IP addresses returned by the GetUnicastIpAddressTable or GetUnicastIpAddressEntry functions in which the SkipAsSource member is set to false in the MIB_UNICASTIPADDRESS_ROW structure.

If the pName parameter points to a string equal to "localhost", all loopback addresses on the local computer are returned.

If the pName parameter contains an empty string, all registered addresses on the local computer are returned.

On Windows Server 2003 and later if the pName parameter points to a string equal to "..localmachine", all registered addresses on the local computer are returned.

If the pName parameter refers to a cluster virtual server name, only virtual server addresses are returned. On Windows Vista and later, these addresses would include all unicast IP addresses returned by the GetUnicastIpAddressTable or GetUnicastIpAddressEntry functions in which the SkipAsSource member is set to true in the MIB_UNICASTIPADDRESS_ROW structure. See Windows Clustering for more information about clustering.

Windows 7 mit Service Pack 1 (SP1) and Windows Server 2008 R2 mit Service Pack 1 (SP1) add support to Netsh.exe for setting the SkipAsSource attribute on an IP address. This also changes the behavior such that if the SkipAsSource member in the MIB_UNICASTIPADDRESS_ROW structure is set to false, the IP address will be registered in DNS. If the SkipAsSource member is set to true, the IP address is not registered in DNS.

A hotfix is available for Windows 7 and Windows Server 2008 R2 that adds support to Netsh.exe for setting the SkipAsSource attribute on an IP address. This hotfix also changes behavior such that if the SkipAsSource member in the MIB_UNICASTIPADDRESS_ROW structure is set to false, the IP address will be registered in DNS. If the SkipAsSource member is set to true, the IP address is not registered in DNS. For more information, see Knowledge Base (KB) 2386184.

A similar hotfix is also available for Windows Vista mit Service Pack 2 (SP2) and Windows Server 2008 mit Service Pack 2 (SP2) that adds support to Netsh.exe for setting the SkipAsSource attribute on an IP address. This hotfix also changes behavior such that if the SkipAsSource member in the MIB_UNICASTIPADDRESS_ROW structure is set to false, the IP address will be registered in DNS. If the SkipAsSource member is set to true, the IP address is not registered in DNS. For more information, see Knowledge Base (KB) 975808.

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

• A value of AF_UNSPEC for ai_family indicates the caller will accept any address family. Note 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 addrinfoex 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 GetAddrInfoEx function treats it as if the addrinfoex structure in pHints were initialized with its ai_family member set to AF_UNSPEC and all other members set to NULL or zero.

When GetAddrInfoEx is called from a service, if the operation is the result of a user process calling the service, the service should impersonate the user. This is to allow security to be properly enforced.

The GetAddrInfoEx function can be used to convert a text string representation of an IP address to an addrinfoex 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 pName parameter must contain a text representation of an IP address and the addrinfoex 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 pName parameter may contain a text representation of either an IPv4 or an IPv6 address. The text IP address is converted to an addrinfoex structure pointed to by the ppResult parameter. The returned addrinfoex structure contains a sockaddr structure for the IP address along with additional information about the IP address.

Multiple namespace providers may be installed on a local computer for the same namespace. For example, the base Windows TCP/IP networking software registers for the NS_DNS namespace. The Microsoft Forefront Threat Management Gateway (TMG) and the older Microsoft Internet Security and Acceleration (ISA) Server include Firewall Client software that also registers for the NS_DNS namespace. When the dwNameSpace parameter is set to a value (NS_DNS, for example) and the lpNspId parameter is NULL, the results returned by the GetAddrInfoEx function are the merged results from all namespace providers that register for the specified namespace. The lpNspId parameter should be set to the GUID of the specific namespace provider if only a single namespace provider is to be queried.

Freeing Address Information from Dynamic Allocation

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

Example Code

The following example demonstrates the use of the GetAddrInfoEx function.

#define UNICODE 1

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

// link with Ws2_32.lib

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

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

    DWORD dwRetval;

    int i = 1;
    
    DWORD dwNamespace = NS_ALL;
      LPGUID lpNspid = NULL;


    ADDRINFOEX *result = NULL;
    ADDRINFOEX *ptr = NULL;
    ADDRINFOEX hints;

    struct sockaddr_in * sockaddr_ipv4;
    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"getaddrinfoex provides protocol-independent translation\n");
        wprintf(L"   from a 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 GetAddrInfoEx with following parameters:\n");
    wprintf(L"\tName = %ws\n", argv[1]);
    wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);

//--------------------------------
// Call getaddrinfoex(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
    dwRetval = GetAddrInfoEx(argv[1], argv[2], dwNamespace, lpNspid, &hints, &result,
        NULL, NULL, NULL, NULL);
    if ( dwRetval != 0 ) {
        wprintf(L"GetAddrInfoEx failed with error: %d\n", dwRetval);
        WSACleanup();
        return 1;
    }

    wprintf(L"GetAddrInfoEx returned success\n");
    
    // Retrieve each address and print out the hex bytes
    for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {

        wprintf(L"GetAddrInfoEx 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");
                // the InetNtop function is available on Windows Vista and later
                sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
                wprintf(L"\tIPv4 address %ws\n",
                    InetNtop(AF_INET, &sockaddr_ipv4->sin_addr, ipstringbuffer, 46) );
                
                // We could also use the WSAAddressToString function
                // 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;
                wprintf(L"\tIPv6 address %ws\n",
                    InetNtop(AF_INET6, &sockaddr_ipv6->sin6_addr, ipstringbuffer, 46) );
                
                // We could also use WSAAddressToString which also returns the scope ID
                // 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);
    }

    FreeAddrInfoEx(result);
    WSACleanup();

    return 0;
}

Hinweis  Ensure that the development environment targets the newest version of Ws2tcpip.h which includes structure and function definitions for addrinfoex and GetAddrInfoEx, respectively.

International Resource Identifiers

Website 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.

The specifications for URIs are documented in RFC 2396 and RFC 3986 published by the Internet Engineering Task Force (IETF).

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 GetAddrInfoExfunction does not currently provide support for IRI or Internationalized Domain Name (IDN) parsing applied to the name passed in the pName parameter. Winsock does not perform any punycode/IDN conversion for any version of Windows including Windows 7.

The wide character version of the GetAddrInfoEx function does not convert a Unicode name to Punycode format as per RFC 3490. The wide characater version of the GetAddrInfoEx function when querying DNS encodes the Unicode name in UTF-8 format, the format used by Microsoft DNS servers in an enterprise environment.

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. The Punycode representation of a Unicode name contains only ASCII characters and always starts 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 the Punycode representation of the original Unicode string. The IdnToAscii function implements the standard algorithm defined in RFC 3490 for converting an IDN to Punycode. 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 pName parameter to the GetAddrInfoEx function when the wide character version of this function is used (when UNICODE or _UNICODE is defined).

Use of ai_flags in the hints parameter

Flags in the ai_flags member of the optional addrinfoex structure provided in the hints 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:

Anforderungen

Siehe auch

addrinfoex

FreeAddrInfoEx

gai_strerror

getaddrinfo

GetAddrInfoW

IdnToAscii

IdnToUnicode

WSAEnumNameSpaceProviders

WSAGetLastError

Windows Sockets Error Codes