SetComputerNameExA-Funktion (sysinfoapi.h)

Artikel
11/20/2024

Legt einen neuen NetBIOS- oder DNS-Namen für den lokalen Computer fest. Von SetComputerName Ex vorgenommene Namensänderungen werden erst wirksam, wenn der Benutzer den Computer neu startet.

Syntax

BOOL SetComputerNameExA(
  [in] COMPUTER_NAME_FORMAT NameType,
  [in] LPCSTR               lpBuffer
);

Parameter

[in] NameType

Der Typ des festzulegenden Namens. Dieser Parameter kann einer der folgenden Werte aus dem COMPUTER_NAME_FORMAT Enumerationstyp sein.

Wert	Bedeutung
ComputerNamePhysicalDnsDomain	Legt das primäre DNS-Suffix des Computers fest.
ComputerNamePhysicalDnsHostname	Legt netBIOS und den Computernamen (die erste Bezeichnung des vollständigen DNS-Namens) auf den in lpBufferangegebenen Namen fest. Wenn der Name MAX_COMPUTERNAME_LENGTH Zeichen überschreitet, wird der NetBIOS-Name auf MAX_COMPUTERNAME_LENGTH Zeichen abgeschnitten, nicht einschließlich des endenden Nullzeichens.
ComputerNamePhysicalNetBIOS	Legt den NetBIOS-Namen auf den in lpBufferangegebenen Namen fest. Der Name darf MAX_COMPUTERNAME_LENGTH Zeichen nicht überschreiten, einschließlich des endenden Nullzeichens. Warnung: Wenn Sie diese Option verwenden, um den NetBIOS-Namen festzulegen, wird die Konvention der interdependenten NetBIOS- und DNS-Namen unterbrochen. Anwendungen, die die DnsHostnameToComputerName-Funktion verwenden, um den NetBIOS-Namen von der ersten Bezeichnung des DNS-Namens abzuleiten, schlagen fehl, wenn diese Konvention unterbrochen ist.

[in] lpBuffer

Der neue Name. Der Name darf keine Steuerzeichen, führende oder nachfolgende Leerzeichen oder eines der folgenden Zeichen enthalten: " / \ [ ] : | <> + = ; , ?

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Wert ungleich Null.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

SetComputerNameEx- kann den Computernamen (die erste Bezeichnung des vollständigen DNS-Namens) oder das primäre DNS-Suffix des lokalen Computers festlegen. Ein vollqualifizierter DNS-Name kann in einem Aufruf nicht festgelegt werden.

Wenn der lokale Computer ein Knoten in einem Cluster ist, legt SetComputerNameEx NetBIOS- oder DNS-Name des lokalen Computers und nicht die des virtuellen Clusterservers fest.

Der Prozess, der die SetComputerNameEx--Funktion aufruft, muss über Administratorrechte auf dem lokalen Computer verfügen.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0500 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Anmerkung

Der sysinfoapi.h-Header definiert SetComputerNameEx 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
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	sysinfoapi.h (include Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll