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

Dans les environnements où la solution WDS (Standard Windows Deployment Services) 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 requêtes 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

  • Windows Deployment Services (WDS) est la version révisée des services d’installation à distance (RIS), vous aurez besoin du rôle de serveur WDS pour implémenter le serveur et les fournisseurs WDS PXE.
  • WDS remplace RIS comme composant standard commençant par Windows Server 2008 et Windows Server 2003 par Service Pack 2 (SP2).
  • Vous devez mettre à jour le serveur RIS sur WDS sur Windows Server 2003 avec Service Pack 1 (SP1). Vous pouvez installer le rôle de serveur WDS avec le Kit d'installation automatisée (Windows AIK) (WAIK).

Inscrire des fournisseurs

  • Inscrivez la bibliothèque de liens dynamiques du fournisseur (DLL) pendant son installation et insérez le fournisseur dans la liste ordonné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 la supprimer de la liste.

  • Spécifiez la séquence du fournisseur dans la liste ordonnée. L’index d’un fournisseur dans la liste ne peut pas être garanti, car un autre fournisseur peut être inscrit ultérieurement avant celui-ci. 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 inscrire le nouveau fournisseur tout en spécifiant une valeur d’index plus grande ou plus petite.

  • L’installation peut stocker les informations de configuration du fournisseur sous la clé de Registre retournée lorsque le fournisseur est inscrit. L’adresse de la clé de Registre est reçue par le phProviderKey de PxeProviderRegister. Le fournisseur reçoit un handle à 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 du fournisseur (DLL) dans le dossier Program Files du serveur.

Initialiser

  • 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é utilisée pour stocker les informations de configuration pendant 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 .
  • Initialiser toutes les ressources internes du fournisseur au sein du traitement de sa fonction PxeProviderInitialize .

Shutdown

Gérer le paquet de requête

Implémentez le rappel PxeProviderRecvRequest pour le fournisseur. Chaque fournisseur doit disposer d’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 façon synchrone, la fonction PxeProviderRecvRequest doit retourner une valeur de ERROR_SUCCESS. Si et uniquement si le fournisseur traite cette requête de manière asynchrone, le rappel PxeProviderRecvRequest doit retourner ERROR_IO_PENDING et appeler la fonction PxeAsyncRecvDone lorsque la requête a été traitée.

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

    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’énumération signifie que le fournisseur a correctement traité le paquet de demande et 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 à DHCP. Le renvoi de la valeur PXE_BA_CUSTOM pour l’énumération signifie que le fournisseur a correctement traité le paquet de demande et 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’énumération signifie que le fournisseur a libéré toutes les ressources associées à la demande et que la demande n’est pas transmise 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’agissait du dernier fournisseur de la liste, cela libère toutes les ressources associées à la demande 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 pour gérer la demande DHCP et 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 des paquets DHCP qui spécifient l’option d’identificateur de classe de fournisseur DHCP (60) comme « PXEClient ».
  • La fonction PxeDhcpIsValid vérifie qu’un paquet est un paquet DHCP valide. Les fournisseurs peuvent utiliser la fonction PxeDhcpIsValid pour vérifier si un paquet du client est un paquet DHCP lorsque le filtre défini avec la fonction PxeProviderSetAttribute est défini pour recevoir tous les paquets pour 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 d’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 clientes 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 le libérer à l’aide de la fonction PxePacketFree .

Énumérer les fournisseurs inscrits

  • Utilisez l’API pour écrire des fournisseurs qui énumèrent et vérifient 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 de 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 pour 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 le suivi pour aider les administrateurs à résoudre les problèmes. Les fournisseurs peuvent enregistrer les entrées de trace de différents niveaux de gravité. Les administrateurs peuvent configurer WDSPXE pour enregistrer uniquement les entrées de journalisation 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