Fonction DsGetDcNameW (dsgetdc.h)

Article
08/23/2023

La fonction DsGetDcName retourne le nom d’un contrôleur de domaine dans un domaine spécifié. Cette fonction accepte des critères de sélection de contrôleur de domaine supplémentaires pour indiquer la préférence pour un contrôleur de domaine avec des caractéristiques particulières.

Syntaxe

DSGETDCAPI DWORD DsGetDcNameW(
  [in]  LPCWSTR                  ComputerName,
  [in]  LPCWSTR                  DomainName,
  [in]  GUID                     *DomainGuid,
  [in]  LPCWSTR                  SiteName,
  [in]  ULONG                    Flags,
  [out] PDOMAIN_CONTROLLER_INFOW *DomainControllerInfo
);

Paramètres

[in] ComputerName

Pointeur vers une chaîne terminée par null qui spécifie le nom du serveur pour traiter cette fonction. En règle générale, ce paramètre a la valeur NULL, ce qui indique que l’ordinateur local est utilisé.

[in] DomainName

Pointeur vers une chaîne terminée par null qui spécifie le nom du domaine ou de la partition d’application à interroger. Ce nom peut être un nom de style DNS, par exemple, fabrikam.com, ou un nom de style plat, par exemple Fabrikam. Si un nom de style DNS est spécifié, il peut être spécifié avec ou sans point de fin.

Si le paramètre Flags contient l’indicateur DS_GC_SERVER_REQUIRED , DomainName doit être le nom de la forêt. Dans ce cas, DsGetDcName échoue si DomainName spécifie un nom qui n’est pas la racine de la forêt.

Si le paramètre Flags contient l’indicateur DS_GC_SERVER_REQUIRED et DomainName a la valeur NULL, DsGetDcName tente de trouver un catalogue global dans la forêt de l’ordinateur identifié par ComputerName, qui est l’ordinateur local si ComputerName a la valeur NULL.

Si DomainName a la valeur NULL et que le paramètre Flags ne contient pas l’indicateur DS_GC_SERVER_REQUIRED , ComputerName est défini sur le nom de domaine par défaut du domaine principal de l’ordinateur identifié par ComputerName.

[in] DomainGuid

Pointeur vers une structure GUID qui spécifie le GUID du domaine interrogé. Si DomainGuid n’a pas la valeur NULL et que le domaine spécifié par DomainName ou ComputerName est introuvable, DsGetDcName tente de localiser un contrôleur de domaine dans le domaine dont le GUID est spécifié par DomainGuid.

[in] SiteName

Pointeur vers une chaîne terminée par null qui spécifie le nom du site où le contrôleur de domaine retourné doit exister physiquement. Si ce paramètre a la valeur NULL, DsGetDcName tente de retourner un contrôleur de domaine dans le site le plus proche du site de l’ordinateur spécifié par ComputerName. Ce paramètre doit être NULL, par défaut.

[in] Flags

Contient un ensemble d’indicateurs qui fournissent des données supplémentaires utilisées pour traiter la demande. Ce paramètre peut être une combinaison des valeurs suivantes.

DS_AVOID_SELF

En cas d’appel à partir d’un contrôleur de domaine, spécifie que le nom du contrôleur de domaine retourné ne doit pas être l’ordinateur actuel. Si l'ordinateur actuel n'est pas un contrôleur de domaine, cet indicateur est ignoré. Cet indicateur peut être utilisé pour obtenir le nom d’un autre contrôleur de domaine dans le domaine.

DS_BACKGROUND_ONLY

Si l’indicateur DS_FORCE_REDISCOVERY n’est pas spécifié, cette fonction utilise des données de contrôleur de domaine mises en cache. Si les données mises en cache datent de plus de 15 minutes, le cache est actualisé en effectuant un test ping sur le contrôleur de domaine. Si cet indicateur est spécifié, cette actualisation est évitée même si les données mises en cache ont expiré. Cet indicateur doit être utilisé si la fonction DsGetDcName est appelée régulièrement.

DS_DIRECTORY_SERVICE_PREFERRED

DsGetDcName tente de trouver un contrôleur de domaine qui prend en charge les fonctions de service d’annuaire. Si un contrôleur de domaine qui prend en charge les services d’annuaire n’est pas disponible, DsGetDcName renvoie le nom d’un contrôleur de domaine de service non d’annuaire. Toutefois, DsGetDcName ne retourne un contrôleur de domaine de service non d’annuaire qu’après l’expiration de la tentative de recherche d’un contrôleur de domaine de service d’annuaire.

DS_DIRECTORY_SERVICE_REQUIRED

Nécessite que le contrôleur de domaine retourné prend en charge les services d’annuaire.

DS_DIRECTORY_SERVICE_6_REQUIRED

Nécessite que le contrôleur de domaine retourné exécute Windows Server 2008 ou une version ultérieure.

DS_DIRECTORY_SERVICE_8_REQUIRED

Nécessite que le contrôleur de domaine retourné s’exécute Windows Server 2012 ou une version ultérieure.

DS_FORCE_REDISCOVERY

Force l’ignorée des données du contrôleur de domaine mises en cache. Lorsque l’indicateur DS_FORCE_REDISCOVERY n’est pas spécifié, DsGetDcName peut retourner des données de contrôleur de domaine mises en cache. Si cet indicateur est spécifié, DsGetDcName n’utilise pas les informations mises en cache (le cas échéant), mais effectue à la place une nouvelle découverte de contrôleur de domaine.

Cet indicateur ne doit pas être utilisé dans des conditions normales, car l’utilisation des informations du contrôleur de domaine mis en cache présente de meilleures caractéristiques de performances et permet de garantir que le même contrôleur de domaine est utilisé de manière cohérente par toutes les applications. Cet indicateur doit être utilisé uniquement une fois que l’application a déterminé que le contrôleur de domaine retourné par DsGetDcName (lorsqu’il est appelé sans cet indicateur) n’est pas accessible. Dans ce cas, l’application doit répéter l’appel DsGetDcName avec cet indicateur pour s’assurer que les informations mises en cache inutilisées (le cas échéant) sont ignorées et qu’un contrôleur de domaine accessible est découvert.

DS_GC_SERVER_REQUIRED

Exige que le contrôleur de domaine retourné soit un serveur de catalogue global pour la forêt de domaines avec ce domaine comme racine. Si cet indicateur est défini et que le paramètre DomainName n’est pas NULL, DomainName doit spécifier un nom de forêt. Cet indicateur ne peut pas être combiné avec les indicateurs DS_PDC_REQUIRED ou DS_KDC_REQUIRED .

DS_GOOD_TIMESERV_PREFERRED

DsGetDcName tente de trouver un contrôleur de domaine qui est un serveur de temps fiable. Le service de temps Windows peut être configuré pour déclarer un ou plusieurs contrôleurs de domaine en tant que serveur de temps fiable. Pour plus d’informations, consultez la documentation du service de temps Windows . Cet indicateur est destiné à être utilisé uniquement par le service de temps Windows.

DS_IP_REQUIRED

Ce paramètre indique que le contrôleur de domaine doit avoir une adresse IP. Dans ce cas, DsGetDcName place l’adresse de protocole Internet du contrôleur de domaine dans le membre DomainControllerAddress de DomainControllerInfo.

DS_IS_DNS_NAME

Spécifie que le paramètre DomainName est un nom DNS. Cet indicateur ne peut pas être combiné avec l’indicateur DS_IS_FLAT_NAME .

Spécifiez DS_IS_DNS_NAME ou DS_IS_FLAT_NAME. Si aucun indicateur n’est spécifié, DsGetDcName peut prendre plus de temps pour trouver un contrôleur de domaine, car il peut être nécessaire de rechercher à la fois le nom de style DNS et le nom plat.

DS_IS_FLAT_NAME

Spécifie que le paramètre DomainName est un nom plat. Cet indicateur ne peut pas être combiné avec l’indicateur DS_IS_DNS_NAME .

DS_KDC_REQUIRED

Exige que le contrôleur de domaine retourné exécute actuellement le service Centre de distribution de clés Kerberos. Cet indicateur ne peut pas être combiné avec les indicateurs DS_PDC_REQUIRED ou DS_GC_SERVER_REQUIRED .

DS_ONLY_LDAP_NEEDED

Spécifie que le serveur retourné est un serveur LDAP. Le serveur retourné n’est pas nécessairement un contrôleur de domaine. Aucun autre service n’est implicitement présent sur le serveur. Le serveur retourné n’a pas nécessairement de conteneur de configuration accessible en écriture ni de conteneur de schémas accessibles en écriture. Le serveur retourné ne peut pas nécessairement être utilisé pour créer ou modifier des principes de sécurité. Cet indicateur peut être utilisé avec l’indicateur DS_GC_SERVER_REQUIRED pour renvoyer un serveur LDAP qui héberge également un serveur de catalogue global. Le serveur de catalogue global retourné n’est pas nécessairement un contrôleur de domaine. Aucun autre service n’est implicitement présent sur le serveur. Si cet indicateur est spécifié, les indicateurs DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIRED et DS_KDC_REQUIRED sont ignorés.

DS_PDC_REQUIRED

Exige que le contrôleur de domaine retourné soit le contrôleur de domaine principal du domaine. Cet indicateur ne peut pas être combiné avec les indicateurs DS_KDC_REQUIRED ou DS_GC_SERVER_REQUIRED .

DS_RETURN_DNS_NAME

Spécifie que les noms retournés dans les membres DomainControllerName et DomainName de DomainControllerInfo doivent être des noms DNS. Si un nom DNS n’est pas disponible, une erreur est retournée. Cet indicateur ne peut pas être spécifié avec l’indicateur DS_RETURN_FLAT_NAME . Cet indicateur implique l’indicateur DS_IP_REQUIRED .

DS_RETURN_FLAT_NAME

Spécifie que les noms retournés dans les membres DomainControllerName et DomainName de DomainControllerInfo doivent être des noms plats. Si un nom plat n’est pas disponible, une erreur est retournée. Cet indicateur ne peut pas être spécifié avec l’indicateur DS_RETURN_DNS_NAME .

DS_TIMESERV_REQUIRED

Exige que le contrôleur de domaine retourné exécute actuellement le service de temps Windows.

DS_TRY_NEXTCLOSEST_SITE

Lorsque cet indicateur est spécifié, DsGetDcName tente de trouver un contrôleur de domaine dans le même site que l’appelant. Si aucun contrôleur de domaine de ce type n’est trouvé, il trouve un contrôleur de domaine qui peut fournir des informations de topologie et appeler DsBindToISTG pour obtenir un handle de liaison, puis appeler DsQuerySitesByCost via UDP pour déterminer le « site le plus proche suivant », et enfin mettre en cache le nom du site trouvé. Si aucun contrôleur de domaine n’est trouvé dans ce site, DsGetDcName revient sur la méthode par défaut de localisation d’un contrôleur de domaine.

Si cet indicateur est utilisé conjointement avec une valeur non NULL dans le paramètre d’entrée SiteName, ERROR_INVALID_FLAGS est levée.

En outre, le type de recherche utilisé avec DS_TRY_NEXT_CLOSEST_SITE est propre au site. Cet indicateur est donc ignoré s’il est utilisé conjointement avec DS_PDC_REQUIRED. Enfin, DS_TRY_NEXTCLOSEST_SITE est ignoré lorsqu’il est utilisé conjointement avec DS_RETURN_FLAT_NAME , car il utilise NetBIOS pour résoudre le nom, mais le domaine du contrôleur de domaine trouvé ne correspond pas nécessairement au domaine auquel le client est joint.

Note Cet indicateur est stratégie de groupe activé. Si vous activez le paramètre de stratégie « Site le plus proche suivant », l’emplacement dc du site le plus proche suivant est activé pour l’ordinateur sur toutes les cartes réseau disponibles mais non configurées. Si vous désactivez le paramètre de stratégie, l’emplacement dc du site le plus proche suivant n’est pas utilisé par défaut pour l’ordinateur sur toutes les cartes réseau disponibles, mais non configurées. Toutefois, si un appel de localisateur de contrôleur de domaine est effectué à l’aide de l’indicateur DS_TRY_NEXTCLOSEST_SITE explicitement, DsGetDcName respecte le comportement du site le plus proche suivant. Si vous ne configurez pas ce paramètre de stratégie, l’emplacement du contrôleur de domaine du site le plus proche suivant ne sera pas utilisé par défaut pour l’ordinateur sur toutes les cartes réseau disponibles mais non configurées. Si l’indicateur DS_TRY_NEXTCLOSEST_SITE est utilisé explicitement, le comportement site le plus proche suivant est utilisé.

DS_WRITABLE_REQUIRED

Exige que le contrôleur de domaine retourné soit accessible en écriture ; c’est-à-dire héberger une copie accessible en écriture du service d’annuaire.

DS_WEB_SERVICE_REQUIRED

Nécessite que le contrôleur de domaine retourné exécute actuellement le service web Active Directory.

[out] DomainControllerInfo

Pointeur vers une valeur PDOMAIN_CONTROLLER_INFO qui reçoit un pointeur vers une structure DOMAIN_CONTROLLER_INFO qui contient des données sur le contrôleur de domaine sélectionné. Cette structure est allouée par DsGetDcName. L’appelant doit libérer la structure à l’aide de la fonction NetApiBufferFree quand elle n’est plus nécessaire.

Valeur retournée

Si la fonction retourne des données du contrôleur de domaine, la valeur de retour est ERROR_SUCCESS.

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

Remarques

La fonction DsGetDcName est envoyée au service Netlogon sur l’ordinateur distant spécifié par ComputerName. Si ComputerName a la valeur NULL, la fonction est traitée sur l’ordinateur local.

DsGetDcName ne vérifie pas que le nom du contrôleur de domaine retourné est le nom d’un contrôleur de domaine ou d’un catalogue global réel. Si l’authentification mutuelle est requise, l’appelant doit effectuer l’authentification.

DsGetDcName ne nécessite aucun accès particulier au domaine spécifié. Par défaut, cette fonction ne garantit pas que le contrôleur de domaine retourné est actuellement disponible. Au lieu de cela, l’appelant doit tenter d’utiliser le contrôleur de domaine retourné. Si le contrôleur de domaine n’est pas disponible, l’appelant doit à nouveau appeler la fonction DsGetDcName , en spécifiant l’indicateur DS_FORCE_REDISCOVERY .

Temps de réponse

Lorsque vous utilisez DsGetDcName , tenez compte des détails de minutage suivants :

DsGetDcName effectue des appels réseau et peut prendre de quelques secondes à une minute, en fonction du trafic réseau, de la topologie, de la charge du contrôleur de domaine, etc.
Il n’est PAS recommandé d’appeler DsGetDcName à partir d’une interface utilisateur ou d’un autre thread critique de minutage.
Le localisateur de contrôleurs de domaine utilise une logique optimisée pour fournir les informations de contrôleur de domaine aussi rapidement que possible. Il utilise également les informations mises en cache sur le site pour contacter le contrôleur de domaine le plus proche.

Remarques sur l’adhérence du contrôleur de domaine

Dans services de domaine Active Directory, la fonction de localisateur de contrôleur de domaine est conçue de telle sorte qu’une fois qu’un client a trouvé un contrôleur de domaine préféré, le client ne recherche pas d’autre contrôleur de domaine, sauf si ce contrôleur de domaine cesse de répondre ou si le client est redémarré. C’est ce que l’on appelle « Stickiness du contrôleur de domaine ». Étant donné que les stations de travail fonctionnent généralement pendant des mois sans problème ni redémarrage, une conséquence inattendue de ce comportement est que si un contrôleur de domaine particulier tombe en panne pour maintenance, tous les clients qui y étaient connectés déplacent leurs connexions à un autre contrôleur de domaine. Mais lorsque le contrôleur de domaine revient, aucun client ne s’y reconnecte, car les clients ne redémarrent pas très souvent. Cela peut entraîner des problèmes d’équilibrage de charge.

Auparavant, la solution la plus courante à ce problème était de déployer un script sur chaque ordinateur client qui appelait périodiquement DsGetDcName à l’aide de l’indicateur DS_FORCE_REDISCOVERY . Il s’agissait d’une solution un peu fastidieuse, donc Windows Server 2008 et Windows Vista ont introduit un nouveau mécanisme qui a provoqué des problèmes d’adhérence du contrôleur de domaine.

Chaque fois que DsGetDcName récupère un nom de contrôleur de domaine à partir de son cache, il vérifie si cette entrée mise en cache a expiré et, si c’est le cas, ignore ce nom de contrôleur de domaine et tente de redécouvrir un nom de contrôleur de domaine. La durée de vie d’une entrée mise en cache est contrôlée par la valeur dans les clés de Registre suivantes

HKEY_LOCAL_MACHINE\SYSTÈME\Currentcontrolset\Services\Netlogon\Paramètres\ForceRediscoveryInterval

HKEY_LOCAL_MACHINE\Logiciel\Politiques\Microsoft\Netlogon\Paramètres\ForceRediscoveryInterval

Les valeurs de ces clés de Registre sont de type REG_DWORD. Ils spécifient la durée en secondes avant que DsGetDcName ne tente de redécouvrir le nom du contrôleur de domaine. La valeur par défaut est 43200 secondes (12 heures). Si la valeur de l’entrée de Registre ForceRediscoveryInterval est définie sur 0, le client effectue toujours la redécouverte. Si la valeur est définie sur 4294967295, le cache n’expire jamais et le contrôleur de domaine mis en cache continue d’être utilisé. Nous vous recommandons de ne pas définir l’entrée de Registre ForceRediscoveryInterval sur une valeur inférieure à 3600 secondes (60 minutes).

Note Les paramètres de Registre de ForceRediscoveryInterval sont activés par la stratégie de groupe. Si vous désactivez le paramètre de stratégie, force la redécouverte sera utilisée par défaut pour l’ordinateur toutes les 12 heures. Si vous ne configurez pas ce paramètre de stratégie, force la redécouverte sera utilisée par défaut pour l’ordinateur toutes les 12 heures, sauf si le paramètre d’ordinateur local dans le Registre est une valeur différente.

Notez que si l’indicateur DS_BACKGROUND_ONLY est spécifié, DsGetDcName n’essaiera jamais de redécouvrir le nom du contrôleur de domaine, car le point de cet indicateur est de forcer DsGetDcName à utiliser le nom du contrôleur de domaine mis en cache même s’il a expiré.

Suivi ETW dans DsGetDcName

Pour activer le suivi ETW pour DsGetDcName, créez la clé de Registre suivante :

HKEY_LOCAL_MACHINE\Système\Currentcontrolset\Services\DCLocator\Traçage

La clé aura une structure comme suit :

String ProcessName
  DWORD  PID <optional>

ProcessName doit être le nom complet, y compris l’extension du processus pour lequel vous souhaitez obtenir des informations de trace. Le PID n’est requis que lorsque plusieurs processus portant le même nom existent. S’il est défini, seul le processus avec ce PID sera activé pour le suivi. Il n’est pas possible de suivre seulement 2 processus sur 3 (ou plus) portant le même nom. Vous pouvez activer une instance ou toutes les instances (lorsque plusieurs instances portant le même nom de processus existent et que le PID n’est pas spécifié, toutes les instances sont activées pour le suivi).

Par exemple, cela permet de suivre toutes les instances de App1.exe et de App2.exe, mais uniquement les instance de App3.exe qui ont un PID de 999 :

App1.exe 
App2.exe
App3.exe
     PID 999

Exécutez la commande suivante pour démarrer la session de suivi :

tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>

sessionname est le nom donné pour la session de trace. Le guid du fournisseur de suivi DCLocator est « cfaa5446-c6c4-4f5c-866f-31c9b55b962d ». filename est le nom du fichier journal dans lequel les événements sont écrits. traceFlags est un ou plusieurs des indicateurs suivants qui indiquent les zones à suivre :

Indicateur	Valeur hexadécimale	Description
DCLOCATOR_MISC	0x00000002	Débogage divers
DCLOCATOR_MAILSLOT	0x00000010	Messages d’un maillot
DCLOCATOR_SITE	0x00000020	Sites
DCLOCATOR_CRITICAL	0x00000100	Erreurs importantes
DCLOCATOR_SESSION_SETUP	0x00000200	Maintenance de domaine approuvé
DCLOCATOR_DNS	0x00004000	Inscription de nom
DCLOCATOR_DNS_MORE	0x00020000	Inscription de nom détaillé
DCLOCATOR_MAILBOX_TEXT	0x02000000	Messages de boîte aux lettres détaillés
DCLOCATOR_SITE_MORE	0x08000000	Sites détaillés

Exécutez la commande suivante pour arrêter la session de trace :

tracelog.exe -stop <sessionname>

sessionname est le même nom que celui que vous avez utilisé lors du démarrage de la session.

Note La clé de Registre du processus en cours de suivi doit être présente dans le Registre au moment du démarrage de la session de suivi. Lorsque la session démarre, le processus vérifie s’il doit ou non générer des messages de trace (en fonction de la présence ou de l’absence d’une clé de Registre pour ce nom de processus et du PID facultatif). Le processus vérifie le Registre uniquement au début de la session. Les modifications apportées au Registre après n’auront aucun effet sur le suivi.

Notes

L’en-tête dsgetdc.h définit DsGetDcName comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	dsgetdc.h
Bibliothèque	NetApi32.lib
DLL	NetApi32.dll