NetRequestOfflineDomainJoin, fonction (lmjoin.h)

Article
03/14/2023

La fonction NetRequestOfflineDomainJoin s’exécute localement sur un ordinateur pour modifier une image du système d’exploitation Windows montée sur un volume. Le Registre est chargé à partir de l’image et les données d’objet blob d’approvisionnement sont écrites où elles peuvent être récupérées pendant la phase d’achèvement d’une opération de jointure de domaine hors connexion.

Syntaxe

NET_API_STATUS NET_API_FUNCTION NetRequestOfflineDomainJoin(
  [in] BYTE    *pProvisionBinData,
  [in] DWORD   cbProvisionBinDataSize,
  [in] DWORD   dwOptions,
  [in] LPCWSTR lpWindowsPath
);

Paramètres

[in] pProvisionBinData

Pointeur vers une mémoire tampon requise pour initialiser le registre d’une image de système d’exploitation Windows afin de traiter le changement d’état local final pendant la phase d’achèvement de l’opération de jointure de domaine hors connexion.

L’objet blob binaire opaque des métadonnées sérialisées passées dans le paramètre pProvisionBinData est retourné par la fonction NetProvisionComputerAccount .

[in] cbProvisionBinDataSize

Taille, en octets, de la mémoire tampon pointée vers le paramètre pProvisionBinData .

Ce paramètre ne doit pas avoir la valeur NULL.

[in] dwOptions

Ensemble d’indicateurs de bits qui définissent des options pour cette fonction. 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_PROVISION_ONLINE_CALLER 0x40000000	Cet indicateur est requis si le paramètre lpWindowsPath fait référence au répertoire du système d’exploitation Windows en cours d’exécution plutôt qu’à une image du système d’exploitation Windows hors connexion montée sur un volume accessible. Si cet indicateur est spécifié, la fonction NetRequestOfflineDomainJoin doit être appelée par un membre du groupe Administrateurs local.

Valeur

Signification

NETSETUP_PROVISION_ONLINE_CALLER
0x40000000

Cet indicateur est requis si le paramètre lpWindowsPath fait référence au répertoire du système d’exploitation Windows en cours d’exécution plutôt qu’à une image du système d’exploitation Windows hors connexion montée sur un volume accessible. Si cet indicateur est spécifié, la fonction NetRequestOfflineDomainJoin doit être appelée par un membre du groupe Administrateurs local.

[in] lpWindowsPath

Pointeur vers une chaîne de caractères null constante qui spécifie le chemin d’accès à une image du système d’exploitation Windows sous laquelle se trouvent les ruches du Registre. Cette image doit être hors connexion et ne pas démarrer actuellement, sauf si le paramètre dwOptions contient NETSETUP_PROVISION_ONLINE_CALLER auquel cas le répertoire du système d’exploitation en cours d’exécution locale est autorisé.

Ce chemin peut être un chemin UNC sur un serveur distant.

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 ne dispose pas des privilèges suffisants pour terminer l’opération.
ERROR_ELEVATION_REQUIRED	L’opération demandée nécessite une élévation.
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est retournée si les paramètres pProvisionBinData, cbProvisionBinDataSize ou lpWindowsPath ont la valeur NULL. Cette erreur est également retournée si la mémoire tampon pointée vers par le paramètre pProvisionBinData ne contient pas de données valides dans l’objet blob pour le domaine, le nom du compte d’ordinateur ou le mot de passe du compte d’ordinateur. Cette erreur est également retournée si la chaîne pointée vers le paramètre lpWindowsPath ne spécifie pas le chemin d’accès à une image du système d’exploitation Windows.
ERROR_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette erreur est retournée si le serveur spécifié ne prend pas en charge cette opération. Par exemple, si le paramètre lpWindowsPath fait référence à une installation Windows configurée en tant que contrôleur de domaine.
NERR_WkstaNotStarted	Le service Station de travail n’a pas démarré.

Notes

La fonction NetRequestOfflineDomainJoin est prise en charge sur Windows 7 pour les opérations de jointure de domaine hors connexion.

La fonction NetRequestOfflineDomainJoin est utilisée localement sur un ordinateur pour modifier une image du système d’exploitation Windows montée sur un volume. Le Registre est chargé pour l’image et l’approvisionnement des données d’objets blob est écrit où elles peuvent être récupérées pendant la phase d’achèvement d’une opération de jointure de domaine hors connexion. Le scénario de jointure de domaine hors connexion utilise ces fonctions comme suit :

NetProvisionComputerAccount est une fonction d’approvisionnement qui est d’abord appelée pour effectuer les opérations réseau nécessaires à la création et à la configuration de l’objet ordinateur dans Active Directory. La sortie de NetProvisionComputerAccount est un objet blob binaire opaque de métadonnées sérialisées utilisées pour l’étape suivante.
NetRequestOfflineDomainJoin , une fonction d’initialisation d’image, est ensuite appelé pour injecter la sortie de la fonction d’approvisionnement NetProvisionComputerAccount dans une image du système d’exploitation Windows à utiliser pendant l’installation. Les modifications apportées au code d’initialisation Windows détectent cet état enregistré et affectent uniquement la partie locale de la jointure de domaine.

La fonction NetProvisionComputerAccount crée ou réutilise le compte d’ordinateur dans le domaine, collecte toutes les métadonnées nécessaires et les retourne dans un objet blob binaire opaque versionné ou sous forme de texte pour l’incorporation dans un fichier de réponses d’installation sans assistance. L’objet blob binaire opaque peut être consommé par l’opération de demande de jonction de domaine hors connexion fournissant toutes les entrées nécessaires pour terminer la jonction de domaine au premier démarrage sans aucune opération réseau (mises à jour d’état locales uniquement). Notez que l’objet blob contient essentiellement le contenu du mot de passe du compte d’ordinateur en clair. La conception ne prend aucune disposition pour la sécurisation de ces données. Ce problème existe aujourd’hui avec les fichiers de réponse d’installation sans assistance qui peuvent contenir un certain nombre de secrets, y compris les mots de passe utilisateur de domaine. L’appelant doit sécuriser l’objet blob et les fichiers d’installation sans assistance. Les solutions à ce problème sont variées. Par exemple, une clé pré-échangée peut être utilisée pour chiffrer une session entre le consommateur et l’entité d’approvisionnement, ce qui permet un transfert sécurisé de l’objet blob opaque .

L’objet blob opaque retourné dans le paramètre pProvisionBinData par la fonction NetProvisionComputerAccount est versionné pour permettre des scénarios d’interopérabilité et de facilité de maintenance entre différentes versions de Windows (jonction du client, machine d’approvisionnement et contrôleur de domaine). Actuellement, le scénario de jointure hors connexion ne limite pas la durée de vie de l’objet blob retourné par la fonction NetProvisionComputerAccount .

Pour plus d’informations sur les opérations de jointure de domaine hors connexion, consultez le Guide pas à pas de jointure de domaine hors connexion.

Spécifications


Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Aucun pris en charge
Plateforme cible	Windows
En-tête	lmjoin.h (include Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll