Função NetGetDCName (lmaccess.h)

Artigo
08/24/2023

A função NetGetDCName retorna o nome do controlador de domínio primário (PDC). Ele não retorna o nome do BDC (controlador de domínio de backup) para o domínio especificado. Além disso, você não pode remotamente essa função para um servidor não PDC.

Aplicativos que dão suporte a nomes de estilo DNS devem chamar a função DsGetDcName . Os controladores de domínio nesse tipo de ambiente têm uma relação de replicação de diretório de várias master. Portanto, pode ser vantajoso para seu aplicativo usar um DC que não seja o PDC. Você pode chamar a função DsGetDcName para localizar qualquer controlador de domínio no domínio; NetGetDCName retorna apenas o nome do PDC.

Sintaxe

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

Parâmetros

ServerName

Um ponteiro para uma cadeia de caracteres constante que especifica o nome DNS ou NetBIOS do servidor remoto no qual a função deve ser executada. Se esse parâmetro for NULL, o computador local será usado.

DomainName

Um ponteiro para uma cadeia de caracteres constante que especifica o nome do domínio. O nome de domínio deve ser um nome de domínio NetBIOS (por exemplo, microsoft). NetGetDCName não dá suporte a nomes de estilo DNS (por exemplo, microsoft.com). Se esse parâmetro for NULL, a função retornará o nome do controlador de domínio para o domínio primário.

Buffer

Retornar valor

Se a função for bem-sucedida, o valor retornado será NERR_Success.

Se a função falhar, o valor retornado poderá ser um dos códigos de erro a seguir.

Código de retorno	Descrição
NERR_DCNotFound	Não foi possível localizar o controlador de domínio para o domínio especificado no parâmetro domainname .
ERROR_BAD_NETPATH	O caminho da rede não foi encontrado. Esse erro será retornado se o computador especificado no parâmetro servername não puder ser encontrado.
ERROR_INVALID_NAME	A sintaxe do nome está incorreta. Esse erro será retornado se o nome especificado no parâmetro servername contiver caracteres ilegais.
ERROR_NOT_SUPPORTED	A solicitação não terá suporte.

Comentários

Nenhuma associação de grupo especial é necessária para executar com êxito a função NetGetDCName .

Exemplos

O exemplo de código a seguir demonstra como recuperar o controlador de domínio primário usando o
Função NetGetDCName . O exemplo chama NetGetDCName especificando os parâmetros servername e domainname. Se a chamada for bem-sucedida, o código imprimirá informações sobre o nome do controlador de domínio primário. Por fim, o exemplo libera a memória alocada para o buffer em que o nome do controlador de domínio foi retornado.

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	lmaccess.h (inclua Lm.h)
Biblioteca	Netapi32.lib
DLL	Netapi32.dll