getaddrinfo-Funktion (ws2tcpip.h)
Die getaddrinfo-Funktion ermöglicht eine protokollunabhängige Übersetzung von einem ANSI-Hostnamen in eine Adresse.
Syntax
INT WSAAPI getaddrinfo(
[in, optional] PCSTR pNodeName,
[in, optional] PCSTR pServiceName,
[in, optional] const ADDRINFOA *pHints,
[out] PADDRINFOA *ppResult
);
Parameter
[in, optional] pNodeName
Ein Zeiger auf eine NULL-beendete ANSI-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 NULL-beendete ANSI-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 addrinfo-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 addrinfo-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 addrinfo-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 getaddrinfo-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 getaddrinfo-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 |
|---|---|
| Zum Ausführen des Vorgangs war nicht genügend Arbeitsspeicher vorhanden. | |
| Es wurde eine Adresse verwendet, die mit dem angeforderten Protokoll nicht kompatibel ist. Dieser Fehler wird zurückgegeben, wenn das ai_family Member der addrinfo-Struktur , auf die vom pHints-Parameter verwiesen wird, nicht unterstützt wird. | |
| Ein ungültiges Argument wurde angegeben. Dieser Fehler wird zurückgegeben, wenn ein ungültiger Wert für das ai_flags Member der addrinfo-Struktur angegeben wurde, auf das vom pHints-Parameter verwiesen wird. | |
| 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 addrinfo-Struktur , auf die vom pHints-Parameter verwiesen wird, nicht unterstützt wird. | |
| 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. | |
| Der angeforderte Name ist gültig, es wurde jedoch keine Daten mit dem angeforderten Typ gefunden. | |
| Beim Datenbankaufruf ist ein nicht behebbarer Fehler aufgetreten. Dieser Fehler wird zurückgegeben, wenn ein nicht wiederherstellbarer Fehler bei der Namensauflösung aufgetreten ist. | |
| Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen. | |
| 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. | |
| Die angegebene Klasse wurde nicht gefunden. Der pServiceName-Parameter wird für die angegebene ai_socktype Member der addrinfo-Struktur nicht unterstützt, auf die vom pHints-Parameter verwiesen wird . |
Hinweise
Die getaddrinfo-Funktion ist die ANSI-Version einer Funktion, die eine protokollunabhängige Übersetzung von Hostnamen zu Adresse ermöglicht. Die Unicode-Version dieser Funktion ist GetAddrInfoW. Entwickler werden empfohlen, die Unicode-Funktion GetAddrInfoW anstelle der getaddrinfo ANSI-Funktion zu verwenden.
Die getaddrinfo-Funktion gibt Ergebnisse für den NS_DNS Namespace zurück. Die getaddrinfo-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.
Ein weiterer Name, der für die getaddrinfo-Funktion verwendet werden kann, ist GetAddrInfoA. Makros in der Ws2tcpip.h-Headerdatei definieren GetAddrInfoA in getaddrinfo.
Makros in der Ws2tcpip.h-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 nicht definiert ist, wird GetAddrInfo für getaddrinfo, die ANSI-Version der Funktion, und ADDRINFOT für die addrinfo-Struktur definiert. Wenn UNICODE oder _UNICODE definiert ist, wird GetAddrInfo für GetAddrInfoW, die Unicode-Version der Funktion, und ADDRINFOT für die addrinfoW-Struktur definiert.
Die Parameternamen und Parametertypen für die getaddrinfo-Funktion , die in der Ws2tcpip.h-Headerdatei im Platform Software Development Kit (SDK) für Windows Server 2003 und Windows XP definiert wurden, waren unterschiedlich.
Ein oder beide pNodeName- oder pServiceName-Parameter müssen auf eine MIT NULL beendete ANSI-Zeichenfolge verweisen. in der Regel werden beide bereitgestellt.
Bei Erfolg wird eine verknüpfte Liste von addrinfo-Strukturen im ppResult-Parameter zurückgegeben. Die Liste kann verarbeitet werden, indem Sie dem im ai_next-Member jeder zurückgegebenen addrinfo-Struktur angegebenen Zeiger folgen, bis ein NULL-Zeiger gefunden wird. In jeder zurückgegebenen addrinfo-Struktur entsprechen die elemente ai_family, ai_socktype und ai_protocol den entsprechenden Argumenten in einem Socket - oder WSASocket-Funktionsaufruf . Außerdem verweist der ai_addr Member in jeder zurückgegebenen addrinfo-Struktur auf eine ausgefüllte Socketadressstruktur, deren Länge im ai_addrlen-Element angegeben ist.
Wenn der Parameter pNodeName auf einen Computernamen verweist, werden alle permanenten 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 den Funktionen GetUnicastIpAddressTable oder GetUnicastIpAddressEntry zurückgegeben werden, bei denen das SkipAsSource-Element in der MIB_UNICASTIPADDRESS_ROW-Struktur auf false festgelegt ist.
Wenn der Parameter pNodeName auf eine Zeichenfolge zeigt, die "localhost" entspricht, werden alle Loopbackadressen auf dem lokalen Computer zurückgegeben.
Wenn der Parameter pNodeName 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 den Namen eines virtuellen Clustersservers verweist, werden nur virtuelle Serveradressen zurückgegeben. Unter Windows Vista und höher enthalten diese Adressen alle Unicast-IP-Adressen, die von den Funktionen GetUnicastIpAddressTable oder GetUnicastIpAddressEntry zurückgegeben werden, in denen 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) bieten Unterstützung für Netsh.exe zum Festlegen des SkipAsSource-Attributs für eine IP-Adresse. Dies ändert auch das Verhalten, sodass die IP-Adresse im 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 im 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, sodass die IP-Adresse im 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 im 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, sodass die IP-Adresse im 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 im DNS registriert.
Aufrufer der getaddrinfo-Funktion können Hinweise zum Typ des Sockets bereitstellen, der durch eine addrinfo-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 addrinfo-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.
Der Wert AF_UNSPEC für ai_family gibt an, dass der Aufrufer jede Protokollfamilie akzeptiert. Dieser Wert kann verwendet werden, um sowohl IPv4- als auch IPv6-Adressen für den Hostnamen zurückzugeben, auf den der pNodeName-Parameter verweist. Unter Windows Server 2003 und Windows XP werden IPv6-Adressen nur zurückgegeben, wenn IPv6 auf dem lokalen Computer installiert ist.
Andere Werte in der addrinfo-Struktur , die im pHints-Parameter bereitgestellt werden, weisen auf bestimmte Anforderungen hin. 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 getaddrinfo-Funktion den Parameter so, als ob die addrinfo-Struktur in pHints initialisiert wurde, wobei der ai_family Member auf AF_UNSPEC und alle anderen Member auf 0 (null) festgelegt wurde.
Unter Windows Vista und höher, wenn getaddrinfo 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 getaddrinfo-Funktion kann verwendet werden, um eine Textzeichenfolgendarstellung einer IP-Adresse in eine addrinfo-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 addrinfo-Struktur , auf die der pHints-Parameter verweist, 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 addrinfo-Struktur konvertiert, auf die der ppResult-Parameter verweist. Die zurückgegebene addrinfo-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 getaddrinfo-Funktion zurückgegeben werden, auf die der ppResult-Parameter verweist, werden dynamisch zugeordnet, einschließlich aller addrinfo-Strukturen , Socketadressstrukturen und kanonischen Hostnamenzeichenfolgen, auf die von addrinfo-Strukturen verwiesen wird. Der durch einen erfolgreichen Aufruf dieser Funktion zugeordnete Arbeitsspeicher muss mit einem nachfolgenden Aufruf von freeaddrinfo freigegeben werden.Beispielcode
Im folgenden Codebeispiel wird die Verwendung der getaddrinfo-Funktion veranschaulicht.#undef UNICODE
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
// link with Ws2_32.lib
#pragma comment (lib, "Ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
INT iRetval;
DWORD dwRetval;
int i = 1;
struct addrinfo *result = NULL;
struct addrinfo *ptr = NULL;
struct addrinfo hints;
struct sockaddr_in *sockaddr_ipv4;
// struct sockaddr_in6 *sockaddr_ipv6;
LPSOCKADDR sockaddr_ip;
char ipstringbuffer[46];
DWORD ipbufferlength = 46;
// Validate the parameters
if (argc != 3) {
printf("usage: %s <hostname> <servicename>\n", argv[0]);
printf("getaddrinfo provides protocol-independent translation\n");
printf(" from an ANSI host name to an IP address\n");
printf("%s example usage\n", argv[0]);
printf(" %s www.contoso.com 0\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
printf("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;
printf("Calling getaddrinfo with following parameters:\n");
printf("\tnodename = %s\n", argv[1]);
printf("\tservname (or port) = %s\n\n", argv[2]);
//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
dwRetval = getaddrinfo(argv[1], argv[2], &hints, &result);
if ( dwRetval != 0 ) {
printf("getaddrinfo failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
printf("getaddrinfo returned success\n");
// Retrieve each address and print out the hex bytes
for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {
printf("getaddrinfo response %d\n", i++);
printf("\tFlags: 0x%x\n", ptr->ai_flags);
printf("\tFamily: ");
switch (ptr->ai_family) {
case AF_UNSPEC:
printf("Unspecified\n");
break;
case AF_INET:
printf("AF_INET (IPv4)\n");
sockaddr_ipv4 = (struct sockaddr_in *) ptr->ai_addr;
printf("\tIPv4 address %s\n",
inet_ntoa(sockaddr_ipv4->sin_addr) );
break;
case AF_INET6:
printf("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)
printf("WSAAddressToString failed with %u\n", WSAGetLastError() );
else
printf("\tIPv6 address %s\n", ipstringbuffer);
break;
case AF_NETBIOS:
printf("AF_NETBIOS (NetBIOS)\n");
break;
default:
printf("Other %ld\n", ptr->ai_family);
break;
}
printf("\tSocket type: ");
switch (ptr->ai_socktype) {
case 0:
printf("Unspecified\n");
break;
case SOCK_STREAM:
printf("SOCK_STREAM (stream)\n");
break;
case SOCK_DGRAM:
printf("SOCK_DGRAM (datagram) \n");
break;
case SOCK_RAW:
printf("SOCK_RAW (raw) \n");
break;
case SOCK_RDM:
printf("SOCK_RDM (reliable message datagram)\n");
break;
case SOCK_SEQPACKET:
printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
break;
default:
printf("Other %ld\n", ptr->ai_socktype);
break;
}
printf("\tProtocol: ");
switch (ptr->ai_protocol) {
case 0:
printf("Unspecified\n");
break;
case IPPROTO_TCP:
printf("IPPROTO_TCP (TCP)\n");
break;
case IPPROTO_UDP:
printf("IPPROTO_UDP (UDP) \n");
break;
default:
printf("Other %ld\n", ptr->ai_protocol);
break;
}
printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
printf("\tCanonical name: %s\n", ptr->ai_canonname);
}
freeaddrinfo(result);
WSACleanup();
return 0;
}
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 getaddrinfo-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 beschriebenen AI_DISABLE_IDN_ENCODING-Flags deaktiviert werden.
Unter Windows 7 und Windows Server 2008 R2 oder früher bietet die getaddrinfo-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 aus. Die Breitzeichenversion der GetAddrInfo-Funktion verwendet punycode nicht, um einen IDN gemäß RFC 3490 zu konvertieren. Die Breitzeichenversion der GetAddrInfo-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 das ASCII-Formular zu konvertieren, das dann im pNodeName-Parameter an die getaddrinfo-Funktion übergeben werden kann. Um diesen IDN-Namen an die GetAddrInfo-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 pHints-Parameter
Flags im ai_flags Member der optionalen addrinfo-Struktur , die im pHints-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 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 pNodeName 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 pNodeName-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 getaddrinfo-Funktion die Auflösung. Wenn eine Literalzeichenfolge übergeben wird, versucht getaddrinfo , die Zeichenfolge zu konvertieren, und wenn ein Hostname übergeben wird, versucht die getaddrinfo-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 getaddrinfo-Funktion mit WSANO_RECOVERY fehl. Wenn das AI_CANONNAME Bit festgelegt ist und die getaddrinfo-Funktion erfolgreich zurückgibt, zeigt der ai_canonname Member im ppResult-Parameter auf eine NULL-beendete Zeichenfolge, die den kanonischen Namen des angegebenen Knotens enthält. Hinweis Die getaddrinfo-Funktion kann einen Erfolg 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 addrinfo-StrukturNULL ist.
|
| AI_NUMERICHOST | Wenn das AI_NUMERICHOST Bits festgelegt ist, muss der pNodeName-Parameter eine numerische Hostadresszeichenfolge 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 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 AI_ALL-Flag wird unter Windows Vista und höher unterstützt. |
| AI_ADDRCONFIG |
Wenn das AI_ADDRCONFIG Bit festgelegt ist, löst getaddrinfo 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-Adressformat konvertiert.
Das AI_V4MAPPED-Flag 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 Bit 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 autorisierende Ergebnisse zurück.
Das AI_NON_AUTHORITATIVE-Flag ist im Windows SDK für Windows Vista und höher definiert. Das AI_NON_AUTHORITATIVE-Flag 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 im pNodeName-Parameter kein Name 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 und ein flacher Name (einzelne Bezeichnung) angegeben ist, gibt getaddrinfo 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 addrinfo-Struktur zurückgegeben. Dies unterscheidet sich von AI_CANONNAME Bitflag, das den in DNS registrierten kanonischen Namen zurückgibt, der 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 getaddrinfo-Funktion schlägt fehl, wenn beide Flags mit EAI_BADFLAGS vorhanden sind.
Wenn das AI_FQDN Bits 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 AI_FQDN-Flag 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. Dieser Hinweis kann vom Namespaceanbieter ignoriert werden.
Windows 7: Das flag AI_FILESERVER wird im Windows SDK für Windows 7 und höher definiert. Das AI_FILESERVER-Flag wird unter Windows 7 und höher unterstützt. |
Beispielcode mit AI_NUMERICHOST
Im folgenden Codebeispiel wird gezeigt, wie Sie mithilfe der getaddrinfo-Funktion eine Textzeichenfolgendarstellung einer IP-Adresse in eine addrinfo-Struktur konvertieren, die eine Sockaddr-Struktur für die IP-Adresse und andere Informationen enthält.#undef UNICODE
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
// link with Ws2_32.lib
#pragma comment (lib, "Ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
DWORD dwRetval;
int i = 1;
struct addrinfo *result = NULL;
struct addrinfo *ptr = NULL;
struct addrinfo hints;
// Validate the parameters
if (argc != 2) {
printf("usage: %s <IP Address String>\n", argv[0]);
printf(" getaddrinfo determines the IP binary network address\n");
printf(" %s 207.46.197.32\n", argv[0]); /* www.contoso.com */
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
printf("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_flags = AI_NUMERICHOST;
hints.ai_family = AF_UNSPEC;
// hints.ai_socktype = SOCK_STREAM;
// hints.ai_protocol = IPPROTO_TCP;
//--------------------------------
// Call getaddrinfo(). If the call succeeds,
// the result variable will hold a linked list
// of addrinfo structures containing response
// information
dwRetval = getaddrinfo(argv[1], NULL, &hints, &result);
if ( dwRetval != 0 ) {
printf("getaddrinfo failed with error: %d\n", dwRetval);
WSACleanup();
return 1;
}
printf("getaddrinfo returned success\n");
// Retrieve each address and print out the hex bytes
for(ptr=result; ptr != NULL ;ptr=ptr->ai_next) {
printf("getaddrinfo response %d\n", i++);
printf("\tFlags: 0x%x\n", ptr->ai_flags);
printf("\tFamily: ");
switch (ptr->ai_family) {
case AF_UNSPEC:
printf("Unspecified\n");
break;
case AF_INET:
printf("AF_INET (IPv4)\n");
break;
case AF_INET6:
printf("AF_INET6 (IPv6)\n");
break;
case AF_NETBIOS:
printf("AF_NETBIOS (NetBIOS)\n");
break;
default:
printf("Other %ld\n", ptr->ai_family);
break;
}
printf("\tSocket type: ");
switch (ptr->ai_socktype) {
case 0:
printf("Unspecified\n");
break;
case SOCK_STREAM:
printf("SOCK_STREAM (stream)\n");
break;
case SOCK_DGRAM:
printf("SOCK_DGRAM (datagram) \n");
break;
case SOCK_RAW:
printf("SOCK_RAW (raw) \n");
break;
case SOCK_RDM:
printf("SOCK_RDM (reliable message datagram)\n");
break;
case SOCK_SEQPACKET:
printf("SOCK_SEQPACKET (pseudo-stream packet)\n");
break;
default:
printf("Other %ld\n", ptr->ai_socktype);
break;
}
printf("\tProtocol: ");
switch (ptr->ai_protocol) {
case 0:
printf("Unspecified\n");
break;
case IPPROTO_TCP:
printf("IPPROTO_TCP (TCP)\n");
break;
case IPPROTO_UDP:
printf("IPPROTO_UDP (UDP) \n");
break;
default:
printf("Other %ld\n", ptr->ai_protocol);
break;
}
printf("\tLength of this sockaddr: %d\n", ptr->ai_addrlen);
printf("\tCanonical name: %s\n", ptr->ai_canonname);
}
freeaddrinfo(result);
WSACleanup();
return 0;
}
Unterstützung für getaddrinfo unter Windows 2000 und älteren Versionen
Die funktion getaddrinfo wurde dem Ws2_32.dll unter Windows XP und höher hinzugefügt. Um eine Anwendung auszuführen, die diese Funktion in früheren Versionen von Windows verwendet, müssen Sie die Dateien Ws2tcpip.h und Wspiapi.h einschließen. Wenn die Include-Datei Wspiapi.h hinzugefügt wird, wird die getaddrinfo-Funktion für die Inlinefunktion WspiapiGetAddrInfo in der Datei Wspiapi.h definiert. Zur Laufzeit wird die WspiapiGetAddrInfo-Funktion so implementiert, dass, wenn die Ws2_32.dll oder der Wship6.dll (die Datei, die getaddrinfo in der IPv6 Technology Preview für Windows 2000 enthält) getaddrinfo nicht enthält, eine Version von getaddrinfo inline basierend auf Code in der Headerdatei Wspiapi.h implementiert wird. Dieser Inlinecode wird auf älteren Windows-Plattformen verwendet, die die getaddrinfo-Funktion nicht nativ unterstützen.Das IPv6-Protokoll wird unter Windows 2000 unterstützt, wenn die IPv6 Technology Preview für Windows 2000 installiert ist. Andernfalls ist die Getaddrinfo-Unterstützung für Versionen von Windows vor Windows XP auf die Behandlung der IPv4-Namensauflösung beschränkt.
Die GetAddrInfoW-Funktion ist die Unicode-Version von getaddrinfo. Die GetAddrInfoW-Funktion wurde dem Ws2_32.dll in Windows XP mit Service Pack 2 (SP2) hinzugefügt. Die GetAddrInfoW-Funktion kann nicht in Versionen von Windows vor Windows XP mit SP2 verwendet werden.
Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps unter Windows Phone 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.
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 |