SetComputerNameExA-Funktion (sysinfoapi.h)

Artikel
03/02/2024

Legt einen neuen NetBIOS- oder DNS-Namen für den lokalen Computer fest. Von SetComputerNameEx 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
ComputernamePhysischeDnsDomäne	Legt das primäre DNS-Suffix des Computers fest.
ComputernamePhysischerDnsHostname	Legt netBIOS und computer name (die erste Bezeichnung des vollständigen DNS-Namens) auf den in lpBuffer angegebenen Namen fest. Wenn der Name MAX_COMPUTERNAME_LENGTH Zeichen überschreitet, wird der NetBIOS-Name auf MAX_COMPUTERNAME_LENGTH Zeichen abgeschnitten, ohne das abschließende NULL-Zeichen.
ComputernamePhysischerNetBIOS	Legt den NetBIOS-Namen auf den in lpBuffer angegebenen Namen fest. Der Name darf MAX_COMPUTERNAME_LENGTH Zeichen nicht überschreiten, ohne das abschließende NULL-Zeichen. Warnung: Wenn Sie diese Option verwenden, um den NetBIOS-Namen festzulegen, wird die Konvention von voneinander abhängigen 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 nicht funktioniert.

[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 fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

SetComputerNameEx kann den Computernamen (die erste Bezeichnung des vollständigen DNS-Namens) oder das primäre DNS-Suffix des lokalen Computers festlegen. Es kann keinen vollqualifizierten DNS-Namen in einem Aufruf festlegen.

Wenn der lokale Computer ein Knoten in einem Cluster ist, legt SetComputerNameEx netBIOS oder den DNS-Namen des lokalen Computers fest, nicht den des virtuellen Clustersservers.

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.

Hinweis

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
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	sysinfoapi.h (windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll