GetAddrInfoExA-Funktion (ws2tcpip.h)

Die GetAddrInfoEx-Funktion bietet eine protokollunabhängige Namensauflösung mit zusätzlichen Parametern, um zu bestimmen, welche Namespaceanbieter die Anforderung verarbeiten sollen.

Syntax

INT WSAAPI GetAddrInfoExA(
  [in, optional]  PCSTR                              pName,
  [in, optional]  PCSTR                              pServiceName,
  [in]            DWORD                              dwNameSpace,
  [in, optional]  LPGUID                             lpNspId,
  [in, optional]  const ADDRINFOEXA                  *hints,
  [out]           PADDRINFOEXA                       *ppResult,
  [in, optional]  timeval                            *timeout,
  [in, optional]  LPOVERLAPPED                       lpOverlapped,
  [in, optional]  LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
  [out, optional] LPHANDLE                           lpNameHandle
);

Parameter

[in, optional] pName

Ein Zeiger auf eine NULL-endende Zeichenfolge, die einen Hostnamen (Knoten) oder eine numerische Hostadressenzeichenfolge enthält. Für das Internetprotokoll ist die numerische Hostadressenzeichenfolge eine IPv4-Adresse mit punktierter Dezimaladresse oder eine IPv6-Hexadezimaladresse.

[in, optional] pServiceName

Ein Zeiger auf eine optionale NULL-endende 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 ist, sind in der folgenden Datei aufgeführt:

%WINDIR%\system32\drivers\etc\services

[in] dwNameSpace

Ein optionaler Namespacebezeichner, der bestimmt, welche Namespaceanbieter abgefragt werden. Das Übergeben eines bestimmten Namespacebezeichners führt dazu, dass nur Namespaceanbieter abgefragt werden, die den angegebenen Namespace unterstützen. Wenn Sie NS_ALL angeben, werden alle installierten und aktiven Namespaceanbieter abgefragt.

Optionen für den dwNameSpace-Parameter sind in der Winsock2.h-Includedatei aufgeführt. Unter Windows Vista und höher werden mehrere Namespaceanbieter hinzugefügt. Andere Namespaceanbieter können installiert werden, sodass die folgenden möglichen Werte nur die allgemein verfügbaren sind. Viele andere Werte sind möglich.

Wert Bedeutung
NS_ALL
0
Alle installierten und aktiven Namespaces.
NS_DNS
12
Der DNS-Namespace (Domain Name System).
NS_NETBT
13
Der NETBT-Namespace (NetBIOS over TCP/IP).
NS_WINS
14
Der Windows Internet Naming Service(NS_WINS)-Namespace.
NS_NLA
15
Der NLA-Namespace (Network Location Awareness).

Dieser Namespacebezeichner wird unter Windows XP und höher unterstützt.

NS_BTH
16
Der Bluetooth-Namespace.

Dieser Namespacebezeichner wird unter Windows Vista und höher unterstützt.

NS_NTDS
32
Der Windows NT Directory Services-Namespace (NS_NTDS).
NS_EMAIL
37
Der E-Mail-Namespace.

Dieser Namespacebezeichner wird unter Windows Vista und höher unterstützt.

NS_PNRPNAME
38
Der Peer-to-Peer-Namespace für einen bestimmten Peernamen.

Dieser Namespacebezeichner wird unter Windows Vista und höher unterstützt.

NS_PNRPCLOUD
39
Der Peer-to-Peer-Namespace für eine Sammlung von Peernamen.

Dieser Namespacebezeichner wird unter Windows Vista und höher unterstützt.

[in, optional] lpNspId

Ein Zeiger auf eine optionale GUID eines bestimmten Namespaceanbieters, der abgefragt werden soll, wenn mehrere Namespaceanbieter unter einem einzelnen Namespace registriert sind, z. B. NS_DNS. Das Übergeben der GUID für einen bestimmten Namespaceanbieter führt dazu, dass nur der angegebene Namespaceanbieter abgefragt wird. Die WSAEnumNameSpaceProviders-Funktion kann aufgerufen werden, um die GUID für einen Namespaceanbieter abzurufen.

[in, optional] hints

Ein Zeiger auf eine addrinfoex-Struktur , die Hinweise zum Typ des Vom Aufrufer unterstützten Sockets bereitstellt.

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

Weitere Informationen finden Sie in den Hinweisen.

[out] ppResult

Ein Zeiger auf eine verknüpfte Liste einer oder mehrerer addrinfoex-Strukturen , die Antwortinformationen zum Host enthält.

[in, optional] timeout

Ein optionaler Parameter, der angibt, wie lange in Millisekunden auf eine Antwort vom Namespaceanbieter gewartet wird, bevor der Aufruf abgebrochen wird.

Dieser Parameter wird nur unterstützt, wenn das UNICODE- oder _UNICODE-Makro in den Quellen definiert wurde, bevor die GetAddrInfoEx-Funktion aufgerufen wird. Andernfalls ist dieser Parameter derzeit reserviert und muss auf NULL festgelegt werden, da eine Timeoutoption nicht unterstützt wird.

[in, optional] lpOverlapped

Ein optionaler Zeiger auf eine überlappende Struktur, die für asynchrone Vorgänge verwendet wird.

Dieser Parameter wird nur unterstützt, wenn das UNICODE- oder _UNICODE-Makro in den Quellen definiert wurde, bevor die GetAddrInfoEx-Funktion aufgerufen wird.

Wenn unter Windows 8 und Windows Server 2012 kein lpCompletionRoutine-Parameter angegeben ist, muss der hEvent-Member der OVERLAPPED-Struktur auf ein Ereignis für manuelles Zurücksetzen festgelegt werden, das nach Abschluss eines asynchronen Aufrufs aufgerufen wird. Wenn eine Vervollständigungsroutine angegeben wurde, muss das hEvent-Element NULL sein. Wenn das durch hEvent angegebene Ereignis festgelegt wurde, kann das Ergebnis des Vorgangs durch Aufrufen der GetAddrInfoExOverlappedResult-Funktion abgerufen werden.

Unter Windows 8 und Windows Server 2012 ist dieser Parameter derzeit reserviert und muss auf NULL festgelegt werden, wenn das UNICODE- oder _UNICODE-Makro nicht definiert ist.

Unter Windows 7 und Windows Server 2008 R2 oder früher ist dieser Parameter derzeit reserviert und muss auf NULL festgelegt werden, da asynchrone Vorgänge nicht unterstützt werden.

[in, optional] lpCompletionRoutine

Ein optionaler Zeiger auf eine Funktion, die bei erfolgreichem Abschluss für asynchrone Vorgänge aufgerufen werden soll.

Dieser Parameter wird nur unterstützt, wenn das UNICODE- oder _UNICODE-Makro in den Quellen definiert wurde, bevor die GetAddrInfoEx-Funktion aufgerufen wird.

Wenn dieser Parameter angegeben ist, muss er ein Zeiger auf eine Funktion mit der folgenden Signatur sein:

typedef   
void   
(CALLBACK * LPLOOKUPSERVICE_COMPLETION_ROUTINE)(   
    __in      DWORD    dwError,   
    __in      DWORD    dwBytes,   
    __in      LPWSAOVERLAPPED lpOverlapped   
    );   

Wenn der asynchrone Vorgang abgeschlossen ist, wird die Vervollständigungsroutine mit dem parameter lpOverlapped aufgerufen, der auf den Wert des lpOverlapped-Parameters festgelegt ist, der an GetAddrInfoEx übergeben wird. Der Zeigermember der OVERLAPPED-Struktur wird auf den Wert des ppResult-Parameters des ursprünglichen Aufrufs festgelegt. Wenn der Zeigermember auf einen Nicht-NULL-Zeiger auf die addrinfoex-Struktur zeigt, liegt es in der Verantwortung des Aufrufers, FreeAddrInfoEx aufzurufen, um die addrinfoex-Struktur freizugeben. Der an die Vervollständigungsroutine übergebene dwError-Parameter wird auf einen Winsock-Fehlercode festgelegt. Der dwBytes-Parameter ist für die zukünftige Verwendung reserviert und muss ignoriert werden.

Unter Windows 8 und Windows Server 2012 ist dieser Parameter derzeit reserviert und muss auf NULL festgelegt werden, wenn das UNICODE- oder _UNICODE-Makro nicht definiert ist.

Unter Windows 7 und Windows Server 2008 R2 oder früher ist dieser Parameter derzeit reserviert und muss auf NULL festgelegt werden, da asynchrone Vorgänge nicht unterstützt werden.

[out, optional] lpNameHandle

Ein optionaler Zeiger, der nur für asynchrone Vorgänge verwendet wird.

Dieser Parameter wird nur unterstützt, wenn das UNICODE- oder _UNICODE-Makro in den Quellen definiert wurde, bevor die GetAddrInfoEx-Funktion aufgerufen wird.

Wenn die GetAddrInfoEx-Funktion unter Windows 8 und Windows Server 2012 asynchron abgeschlossen wird, kann der in diesem Feld zurückgegebene Zeiger mit der GetAddrInfoExCancel-Funktion verwendet werden. Das zurückgegebene Handle ist gültig, wenn GetAddrInfoEx zurückgibt, bis die Vervollständigungsroutine aufgerufen wird, das Ereignis ausgelöst wird oder die GetAddrInfoExCancel-Funktion mit diesem Handle aufgerufen wird.

Unter Windows 8 und Windows Server 2012 ist dieser Parameter derzeit reserviert und muss auf NULL festgelegt werden, wenn das UNICODE- oder _UNICODE-Makro nicht definiert ist.

Unter Windows 7 und Windows Server 2008 R2 oder früher ist dieser Parameter derzeit reserviert und muss auf NULL festgelegt werden, da asynchrone Vorgänge nicht unterstützt werden.

Rückgabewert

Bei Erfolg gibt GetAddrInfoExNO_ERROR (0) zurück. Fehler gibt einen Windows Sockets-Fehlercode ungleich null zurück, wie in den Windows Sockets-Fehlercodes zu finden.

Die meisten Fehlercodes ungleich null, die von der GetAddrInfoEx-Funktion zurückgegeben werden, entsprechen dem Satz von Fehlern, die in den Empfehlungen der Internet Engineering Task Force (IETF) 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 winsock-Programmierern vertraute und umfassende Fehlerinformationen bieten.

Fehlerwert WSA-Entsprechung BESCHREIBUNG
EAI_AGAIN WSATRY_AGAIN Es ist ein temporärer Fehler bei der Namensauflösung aufgetreten.
EAI_BADFLAGS WSAEINVAL Ein ungültiger Parameter wurde bereitgestellt. Dieser Fehler wird zurückgegeben, wenn einer der reservierten Parameter nicht NULL ist. Dieser Fehler wird auch zurückgegeben, wenn ein ungültiger Wert für das ai_flags Member des pHints-Parameters angegeben wurde.
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 pName 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 GetAddrInfoEx-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 herkömmlicher Windows Sockets-Funktionen 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 addrinfoex-Struktur , auf die vom pHints-Parameter verwiesen wird, nicht unterstützt wird.
WSAEINVAL
Ein ungültiges Argument wurde angegeben. Dieser Fehler wird zurückgegeben, wenn für das ai_flags Member der addrinfoex-Struktur , auf die vom pHints-Parameter verwiesen wird, ein ungültiger Wert angegeben wurde. Dieser Fehler wird auch zurückgegeben, wenn der dwNameSpace-Parameter NS_PNRPNAME oder NS_PNRPCLOUD ist und der Peer-to-Peer-Name-Dienst nicht ausgeführt 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 addrinfoex-Struktur , auf die vom pHints-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 pName 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.
WSASERVICE_NOT_FOUND
Ein solcher Dienst ist nicht bekannt. Der Dienst kann nicht im angegebenen Namensraum gefunden werden. Dieser Fehler wird zurückgegeben, wenn der pName- oder pServiceName-Parameter für den im dwNameSpace-Parameter angegebenen Namespace nicht gefunden oder der im dwNameSpace-Parameter angegebene Namespace nicht installiert ist.
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 addrinfoex-Struktur nicht unterstützt, auf die vom pHints-Parameter verwiesen wird.

Hinweise

Die GetAddrInfoEx-Funktion bietet eine protokollunabhängige Übersetzung vom Hostnamen in die Adresse und vom Dienstnamen auf die Portnummer. Die GetAddrInfoEx-Funktion ist eine erweiterte Version der Funktionen getaddrinfo und GetAddrInfoW . Die GetAddrInfoEx-Funktion ermöglicht die Angabe des Namespaceanbieters zum Auflösen der Abfrage.

Die GetAddrInfoEx-Funktion aggregiert und gibt Ergebnisse von mehreren Namespaceanbietern zurück, es sei denn, es wird ein bestimmter Namespaceanbieter angegeben. Für die Verwendung mit dem IPv6- und IPv4-Protokoll kann die Namensauflösung durch das Domain Name System (DNS), eine lokale Hostdatei , einen E-Mail-Anbieter (der NS_EMAIL Namespace) oder durch andere Benennungsmechanismen erfolgen.

Wenn UNICODE oder _UNICODE definiert ist, wird GetAddrInfoEx fürGetAddrInfoExW definiert, die Unicode-Version dieser Funktion. Die Zeichenfolgenparameter werden für den PWSTR-Datentyp definiert, und die ADDRINFOEXW-Struktur wird verwendet. Unter Windows 8 und Windows Server 2012 können die TimeoutparameterlpOverlapped, lpCompletionRoutine und lpNameHandle verwendet werden, um die GetAddrInfoEx-Funktion aufzurufen, damit sie asynchron abgeschlossen werden kann.

Wenn UNICODE oder _UNICODE nicht definiert ist, wird GetAddrInfoEx für GetAddrInfoExA definiert, die ANSI-Version dieser Funktion. Die Zeichenfolgenparameter sind vom PCSTR-Datentyp , und die STRUKTUR ADDRINFOEXA wird verwendet. Die Parameter timeout, lpOverlapped, lpCompletionRoutine und lpNameHandle müssen auf NULL festgelegt werden.

Ein oder beide Parameter pName oder pServiceName müssen auf eine NULL-beendete Zeichenfolge verweisen. Im Allgemeinen werden beide bereitgestellt.

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

Wenn der pName-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 pName-Parameter auf eine Zeichenfolge zeigt, die "localhost" entspricht, werden alle Loopbackadressen auf dem lokalen Computer zurückgegeben.

Wenn der pName-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 pName-Parameter auf eine Zeichenfolge zeigt, die ".. localmachine", werden alle registrierten Adressen auf dem lokalen Computer zurückgegeben.

Wenn der pName-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 GetAddrInfoEx-Funktion können Hinweise zum Typ des Sockets bereitstellen, der durch eine addrinfoex-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 addrinfoex-Struktur :

  • Der Wert AF_UNSPEC für ai_family gibt an, dass der Aufrufer nur die adressfamilien AF_INET und AF_INET6 akzeptiert. Beachten Sie, dass AF_UNSPEC und PF_UNSPEC identisch sind.
  • Der Wert 0 (null) 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 (null) festgelegt werden.
  • Der ai_canonname-Member muss auf NULL festgelegt werden.
  • Der ai_addr-Member muss auf NULL festgelegt werden.
  • Der ai_next-Member muss auf NULL festgelegt werden.

Andere Werte in der addrinfoex-Struktur , die im pHints-Parameter bereitgestellt werden, geben spezifische Anforderungen an. Wenn der Aufrufer beispielsweise nur IPv4 und nicht IPv6 verarbeitet, sollte der ai_family-Member auf AF_INET festgelegt werden. Ein weiteres Beispiel: Wenn der Aufrufer nur TCP und udp nicht verarbeitet, sollte der ai_socktype Member auf SOCK_STREAM festgelegt werden.

Wenn der pHints-Parameter ein NULL-Zeiger ist, behandelt die GetAddrInfoEx-Funktion ihn so, als ob die addrinfoex-Struktur in pHints initialisiert wurde, wobei ihr ai_family Member auf AF_UNSPEC und alle anderen Member auf NULL oder Null festgelegt wurde.

Wenn GetAddrInfoEx von einem Dienst aufgerufen wird und der Vorgang das Ergebnis eines Benutzerprozesses ist, der den Dienst aufruft, sollte der Dienst die Identität des Benutzers annehmen. Dadurch kann die Sicherheit ordnungsgemäß erzwungen werden.

Die GetAddrInfoEx-Funktion kann verwendet werden, um eine Textzeichenfolgendarstellung einer IP-Adresse in eine addrinfoex-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 pName-Parameter verweist, eine Textdarstellung einer IP-Adresse enthalten, und die addrinfoex-Struktur , auf die der pHints-Parameter verweist, muss das flag AI_NUMERICHOST im ai_flags-Member festgelegt sein. Die Zeichenfolge, auf die der pName-Parameter verweist, kann eine Textdarstellung einer IPv4- oder einer IPv6-Adresse enthalten. Die Text-IP-Adresse wird in eine addrinfoex-Struktur konvertiert, auf die der ppResult-Parameter verweist. Die zurückgegebene addrinfoex-Struktur enthält eine sockaddr-Struktur für die IP-Adresse sowie zusätzliche Informationen zur IP-Adresse.

Mehrere Namespaceanbieter können auf einem lokalen Computer für denselben Namespace installiert werden. Beispielsweise registriert sich die Windows TCP/IP-Basis-Netzwerksoftware für den NS_DNS-Namespace. Das Microsoft Forefront Threat Management Gateway (TMG) und der ältere Microsoft Internet Security and Acceleration (ISA)-Server enthalten Firewallclientsoftware, die sich auch für den NS_DNS-Namespace registriert. Wenn der dwNameSpace-Parameter auf einen Wert (z. B. NS_DNS) festgelegt ist und der lpNspId-ParameterNULL ist, sind die von der GetAddrInfoEx-Funktion zurückgegebenen Ergebnisse die zusammengeführten Ergebnisse aller Namespaceanbieter, die sich für den angegebenen Namespace registrieren, wobei doppelte Ergebnisse eliminiert werden. Der lpNspId-Parameter sollte auf die GUID des jeweiligen Namespaceanbieters festgelegt werden, wenn nur ein einzelner Namespaceanbieter abgefragt werden soll.

Wenn der Parameter pNameSpace auf NS_ALL festgelegt ist, werden die Ergebnisse der Abfrage aller Namespaceanbieter zusammengeführt und zurückgegeben. In diesem Fall können doppelte Antworten in den Ergebnissen zurückgegeben werden, auf die der ppResult-Parameter verweist, wenn mehrere Namespaceanbieter dieselben Informationen zurückgeben.

Wenn die GetAddrInfoEx-Funktion unter Windows 8 und Windows Server 2012 asynchron abgeschlossen wird, kann der im parameter lpNameHandle zurückgegebene Zeiger mit der GetAddrInfoExCancel-Funktion verwendet werden. Das zurückgegebene Handle ist gültig, wenn GetAddrInfoEx zurückgibt, bis die Vervollständigungsroutine aufgerufen wird, das Ereignis ausgelöst wird oder die GetAddrInfoExCancel-Funktion mit diesem Handle aufgerufen wird.

Freigeben von Adressinformationen aus der dynamischen Zuordnung

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

Beispielcode

Im folgenden Beispiel wird die Verwendung der GetAddrInfoEx-Funktion veranschaulicht.
#ifndef UNICODE
#define UNICODE
#endif

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

// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")

// Need to link with Ole32.lib to print GUID
#pragma comment(lib, "ole32.lib")

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

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

    DWORD dwRetval;

    int i = 1;

    DWORD dwNamespace = NS_ALL;
    LPGUID lpNspid = NULL;

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

    // LPSOCKADDR sockaddr_ip;
    struct sockaddr_in *sockaddr_ipv4;
    struct sockaddr_in6 *sockaddr_ipv6;

    // DWORD ipbufferlength = 46;
    wchar_t ipstringbuffer[46];

    // variables needed to print namespace provider GUID
    int iRet = 0;
    WCHAR GuidString[40] = { 0 };

    // Validate the parameters
    if (argc != 4) {
        wprintf(L"usage: %ws <hostname> <servicename> <namespace>\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 12\n", argv[0]);
        wprintf(L"   looks up the www.contoso.com in the NS_DNS namespace\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;

    dwNamespace = (DWORD) _wtoi(argv[3]);

    wprintf(L"Calling GetAddrInfoEx with following parameters:\n");
    wprintf(L"\tName = %ws\n", argv[1]);
    wprintf(L"\tServiceName (or port) = %ws\n", argv[2]);
    wprintf(L"\tNamespace = %s (", argv[3]);
    switch (dwNamespace) {
    case NS_ALL:
        wprintf(L"(NS_ALL)\n");
        break;
    case NS_DNS:
        wprintf(L"(NS_DNS)\n");
        break;
    case NS_NETBT:
        wprintf(L"NS_NETBT");
        break;
    case NS_WINS:
        wprintf(L"NS_WINS");
        break;
    case NS_NLA:
        wprintf(L"NS_NLA");
        break;
    case NS_BTH:
        wprintf(L"NS_BTH");
        break;
    case NS_NTDS:
        wprintf(L"NS_NTDS");
        break;
    case NS_EMAIL:
        wprintf(L"NS_EMAIL");
        break;
    case NS_PNRPNAME:
        wprintf(L"NS_PNRPNAME");
        break;
    case NS_PNRPCLOUD:
        wprintf(L"NS_PNRPCLOUD");
        break;
    default:
        wprintf(L"Other");
        break;
    }
    wprintf(L")\n\n");

//--------------------------------
// 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);

        if (ptr->ai_blob == NULL)
            wprintf(L"\tBlob: (null)\n");
        else    
            wprintf(L"\tLength of the blob: %u\n",
                    (DWORD) ptr->ai_bloblen);

        if (ptr->ai_provider == NULL)
            wprintf(L"\tNamespace provider GUID: (null)\n");
        else {
            iRet =
                StringFromGUID2(*(ptr->ai_provider), (LPOLESTR) & GuidString,
                                39);
            // For c rather than C++ source code, the above line needs to be
            // iRet = StringFromGUID2(&ptr.ai_provider, (LPOLESTR) &GuidString, 39); 
            if (iRet == 0)
                wprintf(L"StringFromGUID2 failed\n");
            else {
                wprintf(L"\tNamespace provider: %ws\n", GuidString);
            }
        }
    }

    FreeAddrInfoEx(result);
    WSACleanup();

    return 0;
}


Im folgenden Beispiel wird veranschaulicht, wie Sie die GetAddrInfoEx-Funktion asynchron verwenden, um einen Namen in eine IP-Adresse aufzulösen.

//
//    This sample demonstrates how to use asynchronous GetAddrInfoEx to
//    resolve a name to an IP address.
//
//    ResolveName <QueryName>
//

#ifndef UNICODE
#define UNICODE
#endif

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

// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")

#define MAX_ADDRESS_STRING_LENGTH   64

//
//  Asynchronous query context structure.
//

typedef struct _QueryContext
{
    OVERLAPPED      QueryOverlapped;
    PADDRINFOEX     QueryResults;
    HANDLE          CompleteEvent;
}QUERY_CONTEXT, *PQUERY_CONTEXT;

VOID
WINAPI
QueryCompleteCallback(
    _In_ DWORD Error,
    _In_ DWORD Bytes,
    _In_ LPOVERLAPPED Overlapped
    );

int
__cdecl
wmain(
    _In_ int Argc, PWCHAR Argv[]
    )
{
    INT                 Error = ERROR_SUCCESS;
    WSADATA             wsaData;
    BOOL                IsWSAStartupCalled = FALSE;
    ADDRINFOEX          Hints;
    QUERY_CONTEXT       QueryContext;
    HANDLE              CancelHandle = NULL;
    DWORD               QueryTimeout = 5 * 1000; // 5 seconds

    ZeroMemory(&QueryContext, sizeof(QueryContext));

    //
    //  Validate the parameters
    //

    if (Argc != 2)
    {
        wprintf(L"Usage: ResolveName <QueryName>\n");
        goto exit;
    }

    //
    //  All Winsock functions require WSAStartup() to be called first
    //

    Error = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (Error != 0)
    {
        wprintf(L"WSAStartup failed with %d\n", Error);
        goto exit;
    }

    IsWSAStartupCalled = TRUE;

    ZeroMemory(&Hints, sizeof(Hints));
    Hints.ai_family = AF_UNSPEC;

    //
    //  Note that this is a simple sample that waits/cancels a single
    //  asynchronous query. The reader may extend this to support
    //  multiple asynchronous queries.
    //

    QueryContext.CompleteEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

    if (QueryContext.CompleteEvent == NULL)
    {
        Error = GetLastError();
        wprintf(L"Failed to create completion event: Error %d\n",  Error);
        goto exit;
    }

    //
    //  Initiate asynchronous GetAddrInfoExW.
    //
    //  Note GetAddrInfoEx can also be invoked asynchronously using an event
    //  in the overlapped object (Just set hEvent in the Overlapped object
    //  and set NULL as completion callback.)
    //
    //  This sample uses the completion callback method.
    //

    Error = GetAddrInfoExW(Argv[1],
                           NULL,
                           NS_DNS,
                           NULL,
                           &Hints,
                           &QueryContext.QueryResults,
                           NULL,
                           &QueryContext.QueryOverlapped,
                           QueryCompleteCallback,
                           &CancelHandle);

    //
    //  If GetAddrInfoExW() returns  WSA_IO_PENDING, GetAddrInfoExW will invoke
    //  the completion routine. If GetAddrInfoExW returned anything else we must
    //  invoke the completion directly.
    //

    if (Error != WSA_IO_PENDING)
    {
        QueryCompleteCallback(Error, 0, &QueryContext.QueryOverlapped);
        goto exit;
    }

    //
    //  Wait for query completion for 5 seconds and cancel the query if it has
    //  not yet completed.
    //

    if (WaitForSingleObject(QueryContext.CompleteEvent,
                            QueryTimeout)  == WAIT_TIMEOUT )
    {

        //
        //  Cancel the query: Note that the GetAddrInfoExCancelcancel call does
        //  not block, so we must wait for the completion routine to be invoked.
        //  If we fail to wait, WSACleanup() could be called while an
        //  asynchronous query is still in progress, possibly causing a crash.
        //

        wprintf(L"The query took longer than %d seconds to complete; "
                L"cancelling the query...\n", QueryTimeout/1000);

        GetAddrInfoExCancel(&CancelHandle);

        WaitForSingleObject(QueryContext.CompleteEvent,
                            INFINITE);
    }

exit:

    if (IsWSAStartupCalled)
    {
        WSACleanup();
    }

    if (QueryContext.CompleteEvent)
    {
        CloseHandle(QueryContext.CompleteEvent);
    }

    return Error;
}

//
// Callback function called by Winsock as part of asynchronous query complete
//

VOID
WINAPI
QueryCompleteCallback(
    _In_ DWORD Error,
    _In_ DWORD Bytes,
    _In_ LPOVERLAPPED Overlapped
    )
{
    PQUERY_CONTEXT  QueryContext = NULL;
    PADDRINFOEX     QueryResults = NULL;
    WCHAR           AddrString[MAX_ADDRESS_STRING_LENGTH];
    DWORD           AddressStringLength;

    UNREFERENCED_PARAMETER(Bytes);

    QueryContext = CONTAINING_RECORD(Overlapped,
                                     QUERY_CONTEXT,
                                     QueryOverlapped);

    if (Error != ERROR_SUCCESS)
    {
        wprintf(L"ResolveName failed with %d\n", Error);
        goto exit;
    }

    wprintf(L"ResolveName succeeded. Query Results:\n");

    QueryResults = QueryContext->QueryResults;

    while(QueryResults)
    {
        AddressStringLength = MAX_ADDRESS_STRING_LENGTH;

        WSAAddressToString(QueryResults->ai_addr,
                           (DWORD)QueryResults->ai_addrlen,
                           NULL,
                           AddrString,
                           &AddressStringLength);

        wprintf(L"Ip Address: %s\n", AddrString);
        QueryResults = QueryResults->ai_next;
    }

exit:

    if (QueryContext->QueryResults)
    {
        FreeAddrInfoEx(QueryContext->QueryResults);
    }

    //
    //  Notify caller that the query completed
    //

    SetEvent(QueryContext->CompleteEvent);
    return;
}

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

Internationalisierte Domänennamen

Internethostnamen bestehen in der Regel aus einem sehr eingeschränkten Satz von Zeichen:
  • 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 verarbeiten. Die Spezifikationen für IDNs und IDNA sind in RFC 3490, RTF 5890 und RFC 6365 dokumentiert, die von der Internet Engineering Task Force (IETF) veröffentlicht wurden.

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

Unter Windows 7 und Windows Server 2008 R2 oder früher bietet die GetAddrInfoEx-Funktion derzeit keine Unterstützung für die IDN-Analyse, die auf den im pName-Parameter übergebenen Namen angewendet wird. Die Breitzeichenversion der GetAddrInfoEx-Funktion verwendet punycode nicht, um ein IDN Punycode-Format gemäß RFC 3490 zu konvertieren. Die Breitzeichenversion der GetAddrInfoEx-Funktion beim Abfragen von DNS codiert den Unicode-Namen im UTF-8-Format, das von Microsoft DNS-Servern in einer Unternehmensumgebung verwendet wird.

Mehrere Funktionen unter Windows Vista und später 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 enthielt. 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 Entwürfen von Standards finden Sie unter Handling Internationalized Domain Names (IDNs).

Die IdnToAscii-Funktion kann verwendet werden, um einen IDN-Namen in ein ASCII-Formular zu konvertieren, das dann im pName-Parameter an die GetAddrInfoEx-Funktion übergeben werden kann, wenn die ASCII-Version dieser Funktion verwendet wird (wenn UNICODE und _UNICODE nicht definiert sind). Um diesen IDN-Namen an die GetAddrInfoEx-Funktion zu übergeben, wenn die Breitzeichenversion dieser Funktion verwendet wird (wenn UNICODE oder _UNICODE definiert ist), können Sie die MultiByteToWideChar-Funktion verwenden, um die CHAR-Zeichenfolge in eine WCHAR-Zeichenfolge zu konvertieren.

Verwendung von ai_flags im hinweists-Parameter

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

Diese Flagbits werden in der Ws2def.h-Headerdatei im Microsoft Windows Software Development Kit (SDK) für Windows 7 definiert. Diese Flagbits werden in der Ws2tcpip.h-Headerdatei 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 Bindfunktion verwenden möchte. Wenn das flag AI_PASSIVE festgelegt ist und pName ein NULL-Zeiger ist, wird der IP-Adressteil der Socketadressstruktur für IPv4-Adressen und IN6ADDR_ANY_INIT für IPv6-Adressen auf INADDR_ANY 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 pName-Parameter in diesem Fall ein NULL-Zeiger ist, wird der IP-Adressteil der Socketadressstruktur auf die Loopbackadresse festgelegt.

AI_CANONNAME Wenn weder AI_CANONNAME noch AI_NUMERICHOST verwendet wird, versucht die GetAddrInfoEx-Funktion die Auflösung. Wenn eine Literalzeichenfolge übergeben wird, versucht GetAddrInfoEx , die Zeichenfolge zu konvertieren, und wenn ein Hostname übergeben wird, versucht die GetAddrInfoEx-Funktion , den Namen in eine Adresse oder mehrere Adressen aufzulösen.

Wenn das AI_CANONNAME Bit festgelegt ist, kann der pName-Parameter nicht NULL sein. Andernfalls schlägt die GetAddrInfoEx-Funktion mit WSANO_RECOVERY fehl.

Wenn das AI_CANONNAME Bit festgelegt ist und die GetAddrInfoEx-Funktion erfolgreich zurückgibt, zeigt das ai_canonname-Element im ppResult-Parameter auf eine NULL-beendete Zeichenfolge, die den kanonischen Namen des angegebenen Knotens enthält.

Hinweis Die GetAddrInfoEx-Funktion kann erfolgreich zurückgeben, wenn das AI_CANONNAME-Flag festgelegt ist, aber der ai_canonname Member in der zugeordneten addrinfo-Strukturnull ist. Daher wird das AI_CANONNAME-Flag empfohlen, um zu testen, ob der ai_canonname Member in der zugeordneten addrinfoex-StrukturNULL ist.
 
AI_NUMERICHOST Wenn das AI_NUMERICHOST Bits festgelegt ist, muss der pName-Parameter eine numerische Hostadressenzeichenfolge enthalten, die nicht NULL ist. Andernfalls wird der EAI_NONAME Fehler zurückgegeben. Dieses Flag verhindert, dass ein Namensauflösungsdienst aufgerufen wird.
AI_NUMERICSERV Wenn das AI_NUMERICSERV Bits festgelegt ist, muss der pServiceName-Parameter eine numerische Portnummer enthalten, die nicht NULL ist. Andernfalls wird der EAI_NONAME Fehler zurückgegeben. Dieses Flag verhindert, dass ein Namensauflösungsdienst aufgerufen wird.

Das flag AI_NUMERICSERV ist im Windows SDK für Windows Vista und höher definiert. Das flag AI_NUMERICSERV 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.

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 GetAddrInfoEx 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 pName-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 GetAddrInfoEx 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 addrinfoex-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.

Wenn das AI_FQDN Bit festgelegt ist, kann der pName-Parameter nicht NULL sein. Andernfalls schlägt die GetAddrInfoEx-Funktion mit WSANO_RECOVERY fehl.

Unter Windows 8 und Windows Server 2012 können sowohl die AI_FQDN als auch AI_CANONNAME Bits festgelegt werden. Wenn die GetAddrInfoEx-Funktion sowohl mit dem AI_FQDN als auch mit AI_CANONNAME Bits aufgerufen wird, gibt der ppResult-Parameter einen Zeiger auf eine addrinfoex2-Struktur und nicht auf eine addrinfoex-Struktur zurück.

Unter Windows 7 und Windows Server 2008 R2 kann nur eines der AI_FQDN und AI_CANONNAME Bits festgelegt werden. Die GetAddrInfoEx-Funktion schlägt fehl, wenn beide Flags mit EAI_BADFLAGS vorhanden sind.

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 mit Punycode in den Von der GetAddrInfoEx-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.

 

Hinweis

Der ws2tcpip.h-Header definiert GetAddrInfoEx 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 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile ws2tcpip.h
Bibliothek Ws2_32.lib
DLL Ws2_32.dll

Weitere Informationen

FreeAddrInfoEx

GetAddrInfoExCancel

GetAddrInfoExOverlappedResult

GetAddrInfoW

IdnToAscii

IdnToUnicode

WSAEnumNameSpaceProviders

WSAGetLastError

Windows Sockets-Fehlercodes

addrinfoex

addrinfoex2

gai_strerror

getaddrinfo