getnameinfo-Funktion (ws2tcpip.h)

  • Artikel

Die getnameinfo-Funktion bietet eine protokollunabhängige Namensauflösung von einer Adresse in einen ANSI-Hostnamen und von einer Portnummer zum ANSI-Dienstnamen.

Syntax

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

Parameter

[in] pSockaddr

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

[in] SockaddrLength

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

[out] pNodeBuffer

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

[in] NodeBufferSize

Die Länge des Puffers in Bytes, auf den der Hostparameter verweist. Der Aufrufer muss einen Puffer bereitstellen, der groß genug ist, um den Hostnamen zu enthalten, einschließlich des abschließenden NULL-Zeichens.

[out] pServiceBuffer

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

[in] ServiceBufferSize

Die Länge des Puffers in Bytes, auf den der serv-Parameter verweist. Der Aufrufer muss einen Puffer bereitstellen, der groß genug ist, um den Dienstnamen zu enthalten, einschließlich des beendenden NULL-Zeichens.

[in] Flags

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

Rückgabewert

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

Fehlercodes ungleich null, die von der getnameinfo-Funktion zurückgegeben werden, werden auch dem Satz von Fehlern zugeordnet, die in 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 winsock-Programmierern vertraute und umfassende Fehlerinformationen bieten.

Fehlerwert WSA-Entsprechung BESCHREIBUNG
EAI_AGAIN WSATRY_AGAIN Es ist ein vorübergehender Fehler bei der Namensauflösung aufgetreten.
EAI_BADFLAGS WSAEINVAL Mindestens ein ungültiger Parameter wurde an die getnameinfo-Funktion übergeben. Dieser Fehler wird zurückgegeben, wenn ein Hostname angefordert wurde, aber der hostlen-Parameter null war, oder wenn ein Dienstname angefordert wurde, der servlen-Parameter jedoch null war.
EAI_FAIL WSANO_RECOVERY Es ist ein nicht behebbarer Fehler bei der Namensauflösung aufgetreten.
EAI_FAMILY WSAEAFNOSUPPORT Der sa_family Member der Socketadressstruktur, auf die der sa-Parameter verweist, wird nicht unterstützt.
EAI_MEMORY WSA_NOT_ENOUGH_MEMORY Ein Speicherbelegungsfehler ist aufgetreten.
EAI_NONAME WSAHOST_NOT_FOUND Ein Dienstname wurde angefordert, aber in der Struktur, auf die der sa-Parameter verweist, wurde keine Portnummer gefunden, oder es wurde kein Dienstname gefunden, der der Portnummer entspricht. NI_NAMEREQD festgelegt ist und der Hostname nicht gefunden werden kann, oder die Parameter host und serv waren NULL.
 

Verwenden Sie die funktion gai_strerror , um Fehlermeldungen basierend auf den EAI-Codes zu drucken, die von der getnameinfo-Funktion zurückgegeben werden. Die funktion gai_strerror wird zur Einhaltung von 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
WSAEFAULT
 Dieser Fehler wird zurückgegeben, wenn der sa-ParameterNULL ist oder der salen-Parameter kleiner als die Länge ist, die für die Größe der sockaddr_in-Struktur für IPv4 oder die sockaddr_in6-Struktur für IPv6 erforderlich ist.

Hinweise

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

Bei IPv6- und IPv4-Protokollen 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 getnameinfo-Funktion kann auch verwendet werden, um eine IP-Adresse oder eine Portnummer in einer sockaddr-Struktur in eine ANSI-Zeichenfolge zu konvertieren. Diese Funktion kann auch verwendet werden, um die IP-Adresse für einen Hostnamen zu bestimmen.

Ein weiterer Name, der für die getnameinfo-Funktion verwendet werden kann, ist GetNameInfoA. Makros in der Ws2tcpip.h-Headerdatei definieren GetNameInfoA zu getnameinfo.

Die Unicode-Version dieser Funktion, die unter Windows XP mit Service Pack 2 (SP2) und höher verfügbar ist, ist GetNameInfoW.

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

Um die Ermittlung der Pufferanforderungen für die Host- und serv-Parameter zu vereinfachen, werden die folgenden Werte für die maximale Länge des Hostnamens und den maximalen Dienstnamen in der Ws2tcpip.h-Headerdatei definiert.

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

Der Flags-Parameter kann verwendet werden, um die Verarbeitung der getnameinfo-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 durch DNS aufgelöst werden kann, zu einem Fehler.

Das Festlegen des NI_NOFQDN-Flags führt dazu, dass für lokale Hosts nur der relative Distinguished Name (RDN) im Hostparameter zurückgegeben wird.

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 der sa-Parameter verweist, nicht in einen bekannten Dienst aufgelöst wird, gibt die getnameinfo-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/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 der sa-Parameter verweist, nicht in einen bekannten Dienst aufgelöst wird, schlägt die getnameinfo-Funktion fehl. Wenn NI_NUMERICSERV angegeben wird, wird die Portnummer als numerische Zeichenfolge zurückgegeben.

Das Festlegen des NI_DGRAM-Flags gibt an, dass der Dienst ein Datagrammdienst ist. Dieses Flag ist für die wenigen Dienste erforderlich, die unterschiedliche Portnummern für UDP und TCP-Dienst bereitstellen.

Hinweis Die Möglichkeit, Reverse-DNS-Lookups mithilfe der getnameinfo-Funktion durchzuführen, ist praktisch, aber solche Nachschlagevorgänge werden grundsätzlich als unzuverlässig betrachtet und sollten nur als Hinweis verwendet werden.
 
Hinweis Die getnameinfo-Funktion kann nicht verwendet werden, um Aliasnamen aufzulösen.
 

Beispielcode

Im folgenden Codebeispiel wird die Verwendung der Getnameinfo-Funktion veranschaulicht. 
#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 = {0};
    int iResult = 0;

    DWORD dwRetval;

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

    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s IPv4 address\n", argv[0]);
        printf("  to return hostname\n");
        printf("       %s 127.0.0.1\n", argv[0]);
        return 1;
    }
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("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 getnameinfo
    dwRetval = getnameinfo((struct sockaddr *) &saGNI,
                           sizeof (struct sockaddr),
                           hostname,
                           NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);

    if (dwRetval != 0) {
        printf("getnameinfo failed with error # %ld\n", WSAGetLastError());
        return 1;
    } else {
        printf("getnameinfo returned hostname = %s\n", hostname);
        return 0;
    }
}

Unterstützung für getnameinfo in älteren Versionen von Windows

Die Getnameinfo-Funktion wurde der Ws2_32.dll unter Windows XP und höher hinzugefügt. Wenn Sie eine Anwendung mit dieser Funktion in früheren Versionen von Windows (Windows 2000, Windows NT und Windows Me/98/95) ausführen möchten, müssen Sie die Datei Ws2tcpip.h einschließen und auch die Datei Wspiapi.h einschließen. Wenn die Includedatei Wspiapi.h hinzugefügt wird, wird die getnameinfo-Funktion für die WspiapiGetNameInfo-Inlinefunktion in der Datei Wspiapi.h definiert. Zur Laufzeit ist die WspiapiGetNameInfo-Funktion so implementiert, dass, wenn die Ws2_32.dll oder die Wship6.dll (die Datei, die getnameinfo in der IPv6 Technology Preview für Windows 2000 enthält) nicht getnameinfo enthält, eine Version von getnameinfo basierend auf Code in der Wspiapi.h-Headerdatei inline implementiert wird. Dieser Inlinecode wird auf älteren Windows-Plattformen verwendet, die die getnameinfo-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 Getnameinfo-Unterstützung unter Windows-Versionen vor Windows XP auf die Behandlung der IPv4-Namensauflösung beschränkt.

Die GetNameInfoW-Funktion ist die Unicode-Version von getnameinfo. Die GetNameInfoW-Funktion wurde dem Ws2_32.dll in Windows XP mit SP2 hinzugefügt. Die GetNameInfoW-Funktion kann nicht unter Versionen von Windows vor Windows XP mit SP2 verwendet werden.

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps ab Windows Phone 8 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.

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

Weitere Informationen

GetNameInfoW

WSAGetLastError

Winsock-Funktionen

Winsock-Referenz

gai_strerror

getaddrinfo

sockaddr