Freigeben über


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;

Member

ai_flags

Typ: int

Flags, die optionen angeben, die in der GetAddrInfoEx-Funktion verwendet werden.

Unterstützte Werte für das ai_flags-Member werden in der Winsock2.h-Includedatei definiert und können eine Kombination aus den folgenden Optionen sein.

Wert Bedeutung
AI_PASSIVE
0x01
Die Socketadresse wird in einem Aufruf der Bindungsfunktion verwendet.
AI_CANONNAME
0x02
Der kanonische Name wird im ersten ai_canonname Member zurückgegeben.

Wenn sowohl die AI_CANONNAME - als auch AI_FQDN-Bits festgelegt sind, wird eine addrinfoex2-Struktur zurückgegeben, nicht die addrinfoex-Struktur .

AI_NUMERICHOST
0x04
Der knotenname-Parameter , der an die GetAddrInfoEx-Funktion übergeben wird, muss eine numerische Zeichenfolge sein.
AI_ALL
0x0100
Wenn dieses Bit festgelegt ist, wird eine Anforderung für IPv6-Adressen und IPv4-Adressen mit AI_V4MAPPED gestellt.

Diese Option wird unter Windows Vista und höher unterstützt.

AI_ADDRCONFIG
0x0400
GetAddrInfoEx 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 nur unter Windows Vista und höher unterstützt.

AI_V4MAPPED
0x0800
Wenn bei der GetAddrInfoEx-Anforderung für eine IPv6-Adresse ein Fehler auftritt, wird eine Namensdienstanforderung für IPv4-Adressen erstellt, und diese Adressen werden in das IPv4-Adressformat konvertiert.

Diese Option wird unter Windows Vista und höher unterstützt.

AI_NON_AUTHORITATIVE
0x04000
Die Adressinformationen stammen aus nicht autorisierenden Ergebnissen.

Wenn diese Option im pHints-Parameter von GetAddrInfoEx festgelegt ist, 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.

Im von GetAddrInfoExzurückgegebenen ppResults-Parameter 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.

AI_SECURE
0x08000
Die Adressinformationen stammen aus einem sicheren Kanal. 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.

Wenn diese Option im pHints-Parameter von GetAddrInfoEx festgelegt ist, gibt der NS_EMAIL-Namespaceanbieter nur Ergebnisse zurück, die mit erhöhter Sicherheit abgerufen wurden, um mögliche Spoofing zu minimieren.

Im von GetAddrInfoExzurückgegebenen ppResults-Parameter wird dieses Flag im ai_flags Member der addrinfoex-Struktur für Ergebnisse festgelegt, die mit erhöhter Sicherheit zurückgegeben werden, um mögliche Spoofings zu minimieren.

Diese Option wird nur unter Windows Vista und höher für den NS_EMAIL-Namespace unterstützt.

AI_RETURN_PREFERRED_NAMES
0x010000
Die Adressinformationen gelten für einen bevorzugten Namen für die Veröffentlichung mit einem bestimmten Namespace.

Wenn diese Option im pHints-Parameter von GetAddrInfoEx festgelegt ist, sollte kein Name im pName-Parameter angegeben werden, und der NS_EMAIL Namespaceanbieter gibt bevorzugte Namen für die Veröffentlichung zurück.

Im von GetAddrInfoExzurückgegebenen ppResults-Parameter wird dieses Flag im ai_flags Member der addrinfoex-Struktur für Ergebnisse festgelegt, die für bevorzugte Namen für die Veröffentlichung zurückgegeben werden.

Diese Option wird nur unter Windows Vista und höher für den NS_EMAIL-Namespace unterstützt.

AI_FQDN
0x00020000
Der vollqualifizierte Domänenname wird im ersten ai_canonicalname Member zurückgegeben.

Wenn diese Option im pHints-Parameter von GetAddrInfoEx festgelegt ist und im pName-Parameter ein flacher Name (einzelne Bezeichnung) angegeben wird, wird der vollqualifizierte Domänenname zurückgegeben, in den der Name schließlich aufgelöst wurde.

Wenn sowohl die AI_CANONNAME - als auch AI_FQDN-Bits festgelegt sind, wird eine addrinfoex2-Struktur zurückgegeben, nicht die addrinfoex-Struktur .

Diese Option wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt.

AI_FILESERVER
0x00040000
Ein Hinweis an den Namespaceanbieter, dass der abgefragte Hostname in einem Dateifreigabeszenario verwendet wird. Dieser Hinweis kann vom Namespaceanbieter ignoriert werden.

Diese Option wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt.

AI_DISABLE_IDN_ENCODING
0x00080000
Deaktivieren Sie die automatische internationale Domänennamencodierung mithilfe von Punycode in den Von der GetAddrInfoEx-Funktion aufgerufenen Namensauflösungsfunktionen.

Diese Option wird auf 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 Includedatei Winsock2.h definiert.

Auf der Windows SDK für Windows Vista und höher veröffentlicht, wurde die organization von 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 nie direkt verwendet werden sollte.

Die derzeit unterstützten Werte sind AF_INET oder AF_INET6, d. h. die Internetadressenfamilienformate für IPv4 und IPv6. Andere Optionen für Adressfamilien (AF_NETBIOS für die Verwendung mit NetBIOS) 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.

Wert Bedeutung
AF_UNSPEC
0
Die Adressfamilie ist nicht angegeben.
AF_INET
2
Die IPv4-Adressfamilie (Internet Protocol Version 4).
AF_NETBIOS
17
Die NetBIOS-Adressfamilie. Diese Adressfamilie wird nur unterstützt, wenn ein Windows Sockets-Anbieter für NetBIOS installiert ist.
AF_INET6
23
Die IPv6-Adressfamilie (Internet Protocol Version 6).
AF_IRDA
26
Die IrDA-Adressfamilie (Infrared Data Association). Diese Adressfamilie wird nur unterstützt, wenn auf dem Computer ein Infrarotport und ein Treiber installiert sind.
AF_BTH
32
Die Bluetooth-Adressfamilie. Diese Adressfamilie wird nur unterstützt, wenn unter Windows Server 2003 oder höher ein Bluetooth-Adapter installiert ist.

ai_socktype

Typ: int

Der Sockettyp. Mögliche Werte für den Sockettyp sind in der Includedatei Winsock2.h 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
SOCK_STREAM
1
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.
SOCK_DGRAM
2
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).
SOCK_RAW
3
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.
SOCK_RDM
4
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.
SOCK_SEQPACKET
5
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 Winsock2.h und den Wsrm.h-Headerdateien 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.

Wert Bedeutung
IPPROTO_TCP
6
Das Tcp-Protokoll (Transmission Control Protocol). Dies ist ein möglicher Wert, wenn der ai_family-MemberAF_INET oder AF_INET6 ist und der ai_socktype-Member SOCK_STREAM wird.
IPPROTO_UDP
17
Das User Datagram Protocol (UDP). Dies ist ein möglicher Wert, wenn der ai_family-MemberAF_INET oder AF_INET6 und der TypparameterSOCK_DGRAM ist.
IPPROTO_RM
113
Das PGM-Protokoll für zuverlässiges Multicast. Dies ist ein möglicher Wert, wenn das ai_family-ElementAF_INET und das ai_socktype-Element SOCK_RDM wird. Auf der für Windows Vista und höher veröffentlichten Windows SDK wird dieser Wert auch als IPPROTO_PGM bezeichnet.
 

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: PCTSTR

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 addrinfoex-Struktur verweist auf eine ausgefüllte Socketadressstruktur. Die Länge jeder zurückgegebenen addrinfoex-Struktur in Bytes wird im ai_addrlen-Member angegeben.

ai_blob

Typ: void*

Ein Zeiger auf Daten, der verwendet wird, um anbieterspezifische Namespaceinformationen zurückzugeben, die dem Namen über eine Liste von Adressen hinaus zugeordnet sind. Die Länge des Puffers in Bytes, auf den ai_blob verweist, muss im ai_bloblen-Member angegeben werden.

ai_bloblen

Typ: size_t

Die Länge des ai_blob-Elements in Bytes.

ai_provider

Typ: LPGUID

Ein Zeiger auf die GUID eines bestimmten Namespaceanbieters.

ai_next

Typ: struct addrinfoex*

Ein Zeiger auf die nächste Struktur in einer verknüpften Liste. Dieser Parameter wird in der letzten addrinfoex-Struktur einer verknüpften Liste auf NULL festgelegt.

Hinweise

Die addrinfoex-Struktur wird von der GetAddrInfoEx-Funktion verwendet, um Hostadresseninformationen zu enthalten. Die addrinfoex-Struktur ist eine erweiterte Version der addrinfo - und addrinfoW-Strukturen . Die zusätzlichen Strukturmember gelten für Blobdaten und die GUID für den Namespaceanbieter. Die Blobdaten 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 Blobdaten vom NS_EMAIL-Namespaceanbieter verwendet, um zusätzliche Informationen zur Verfügung zu stellen.

Die addrinfoex-Struktur ist eine erweiterte Version der addrinfo - und addrinfoW-Struktur , die mit der 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 Hostdatei , einen E-Mail-Anbieter (der NS_EMAIL Namespace) oder durch andere Benennungsmechanismen erfolgen.

Wenn UNICODE oder _UNICODE definiert ist, wird addrinfoex für addrinfoexW, die Unicode-Version dieser Struktur, definiert. 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 addrinfoexA, die ANSI-Version dieser Struktur, definiert. Die Zeichenfolgenparameter sind vom PCSTR-Datentyp , und die addrinfoexA-Struktur wird verwendet.

Nach einem erfolgreichen Aufruf von GetAddrInfoEx wird eine verknüpfte Liste von 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 jeder zurückgegebenen addrinfoex-Struktur angegebenen Zeiger folgen, bis ein NULL-Zeiger gefunden wird. In jeder zurückgegebenen addrinfoex-Struktur entsprechen die member 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 addrinfoex-Struktur auf eine ausgefüllte Socketadressstruktur, deren Länge im ai_addrlen-Member angegeben ist.

Beispiele

Im folgenden Beispiel wird die Verwendung der addrinfoex-Struktur veranschaulicht.


#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;
}


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

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [nur Desktop-Apps]
Kopfzeile ws2def.h (einschließlich Windows Server 2012, Windows 7 Windows Server 2008 R2)

Weitere Informationen

GetAddrInfoEx

addrinfo

addrinfoW