Fonction DsGetDcNameA (dsgetdc.h)
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 DsGetDcNameA(
[in] LPCSTR ComputerName,
[in] LPCSTR DomainName,
[in] GUID *DomainGuid,
[in] LPCSTR SiteName,
[in] ULONG Flags,
[out] PDOMAIN_CONTROLLER_INFOA *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é, le nom peut être spécifié avec ou sans période 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 avec le GUID 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 renvoyer un contrôleur de domaine dans le site le plus proche du site de l’ordinateur spécifié par ComputerName. Ce paramètre doit avoir la valeur 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
Lorsqu’il est 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 prenant en charge les services d’annuaire n’est pas disponible, DsGetDcName retourne le nom d’un contrôleur de domaine de service non-annuaire. Toutefois, DsGetDcName retourne un contrôleur de domaine de service non-annuaire uniquement 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 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 les données du contrôleur de domaine mises en cache à être ignorées. 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’utilisera pas les informations mises en cache (le cas échéant), mais effectuera à 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 de contrôleur de domaine mises 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 ne doit être utilisé qu’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 inutiles (le cas échéant) sont ignorées et qu’un contrôleur de domaine accessible est détecté.
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’a pas la valeur 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 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éma accessible 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.
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
et
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).
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.
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 |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour