ADDRINFOA-Struktur (ws2def.h)
Die addrinfo-Struktur wird von der getaddrinfo-Funktion verwendet, um Hostadresseninformationen zu enthalten.
Syntax
typedef struct addrinfo {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
char *ai_canonname;
struct sockaddr *ai_addr;
struct addrinfo *ai_next;
} ADDRINFOA, *PADDRINFOA;
Member
ai_flags
Typ: int
Flags, die optionen angeben, die in der getaddrinfo-Funktion verwendet werden.
Unterstützte Werte für den ai_flags-Member werden in der Ws2def.h-Headerdatei auf der Windows SDK für Windows 7 und höher definiert. Diese Werte werden in der Ws2tcpip.h-Headerdatei auf der Windows SDK für Windows Server 2008 und Windows Vista definiert. Diese Werte werden in der Ws2tcpip.h-Headerdatei im Platform SDK für Windows Server 2003 und Windows XP definiert. Unterstützte Werte für den ai_flags Member können eine Kombination der folgenden Optionen sein.
| Wert | Bedeutung |
|---|---|
|
Die Socketadresse wird in einem Aufruf der Bindfunktion verwendet. |
|
Der kanonische Name wird im ersten ai_canonname Member zurückgegeben. |
|
Der nodename-Parameter , der an die getaddrinfo-Funktion übergeben wird, muss eine numerische Zeichenfolge sein. |
|
Wenn dieses Bit festgelegt ist, wird eine Anforderung für IPv6-Adressen und IPv4-Adressen mit AI_V4MAPPED.
Diese Option wird unter Windows Vista und höher unterstützt. |
|
Getaddrinfo wird nur aufgelöst, wenn eine globale Adresse konfiguriert ist. Die IPv6- und IPv4-Loopbackadresse wird nicht als gültige globale Adresse betrachtet.
Diese Option wird unter Windows Vista und höher unterstützt. |
|
Wenn bei der getaddrinfo-Anforderung für IPv6-Adressen ein Fehler auftritt, wird eine Namensdienstanforderung für IPv4-Adressen gestellt, und diese Adressen werden in das IPv4-zugeordnete IPv6-Adressformat konvertiert.
Diese Option wird unter Windows Vista und höher unterstützt. |
|
Die Adressinformationen können von einem nicht autorisierenden Namespaceanbieter stammen.
Diese Option wird nur unter Windows Vista und höher für den NS_EMAIL-Namespace unterstützt. |
|
Die Adressinformationen stammen aus einem sicheren Kanal.
Diese Option wird nur unter Windows Vista und höher für den NS_EMAIL-Namespace unterstützt. |
|
Die Adressinformationen beziehen sich auf einen bevorzugten Namen für einen Benutzer.
Diese Option wird nur unter Windows Vista und höher für den NS_EMAIL-Namespace unterstützt. |
|
Wenn ein flacher Name (einzelne Bezeichnung) angegeben wird, 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 zurückgegeben.
Dies unterscheidet sich von AI_CANONNAME Bitflag, das den kanonischen Namen zurückgibt, der im DNS registriert ist und sich möglicherweise von dem vollqualifizierten Domänennamen unterscheidet, in den der Flatname aufgelöst wurde. Es kann nur eines der AI_FQDN und AI_CANONNAME Bits festgelegt werden. Die getaddrinfo-Funktion schlägt fehl, wenn beide Flags mit EAI_BADFLAGS vorhanden sind. Diese Option wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt. |
|
Ein Hinweis an den Namespaceanbieter, dass der abgefragte Hostname in einem Dateifreigabeszenario verwendet wird. Der Namespaceanbieter ignoriert diesen Hinweis möglicherweise.
Diese Option wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt. |
ai_family
Typ: int
Die Adressfamilie. Mögliche Werte für die Adressfamilie sind in der Winsock2.h-Headerdatei definiert.
Auf der für Windows Vista und höher veröffentlichten Windows SDK wurde die organization der Headerdateien geändert, und die möglichen Werte für die Adressfamilie sind in der Ws2def.h-Headerdatei definiert. Beachten Sie, dass die Ws2def.h-Headerdatei automatisch in Winsock2.h enthalten ist und niemals direkt verwendet werden sollte.
Die derzeit unterstützten Werte sind AF_INET oder AF_INET6, d. h. die Internetadressfamilienformate für IPv4 und IPv6. Andere Optionen für die Adressfamilie (AF_NETBIOS für die Verwendung mit NetBIOS, z. B.) werden unterstützt, wenn ein Windows Sockets-Dienstanbieter für die Adressfamilie installiert ist. Beachten Sie, dass die Werte für die AF_ Adressfamilie und PF_ Protokollfamilienkonstanten identisch sind (z. B. AF_UNSPEC und PF_UNSPEC), sodass beide Konstanten verwendet werden können.
In der folgenden Tabelle sind allgemeine Werte für die Adressfamilie aufgeführt, obwohl viele andere Werte möglich sind.
ai_socktype
Typ: int
Der Sockettyp. Mögliche Werte für den Sockettyp sind in der Winsock2.h-Headerdatei definiert.
In der folgenden Tabelle sind die möglichen Werte für den für Windows Sockets 2 unterstützten Sockettyp aufgeführt:
| Wert | Bedeutung |
|---|---|
|
Stellt sequenzierte, zuverlässige, bidirektionale, verbindungsbasierte Bytedatenströme mit einem OOB-Datenübertragungsmechanismus bereit. Verwendet tcp (Transmission Control Protocol) für die Internetadressenfamilie (AF_INET oder AF_INET6). Wenn der ai_family-MemberAF_IRDA ist, ist SOCK_STREAM der einzige unterstützte Sockettyp. |
|
Unterstützt Datagramme, bei denen es sich um verbindungslose, unzuverlässige Puffer mit fester (in der Regel kleiner) maximaler Länge handelt. Verwendet das User Datagram Protocol (UDP) für die Internetadressenfamilie (AF_INET oder AF_INET6). |
|
Stellt einen unformatierten Socket bereit, mit dem eine Anwendung den nächsten Protokollheader der oberen Ebene bearbeiten kann. Um den IPv4-Header zu bearbeiten, muss die Option IP_HDRINCL Socket für den Socket festgelegt werden. Um den IPv6-Header zu bearbeiten, muss die Option IPV6_HDRINCL Socket für den Socket festgelegt werden. |
|
Stellt ein zuverlässiges Nachrichten-Datagramm bereit. Ein Beispiel für diesen Typ ist die PGM-Multicastprotokollimplementierung (Pragmatic General Multicast) in Windows, die häufig als zuverlässige Multicastprogrammierung bezeichnet wird. |
|
Stellt ein Pseudostreampaket basierend auf Datagrammen bereit. |
In Windows Sockets 2 wurden neue Sockettypen eingeführt. Eine Anwendung kann die Attribute jedes verfügbaren Transportprotokolls mithilfe der WSAEnumProtocols-Funktion dynamisch ermitteln. Daher kann eine Anwendung die möglichen Sockettyp- und Protokolloptionen für eine Adressfamilie ermitteln und diese Informationen beim Angeben dieses Parameters verwenden. Sockettypdefinitionen in den Headerdateien Winsock2.h und Ws2def.h werden regelmäßig aktualisiert, wenn neue Sockettypen, Adressfamilien und Protokolle definiert werden.
In Windows Sockets 1.1 sind die einzigen möglichen Sockettypen SOCK_DATAGRAM und SOCK_STREAM.
ai_protocol
Typ: int
Der Protokolltyp. Die möglichen Optionen sind spezifisch für die angegebene Adressfamilie und den angegebenen Sockettyp. Mögliche Werte für die ai_protocol sind in den Headerdateien Winsock2.h und Wsrm.h definiert.
Auf der für Windows Vista und höher veröffentlichten Windows SDK wurde die organization der Headerdateien geändert, und dieser Member kann einer der Werte des IPPROTO-Enumerationstyps sein, der in der Ws2def.h-Headerdatei definiert ist. Beachten Sie, dass die Ws2def.h-Headerdatei automatisch in Winsock2.h enthalten ist und niemals direkt verwendet werden sollte.
Wenn für ai_protocol der Wert 0 angegeben wird, möchte der Aufrufer kein Protokoll angeben, und der Dienstanbieter wählt die zu verwendende ai_protocol aus. Legen Sie für andere Protokolle als IPv4 und IPv6 ai_protocol auf Null fest.
In der folgenden Tabelle sind allgemeine Werte für den ai_protocol-Member aufgeführt, obwohl viele andere Werte möglich sind.
Wenn das ai_family-ElementAF_IRDA ist, muss die ai_protocol 0 sein.
ai_addrlen
Typ: size_t
Die Länge des Puffers in Bytes, auf den der ai_addr-Member verweist.
ai_canonname
Typ: char*
Der kanonische Name für den Host.
ai_addr
Typ: struct sockaddr*
Ein Zeiger auf eine sockaddr-Struktur . Der ai_addr-Member in jeder zurückgegebenen addrinfo-Struktur verweist auf eine ausgefüllte Socketadressstruktur. Die Länge jeder zurückgegebenen addrinfo-Struktur in Bytes wird im ai_addrlen-Member angegeben.
ai_next
Typ: struct addrinfo*
Ein Zeiger auf die nächste Struktur in einer verknüpften Liste. Dieser Parameter wird in der letzten addrinfo-Struktur einer verknüpften Liste auf NULL festgelegt.
Hinweise
Die addrinfo-Struktur wird von der ANSI-Funktion getaddrinfo verwendet, um Hostadresseninformationen zu enthalten.
Die addrinfoW-Struktur ist die Version dieser Struktur, die von der Unicode-Funktion GetAddrInfoW verwendet wird.
Makros in der Ws2tcpip.h-Headerdatei definieren eine ADDRINFOT-Struktur und einen Funktionsnamen mit gemischter Groß-/Kleinschreibung getAddrInfo. Die GetAddrInfo-Funktion sollte mit den Parametern nodename und servname eines Zeigers vom Typ TCHAR und den Hinweisen und res-Parametern eines Zeigers vom Typ ADDRINFOT aufgerufen werden. Wenn UNICODE oder _UNICODE nicht definiert ist, wird ADDRINFOT für die addrinfo-Struktur und GetAddrInfo für getaddrinfo, die ANSI-Version dieser Funktion, definiert. Wenn UNICODE oder _UNICODE definiert ist, wird ADDRINFOT für die addrinfoW-Struktur und GetAddrInfo für GetAddrInfoW, die Unicode-Version dieser Funktion, definiert.
Nach einem erfolgreichen Aufruf von getaddrinfo wird im res-Parameter, der an die getaddrinfo-Funktion übergeben wird, 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 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.
Unterstützung für getaddrinfo und die addrinfo-Struktur in älteren Versionen von Windows
Die getaddrinfo-Funktion , die die addrinfo-Struktur verwendet, wurde der Ws2_32.dll unter Windows XP und höher hinzugefügt. Die addrinfo-Struktur ist in der Ws2tcpip.h-Headerdatei definiert, die im Platform SDK enthalten ist, das für Windows XP und höher veröffentlicht wurde, sowie in der für Windows Vista und höher veröffentlichten Windows SDK.Um eine Anwendung auszuführen, die die getaddrinfo-Funktion und die addrinfo-Struktur unter früheren Versionen von Windows (Windows 2000) verwendet, müssen Sie die Dateien Ws2tcpip.h und Wspiapi.h einschließen. Wenn die Includedatei Wspiapi.h hinzugefügt wird, wird die getaddrinfo-Funktion für die Inlinefunktion WspiapiGetAddrInfo in der Datei Wspiapi.h definiert. Zur Laufzeit ist die WspiapiGetAddrInfo-Funktion so implementiert, dass, wenn die Ws2_32.dll oder die Wship6.dll (die Datei, die getaddrinfo in der IPv6-Technologievorschau für Windows 2000 enthält) nicht getaddrinfo enthält, eine Getaddrinfo-Version basierend auf Code in der Headerdatei Wspiapi.h inline 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 IPv6 Technology Preview für Windows 2000 installiert ist. Andernfalls ist die getaddrinfo-Unterstützung unter Windows-Versionen vor Windows XP auf die Behandlung der IPv4-Namensauflösung beschränkt.
Die GetAddrInfoW-Funktion , die die addrinfoW-Struktur verwendet, ist die Unicode-Version der getaddrinfo-Funktion und der zugeordneten addrinfo-Struktur . Die GetAddrInfoW-Funktion wurde dem Ws2_32.dll in Windows XP mit Service Pack 2 (SP2) hinzugefügt. Die GetAddrInfoW-Funktion und die addrinfoW-Struktur können nicht unter Versionen von Windows vor Windows XP mit SP2 verwendet werden.
Beispiele
Im folgenden Codebeispiel wird die Verwendung der addrinfo-Struktur 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(" 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;
}
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Kopfzeile | ws2def.h |