GetNameInfoW-Funktion (ws2tcpip.h)

Die GetNameInfoW-Funktion bietet eine protokollunabhängige Namensauflösung von einer Adresse zu einem Unicode-Hostnamen und von einer Portnummer zum Unicode-Dienstnamen.

Syntax

INT WSAAPI GetNameInfoW(
  [in]  const SOCKADDR *pSockaddr,
  [in]  socklen_t      SockaddrLength,
  [out] PWCHAR         pNodeBuffer,
  [in]  DWORD          NodeBufferSize,
  [out] PWCHAR         pServiceBuffer,
  [in]  DWORD          ServiceBufferSize,
  [in]  INT            Flags
);

Parameter

[in] pSockaddr

Ein Zeiger auf eine Socketadressstruktur, die die IP-Adresse und die Portnummer des Sockets enthält. Für IPv4 verweist der pSockaddr-Parameter auf eine sockaddr_in-Struktur . Für IPv6 zeigt der pSockaddr-Parameter auf eine sockaddr_in6-Struktur .

[in] SockaddrLength

Die Länge der Struktur in Bytes, auf die der pSockaddr-Parameter verweist.

[out] pNodeBuffer

Ein Zeiger auf eine Unicode-Zeichenfolge, die den Hostnamen enthält. Bei Erfolg wird standardmäßig ein Zeiger auf den Unicode-Hostnamen als vollqualifizierter Domänenname (Fully Qualified Domain Name, FQDN) zurückgegeben. Wenn der pNodeBuffer-ParameterNULL ist, gibt dies an, dass der Aufrufer keine Hostnamenzeichenfolge empfangen möchte.

[in] NodeBufferSize

Die Anzahl der WCHAR-Zeichen im Puffer, auf die der pNodeBuffer-Parameter verweist. Der Aufrufer muss einen Puffer bereitstellen, der groß genug ist, um den Unicode-Hostnamen zu enthalten, einschließlich des beendenden NULL-Zeichens.

[out] pServiceBuffer

Ein Zeiger auf eine Unicode-Zeichenfolge, die den Dienstnamen enthält. Bei Erfolg wird ein Zeiger auf eine Unicode-Zeichenfolge zurückgegeben, die den Dienstnamen darstellt, der der Portnummer zugeordnet ist. Wenn der pServiceBuffer-ParameterNULL ist, gibt dies an, dass der Aufrufer keine Dienstnamenzeichenfolge empfangen möchte.

[in] ServiceBufferSize

Die Anzahl der WCHAR-Zeichen im Puffer, auf die der pServiceBuffer-Parameter verweist. Der Aufrufer muss einen Puffer bereitstellen, der groß genug ist, um den Unicode-Dienstnamen zu enthalten, einschließlich des beendenden NULL-Zeichens.

[in] Flags

Ein Wert, der zum Anpassen der Verarbeitung der GetNameInfoW-Funktion verwendet wird. Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.

Rückgabewert

Bei Erfolg gibt GetNameInfoW null zurück. Jeder nichtzero-Rückgabewert gibt einen Fehler an, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Nichtzero-Fehlercodes, die von der GetNameInfoW-Funktion zurückgegeben werden, werden auch dem Satz von Fehlern zugeordnet, die von den 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.

Sie können die gai_strerror-Funktion verwenden, um Fehlermeldungen basierend auf den von der GetNameInfoW-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.

Darüber hinaus können die folgenden Fehlercodes zurückgegeben werden.

Hinweise

Die GetNameInfoW-Funktion ist die Unicode-Version einer Funktion, die eine protokollunabhängige Namensauflösung bereitstellt. Die GetNameInfoW-Funktion wird verwendet, um den Inhalt einer Socketadressstruktur in einen Knotennamen und/oder einen Dienstnamen zu übersetzen.

Für die Protokolle IPv6 und IPv4 kann die Namensauflösung durch das Domain Name System (DNS), eine lokale Hostdatei oder durch andere Benennungsmechanismen erfolgen. Diese Funktion kann verwendet werden, um den Hostnamen für eine IPv4- oder IPv6-Adresse, eine Reverse-DNS-Suche oder den Dienstnamen für eine Portnummer zu bestimmen. Die GetNameInfoW-Funktion kann auch verwendet werden, um eine IP-Adresse oder eine Portnummer in einer SOCKADDR-Struktur in eine Unicode-Zeichenfolge zu konvertieren. Diese Funktion kann auch verwendet werden, um die IP-Adresse für einen Hostnamen zu bestimmen.

Die ANSI-Version dieser Funktion ist getnameinfo.

Makros in der Winsock-Headerdatei definieren einen gemischten Funktionsnamen getNameInfo , der verwendet werden kann, wenn die Anwendung für Windows XP mit Service Pack 2 (SP2) und höher (_WIN32_WINNT >= 0x0502) verwendet werden kann. Diese GetNameInfo-Funktion sollte mit den Parametern pNodeBuffer und pServiceBuffer eines Zeigers vom Typ TCHAR aufgerufen werden. Wenn UNICODE oder _UNICODE definiert ist, wird GetNameInfo für die Unicode-Version definiert, und GetNameInfoW wird mit den Host - und serv-Parametern eines Zeigers vom Typ char aufgerufen. Wenn UNICODE oder _UNICODE nicht definiert ist, wird GetNameInfo für die ANSI-Version definiert, und getnameinfo wird mit den Parametern pNodeBuffer und pServiceBuffer eines Zeigers vom Typ PWCHAR aufgerufen.

Um die Ermittlung der Pufferanforderungen für die Parameter pNodeBuffer und pServiceBuffer zu vereinfachen, werden die folgenden Werte für die maximale Hostnamenlänge und den maximalen Dienstnamen in der Ws2tcpip.h-Headerdatei definiert:

#include <windows.h>

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

Der Flags-Parameter kann verwendet werden, um die Verarbeitung der GetNameInfoW-Funktion anzupassen. Die folgenden Flags sind verfügbar:

• NI_NOFQDN
• NI_NUMERICHOST
• NI_NAMEREQD
• NI_NUMERICSERV
• NI_DGRAM

Wenn das flag NI_NAMEREQD festgelegt ist, führt ein Hostname, der nicht vom DNS aufgelöst werden kann, zu einem Fehler.

Das Festlegen des NI_NOFQDN-Flags führt dazu, dass lokale Hosts nur ihren relativen distinguished Name (RDN) im pNodeBuffer-Parameter zurückgegeben haben.

Das Festlegen des NI_NUMERICHOST-Flags gibt die numerische Form des Hostnamens anstelle des Namens zurück. Die numerische Form des Hostnamens wird auch zurückgegeben, wenn der Hostname nicht durch DNS aufgelöst werden kann.

Durch Festlegen des NI_NUMERICSERV-Flags wird die Portnummer des Diensts anstelle des Namens zurückgegeben. Wenn für eine IP-Adresse (z. B. 127.0.0.2) kein Hostname gefunden wird, wird der Hostname als IP-Adresse zurückgegeben.

Wenn unter Windows Vista und höher NI_NUMERICSERV im Flags-Parameter nicht angegeben ist und die portnummer in der sockaddr-Struktur , auf die vom sa-Parameter verwiesen wird, nicht in einen bekannten Dienst aufgelöst wird, gibt die GetNameInfoW-Funktion die numerische Form der Dienstadresse (die Portnummer) als numerische Zeichenfolge zurück. Wenn NI_NUMERICSERV angegeben wird, wird die Portnummer als numerische Zeichenfolge zurückgegeben. Dieses Verhalten wird in Abschnitt 6.2 von RFC 3493 angegeben. Weitere Informationen finden Sie unter www.ietf.org/rfc/rfc3493.txt

Wenn unter Windows Server 2003 und früher NI_NUMERICSERV nicht im Flags-Parameter angegeben ist und die portnummer in der sockaddr-Struktur, auf die vom sa-Parameter verwiesen wird, nicht in einen bekannten Dienst aufgelöst wird, schlägt die GetNameInfoW-Funktion fehl. Wenn NI_NUMERICSERV angegeben wird, wird die Portnummer als numerische Zeichenfolge zurückgegeben.

Das Festlegen des NI_DGRAM-Flags gibt an, dass es sich bei dem Dienst um einen Datagrammdienst handelt. Dieses Flag ist für die wenigen Dienste erforderlich, die unterschiedliche Portnummern für UDP und TCP-Dienst bereitstellen.

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.

Beispielcode

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

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

    struct sockaddr_in saGNI;
    WCHAR hostname[NI_MAXHOST];
    WCHAR servInfo[NI_MAXSERV];
    u_short port = 27015;

    // Validate the parameters
    if (argc != 2) {
        wprintf(L"usage: %s IPv4 address\n", argv[0]);
        wprintf(L"  to return hostname\n");
        wprintf(L"       %s 127.0.0.1\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;
    }
    //-----------------------------------------
    // Set up sockaddr_in structure which is passed
    // to the getnameinfo function
    saGNI.sin_family = AF_INET;
    saGNI.sin_addr.s_addr = inet_addr(argv[1]);
    saGNI.sin_port = htons(port);

    //-----------------------------------------
    // Call GetNameInfoW
    dwRetval = GetNameInfoW((struct sockaddr *) &saGNI,
                           sizeof (struct sockaddr),
                           hostname,
                           NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);

    if (dwRetval != 0) {
        wprintf(L"GetNameInfoW failed with error # %ld\n", WSAGetLastError());
        return 1;
    } else {
        wprintf(L"GetNameInfoW returned hostname = %ws\n", hostname);
        return 0;
    }
}

Anforderungen

Weitere Informationen

GetAddrInfoW

WSAGetLastError

Winsock-Funktionen

Winsock-Referenz

gai_strerror

getaddrinfo

getnameinfo

sockaddr