GetHostNameW-Funktion (winsock2.h)

Artikel
08/27/2023

Die GetHostNameW-Funktion ruft den Standardhostnamen für den lokalen Computer als Unicode-Zeichenfolge ab.

Syntax

int WSAAPI GetHostNameW(
  [out] PWSTR name,
  [in]  int   namelen
);

Parameter

[out] name

Ein Zeiger auf einen Puffer, der den lokalen Hostnamen als mit NULL endende Unicode-Zeichenfolge empfängt.

[in] namelen

Die Länge des Puffers in Breitzeichen, auf den der Name-Parameter verweist.

Rückgabewert

Wenn kein Fehler auftritt, gibt GetHostNameW null zurück. Andernfalls wird SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSAEFAULT	Der Name-Parameter ist ein NULL-Zeiger oder kein gültiger Teil des Benutzeradressraums. Dieser Fehler wird auch zurückgegeben, wenn die durch den namelen-Parameter angegebene Puffergröße zu klein ist, um den vollständigen Hostnamen zu enthalten.
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSAENETDOWN	Fehler beim Netzwerksubsystem.

Hinweise

Die GetHostNameW-Funktion gibt den Namen des lokalen Hosts in den Puffer zurück, der durch den name-Parameter in Unicode (UTF-16) angegeben wird. Der Hostname wird als mit NULL endende Unicode-Zeichenfolge zurückgegeben. Die Form des Hostnamens hängt vom Windows Sockets-Anbieter ab. Dabei kann es sich um einen einfachen Hostnamen oder um einen vollqualifizierten Domänennamen handeln. Es ist jedoch garantiert, dass der zurückgegebene Name von GetAddrInfoW erfolgreich analysiert wird.

Mit dem Wachstum des Internets wächst die Notwendigkeit, Internethostnamen für andere Sprachen zu identifizieren, die nicht durch den ASCII-Zeichensatz dargestellt werden. Bezeichner, die diese Anforderung erleichtern und die Darstellung von Nicht-ASCII-Zeichen (Unicode) als spezielle ASCII-Zeichenfolgen (Punycode) ermöglichen, werden als internationalisierte Domänennamen (IDNs) bezeichnet. Ein Mechanismus namens Internationalizing Domain Names in Applications (IDNA) wird verwendet, um IDNs standardmäßig zu verarbeiten. Die GetHostNameW-Funktion konvertiert den lokalen Hostnamen nicht zwischen Punycode und Unicode. Die GetAddrInfoW-Funktion bietet Unterstützung für die IDN-Analyse (Internationalized Domain Name) und führt punycode/IDN-Codierung und Konvertierung durch.

Wenn die GetHostNameW-Funktion für eine Clusterressource unter Windows Server 2012 verwendet wird und die umgebungsvariable CLUSTER_NETWORK_NAME definiert ist, überschreibt der Wert in dieser Umgebungsvariable den tatsächlichen Hostnamen und wird zurückgegeben. In einer Clusterressource enthält die umgebungsvariable CLUSTER_NETWORK_NAME den Namen des Clusters.

Die GetHostNameW-Funktion fragt Namespaceanbieter ab, um den lokalen Hostnamen mithilfe der in der Headerdatei Svgguid.h definierten SVCID_HOSTNAME GUID zu bestimmen. Wenn kein Namespaceanbieter antwortet, gibt die GetHostNameW-Funktion den NetBIOS-Namen des lokalen Computers in Unicode zurück.

Die maximale Länge der Zeichenfolge in Breitzeichen, die im Puffer zurückgegeben wird, auf den der name-Parameter verweist, hängt vom Namespaceanbieter ab, aber diese Zeichenfolge muss maximal 256 Breitzeichen umfassen. Wenn also ein Puffer von 256 Breitzeichen im name-Parameter übergeben wird und der namelen-Parameter auf 256 festgelegt ist, ist die Puffergröße immer angemessen.

Hinweis Wenn kein lokaler Hostname konfiguriert wurde, muss GetHostNameW erfolgreich sein und einen Tokenhostnamen zurückgeben, den GetAddrInfoW auflösen kann.

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 unter Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 8.1, Windows 8 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock2.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll

Weitere Informationen