NetGetDCName-Funktion (lmaccess.h)

Artikel
03/01/2024

Die NetGetDCName-Funktion gibt den Namen des primären Domänencontrollers (PDC) zurück. Der Name des Sicherungsdomänencontrollers (Backup Domain Controller, BDC) für die angegebene Domäne wird nicht zurückgegeben. Außerdem können Sie diese Funktion nicht auf einen Nicht-PDC-Server remoten.

Anwendungen, die DNS-artige Namen unterstützen, sollten die DsGetDcName-Funktion aufrufen. Domänencontroller in dieser Umgebung verfügen über eine Replikationsbeziehung mit mehreren master Verzeichnissen. Daher kann es für Ihre Anwendung vorteilhaft sein, einen DC zu verwenden, der nicht der PDC ist. Sie können die DsGetDcName-Funktion aufrufen, um einen beliebigen DC in der Domäne zu suchen. NetGetDCName gibt nur den Namen des PDC zurück.

Syntax

NET_API_STATUS NET_API_FUNCTION NetGetDCName(
        LPCWSTR ServerName,
        LPCWSTR DomainName,
        LPBYTE  *Buffer
);

Parameter

ServerName

Ein Zeiger auf eine konstante Zeichenfolge, die den DNS- oder NetBIOS-Namen des Remoteservers angibt, auf dem die Funktion ausgeführt werden soll. Wenn dieser Parameter NULL ist, wird der lokale Computer verwendet.

DomainName

Ein Zeiger auf eine konstante Zeichenfolge, die den Namen der Domäne angibt. Der Domänenname muss ein NetBIOS-Domänenname sein (z. B. microsoft). NetGetDCName unterstützt keine DNS-Namen (z. B. microsoft.com). Wenn dieser Parameter NULL ist, gibt die Funktion den Namen des Domänencontrollers für die primäre Domäne zurück.

Buffer

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes sein.

Rückgabecode	Beschreibung
NERR_DCNotFound	Der Domänencontroller für die im Domainname-Parameter angegebene Domäne konnte nicht gefunden werden.
ERROR_BAD_NETPATH	Der Netzwerkpfad wurde nicht gefunden.“ Dieser Fehler wird zurückgegeben, wenn der im Servername-Parameter angegebene Computer nicht gefunden werden konnte.
ERROR_INVALID_NAME	Die Namenssyntax ist falsch. Dieser Fehler wird zurückgegeben, wenn der im Servername-Parameter angegebene Name ungültige Zeichen enthält.
ERROR_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt.

Hinweise

Für die erfolgreiche Ausführung der NetGetDCName-Funktion ist keine spezielle Gruppenmitgliedschaft erforderlich.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Sie den primären Domänencontroller mithilfe des
NetGetDCName-Funktion . Im Beispiel wird NetGetDCName aufgerufen, wobei die Parameter servername und domainname angegeben werden. Wenn der Aufruf erfolgreich ist, gibt der Code Informationen aus dem Namen des primären Domänencontrollers aus. Schließlich gibt das Beispiel den Speicher frei, der für den Puffer zugewiesen ist, in dem der Domänencontrollername zurückgegeben wurde.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <stdlib.h>  // for _wtoi function
#include <assert.h>
#include <windows.h>
#include <lm.h>

// Need to link with netapi32.lib
#pragma comment(lib, "netapi32.lib")

int wmain(int argc, wchar_t * argv[])
{

    NET_API_STATUS nStatus;

    LPCWSTR lpServer = NULL;
    LPCWSTR lpDomain = NULL;

    LPCWSTR lpDcName = NULL;
    
    if (argc != 3 ) {
        wprintf(L"Usage: %ws <ServerName> <DomainName>\n",
                argv[0]);
        wprintf(L"     %ws Myserver Domain\n", argv[0]);
        exit(1);
    }

    lpServer = argv[1];
    lpDomain = argv[2];

    wprintf(L"Calling NetGetDCName with parameters\n");
    wprintf(L"    lpServer = %ws\n", lpServer);
    wprintf(L"    lpDomain = %ws\n", lpDomain);

    //
    // Call the NetGetDCName function
    //
    nStatus = NetGetDCName(lpServer, lpDomain, (LPBYTE *) &lpDcName);
    //
    // If the call succeeds,
    //
    if (nStatus == NERR_Success) {
        wprintf(L"NetGetDCName was successful\n", nStatus);
        wprintf(L"DC Name = %ws\n", lpDcName);
        // Need to free the returned buffer
        nStatus = NetApiBufferFree( (LPVOID) lpDcName);
        if (nStatus != NERR_Success)
            wprintf(L"NetApiBufferFree failed with error: %lu (0x%lx)\n",
                nStatus, nStatus);
    } else {
        wprintf(L"NetGetDCName failed with error: %lu (0x%lx)\n", nStatus,
                nStatus);
        wprintf(L"   Error = ");
        switch (nStatus) {
        case ERROR_INVALID_PARAMETER:
            wprintf(L"ERROR_INVALID_PARAMETER\n");
            break;
        case ERROR_NO_SUCH_DOMAIN:
            wprintf(L"ERROR_NO_SUCH_DOMAIN\n");
            break;
        case ERROR_NOT_SUPPORTED:
            wprintf(L"ERROR_NOT_SUPPORTED\n");
            break;
        case ERROR_BAD_NETPATH:
            wprintf(L"ERROR_BAD_NETPATH\n");
            break;
        case ERROR_INVALID_COMPUTERNAME:
            wprintf(L"ERROR_INVALID_COMPUTERNAME\n");
            break;
        case DNS_ERROR_INVALID_NAME_CHAR:
            wprintf(L"DNS_ERROR_INVALID_NAME_CHAR\n");
            break;
        case DNS_ERROR_NON_RFC_NAME:
            wprintf(L"DNS_ERROR_NON_RFC_NAME\n");
            break;
        case ERROR_INVALID_NAME:
            wprintf(L"ERROR_INVALID_NAME\n");
            break;
        case NERR_DCNotFound:
            wprintf(L"NERR_DCNotFound\n");
            break;
        case NERR_WkstaNotStarted:
            wprintf(L"NERR_WkstaNotStarted\n");
            break;
        case RPC_S_SERVER_UNAVAILABLE:
            wprintf(L"RPC_S_SERVER_UNAVAILABLE\n");
            break;
        case RPC_E_REMOTE_DISABLED:
            wprintf(L"RPC_E_REMOTE_DISABLED\n");
            break;
        default:
            wprintf(L"Other error, see Winerror.h or lmerr.h)\n");
            break;
        }
    }

    return nStatus;
}

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	lmaccess.h (lm.h einschließen)
Bibliothek	Netapi32.lib
DLL	Netapi32.dll