ADDRINFOEXW-Struktur (ws2def.h)
Die addrinfoex- Struktur wird von der GetAddrInfoEx--Funktion verwendet, um Hostadresseninformationen zu enthalten.
Syntax
typedef struct addrinfoexW {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
PWSTR ai_canonname;
struct sockaddr *ai_addr;
void *ai_blob;
size_t ai_bloblen;
LPGUID ai_provider;
struct addrinfoexW *ai_next;
} ADDRINFOEXW, *PADDRINFOEXW, *LPADDRINFOEXW;
Angehörige
ai_flags
Typ: int
Flags, die Optionen angeben, die in der GetAddrInfoEx--Funktion verwendet werden.
Unterstützte Werte für das ai_flags-Element werden in der Winsock2.h enthaltene Datei definiert und können eine Kombination der folgenden Optionen sein.
| Wert | Bedeutung |
|---|---|
|
Die Socketadresse wird in einem Aufruf der Bindung Funktion verwendet. |
|
Der kanonische Name wird im ersten ai_canonname-Element zurückgegeben.
Wenn sowohl die bits AI_CANONNAME als auch AI_FQDN festgelegt werden, wird keine addrinfoex2- Struktur zurückgegeben, nicht die addrinfoex- Struktur. |
|
Der Knotenname Parameter, der an die GetAddrInfoEx- 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_V4MAPPEDgestellt.
Diese Option wird unter Windows Vista und höher unterstützt. |
|
Die GetAddrInfoEx- wird nur aufgelöst, wenn eine globale Adresse konfiguriert ist. Die IPv6- und IPv4-Loopbackadresse gilt nicht als gültige globale Adresse.
Diese Option wird nur unter Windows Vista und höher unterstützt. |
|
Wenn die GetAddrInfoEx- 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.
Diese Option wird unter Windows Vista und höher unterstützt. |
|
Die Adressinformationen stammen aus nicht autoritativen Ergebnissen.
Wenn diese Option im pHints Parameter von GetAddrInfoExfestgelegt wird, gibt der NS_EMAIL Namespaceanbieter sowohl autorisierende als auch nicht autorisierende Ergebnisse zurück. Wenn diese Option nicht festgelegt ist, werden nur autorisierende Ergebnisse zurückgegeben. In den ppResults Parameter, der von GetAddrInfoExzurückgegeben wird, wird dieses Flag im ai_flags Member der addrinfoex Struktur für nicht autorisierende Ergebnisse festgelegt. 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. Wenn das AI_SECURE Bit festgelegt ist, gibt der NS_EMAIL Namespaceanbieter Ergebnisse zurück, die mit verbesserter Sicherheit abgerufen wurden, um mögliche Spoofing zu minimieren.
Wenn diese Option im pHints Parameter von GetAddrInfoExfestgelegt wird, gibt der NS_EMAIL Namespaceanbieter nur Ergebnisse zurück, die mit erweiterter Sicherheit abgerufen wurden, um mögliche Spoofing zu minimieren. In dem ppResults Parameter, der von GetAddrInfoExzurückgegeben wird, wird dieses Flag im ai_flags Member der addrinfoex Struktur für Ergebnisse festgelegt, die mit verbesserter Sicherheit zurückgegeben werden, um mögliche Spoofing zu minimieren. Diese Option wird nur unter Windows Vista und höher für den NS_EMAIL Namespace unterstützt. |
|
Die Adressinformationen beziehen sich auf bevorzugte Namen für die Publikation mit einem bestimmten Namespace.
Wenn diese Option im pHints Parameter von GetAddrInfoExfestgelegt wird, sollte kein Name im pName--Parameter angegeben werden, und der NS_EMAIL Namespaceanbieter gibt bevorzugte Namen für die Publikation zurück. Im ppResults Parameter, der von GetAddrInfoExzurückgegeben wird, wird dieses Flag im ai_flags Element der addrinfoex Struktur für Ergebnisse festgelegt, die für bevorzugte Namen für die Publikation zurückgegeben werden. Diese Option wird nur unter Windows Vista und höher für den NS_EMAIL Namespace unterstützt. |
|
Der vollqualifizierte Domänenname wird im ersten ai_canonicalname Mitglied zurückgegeben.
Wenn diese Option im pHints Parameter von GetAddrInfoEx und im pName Parameter ein Flachname (einzelne Bezeichnung) angegeben wird, wird der vollqualifizierte Domänenname zurückgegeben, zu dem der Name schließlich aufgelöst wird. Wenn sowohl die bits AI_CANONNAME als auch AI_FQDN festgelegt werden, wird keine addrinfoex2- Struktur zurückgegeben, nicht die addrinfoex- Struktur. Diese Option wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt. |
|
Ein Hinweis auf den Namespaceanbieter, der abgefragt wird, wird in einem Dateifreigabeszenario verwendet. Dieser Hinweis kann vom Namespaceanbieter ignoriert werden.
Diese Option wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt. |
|
Deaktivieren Sie die automatische Codierung des internationalen Domänennamens mithilfe von Punycode in den Namensauflösungsfunktionen, die von der GetAddrInfoEx--Funktion aufgerufen werden.
Diese Option wird unter Windows 8, Windows Server 2012 und höher unterstützt. |
ai_family
Typ: int
Die Adressfamilie. Mögliche Werte für die Adressfamilie sind in der Winsock2.h enthaltene Datei definiert.
Im windows SDK, das für Windows Vista und höher veröffentlicht wurde, wurde die Organisation von Headerdateien geändert, und die möglichen Werte für die Adressfamilie werden in der Ws2def.h Headerdatei definiert. Beachten Sie, dass die Ws2def.h Headerdatei automatisch in Winsock2.henthalten ist und niemals direkt verwendet werden sollte.
Die derzeit unterstützten Werte werden AF_INET oder AF_INET6, die internetadressfamilienformate für IPv4 und IPv6 sind. Andere Optionen für 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 werden in der Winsock2.h enthaltene Datei 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 Bytestreams mit einem OOB-Datenübertragungsmechanismus bereit. Verwendet das Transmission Control Protocol (TCP) für die Internetadressenfamilie (AF_INET oder AF_INET6). Wenn das ai_family Mitglied AF_IRDAist, ist SOCK_STREAM der einzige unterstützte Sockettyp. |
|
Unterstützt Datagramme, die verbindungslose, unzuverlässige Puffer einer festen (normalerweise kleinen) maximalen Länge sind. Verwendet das User Datagram Protocol (UDP) für die Internetadressenfamilie (AF_INET oder AF_INET6). |
|
Stellt einen unformatierten Socket bereit, der es einer Anwendung ermöglicht, den nächsten Protokollheader der oberen Ebene zu bearbeiten. Um den IPv4-Header zu bearbeiten, muss die IP_HDRINCL Socketoption für den Socket festgelegt werden. Um den IPv6-Header zu bearbeiten, muss die IPV6_HDRINCL Socketoption für den Socket festgelegt werden. |
|
Stellt ein zuverlässiges Nachrichtendatendiagramm bereit. Ein Beispiel für diesen Typ ist die Pragmatische Multicast-Multicast(PGM)-Multicastprotokollimplementierung in Windows, die häufig als zuverlässige Multicastprogrammierungbezeichnet wird. |
|
Stellt ein Pseudodatenstrompaket basierend auf Datagrammen bereit. |
In Windows Sockets 2 wurden neue Sockettypen eingeführt. Eine Anwendung kann die Attribute jedes verfügbaren Transportprotokolls dynamisch über die WSAEnumProtocols-Funktion ermitteln. Daher kann eine Anwendung die möglichen Sockettyp- und Protokolloptionen für eine Adressfamilie bestimmen und diese Informationen verwenden, wenn Sie diesen Parameter angeben. Sockettypdefinitionen in der Winsock2.h und Ws2def.h Headerdateien werden regelmäßig aktualisiert, wenn neue Sockettypen, Adressfamilien und Protokolle definiert sind.
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 werden in Winsock2.h und den Wsrm.h Headerdateien definiert.
Im windows SDK, das für Windows Vista und höher veröffentlicht wurde, hat sich die Organisation von Headerdateien geändert, und dieses Mitglied kann einer der Werte aus dem IPPROTO- Enumerationstyp sein, der in der Ws2def.h Headerdatei definiert ist. Beachten Sie, dass die Ws2def.h Headerdatei automatisch in Winsock2.henthalten ist und niemals direkt verwendet werden sollte.
Wenn für ai_protocolein Wert von 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 das ai_protocol-Element aufgeführt, obwohl viele andere Werte möglich sind.
Wenn das ai_family Mitglied AF_IRDAist, muss die ai_protocol 0 sein.
ai_addrlen
Typ: size_t
Die Länge des Puffers in Byte, auf den das ai_addr-Element verweist.
ai_canonname
Typ: PCTSTR-
Der kanonische Name für den Host.
ai_addr
Typ: struktur sockaddr*
Ein Zeiger auf eine sockaddr- Struktur. Der ai_addr Member in jedem zurückgegebenen addrinfoex- Struktur verweist auf eine gefüllte Socketadressenstruktur. Die Länge jedes zurückgegebenen addrinfoex- Struktur in Byte wird im ai_addrlen-Element angegeben.
ai_blob
Typ: void*
Ein Zeiger auf Daten, die verwendet werden, um anbieterspezifische Namespaceinformationen zurückzugeben, die dem Namen über eine Liste von Adressen hinaus zugeordnet sind. Die Länge des puffers, auf den ai_blob verweist, muss im ai_bloblen-Element angegeben werden.
ai_bloblen
Typ: size_t
Die Länge des ai_blob Elements in Byte.
ai_provider
Typ: LPGUID-
Ein Zeiger auf die GUID eines bestimmten Namespaceanbieters.
ai_next
Typ: struktur addrinfoex*
Ein Zeiger auf die nächste Struktur in einer verknüpften Liste. Dieser Parameter wird auf NULL- in der letzten addrinfoex- Struktur einer verknüpften Liste festgelegt.
Bemerkungen
Die addrinfoex- Struktur wird von der GetAddrInfoEx--Funktion verwendet, um Hostadresseninformationen zu enthalten. Die addrinfoex--Struktur ist eine verbesserte Version der addrinfo und addrinfoW- Strukturen. Die zusätzlichen Strukturmber sind für BLOB-Daten und die GUID für den Namespaceanbieter vorgesehen. Die BLOB-Daten werden verwendet, um zusätzliche anbieterspezifische Namespaceinformationen zurückzugeben, die einem Namen zugeordnet sind. Das Format der Daten im ai_blob-Member ist spezifisch für einen bestimmten Namespaceanbieter. Derzeit werden BLOB-Daten vom NS_EMAIL Namespaceanbieter verwendet, um zusätzliche Informationen zu liefern.
Die addrinfoex-Struktur ist eine erweiterte Version der addrinfo und addrinfoW- Struktur, die mit GetAddrInfoEx--Funktion verwendet wird. Die GetAddrInfoEx--Funktion ermöglicht die Angabe des Namespaceanbieters zum Auflösen der Abfrage. Für die Verwendung mit dem IPv6- und IPv4-Protokoll kann die Namensauflösung durch das Domain Name System (DNS), eine lokale Hosts Datei, einen E-Mail-Anbieter (den NS_EMAIL Namespace) oder durch andere Benennungsmechanismen erfolgen.
Wenn UNICODE oder _UNICODE definiert ist, wird addrinfoex für addrinfoexWdefiniert, die Unicode-Version dieser Struktur. Die Zeichenfolgenparameter werden für den PWSTR Datentyp definiert, und die addrinfoexW Struktur wird verwendet.
Wenn UNICODE oder _UNICODE nicht definiert ist, wird addrinfoex für addrinfoexAdefiniert, die ANSI-Version dieser Struktur. Die Zeichenfolgenparameter sind vom datentyp PCSTR und die addrinfoexA Struktur verwendet wird.
Bei einem erfolgreichen Aufruf von GetAddrInfoExwird eine verknüpfte Liste der addrinfoex Strukturen im ppResult-Parameter zurückgegeben, der an die GetAddrInfoEx--Funktion übergeben wird. Die Liste kann verarbeitet werden, indem sie dem im ai_next Member jedes zurückgegebenen addrinfoex- Struktur folgt, bis ein NULL- Zeiger gefunden wird. In jeder zurückgegebenen addrinfoex--Struktur entsprechen die ai_family, ai_socktypeund ai_protocol Member den entsprechenden Argumenten in einem Socket oder WSASocket Funktionsaufruf. Außerdem verweist das ai_addr Element in jedem zurückgegebenen addrinfoex Struktur auf eine gefüllte Socketadressenstruktur, deren Länge in seinem ai_addrlen Element angegeben wird.
Beispiele
Das folgende Beispiel veranschaulicht die Verwendung der addrinfoex- Struktur.
#ifndef UNICODE
#define UNICODE
#endif
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#pragma comment(lib, "Ws2_32.lib")
int __cdecl wmain(int argc, wchar_t ** argv)
{
//--------------------------------
// Declare and initialize variables.
WSADATA wsaData;
int iResult;
ADDRINFOEX *result = NULL;
ADDRINFOEX *ptr = NULL;
ADDRINFOEX hints;
DWORD dwRetval = 0;
int i = 1;
DWORD dwNamespace = NS_DNS;
LPGUID lpNspid = NULL;
struct sockaddr_in *sockaddr_ipv4;
struct sockaddr_in6 *sockaddr_ipv6;
// LPSOCKADDR sockaddr_ip;
wchar_t ipstringbuffer[46];
// Validate the parameters
if (argc != 3) {
wprintf(L"usage: %ws <hostname> <servicename>\n", argv[0]);
wprintf(L" 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\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 GetAddrInfoW() function
memset(&hints, 0, sizeof (hints));
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
wprintf(L"Calling GetAddrInfoEx with following parameters:\n");
wprintf(L"\tName = %ws\n", argv[1]);
wprintf(L"\tServiceName (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call GetAddrInfoEx(). If the call succeeds,
// the aiList variable will hold a linked list
// of ADDRINFOEX structures containing response
// information about the host
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);
}
FreeAddrInfoEx(result);
WSACleanup();
return 0;
}
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows Vista [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2008 [Nur Desktop-Apps] |
| Header- | ws2def.h (enthalten Windows Server 2012, Windows 7 Windows Server 2008 R2) |