Función NetGetDCName (lmaccess.h)

Artículo
03/09/2023

La función NetGetDCName devuelve el nombre del controlador de dominio principal (PDC). No devuelve el nombre del controlador de dominio de copia de seguridad (BDC) del dominio especificado. Además, no puede remoto esta función a un servidor que no sea PDC.

Las aplicaciones que admiten nombres de estilo DNS deben llamar a la función DsGetDcName . Los controladores de dominio de este tipo de entorno tienen una relación de replicación de directorios multimaestro. Por lo tanto, puede ser ventajoso que la aplicación use un controlador de dominio que no sea el PDC. Puede llamar a la función DsGetDcName para buscar cualquier controlador de dominio en el dominio; NetGetDCName devuelve solo el nombre del PDC.

Sintaxis

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

Parámetros

ServerName

Puntero a una cadena constante que especifica el nombre DNS o NetBIOS del servidor remoto en el que se va a ejecutar la función. Si este parámetro es NULL, se usa el equipo local.

DomainName

Puntero a una cadena constante que especifica el nombre del dominio. El nombre de dominio debe ser un nombre de dominio NetBIOS (por ejemplo, microsoft). NetGetDCName no admite nombres de estilo DNS (por ejemplo, microsoft.com). Si este parámetro es NULL, la función devuelve el nombre del controlador de dominio para el dominio principal.

Buffer

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es NERR_Success.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error.

Código devuelto	Descripción
NERR_DCNotFound	No se encontró el controlador de dominio para el dominio especificado en el parámetro domainname .
ERROR_BAD_NETPATH	No se ha encontrado la ruta de acceso de la red. Este error se devuelve si no se encontró el equipo especificado en el parámetro servername .
ERROR_INVALID_NAME	La sintaxis de nombre es incorrecta. Este error se devuelve si el nombre especificado en el parámetro servername contiene caracteres no válidos.
ERROR_NOT_SUPPORTED	No se admite la solicitud.

Comentarios

No se requiere ninguna pertenencia especial a grupos para ejecutar correctamente la función NetGetDCName .

Ejemplos

En el ejemplo de código siguiente se muestra cómo recuperar el controlador de dominio principal mediante .
Función NetGetDCName . El ejemplo llama a NetGetDCName especificando los parámetros servername y domainname. Si la llamada se realiza correctamente, el código imprime información sobre el nombre del controlador de dominio principal. Por último, el ejemplo libera la memoria asignada para el búfer donde se devolvió el nombre del controlador de 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;
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	lmaccess.h (include Lm.h)
Library	Netapi32.lib
Archivo DLL	Netapi32.dll