Funzione NetGetDCName (lmaccess.h)

Articolo
03/09/2023

La funzione NetGetDCName restituisce il nome del controller di dominio primario (PDC). Non restituisce il nome del controller di dominio di backup (BDC) per il dominio specificato. Non è inoltre possibile remoto questa funzione a un server non PDC.

Le applicazioni che supportano nomi di stile DNS devono chiamare la funzione DsGetDcName . I controller di dominio in questo tipo di ambiente hanno una relazione di replica con directory multi master. Pertanto, può essere vantaggioso per l'applicazione usare un controller di dominio che non è il PDC. È possibile chiamare la funzione DsGetDcName per individuare qualsiasi controller di dominio nel dominio; NetGetDCName restituisce solo il nome del PDC.

Sintassi

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

Parametri

ServerName

Puntatore a una stringa costante che specifica il nome DNS o NetBIOS del server remoto in cui eseguire la funzione. Se questo parametro è NULL, viene usato il computer locale.

DomainName

Puntatore a una stringa costante che specifica il nome del dominio. Il nome di dominio deve essere un nome di dominio NetBIOS, ad esempio Microsoft. NetGetDCName non supporta nomi in stile DNS, ad esempio microsoft.com. Se questo parametro è NULL, la funzione restituisce il nome del controller di dominio per il dominio primario.

Buffer

Valore restituito

Se la funzione ha esito positivo, il valore restituito è NERR_Success.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti.

Codice restituito	Descrizione
NERR_DCNotFound	Impossibile trovare il controller di dominio per il dominio specificato nel parametro domainname .
ERROR_BAD_NETPATH	Impossibile trovare il percorso di rete. Questo errore viene restituito se il computer specificato nel parametro nome server non è stato trovato.
ERROR_INVALID_NAME	La sintassi del nome non è corretta. Questo errore viene restituito se il nome specificato nel parametro nome server contiene caratteri non validi.
ERROR_NOT_SUPPORTED	La richiesta non è supportata.

Commenti

Non è necessaria alcuna appartenenza speciale al gruppo per eseguire correttamente la funzione NetGetDCName .

Esempio

L'esempio di codice seguente illustra come recuperare il controller di dominio primario usando
Funzione NetGetDCName . L'esempio chiama NetGetDCName specificando i parametri nome server e nome dominio. Se la chiamata ha esito positivo, il codice stampa le informazioni sul nome del controller di dominio primario. Infine, l'esempio libera la memoria allocata per il buffer in cui è stato restituito il nome del controller di dominio.

#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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	lmaccess.h (include Lm.h)
Libreria	Netapi32.lib
DLL	Netapi32.dll