Partager via

Utilisation de l’API du serveur des Services de déploiement Windows

  • Article

Dans les environnements où la solution standard des services de déploiement Windows (WDS) ne peut pas être utilisée, le serveur WDS expose une API qui permet aux développeurs d’écrire des plug-ins, appelés fournisseurs, pour gérer les demandes PXE (preboot execution environment). Les développeurs doivent respecter les instructions suivantes lors de l’écriture de fournisseurs PXE pour WDS.

Installer le rôle WDS sur le serveur

  • Les services de déploiement Windows (WDS) sont la version révisée des services d’installation à distance (RIS). Vous aurez besoin du rôle serveur WDS pour implémenter le serveur et les fournisseurs WDS PXE.
  • WDS remplace RIS en tant que composant standard à partir de Windows Server 2008 et Windows Server 2003 avec Service Pack 2 (SP2).
  • Vous devez mettre à jour le serveur RIS vers WDS sur Windows Server 2003 avec Service Pack 1 (SP1). Vous pouvez installer le rôle serveur WDS avec le Kit d'installation automatisée (Windows AIK) (WAIK).

Inscrire des fournisseurs

  • Inscrivez la bibliothèque de liens dynamiques (DLL) du fournisseur lors de son installation et insérez le fournisseur dans la liste triée des fournisseurs inscrits.

    Notes

    Lorsque vous installez un fournisseur nouveau ou modifié, vous devez redémarrer le service WDS PXE pour que les modifications prennent effet.

     

  • Utilisez la fonction PxeProviderRegister pour inscrire le fournisseur et l’ajouter à la liste. Utilisez la fonction PxeProviderUnRegister pour annuler l’inscription d’un fournisseur inscrit et le supprimer de la liste.

  • Spécifiez la séquence du fournisseur dans la liste triée. L’index d’un fournisseur dans la liste ne peut pas être garanti, car un autre fournisseur peut être inscrit ultérieurement avant lui. Pour insérer le fournisseur dans la liste avant ou après un autre fournisseur inscrit, utilisez d’abord la fonction PxeProviderQueryIndex pour obtenir l’index du fournisseur inscrit, puis inscrivez le nouveau fournisseur tout en spécifiant une valeur d’index plus ou plus petite.

  • L’installation peut stocker les informations de configuration du fournisseur sous la clé de Registre retournée lors de l’inscription du fournisseur. L’adresse de la clé de Registre est reçue par le phProviderKey de PxeProviderRegister. Le fournisseur reçoit un handle pour cette même clé que le paramètre hProviderKey à son rappel PxeProviderInitialize . Le fournisseur doit stocker l’adresse de cette clé.

  • Installez toujours la bibliothèque de liens dynamiques (DLL) du fournisseur dans le dossier Program Files du serveur.

Initialize

  • Incluez une DLL qui exporte la fonction de rappel PxeProviderInitialize dans le fournisseur. Chaque fournisseur nécessite un rappel PxeProviderInitialize . Lorsque WDS charge un fournisseur, il appelle la fonction PxeProviderInitialize du fournisseur et transmet un handle à la même clé que celle utilisée pour stocker les informations de configuration lors de l’inscription du fournisseur.
  • Lorsque le rappel PxeProviderInitialize retourne et réussit, le fournisseur doit être entièrement initialisé et prêt à traiter les demandes.
  • Inscrivez chaque rappel dans le fournisseur pendant le traitement de la fonction PxeProviderInitialize . Les rappels doivent être inscrits auprès de la fonction PxeRegisterCallback .
  • Initialisez toutes les ressources internes du fournisseur dans le traitement de sa fonction PxeProviderInitialize .

Shutdown

Gérer le paquet de requête

Implémentez le rappel PxeProviderRecvRequest pour le fournisseur. Chaque fournisseur doit avoir un rappel PxeProviderRecvRequest . Lorsque WDS reçoit une demande, il appelle le rappel PxeProviderRecvRequest pour le premier fournisseur de la liste des fournisseurs inscrits.

  • Si le fournisseur traite cette requête de manière synchrone, la fonction PxeProviderRecvRequest doit retourner une valeur de ERROR_SUCCESS. Si et seulement si le fournisseur traite cette requête de façon asynchrone, le rappel PxeProviderRecvRequest doit retourner ERROR_IO_PENDING et appeler la fonction PxeAsyncRecvDone lorsque la demande a été traitée.

  • Le rappel PxeProviderRecvRequest et la fonction PxeAsyncRecvDone retournent l’adresse d’une énumération PXE_BOOT_ACTION qui décrit l’action effectuée par le fournisseur pour gérer la demande.

    Il existe quatre façons pour un fournisseur de gérer une demande :

    • Le fournisseur répond au client avec un paquet de réponse DHCP standard qui contient un chemin d’accès au programme de démarrage réseau. Le renvoi de la valeur PXE_BA_NBP pour l’enum signifie que le fournisseur a correctement traité le paquet de la demande et a terminé la demande en envoyant un paquet de réponse en appelant les fonctions PxePacketAllocate et PxeSendReply .
    • Le fournisseur répond au client avec un paquet de réponse personnalisé qui n’est pas conforme au protocole DHCP. Le renvoi de la valeur PXE_BA_CUSTOM pour l’enum signifie que le fournisseur a correctement traité le paquet de la demande et a terminé la demande en envoyant un paquet de réponse personnalisé en appelant les fonctions PxePacketAllocate et PxeSendReply .
    • Le fournisseur détermine que la demande doit être ignorée. Le renvoi de la valeur PXE_BA_IGNORE pour l’enum signifie que le fournisseur a libéré toutes les ressources associées à la demande et que la demande n’est pas passée au fournisseur suivant dans la liste des fournisseurs inscrits. Les fournisseurs peuvent utiliser cette option s’ils détectent qu’un paquet de requête n’est pas valide.
    • Le fournisseur refuse de traiter la demande. Le renvoi de la valeur PXE_BA_REJECT pour l’énumération indique au système de transmettre la demande au fournisseur suivant dans la liste des fournisseurs inscrits. S’il s’agit du dernier fournisseur de la liste, toutes les ressources associées à la demande sont alors libérés et la demande est ignorée.
    • Inscrivez le rappel PxeProviderRecvRequest en appelant la fonction PxeRegisterCallback avec PXE_CALLBACK_RECV_REQUEST pendant le traitement du rappel PxeProviderInitialize .

Générer un paquet de réponse

  • Utilisez l’API pour écrire des fournisseurs afin de gérer les requêtes DHCP et de générer des paquets de réponse.
  • La fonction PxeProviderSetAttribute spécifie les attributs utilisés par le fournisseur pour filtrer les paquets. Les attributs du fournisseur peuvent être spécifiés afin que le fournisseur voit tous les paquets, le fournisseur ne voit que les paquets DHCP, ou le fournisseur ne voit que les paquets DHCP qui spécifient l’option Dhcp Vendor Class Identifier (60) comme « PXEClient ».
  • La fonction PxeDhcpIsValid vérifie qu’un paquet est un paquet DHCP valide. Les fournisseurs peuvent utiliser la fonction PxeDhcpIsValid pour case activée si un paquet du client est un paquet DHCP lorsque le jeu de filtres avec la fonction PxeProviderSetAttribute est défini pour recevoir tous les paquets afin de déterminer si un paquet spécifié est un paquet DHCP valide.
  • La fonction PxeDhcpInitialize initialise un paquet de réponse en tant que paquet de réponse DHCP basé sur les informations contenues dans un paquet reçu du client. La fonction PxeProviderInitialize prend l’adresse d’un paquet DHCP valide reçu du client dans le rappel PxeProviderRecvRequest . La fonction PxeDhcpInitialize prend un pointeur vers un paquet de réponse alloué avec la fonction PxePacketAllocate .
  • La fonction PxeDhcpGetOptionValue récupère une valeur d’option à partir d’un paquet DHCP. La fonction PxeDhcpGetVendorOptionValue récupère une valeur d’option à partir du champ Informations spécifiques du fournisseur (43) d’un paquet DHCP.
  • Le fournisseur peut ensuite remplir le paquet de réponse avec des informations et utiliser la fonction PxeSendReply pour envoyer le paquet de réponse au client. La fonction PxeDhcpAppendOption ajoute une option DHCP au paquet de réponse.
  • Un fournisseur qui répond aux demandes du client en envoyant un paquet doit allouer le paquet de réponse à l’aide de la fonction PxePacketAllocate . Le fournisseur peut ensuite remplir le paquet de réponse avec des informations et utiliser la fonction PxeSendReply pour envoyer le paquet de réponse au client.
  • Lorsque la mémoire allouée n’est plus nécessaire, le fournisseur doit la libérer à l’aide de la fonction PxePacketFree .

Énumérer les fournisseurs inscrits

  • Utilisez l’API pour écrire des fournisseurs qui énumèrent et case activée d’autres fournisseurs inscrits dans la liste.
  • La fonction PxeGetServerInfo retourne des informations sur le serveur PXE. La fonction PxeGetServerInfo retourne un BOOL qui indique si le suivi est activé pour le serveur. TRUE indique que le suivi est activé.
  • La fonction PxeProviderEnumFirst démarre une énumération des fournisseurs dans la liste des fournisseurs inscrits. La fonction PxeProviderEnumFirst démarre l’énumération et retourne l’adresse du handle qui doit être utilisé lors de l’appel de la fonction PxeProviderEnumNext . La fonction PxeProviderEnumNext retourne une structure PXE_PROVIDER contenant les informations sur le fournisseur. La fonction PxeProviderFreeInfo libère la mémoire allouée à la structure PXE_PROVIDER par la fonction PxeProviderEnumNext . La fonction PxeProviderEnumClose ferme l’énumération des fournisseurs dans la liste des fournisseurs inscrits.

Gérer les codes de contrôle de service

Ajouter des entrées de trace au journal PXE

  • La fonction PxeTrace ajoute une entrée de trace au journal PXE. WDSPXE fournit un suivi pour aider les administrateurs à résoudre les problèmes. Les fournisseurs peuvent enregistrer des entrées de trace de différents niveaux de gravité. Les administrateurs peuvent configurer WDSPXE pour journaliser uniquement les entrées pour certains niveaux de gravité.

À propos de l’API Des services de déploiement Windows

Utilisation de l’API du client des Services de déploiement Windows