NetJoinDomain, fonction (lmjoin.h)

Article
08/24/2023

La fonction NetJoinDomain joint un ordinateur à un groupe de travail ou un domaine.

Syntaxe

NET_API_STATUS NET_API_FUNCTION NetJoinDomain(
  [in] LPCWSTR lpServer,
  [in] LPCWSTR lpDomain,
  [in] LPCWSTR lpMachineAccountOU,
  [in] LPCWSTR lpAccount,
  [in] LPCWSTR lpPassword,
  [in] DWORD   fJoinOptions
);

Paramètres

[in] lpServer

Pointeur vers une chaîne constante qui spécifie le nom DNS ou NetBIOS de l’ordinateur sur lequel exécuter l’opération de jointure de domaine. Si ce paramètre a la valeur NULL, l’ordinateur local est utilisé.

[in] lpDomain

Pointeur vers une chaîne de caractères constante terminée par une valeur Null qui spécifie le nom du domaine ou du groupe de travail à joindre.

Si vous le souhaitez, vous pouvez spécifier le contrôleur de domaine préféré pour effectuer l’opération de jointure. Dans cette instance, la chaîne doit être de la forme DomainName\MachineName, où DomainName est le nom du domaine à joindre et MachineName est le nom du contrôleur de domaine pour effectuer la jointure.

[in] lpMachineAccountOU

Spécifie éventuellement le pointeur vers une chaîne de caractères constante terminée par null qui contient le nom de format RFC 1779 de l’unité d’organisation (UO) pour le compte d’ordinateur. Si vous spécifiez ce paramètre, la chaîne doit contenir un chemin d’accès complet, par exemple, OU=testOU,DC=domain,DC=domain,DC=com. Sinon, ce paramètre doit être NULL.

[in] lpAccount

Pointeur vers une chaîne de caractères constante terminée par null qui spécifie le nom de compte à utiliser lors de la connexion au contrôleur de domaine. La chaîne doit spécifier un nom netBIOS de domaine et un compte d’utilisateur (par exemple, REDMOND\user) ou le nom d’utilisateur principal (UPN) de l’utilisateur sous la forme d’un nom de connexion de style Internet (par exemple, «someone@example.com »). Si ce paramètre a la valeur NULL, le contexte de l’appelant est utilisé.

[in] lpPassword

Si le paramètre lpAccount spécifie un nom de compte, ce paramètre doit pointer vers le mot de passe à utiliser lors de la connexion au contrôleur de domaine. Sinon, ce paramètre doit être NULL.

Vous pouvez spécifier un mot de passe de compte d’ordinateur local plutôt qu’un mot de passe utilisateur pour les jointures non sécurisées. Pour plus d’informations, consultez la description de l’indicateur NETSETUP_MACHINE_PWD_PASSED décrit dans le paramètre fJoinOptions .

[in] fJoinOptions

Ensemble d’indicateurs de bits définissant les options de jointure. Ce paramètre peut être une ou plusieurs des valeurs suivantes définies dans le fichier d’en-tête Lmjoin.h .

Valeur	Signification
NETSETUP_JOIN_DOMAIN 0x00000001	Joint l’ordinateur à un domaine. Si cette valeur n’est pas spécifiée, joint l’ordinateur à un groupe de travail.
NETSETUP_ACCT_CREATE 0x00000002	Crée le compte sur le domaine.
NETSETUP_WIN9X_UPGRADE 0x00000010	L’opération de jointure se produit dans le cadre d’une mise à niveau.
NETSETUP_DOMAIN_JOIN_IF_JOINED 0x00000020	Autorise une jointure à un nouveau domaine même si l’ordinateur est déjà joint à un domaine.
NETSETUP_JOIN_UNSECURE 0x00000040	Effectue une jonction non sécurisée. Cette option demande une jointure de domaine à un compte précréé sans s’authentifier avec les informations d’identification de l’utilisateur du domaine. Cette option peut être utilisée conjointement avec NETSETUP_MACHINE_PWD_PASSED option. Dans ce cas, lpPassword est le mot de passe du compte d’ordinateur précréé. Avant Windows Vista avec SP1 et Windows Server 2008, une jointure non sécurisée ne s’authentifie pas auprès du contrôleur de domaine. Toutes les communications ont été effectuées à l’aide d’une session Null (non authentifiée). À compter de Windows Vista avec SP1 et Windows Server 2008, le nom et le mot de passe du compte d’ordinateur sont utilisés pour s’authentifier auprès du contrôleur de domaine.
NETSETUP_MACHINE_PWD_PASSED 0x00000080	Indique que le paramètre lpPassword spécifie un mot de passe de compte d’ordinateur local plutôt qu’un mot de passe utilisateur. Cet indicateur est valide uniquement pour les jointures non sécurisées, que vous devez indiquer en définissant également l’indicateur NETSETUP_JOIN_UNSECURE. Si vous définissez cet indicateur, une fois l’opération de jointure réussie, le mot de passe de l’ordinateur est défini sur la valeur lpPassword, si cette valeur est un mot de passe d’ordinateur valide.
NETSETUP_DEFER_SPN_SET 0x00000100	Indique que le nom du principal de service (SPN) et les propriétés DnsHostName sur l’objet ordinateur ne doivent pas être mis à jour pour l’instant. En règle générale, ces propriétés sont mises à jour pendant l’opération de jointure. Au lieu de cela, ces propriétés doivent être mises à jour lors d’un appel suivant à la fonction NetRenameMachineInDomain . Ces propriétés sont toujours mises à jour pendant l’opération de renommage. Pour plus d'informations, consultez la section Notes qui suit.
NETSETUP_JOIN_DC_ACCOUNT 0x00000200	Autorisez la jonction de domaine si le compte existant est un contrôleur de domaine. Note Cet indicateur est pris en charge sur Windows Vista et versions ultérieures.
NETSETUP_JOIN_WITH_NEW_NAME 0x00000400	Joignez la machine cible spécifiée dans le paramètre lpServer avec un nouveau nom interrogé à partir du Registre sur l’ordinateur spécifié dans le paramètre lpServer . Cette option est utilisée si SetComputerNameEx a été appelé avant le redémarrage de l’ordinateur. Le nouveau nom d’ordinateur n’entrera pas en vigueur tant qu’un redémarrage n’est pas effectué. Avec cette option, l’appelant indique à la fonction NetJoinDomain d’utiliser le nouveau nom pendant l’opération de jointure de domaine. Un redémarrage est nécessaire après avoir appelé NetJoinDomain avec succès, à quel moment le changement de nom d’ordinateur et le changement d’appartenance au domaine auront eu une incidence. Note Cet indicateur est pris en charge sur Windows Vista et versions ultérieures.
NETSETUP_JOIN_READONLY 0x00000800	Joignez la machine cible spécifiée dans le paramètre lpServer à l’aide d’un compte précréé sans nécessiter de contrôleur de domaine accessible en écriture. Cette option offre la possibilité de joindre une machine à un domaine si un compte a déjà été provisionné et répliqué sur un contrôleur de domaine en lecture seule. Le contrôleur de domaine en lecture seule cible est spécifié dans le cadre du paramètre lpDomain , après le nom de domaine délimité par un caractère « \ ». Ce provisionnement doit inclure le secret de l’ordinateur. Le compte d’ordinateur doit être ajouté via l’appartenance au groupe dans la liste autorisée pour la stratégie de réplication de mot de passe, et le mot de passe du compte doit être répliqué sur le contrôleur de domaine en lecture seule avant l’opération de jointure. Pour plus d’informations, consultez les informations sur l’administration de la stratégie de réplication de mot de passe. À compter de Windows 7, un autre mécanisme consiste à utiliser le mécanisme de jointure de domaine hors connexion. Pour plus d’informations, consultez les fonctions NetProvisionComputerAccount et NetRequestOfflineDomainJoin . Note Cet indicateur est pris en charge sur Windows Vista et versions ultérieures.
NETSETUP_AMBIGUOUS_DC 0x00001000	Lorsque vous joignez le domaine, n’essayez pas de définir le contrôleur de domaine préféré dans le Registre. Note Cet indicateur est pris en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.
NETSETUP_NO_NETLOGON_CACHE 0x00002000	Lorsque vous joignez le domaine, ne créez pas le cache Netlogon. Note Cet indicateur est pris en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.
NETSETUP_DONT_CONTROL_SERVICES 0x00004000	Lorsque vous joignez le domaine, ne forcez pas le service Netlogon à démarrer. Note Cet indicateur est pris en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.
NETSETUP_SET_MACHINE_NAME 0x00008000	Lorsque vous joignez le domaine pour la jointure hors connexion uniquement, définissez le nom d’hôte de l’ordinateur cible et le nom NetBIOS. Note Cet indicateur est pris en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.
NETSETUP_FORCE_SPN_SET 0x00010000	Lorsque vous joignez le domaine, remplacez d’autres paramètres lors de la jonction de domaine et définissez le nom du principal de service (SPN). Note Cet indicateur est pris en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.
NETSETUP_NO_ACCT_REUSE 0x00020000	Lorsque vous rejoignez le domaine, ne réutilisez pas un compte existant. Note Cet indicateur est pris en charge sur Windows 7, Windows Server 2008 R2 et versions ultérieures.
NETSETUP_IGNORE_UNSUPPORTED_FLAGS 0x10000000	Si ce bit est défini, les indicateurs non reconnus seront ignorés par la fonction NetJoinDomain et NetJoinDomain se comportera comme si les indicateurs n’étaient pas définis.

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 ou l’un des codes d’erreur système.

Code de retour	Description
ERROR_ACCESS_DENIED	Accès refusé. Cette erreur est retournée si l’appelant n’était pas membre du groupe local Administrateurs sur l’ordinateur cible.
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est retournée si le paramètre lpDomain a la valeur NULL.
ERROR_NO_SUCH_DOMAIN	Le domaine spécifié n’existait pas.
ERROR_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette erreur est retournée si l’ordinateur spécifié dans le paramètre lpServer ne prend pas en charge certaines des options passées dans le paramètre fJoinOptions .
NERR_InvalidWorkgroupName	Le nom de groupe de travail spécifié n’est pas valide.
NERR_SetupAlreadyJoined	L’ordinateur est déjà joint à un domaine.
NERR_WkstaNotStarted	Le service Station de travail n’a pas démarré.
RPC_S_CALL_IN_PROGRESS	Un appel de procédure distante est déjà en cours pour ce thread.
RPC_S_PROTSEQ_NOT_SUPPORTED	La séquence de protocole d’appel de procédure distante n’est pas prise en charge.

Notes

La jointure (et la dissociation) d’un ordinateur à un domaine ou un groupe de travail ne peut être effectuée que par un membre du groupe local Administrateurs sur l’ordinateur cible. Notez que l’administrateur de domaine peut définir des exigences supplémentaires pour rejoindre le domaine à l’aide de la délégation et de l’attribution de privilèges.

Si vous appelez la fonction NetJoinDomain à distance, vous devez fournir des informations d’identification, car vous ne pouvez pas déléguer d’informations d’identification dans ces circonstances.

Différents processus, ou différents threads du même processus, ne doivent pas appeler la fonction NetJoinDomain en même temps. Cette situation peut laisser l’ordinateur dans un état incohérent.

Si vous rencontrez un problème lors d’une opération de jointure, vous ne devez pas supprimer un compte d’ordinateur et suivre immédiatement la suppression avec une autre tentative de jointure. Cela peut entraîner des problèmes liés à la réplication qui sont difficiles à examiner. Lorsque vous supprimez un compte d’ordinateur, attendez que la modification ait été répliquée sur tous les contrôleurs de domaine avant de tenter une autre opération de jointure.

Un redémarrage du système est nécessaire après l’appel de la fonction NetJoinDomain pour que l’opération se termine.

Windows Server 2003 et Windows XP : Lorsqu’un appel à la fonction NetJoinDomain précède un appel à la fonction NetRenameMachineInDomain , vous devez différer la mise à jour des propriétés SPN et DnsHostName sur l’objet ordinateur jusqu’à l’opération de renommage. En effet, l’opération de jointure peut échouer dans certaines situations. Par exemple, le SPN dérivé du nom d’ordinateur actuel n’est pas valide dans le nouveau domaine auquel l’ordinateur est joint, mais le SPN dérivé du nouveau nom que l’ordinateur aura après l’opération de renommage est valide dans le nouveau domaine. Dans ce cas, l’appel à NetJoinDomain échoue, sauf si vous reportez la mise à jour des deux propriétés jusqu’à l’opération de renommage en spécifiant l’indicateur NETSETUP_DEFER_SPN_SET dans le paramètre fJoinOptions lorsque vous appelez NetJoinDomain.

Spécifications


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	lmjoin.h (include Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll