NetGetDCName, fonction (lmaccess.h)

Article
03/04/2024

La fonction NetGetDCName retourne le nom du contrôleur de domaine principal (PDC). Il ne retourne pas le nom du contrôleur de domaine de sauvegarde (BDC) pour le domaine spécifié. En outre, vous ne pouvez pas mettre à distance cette fonction vers un serveur non PDC.

Les applications qui prennent en charge les noms de style DNS doivent appeler la fonction DsGetDcName . Les contrôleurs de domaine dans ce type d’environnement ont une relation de réplication d’annuaires multi-master. Par conséquent, il peut être avantageux pour votre application d’utiliser un contrôleur de domaine qui n’est pas le contrôleur de domaine principal. Vous pouvez appeler la fonction DsGetDcName pour localiser n’importe quel contrôleur de domaine dans le domaine ; NetGetDCName retourne uniquement le nom du contrôleur de domaine principal.

Syntaxe

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

Paramètres

ServerName

Pointeur vers une chaîne constante qui spécifie le nom DNS ou NetBIOS du serveur distant sur lequel la fonction doit s’exécuter. Si ce paramètre a la valeur NULL, l’ordinateur local est utilisé.

DomainName

Pointeur vers une chaîne constante qui spécifie le nom du domaine. Le nom de domaine doit être un nom de domaine NetBIOS (par exemple, microsoft). NetGetDCName ne prend pas en charge les noms de style DNS (par exemple, microsoft.com). Si ce paramètre a la valeur NULL, la fonction retourne le nom du contrôleur de domaine pour le domaine principal.

Buffer

Valeur retournée

Si la fonction réussit, la valeur de retour est NERR_Success.

Si la fonction échoue, la valeur de retour peut être l’un des codes d’erreur suivants.

Code de retour	Description
NERR_DCNotFound	Impossible de trouver le contrôleur de domaine pour le domaine spécifié dans le paramètre domainname .
ERROR_BAD_NETPATH	Le chemin d’accès réseau est introuvable. Cette erreur est retournée si l’ordinateur spécifié dans le paramètre servername est introuvable.
ERROR_INVALID_NAME	La syntaxe de nom est incorrecte. Cette erreur est retournée si le nom spécifié dans le paramètre servername contient des caractères non conformes.
ERROR_NOT_SUPPORTED	La demande n'est pas prise en charge.

Remarques

Aucune appartenance à un groupe spécial n’est requise pour exécuter correctement la fonction NetGetDCName .

Exemples

L’exemple de code suivant montre comment récupérer le contrôleur de domaine principal à l’aide du
NetGetDCName, fonction. L’exemple appelle NetGetDCName en spécifiant les paramètres servername et domainname. Si l’appel réussit, le code imprime des informations sur le nom du contrôleur de domaine principal. Enfin, l’exemple libère la mémoire allouée à la mémoire tampon dans laquelle le nom du contrôleur de domaine a été retourné.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	lmaccess.h (include Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll