GetComputerNameExA-Funktion (sysinfoapi.h)

Artikel
08/26/2023

Ruft einen NetBIOS- oder DNS-Namen ab, der dem lokalen Computer zugeordnet ist. Die Namen werden beim Systemstart festgelegt, wenn das System sie aus der Registrierung liest.

Syntax

BOOL GetComputerNameExA(
  [in]      COMPUTER_NAME_FORMAT NameType,
  [out]     LPSTR                lpBuffer,
  [in, out] LPDWORD              nSize
);

Parameter

[in] NameType

Der Typ des abzurufenden Namens. Dieser Parameter ist ein Wert aus dem COMPUTER_NAME_FORMAT Enumerationstyp. Die folgende Tabelle enthält zusätzliche Informationen.

Wert	Bedeutung
ComputernameDnsDomäne	Der Name der dem lokalen Computer zugewiesenen DNS-Domäne. Wenn der lokale Computer ein Knoten in einem Cluster ist, empfängt lpBuffer den DNS-Domänennamen des virtuellen Clusterservers.
ComputernameDnsVollqualifiziert	Der vollqualifizierte DNS-Name, der den lokalen Computer eindeutig identifiziert. Dieser Name ist eine Kombination des DNS-Hostnamens und des DNS-Domänennamens und verwendet die Form Hostname.Domänenname. Wenn der lokale Computer ein Knoten in einem Cluster ist, empfängt lpBuffer den vollqualifizierten DNS-Namen des virtuellen Clusterservers.
ComputernameDnsHostname	Der DNS-Hostname des lokalen Computers. Wenn der lokale Computer ein Knoten in einem Cluster ist, empfängt lpBuffer den DNS-Hostnamen des virtuellen Clusterservers.
ComputernameNetBIOS	Der NetBIOS-Name des lokalen Computers. Wenn der lokale Computer ein Knoten in einem Cluster ist, empfängt lpBuffer den NetBIOS-Namen des virtuellen Clusterservers.
ComputernamePhysischeDnsDomäne	Der Name der dem lokalen Computer zugewiesenen DNS-Domäne. Wenn der lokale Computer ein Knoten in einem Cluster ist, empfängt lpBuffer den DNS-Domänennamen des lokalen Computers, nicht den Namen des virtuellen Clusterservers.
ComputernamePhysischerDnsVollqualifiziert	Der vollqualifizierte DNS-Name, der den Computer eindeutig identifiziert. Wenn der lokale Computer ein Knoten in einem Cluster ist, empfängt lpBuffer den vollqualifizierten DNS-Namen des lokalen Computers, nicht den Namen des virtuellen Clusterservers. Der vollqualifizierte DNS-Name ist eine Kombination des DNS-Hostnamens und des DNS-Domänennamens und verwendet die Form Hostname.Domänenname.
ComputernamePhysischerDnsHostname	Der DNS-Hostname des lokalen Computers. Wenn der lokale Computer ein Knoten in einem Cluster ist, empfängt lpBuffer den DNS-Hostnamen des lokalen Computers, nicht den Namen des virtuellen Clusterservers.
ComputernamePhysischerNetBIOS	Der NetBIOS-Name des lokalen Computers. Wenn der lokale Computer ein Knoten in einem Cluster ist, empfängt lpBuffer den NetBIOS-Namen des lokalen Computers, nicht den Namen des virtuellen Clusterservers.

[out] lpBuffer

Ein Zeiger auf einen Puffer, der den Computernamen oder den Namen des virtuellen Clustersservers empfängt.

Die Länge des Namens kann größer als MAX_COMPUTERNAME_LENGTH Zeichen sein, da DNS längere Namen zulässt. Um sicherzustellen, dass dieser Puffer groß genug ist, legen Sie diesen Parameter auf NULL fest, und verwenden Sie die erforderliche Puffergröße, die im lpnSize-Parameter zurückgegeben wird.

[in, out] nSize

Gibt bei der Eingabe die Größe des Puffers in TCHARs an. Empfängt bei der Ausgabe die Anzahl der TCHARs , die in den Zielpuffer kopiert wurden, ohne das abschließende NULL-Zeichen .

Wenn der Puffer zu klein ist, schlägt die Funktion fehl, und GetLastError gibt ERROR_MORE_DATA zurück. Dieser Parameter empfängt die Größe des erforderlichen Puffers, einschließlich des abschließenden NULL-Zeichens .

Wenn lpBufferNULL ist, muss dieser Parameter null sein.

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. Die folgenden Werte sind möglich.

Rückgabecode	Beschreibung
ERROR_MORE_DATA	Der lpBuffer-Puffer ist zu klein. Der parameter lpnSize enthält die Anzahl der Bytes, die zum Empfangen des Namens erforderlich sind.

Hinweise

Wenn die Gruppenrichtlinie für den lokalen Computer nicht festgelegt ist, ruft die GetComputerNameEx-Funktion die NetBIOS- oder DNS-Namen ab, die beim Systemstart eingerichtet wurden. Wenn die Gruppenrichtlinie festgelegt ist, gibt die Funktion den primären Domänennamen zurück, der durch die Gruppenrichtlinie festgelegt wird. Von den Funktionen SetComputerName oder SetComputerNameEx vorgenommene Namensänderungen werden erst wirksam, wenn der Benutzer den Computer neu startet.

Wenn der lokale Computer nicht für die Verwendung von DNS-Namen konfiguriert ist, gibt GetComputerNameEx keine DNS-Informationen zurück. Um den Computer dafür zu konfigurieren, führen Sie die in der Betriebssystemhilfe beschriebenen Schritte aus, ändern Sie das primäre DNS-Suffix des Computers, und starten Sie dann den Computer neu.

Das Verhalten dieser Funktion kann beeinflusst werden, wenn der lokale Computer ein Knoten in einem Cluster ist. Weitere Informationen finden Sie unter ResUtilGetEnvironmentWithNetName und UseNetworkName.

Wenn Sie mit Umgebungen arbeiten, die unterschiedliche DNS-Layouts verwenden, in denen der FQDN des Computers nicht mit dem FQDN seiner Domäne übereinstimmt, verwenden Sie stattdessen LsaQueryInformationPolicy .

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

Beispiele

#define _WIN32_WINNT 0x0500

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

void _tmain(void)
{
    TCHAR buffer[256] = TEXT("");
    TCHAR szDescription[8][32] = {TEXT("NetBIOS"), 
        TEXT("DNS hostname"), 
        TEXT("DNS domain"), 
        TEXT("DNS fully-qualified"), 
        TEXT("Physical NetBIOS"), 
        TEXT("Physical DNS hostname"), 
        TEXT("Physical DNS domain"), 
        TEXT("Physical DNS fully-qualified")};
    int cnf = 0;
    DWORD dwSize = _countof(buffer);
    
    for (cnf = 0; cnf < ComputerNameMax; cnf++)
    {
        if (!GetComputerNameEx((COMPUTER_NAME_FORMAT)cnf, buffer, &dwSize))
        {
            _tprintf(TEXT("GetComputerNameEx failed (%d)\n"), GetLastError());
            return;
        }
        else _tprintf(TEXT("%s: %s\n"), szDescription[cnf], buffer);

        dwSize = _countof(buffer);
        ZeroMemory(buffer, dwSize);
    }
}

Hinweis

Der sysinfoapi.h-Header definiert GetComputerNameEx 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