getaddrinfo-Funktion (ws2tcpip.h)
Die getaddrinfo-Funktion bietet 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 MIT NULL endende ANSI-Zeichenfolge, die einen Hostnamen (Knoten) oder eine numerische Hostadresszeichenfolge 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 MIT NULL endende 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 ist, 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 Vom Aufrufer unterstützten Sockets bereitstellt.
Die elemente ai_addrlen, ai_canonname, ai_addr und ai_next der addrinfo-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 addrinfo-Strukturen , die Antwortinformationen zum Host enthält.
Rückgabewert
Success gibt null 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 getaddrinfo-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 vorübergehender 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 behebbarer Fehler bei der Namensauflösung aufgetreten. |
| EAI_FAMILY | WSAEAFNOSUPPORT | Der ai_family Member des pHints-Parameters wird nicht unterstützt. |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | Ein Speicherbelegungsfehler 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 bereitgestellt. |
| 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 | Der ai_socktype Member des pHints-Parameters wird nicht unterstützt. |
Verwenden Sie die funktion gai_strerror , um Fehlermeldungen basierend auf den EAI-Codes zu drucken, die von der getaddrinfo-Funktion zurückgegeben werden. Die funktion gai_strerror wird zur Einhaltung von IETF-Empfehlungen bereitgestellt, ist aber nicht threadsicher. Daher wird die Verwendung herkömmlicher Windows Sockets-Funktionen wie WSAGetLastError empfohlen.
| Fehlercode | Bedeutung |
|---|---|
| Es war nicht genügend Arbeitsspeicher vorhanden, um den Vorgang auszuführen. | |
| Es wurde eine Adresse verwendet, die mit dem angeforderten Protokoll nicht kompatibel ist. Dieser Fehler wird zurückgegeben, wenn der ai_family Member der addrinfo-Struktur , auf die der pHints-Parameter verweist, nicht unterstützt wird. | |
| Ein ungültiges Argument wurde angegeben. Dieser Fehler wird zurückgegeben, wenn ein ungültiger Wert für den ai_flags Member der addrinfo-Struktur bereitgestellt wurde, auf die der pHints-Parameter verweist. | |
| In dieser Adressfamilie ist die Unterstützung für den angegebenen Sockettyp nicht vorhanden. Dieser Fehler wird zurückgegeben, wenn der ai_socktype Member der addrinfo-Struktur , auf die der pHints-Parameter verweist, 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 bereitgestellt 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 behebbarer 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 vorübergehender 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 der pHints-Parameter verweist. |
Hinweise
Die getaddrinfo-Funktion ist die ANSI-Version einer Funktion, die eine protokollunabhängige Übersetzung vom Hostnamen zur Adresse bereitstellt. Die Unicode-Version dieser Funktion ist GetAddrInfoW. Entwicklern wird empfohlen, die Unicode-Funktion GetAddrInfoW anstelle der ANSI-Funktion getaddrinfo 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 zu getaddrinfo.
Makros in der Ws2tcpip.h-Headerdatei definieren einen Funktionsnamen mit gemischter Groß-/Kleinschreibung von GetAddrInfo und eine ADDRINFOT-Struktur . Diese GetAddrInfo-Funktion sollte mit den Parametern pNodeName und pServiceName eines Zeigers vom Typ TCHAR und den Parametern pHints und ppResult 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.
Einer oder beide der Parameter pNodeName oder pServiceName müssen auf eine NULL-endende ANSI-Zeichenfolge verweisen. in der Regel werden beide bereitgestellt.
Bei erfolgreicher Ausführung wird im ppResult-Parameter eine verknüpfte Liste von addrinfo-Strukturen zurückgegeben. Die Liste kann verarbeitet werden, indem Sie dem Im ai_next-Member jeder zurückgegebenen addrinfo-Struktur folgen, bis ein NULL-Zeiger gefunden wird. In jeder zurückgegebenen addrinfo-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 addrinfo-Struktur auf eine ausgefüllte Socketadressstruktur, deren Länge im ai_addrlen-Element 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 getaddrinfo-Funktion können Hinweise zum Typ des Sockets geben, 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 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.
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, geben spezifische Anforderungen an. 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 getaddrinfo-Funktion ihn so, als würde die addrinfo-Struktur in pHints initialisiert, wobei ihr ai_family Member auf AF_UNSPEC und alle anderen Member auf 0 festgelegt wurde.
Wenn unter Windows Vista und höher 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 die addrinfo-Struktur , auf die vom pHints-Parameter verwiesen wird, muss das AI_NUMERICHOST-Flag im ai_flags-Member festgelegt haben. 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 zugewiesene Arbeitsspeicher muss mit einem nachfolgenden Aufruf von freeaddrinfo freigegeben werden.Beispielcode
Im folgenden Codebeispiel wird gezeigt, wie die getaddrinfo-Funktion verwendet wird.#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 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.
Auf 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 erläuterten 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 durch. 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, 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, der 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 Headerdatei Ws2def.h im Microsoft Windows Software Development Kit (SDK) für Windows 7 definiert. Diese Flagbits werden in der Ws2tcpip.h-Headerdatei auf dem Windows SDK für Windows Server 2008 und Windows Vista definiert. Diese Flagbits werden in der Headerdatei Ws2tcpip.h 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 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 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 den Erfolg zurückgibt, verweist das 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 den Erfolg zurückgeben, wenn das AI_CANONNAME-Flag festgelegt ist, aber der ai_canonname Member in der zugeordneten addrinfo-Struktur ist NULL. Die empfohlene Verwendung des AI_CANONNAME-Flags umfasst daher das Testen, ob das ai_canonname Member in der zugeordneten addrinfo-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 AI_NUMERICSERV-Flag wird auf 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 wird auf dem 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 wird auf dem 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 wird auf dem 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 wird auf dem 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 wird auf dem 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 wird auf dem 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 wird auf dem 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 AI_FILESERVER-Flag ist auf dem 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 auf Windows Phone 8 und höher unterstützt.
Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 8.1, Windows Vista [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 |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für