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.
| Fehlerwert | WSA-Entsprechung | BESCHREIBUNG |
|---|---|---|
| EAI_AGAIN | WSATRY_AGAIN | Es ist ein temporärer Fehler bei der Namensauflösung aufgetreten. |
| EAI_BADFLAGS | WSAEINVAL | Mindestens ein ungültiger Parameter wurde an die GetNameInfoW-Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn ein Hostname angefordert wurde, aber der NodeBufferSize-Parameter 0 war oder wenn ein Dienstname angefordert wurde, der ServiceBufferSize-Parameter jedoch 0 war. |
| EAI_FAIL | WSANO_RECOVERY | Es ist ein nicht wiederherstellbarer Fehler bei der Namensauflösung aufgetreten. |
| EAI_FAMILY | WSAEAFNOSUPPORT | Das sa_family Member der Socketadressstruktur, auf das der pSockaddr-Parameter verweist, wird nicht unterstützt. |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | Ein Fehler bei der Speicherzuordnung ist aufgetreten. |
| EAI_NONAME | WSAHOST_NOT_FOUND | Ein Dienstname wurde angefordert, aber es wurde keine Portnummer in der Struktur gefunden, auf die der pSockaddr-Parameter verweist, oder es wurde kein Dienstname gefunden, der der Portnummer entspricht. NI_NAMEREQD festgelegt ist und der Name des Hosts nicht gefunden werden kann, oder die Parameter pNodeBuffer und pServiceBuffer waren NULL. |
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.
| Fehlercode | Bedeutung |
|---|---|
| Dieser Fehler wird zurückgegeben, wenn der pSockaddr-ParameterNULL oder der SockaddrLength-Parameter kleiner als die Länge ist, die für die Größe sockaddr_in Struktur für IPv4 oder die sockaddr_in6-Struktur für IPv6 erforderlich ist. |
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
Im folgenden Beispiel wird die Verwendung der GetNameInfoW-Funktion veranschaulicht.#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;
}
}
Hinweis
Der ws2tcpip.h-Header definiert GetNameInfo als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
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 |