GetAddrInfoW-Funktion (ws2tcpip.h)

Artikel
08/28/2023

Die GetAddrInfoW-Funktion ermöglicht eine protokollunabhängige Übersetzung von einem Unicode-Hostnamen in eine Adresse.

Syntax

INT WSAAPI GetAddrInfoW(
  [in, optional] PCWSTR          pNodeName,
  [in, optional] PCWSTR          pServiceName,
  [in, optional] const ADDRINFOW *pHints,
  [out]          PADDRINFOW      *ppResult
);

Parameter

[in, optional] pNodeName

Ein Zeiger auf eine MIT NULL beendete Unicode-Zeichenfolge, die einen Hostnamen (Knoten) oder eine numerische Hostadressenzeichenfolge enthält. Für das Internetprotokoll ist die numerische Hostadressenzeichenfolge eine gepunktete dezimale IPv4-Adresse oder eine IPv6-Hexadresse.

[in, optional] pServiceName

Ein Zeiger auf eine MIT NULL beendete Unicode-Zeichenfolge, die entweder einen Dienstnamen oder eine Portnummer enthält, die als Zeichenfolge dargestellt wird.

Ein Dienstname ist ein Zeichenfolgenalias für eine Portnummer. Beispielsweise ist "http" ein Alias für Port 80, der von der Internet Engineering Task Force (IETF) als Standardport definiert wird, der von Webservern für das HTTP-Protokoll verwendet wird. Mögliche Werte für den pServiceName-Parameter , wenn keine Portnummer angegeben wird, sind in der folgenden Datei aufgeführt:

%WINDIR%\system32\drivers\etc\services

[in, optional] pHints

Ein Zeiger auf eine addrinfoW-Struktur , die Hinweise zum Typ des Sockets enthält, den der Aufrufer unterstützt.

Die ai_addrlen, ai_canonname, ai_addr und ai_next Member der addrinfoW-Struktur , auf die vom pHints-Parameter verwiesen wird, müssen null oder NULL sein. Andernfalls schlägt die GetAddrInfoEx-Funktion mit WSANO_RECOVERY fehl.

Weitere Informationen finden Sie in den Anmerkungen.

[out] ppResult

Ein Zeiger auf eine verknüpfte Liste mit mindestens einer addrinfoW-Struktur , die Antwortinformationen zum Host enthält.

Rückgabewert

Success gibt null zurück. Fehler gibt einen fehlerfreien Windows Sockets-Fehlercode zurück, wie in den Windows Sockets-Fehlercodes zu finden.

Die meisten nichtzero-Fehlercodes, die von der GetAddrInfoW-Funktion zurückgegeben werden, entsprechen dem Satz von Fehlern, die von IETF-Empfehlungen (Internet Engineering Task Force) beschrieben werden. In der folgenden Tabelle sind diese Fehlercodes und ihre WSA-Entsprechungen aufgeführt. Es wird empfohlen, die WSA-Fehlercodes zu verwenden, da sie vertraute und umfassende Fehlerinformationen für Winsock-Programmierer bieten.

Fehlerwert	WSA-Entsprechung	BESCHREIBUNG
EAI_AGAIN	WSATRY_AGAIN	Es ist ein temporärer Fehler bei der Namensauflösung aufgetreten.
EAI_BADFLAGS	WSAEINVAL	Für den ai_flags Member des pHints-Parameters wurde ein ungültiger Wert bereitgestellt.
EAI_FAIL	WSANO_RECOVERY	Es ist ein nicht wiederherstellbarer Fehler bei der Namensauflösung aufgetreten.
EAI_FAMILY	WSAEAFNOSUPPORT	Das ai_family Member des pHints-Parameters wird nicht unterstützt.
EAI_MEMORY	WSA_NOT_ENOUGH_MEMORY	Ein Fehler bei der Speicherzuordnung ist aufgetreten.
EAI_NONAME	WSAHOST_NOT_FOUND	Der Name wird für die angegebenen Parameter nicht aufgelöst, oder die Parameter pNodeName und pServiceName wurden nicht angegeben.
EAI_SERVICE	WSATYPE_NOT_FOUND	Der pServiceName-Parameter wird für den angegebenen ai_socktype Member des pHints-Parameters nicht unterstützt.
EAI_SOCKTYPE	WSAESOCKTNOSUPPORT	Das ai_socktype Member des pHints-Parameters wird nicht unterstützt.

Verwenden Sie die gai_strerror-Funktion , um Fehlermeldungen basierend auf den von der GetAddrInfoW-Funktion zurückgegebenen EAI_*-Codes zu drucken. Die gai_strerror-Funktion wird zur Einhaltung der IETF-Empfehlungen bereitgestellt, ist aber nicht threadsicher. Daher wird die Verwendung einer herkömmlichen Windows Sockets-Funktion wie WSAGetLastError empfohlen.

Fehlercode	Bedeutung
WSA_NOT_ENOUGH_MEMORY	Zum Ausführen des Vorgangs war nicht genügend Arbeitsspeicher vorhanden.
WSAEAFNOSUPPORT	Es wurde eine Adresse verwendet, die mit dem angeforderten Protokoll nicht kompatibel ist. Dieser Fehler wird zurückgegeben, wenn das ai_family Member der addrinfoW-Struktur , auf die vom Hinweisparameter verwiesen wird, nicht unterstützt wird.
WSAEINVAL	Ein ungültiges Argument wurde angegeben. Dieser Fehler wird zurückgegeben, wenn ein ungültiger Wert für das ai_flags Member der addrinfoW-Struktur angegeben wurde, auf die vom Hinweisparameter verwiesen wird.
WSAESOCKTNOSUPPORT	In dieser Adressfamilie ist die Unterstützung für den angegebenen Sockettyp nicht vorhanden. Dieser Fehler wird zurückgegeben, wenn das ai_socktype Member der addrinfoW-Struktur , auf die vom hinweis-Parameter verwiesen wird, nicht unterstützt wird.
WSAHOST_NOT_FOUND	Ein solcher Host ist nicht bekannt. Dieser Fehler wird zurückgegeben, wenn der Name für die angegebenen Parameter nicht aufgelöst wird oder die Parameter pNodename und pServicename nicht angegeben wurden.
WSANO_DATA	Der angeforderte Name ist gültig, es wurde jedoch keine Daten mit dem angeforderten Typ gefunden.
WSANO_RECOVERY	Beim Datenbankaufruf ist ein nicht behebbarer Fehler aufgetreten. Dieser Fehler wird zurückgegeben, wenn ein nicht wiederherstellbarer Fehler bei der Namensauflösung aufgetreten ist.
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSATRY_AGAIN	Hierbei handelt es sich in der Regel um einen temporären Fehler, der während der Auflösung von Hostnamen auftritt und einen Hinweis darauf liefert, dass der lokale Server keine Antwort von einem autorisierenden Server erhalten hat. Dieser Fehler wird zurückgegeben, wenn ein temporärer Fehler bei der Namensauflösung aufgetreten ist.
WSATYPE_NOT_FOUND	Die angegebene Klasse wurde nicht gefunden. Der pServiceName-Parameter wird für die angegebene ai_socktype Member der addrinfoW-Struktur nicht unterstützt, auf die vom Hinweisparameter verwiesen wird.

Hinweise

Die GetAddrInfoW-Funktion ist die Unicode-Version einer Funktion, die eine protokollunabhängige Übersetzung von Hostnamen zu Adresse ermöglicht. Die ANSI-Version dieser Funktion ist getaddrinfo.

Die GetAddrInfoW-Funktion gibt Ergebnisse für den NS_DNS Namespace zurück. Die GetAddrInfoW-Funktion aggregiert alle Antworten, wenn mehr als ein Namespaceanbieter Informationen zurückgibt. Für die Verwendung mit dem IPv6- und IPv4-Protokoll kann die Namensauflösung durch das Domain Name System (DNS), eine lokale Hostdatei oder durch andere Benennungsmechanismen für den NS_DNS Namespace erfolgen.

Makros in der Winsock-Headerdatei definieren einen funktionsübergreifenden Namen von GetAddrInfo und eine ADDRINFOT-Struktur . Diese GetAddrInfo-Funktion sollte mit den Parametern pNodeName und pServiceName eines Zeigers vom Typ TCHAR und den pHints - und ppResult-Parametern eines Zeigers vom Typ ADDRINFOT aufgerufen werden. Wenn UNICODE oder _UNICODE definiert ist, wird GetAddrInfo für GetAddrInfoW, die Unicode-Version der Funktion, und ADDRINFOT für die addrinfoW-Struktur definiert. Wenn UNICODE oder _UNICODE nicht definiert ist, wird GetAddrInfo für getaddrinfo, die ANSI-Version der Funktion, und ADDRINFOT für die addrinfo-Struktur definiert.

Ein oder beide pNodeName - oder pServiceName-Parameter müssen auf eine UNICODE-Zeichenfolge mit NULL-Beendigung verweisen. in der Regel werden beide bereitgestellt.

Bei Erfolg wird eine verknüpfte Liste von addrinfoW-Strukturen im ppResult-Parameter zurückgegeben. Die Liste kann verarbeitet werden, indem Sie dem Zeiger folgen, der im ai_next Member jeder zurückgegebenen addrinfoW-Struktur angegeben ist, bis ein NULL-Zeiger gefunden wird. In jeder zurückgegebenen addrinfoW-Struktur entsprechen die ai_family, ai_socktype und ai_protocol Member den entsprechenden Argumenten in einem Socket- oder WSASocket-Funktionsaufruf . Außerdem verweist das ai_addr-Member in jeder zurückgegebenen addrinfoW-Struktur auf eine ausgefüllte Socketadressstruktur, deren Länge im ai_addrlen-Member angegeben ist.

Wenn der pNodeName-Parameter auf einen Computernamen verweist, werden alle dauerhaften Adressen für den Computer zurückgegeben, die als Quelladresse verwendet werden können. Unter Windows Vista und höher enthalten diese Adressen alle Unicast-IP-Adressen, die von der GetUnicastIpAddressTable - oder GetUnicastIpAddressEntry-Funktion zurückgegeben werden, bei der das SkipAsSource-Element in der MIB_UNICASTIPADDRESS_ROW-Struktur auf false festgelegt ist.

Wenn der pNodeName-Parameter auf eine Zeichenfolge zeigt, die "localhost" entspricht, werden alle Loopbackadressen auf dem lokalen Computer zurückgegeben.

Wenn der pNodeName-Parameter eine leere Zeichenfolge enthält, werden alle registrierten Adressen auf dem lokalen Computer zurückgegeben.

Unter Windows Server 2003 und höher, wenn der pNodeName-Parameter auf eine Zeichenfolge zeigt, die ".. localmachine", werden alle registrierten Adressen auf dem lokalen Computer zurückgegeben.

Wenn der pNodeName-Parameter auf einen Virtuellen Clusterservernamen verweist, werden nur virtuelle Serveradressen zurückgegeben. Unter Windows Vista und höher enthalten diese Adressen alle Unicast-IP-Adressen, die von der GetUnicastIpAddressTable - oder GetUnicastIpAddressEntry-Funktion zurückgegeben werden, bei der das SkipAsSource-Element in der MIB_UNICASTIPADDRESS_ROW-Struktur auf true festgelegt ist. Weitere Informationen zum Clustering finden Sie unter Windows-Clustering .

Windows 7 mit Service Pack 1 (SP1) und Windows Server 2008 R2 mit Service Pack 1 (SP1) unterstützen Netsh.exe, um das SkipAsSource-Attribut für eine IP-Adresse festzulegen. Dadurch wird auch das Verhalten so geändert, dass die IP-Adresse in DNS registriert wird, wenn das SkipAsSource-Element in der MIB_UNICASTIPADDRESS_ROW-Struktur auf false festgelegt ist. Wenn das SkipAsSource-Element auf true festgelegt ist, wird die IP-Adresse nicht in DNS registriert.

Für Windows 7 und Windows Server 2008 R2 ist ein Hotfix verfügbar, der Netsh.exe unterstützung für das Festlegen des SkipAsSource-Attributs für eine IP-Adresse hinzufügt. Dieser Hotfix ändert auch das Verhalten so, dass die IP-Adresse in DNS registriert wird, wenn das SkipAsSource-Element in der MIB_UNICASTIPADDRESS_ROW-Struktur auf false festgelegt ist. Wenn das SkipAsSource-Element auf true festgelegt ist, wird die IP-Adresse nicht in DNS registriert. Weitere Informationen finden Sie unter Knowledge Base (KB) 2386184.

Ein ähnlicher Hotfix ist auch für Windows Vista mit Service Pack 2 (SP2) und Windows Server 2008 mit Service Pack 2 (SP2) verfügbar, der unterstützung für Netsh.exe zum Festlegen des SkipAsSource-Attributs für eine IP-Adresse hinzufügt. Dieser Hotfix ändert auch das Verhalten so, dass die IP-Adresse in DNS registriert wird, wenn das SkipAsSource-Element in der MIB_UNICASTIPADDRESS_ROW-Struktur auf false festgelegt ist. Wenn das SkipAsSource-Element auf true festgelegt ist, wird die IP-Adresse nicht in DNS registriert.

Aufrufer der GetAddrInfoW-Funktion können Hinweise zum Typ des Sockets geben, der durch eine addrinfoW-Struktur unterstützt wird, auf die der pHints-Parameter verweist. Wenn der pHints-Parameter verwendet wird, gelten die folgenden Regeln für die zugehörige addrinfoW-Struktur :

Der Wert AF_UNSPEC für ai_family gibt an, dass der Aufrufer nur die AF_INET - und AF_INET6 Adressfamilien akzeptiert. Beachten Sie, dass AF_UNSPEC und PF_UNSPEC identisch sind.
Der Wert 0 für ai_socktype gibt an, dass der Aufrufer jeden Sockettyp akzeptiert.
Der Wert null für ai_protocol gibt an, dass der Aufrufer jedes Protokoll akzeptiert.
Der ai_addrlen-Member muss auf 0 festgelegt werden.
Das ai_canonname-Member muss auf NULL festgelegt werden.
Das ai_addr-Member muss auf NULL festgelegt werden.
Das ai_next-Member muss auf NULL festgelegt werden.

Andere Werte in der addrinfoW-Struktur , die im pHints-Parameter bereitgestellt werden, weisen auf bestimmte Anforderungen hin. Wenn der Aufrufer beispielsweise nur IPv4 verarbeitet und IPv6 nicht verarbeitet, sollte der ai_family Member auf AF_INET festgelegt werden. Ein anderes Beispiel: Wenn der Aufrufer nur TCP und nicht UDP verarbeitet, sollte das ai_socktype-Member auf SOCK_STREAM festgelegt werden.

Wenn der pHints-Parameter ein NULL-Zeiger ist, behandelt die GetAddrInfoW-Funktion dies so, als würde die addrinfoW-Struktur in pHints initialisiert, wobei ihr ai_family Member auf AF_UNSPEC und alle anderen Member auf null festgelegt wurde.

Wenn Unter Windows Vista und höher GetAddrInfoW von einem Dienst aufgerufen wird, sollte der Dienst die Identität des Benutzers annehmen, wenn der Vorgang das Ergebnis eines Benutzerprozesses ist, der den Dienst aufruft. Dadurch kann die Sicherheit ordnungsgemäß erzwungen werden.

Die GetAddrInfoW-Funktion kann verwendet werden, um eine Textzeichenfolgendarstellung einer IP-Adresse in eine addrinfoW-Struktur zu konvertieren, die eine Sockaddr-Struktur für die IP-Adresse und andere Informationen enthält. Um auf diese Weise verwendet zu werden, muss die Zeichenfolge, auf die der pNodeName-Parameter verweist, eine Textdarstellung einer IP-Adresse enthalten, und für die addrinfoW-Struktur , auf die vom pHints-Parameter verwiesen wird, muss das AI_NUMERICHOST-Flag im ai_flags-Member festgelegt sein. Die Zeichenfolge, auf die der pNodeName-Parameter verweist, kann eine Textdarstellung einer IPv4- oder einer IPv6-Adresse enthalten. Die TEXT-IP-Adresse wird in eine addrinfoW-Struktur konvertiert, auf die der ppResult-Parameter verweist. Die zurückgegebene addrinfoW-Struktur enthält eine Sockaddr-Struktur für die IP-Adresse sowie zusätzliche Informationen zur IP-Adresse. Damit diese Methode mit einer IPv6-Adresszeichenfolge unter Windows Server 2003 und Windows XP funktioniert, muss das IPv6-Protokoll auf dem lokalen Computer installiert sein. Andernfalls wird der WSAHOST_NOT_FOUND-Fehler zurückgegeben.

Freigeben von Adressinformationen aus der dynamischen Zuordnung

Alle Informationen, die von der GetAddrInfoW-Funktion zurückgegeben werden, auf die der ppResult-Parameter verweist, werden dynamisch zugeordnet, einschließlich aller addrinfoW-Strukturen , Socketadressstrukturen und kanonischen Hostnamenzeichenfolgen, auf die von addrinfoW-Strukturen verwiesen wird. Der durch einen erfolgreichen Aufruf dieser Funktion zugewiesene Arbeitsspeicher muss mit einem nachfolgenden Aufruf von FreeAddrInfoW freigegeben werden.

Beispielcode

Im folgenden Codebeispiel wird die Verwendung der GetAddrInfoW-Funktion veranschaulicht.

#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;
}

Hinweis Stellen Sie sicher, dass die Entwicklungsumgebung auf die neueste Version von Ws2tcpip.h abzielt, die Struktur- und Funktionsdefinitionen für addrinfoW bzw . GetAddrInfoW enthält.

Internationalisierte Domänennamen

Internethostnamen bestehen in der Regel aus einem sehr eingeschränkten Zeichensatz:

ASCII-Großbuchstaben und -Kleinbuchstaben des englischen Alphabets
Ziffern von 0 bis 9
ASCII-Bindestriche.

Mit dem Wachstum des Internets wächst die Notwendigkeit, Internethostnamen für andere Sprachen zu identifizieren, die nicht durch den ASCII-Zeichensatz dargestellt werden. Bezeichner, die diese Anforderung erleichtern und die Darstellung von Nicht-ASCII-Zeichen (Unicode) als spezielle ASCII-Zeichenfolgen ermöglichen, werden als internationalisierte Domänennamen (IDNs) bezeichnet. Ein Mechanismus namens Internationalizing Domain Names in Applications (IDNA) wird verwendet, um IDNs standardmäßig zu behandeln. Die Spezifikationen für IDNs und IDNA sind in RFC 3490, RTF 5890 und RFC 6365 der Internet Engineering Task Force (IETF) dokumentiert.

Unter Windows 8 und Windows Server 2012 bietet die GetAddrInfoW-Funktion Unterstützung für die IDN-Analyse (Internationalized Domain Name), die auf den im pNodeName-Parameter übergebenen Namen angewendet wird. Winsock führt punycode/IDN-Codierung und Konvertierung durch. Dieses Verhalten kann mithilfe des unten erläuterten AI_DISABLE_IDN_ENCODING-Flags deaktiviert werden.

Unter Windows 7 und Windows Server 2008 R2 oder früher bietet die GetAddrInfoW-Funktion derzeit keine Unterstützung für die IDN-Analyse, die auf den im pNodeName-Parameter übergebenen Namen angewendet wird. Winsock führt keine Punycode/IDN-Konvertierung durch. Die GetAddrInfoW-Funktion verwendet Punycode nicht zum Konvertieren eines IDN gemäß RFC 3490. Die GetAddrInfoW-Funktion beim Abfragen von DNS codiert den Unicode-Namen im UTF-8-Format, dem Format, das von Microsoft DNS-Servern in einer Unternehmensumgebung verwendet wird.

Mehrere Funktionen unter Windows Vista und höher unterstützen die Konvertierung zwischen Unicode-Bezeichnungen in einem IDN in ihre ASCII-Entsprechungen. Die resultierende Darstellung jeder Unicode-Bezeichnung enthält nur ASCII-Zeichen und beginnt mit dem Präfix xn- wenn die Unicode-Bezeichnung Keine-ASCII-Zeichen enthält. Der Grund dafür ist die Unterstützung vorhandener DNS-Server im Internet, da einige DNS-Tools und Server nur ASCII-Zeichen unterstützen (siehe RFC 3490).

Die IdnToAscii-Funktion verwendet Punycode, um einen IDN mithilfe des in RFC 3490 definierten Standardalgorithmus in die ASCII-Darstellung der ursprünglichen Unicode-Zeichenfolge zu konvertieren. Die IdnToUnicode-Funktion konvertiert die ASCII-Form eines IDN in die normale Unicode UTF-16-Codierungssyntax. Weitere Informationen und Links zu zugehörigen Normenentwürfen finden Sie unter Handling Internationalized Domain Names (IDNs).

Die IdnToAscii-Funktion kann verwendet werden, um einen IDN-Namen in das ASCII-Formular zu konvertieren. Um dieses ASCII-Formular an die GetAddrInfoW-Funktion zu übergeben, können Sie die Char-Zeichenfolge mit der MultiByteToWideChar-Funktion in eine WCHAR-Zeichenfolge konvertieren, die dann im pNodeName-Parameter an die GetAddrInfoW-Funktion übergeben werden kann.

Verwendung von ai_flags im Hinweisparameter

Flags im ai_flags Member der optionalen addrinfoW-Struktur , die im pHints-Parameter bereitgestellt wird, ändern das Verhalten der Funktion.

Diese Flagbits sind in der Ws2def.h-Headerdatei im Microsoft Windows Software Development Kit (SDK) für Windows 7 definiert. Diese Flagbits werden in der Headerdatei Ws2tcpip.h im Windows SDK für Windows Server 2008 und Windows Vista definiert. Diese Flagbits werden in der Ws2tcpip.h-Headerdatei im Platform Software Development Kit (SDK) für Windows Server 2003 und Windows XP definiert.

Die Flagbits können eine Kombination aus folgenden Komponenten sein:

Flagbits	BESCHREIBUNG
AI_PASSIVE	Das Festlegen des AI_PASSIVE-Flags gibt an, dass der Aufrufer die zurückgegebene Socketadressstruktur in einem Aufruf der Bindungsfunktion verwenden möchte. Wenn das flag AI_PASSIVE festgelegt ist und pNodeName ein NULL-Zeiger ist, wird der IP-Adressteil der Socketadressstruktur auf INADDR_ANY für IPv4-Adressen und IN6ADDR_ANY_INIT für IPv6-Adressen festgelegt. Wenn das flag AI_PASSIVE nicht festgelegt ist, ist die zurückgegebene Socketadressstruktur bereit für einen Aufruf der Verbindungsfunktion für ein verbindungsorientiertes Protokoll oder bereit für einen Aufruf der Verbindungs-, Sendto- oder Sendefunktionen für ein verbindungsloses Protokoll. Wenn der pNodeName-Parameter in diesem Fall ein NULL-Zeiger ist, wird der IP-Adressteil der Socketadressenstruktur auf die Loopbackadresse festgelegt.
AI_CANONNAME	Wenn weder AI_CANONNAME noch AI_NUMERICHOST verwendet wird, versucht die GetAddrInfoW-Funktion die Auflösung. Wenn eine Literalzeichenfolge übergeben wird , versucht GetAddrInfoW , die Zeichenfolge zu konvertieren, und wenn ein Hostname übergeben wird, versucht die GetAddrInfoW-Funktion , den Namen in eine Adresse oder mehrere Adressen aufzulösen. Wenn das AI_CANONNAME Bit festgelegt ist, kann der pNodeName-Parameter nicht NULL sein. Andernfalls schlägt die GetAddrInfoEx-Funktion mit WSANO_RECOVERY fehl. Wenn das AI_CANONNAME Bit festgelegt ist und die GetAddrInfoW-Funktion den Erfolg zurückgibt, zeigt das ai_canonname Member im ppResult-Parameter auf eine NULL-beendete Zeichenfolge, die den kanonischen Namen des angegebenen Knotens enthält. Hinweis Die GetAddrInfoW-Funktion kann den Erfolg zurückgeben, wenn das AI_CANONNAME-Flag festgelegt ist, aber der ai_canonname Member in der zugeordneten addrinfoW-Struktur ist NULL. Daher wird empfohlen, das AI_CANONNAME-Flag zu verwenden, um zu testen, ob das ai_canonname Member in der zugeordneten addrinfoW-StrukturNULL ist.
AI_NUMERICHOST	Wenn das AI_NUMERICHOST Bit festgelegt ist, muss der pNodeName-Parameter eine numerische Hostadressenzeichenfolge enthalten, die nicht NULL ist. Andernfalls wird der EAI_NONAME-Fehler zurückgegeben. Dieses Flag verhindert den Aufruf eines Namensauflösungsdiensts.
AI_NUMERICSERV	Wenn das AI_NUMERICSERV Bit festgelegt ist, muss der pServiceName-Parameter eine numerische Portnummer ohne NULL enthalten, andernfalls wird der EAI_NONAME-Fehler zurückgegeben. Dieses Flag verhindert den Aufruf eines Namensauflösungsdiensts. Das flag AI_NUMERICSERV wird im Windows SDK für Windows Vista und höher definiert. Das AI_NUMERICSERV-Flag wird von Microsoft-Anbietern nicht unterstützt.
AI_ALL	Wenn das AI_ALL Bit festgelegt ist, wird eine Anforderung für IPv6-Adressen und IPv4-Adressen mit AI_V4MAPPED gestellt. Das AI_ALL-Flag ist im Windows SDK für Windows Vista und höher definiert. Das flag AI_ALL wird unter Windows Vista und höher unterstützt.
AI_ADDRCONFIG	Wenn das AI_ADDRCONFIG Bit festgelegt ist, löst GetAddrInfoW nur auf, wenn eine globale Adresse konfiguriert ist. Wenn AI_ADDRCONFIG Flag angegeben ist, werden IPv4-Adressen nur zurückgegeben, wenn eine IPv4-Adresse auf dem lokalen System konfiguriert ist, und IPv6-Adressen werden nur zurückgegeben, wenn eine IPv6-Adresse auf dem lokalen System konfiguriert ist. Die IPv4- oder IPv6-Loopbackadresse wird nicht als gültige globale Adresse betrachtet. Das AI_ADDRCONFIG-Flag ist im Windows SDK für Windows Vista und höher definiert. Das AI_ADDRCONFIG-Flag wird unter Windows Vista und höher unterstützt.
AI_V4MAPPED	Wenn das AI_V4MAPPED Bit festgelegt ist und eine Anforderung für IPv6-Adressen fehlschlägt, wird eine Namensdienstanforderung für IPv4-Adressen gestellt, und diese Adressen werden in das IPv4-zugeordnete IPv6-Adressformat konvertiert. Das flag AI_V4MAPPED ist im Windows SDK für Windows Vista und höher definiert. Das AI_V4MAPPED-Flag wird unter Windows Vista und höher unterstützt.
AI_NON_AUTHORITATIVE	Wenn das AI_NON_AUTHORITATIVE Bits festgelegt ist, gibt der NS_EMAIL-Namespaceanbieter sowohl autorisierende als auch nicht autorisierende Ergebnisse zurück. Wenn das AI_NON_AUTHORITATIVE Bit nicht festgelegt ist, gibt der NS_EMAIL-Namespaceanbieter nur autoritative Ergebnisse zurück. Das AI_NON_AUTHORITATIVE-Flag ist im Windows SDK für Windows Vista und höher definiert. Das flag AI_NON_AUTHORITATIVE wird unter Windows Vista und höher unterstützt und gilt nur für den NS_EMAIL Namespace.
AI_SECURE	Wenn das AI_SECURE Bit festgelegt ist, gibt der NS_EMAIL-Namespaceanbieter Ergebnisse zurück, die mit erhöhter Sicherheit abgerufen wurden, um mögliche Spoofings zu minimieren. Das AI_SECURE-Flag ist im Windows SDK für Windows Vista und höher definiert. Das AI_SECURE-Flag wird unter Windows Vista und höher unterstützt und gilt nur für den NS_EMAIL-Namespace .
AI_RETURN_PREFERRED_NAMES	Wenn die AI_RETURN_PREFERRED_NAMES festgelegt ist, sollte kein Name im pNodeName-Parameter angegeben werden. Der NS_EMAIL-Namespaceanbieter gibt bevorzugte Namen für die Veröffentlichung zurück. Das AI_RETURN_PREFERRED_NAMES-Flag ist im Windows SDK für Windows Vista und höher definiert. Das AI_RETURN_PREFERRED_NAMES-Flag wird unter Windows Vista und höher unterstützt und gilt nur für den NS_EMAIL-Namespace .
AI_FQDN	Wenn die AI_FQDN festgelegt ist und ein flacher Name (einzelne Bezeichnung) angegeben wird, gibt GetAddrInfoW den vollqualifizierten Domänennamen zurück, in den der Name schließlich aufgelöst wurde. Der vollqualifizierte Domänenname wird im ai_canonname-Member in der zugeordneten addrinfoW-Struktur zurückgegeben. Dies unterscheidet sich von AI_CANONNAME Bitflag, das den kanonischen Namen zurückgibt, der im DNS registriert ist und sich möglicherweise von dem vollqualifizierten Domänennamen unterscheidet, in den der Flatname aufgelöst wurde. Es kann nur eines der AI_FQDN und AI_CANONNAME Bits festgelegt werden. Die GetAddrInfoW-Funktion schlägt fehl, wenn beide Flags mit EAI_BADFLAGS vorhanden sind. Wenn das AI_FQDN Bit festgelegt ist, kann der pNodeName-Parameter nicht NULL sein. Andernfalls schlägt die GetAddrInfoEx-Funktion mit WSANO_RECOVERY fehl. Windows 7: Das AI_FQDN-Flag ist im Windows SDK für Windows 7 und höher definiert. Das flag AI_FQDN wird unter Windows 7 und höher unterstützt.
AI_FILESERVER	Wenn die AI_FILESERVER festgelegt ist, ist dies ein Hinweis an den Namespaceanbieter, dass der abgefragte Hostname im Dateifreigabeszenario verwendet wird. Der Namespaceanbieter ignoriert diesen Hinweis möglicherweise. Windows 7: Das flag AI_FILESERVER ist im Windows SDK für Windows 7 und höher definiert. Das AI_FILESERVER-Flag wird unter Windows 7 und höher unterstützt.
AI_DISABLE_IDN_ENCODING	Wenn die AI_DISABLE_IDN_ENCODING festgelegt ist, deaktiviert dies die automatische Codierung internationaler Domänennamen mithilfe von Punycode in den Von der GetAddrInfoW-Funktion aufgerufenen Namensauflösungsfunktionen. Windows 8: Das AI_DISABLE_IDN_ENCODING-Flag ist im Windows SDK für Windows 8 und höher definiert. Das flag AI_DISABLE_IDN_ENCODING wird unter Windows 8 und höher unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Hinweis

Der ws2tcpip.h-Header definiert GetAddrInfo als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP, Windows 8.1 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	ws2tcpip.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll