Freigeben über

Verwenden der Server-API der Windows-Bereitstellungsdienste

In Umgebungen, in denen die WDS-Standardlösung (Windows Deployment Services) nicht verwendet werden kann, macht der WDS-Server eine API verfügbar, mit der Entwickler Plug-Ins, die als Anbieter bezeichnet werden, schreiben können, um PXE-Anforderungen (Preboot Execution Environment) zu verarbeiten. Entwickler sollten sich beim Schreiben von PXE-Anbietern für WDS an die folgenden Richtlinien halten.

Installieren der WDS-Rolle auf dem Server

  • Windows-Bereitstellungsdienste (WDS) ist die überarbeitete Version von RemoteInstallation Services (RIS). Sie benötigen die WDS-Serverrolle, um den WDS PXE-Server und die Anbieter zu implementieren.
  • WDS ersetzt RIS als Standardkomponente ab Windows Server 2008 und Windows Server 2003 durch Service Pack 2 (SP2).
  • Sie müssen den RIS-Server auf WDS unter Windows Server 2003 mit Service Pack 1 (SP1) aktualisieren. Sie können die WDS-Serverrolle mit dem Windows Automated Installation Kit (WAIK) installieren.

Anbieter registrieren

  • Registrieren Sie die Anbieter-DLL (Provider Dynamic Link Library) während der Installation, und fügen Sie den Anbieter in die geordnete Liste der registrierten Anbieter ein.

    Hinweis

    Wenn Sie einen neuen oder geänderten Anbieter installieren, müssen Sie den WDS PXE-Dienst neu starten, damit die Änderungen wirksam werden.

     

  • Verwenden Sie die PxeProviderRegister-Funktion , um den Anbieter zu registrieren und der Liste hinzuzufügen. Verwenden Sie die PxeProviderUnRegister-Funktion , um die Registrierung eines registrierten Anbieters aufzuheben und aus der Liste zu entfernen.

  • Geben Sie die Reihenfolge des Anbieters in der sortierten Liste an. Der Index eines Anbieters in der Liste kann nicht garantiert werden, da später möglicherweise ein anderer Anbieter davor registriert wird. Um den Anbieter vor oder nach einem anderen registrierten Anbieter in die Liste einzufügen, verwenden Sie zuerst die PxeProviderQueryIndex-Funktion , um den Index des registrierten Anbieters abzurufen, und registrieren Sie dann den neuen Anbieter, während Sie einen größeren oder kleineren Indexwert angeben.

  • Die Installation kann Anbieterkonfigurationsinformationen unter dem Registrierungsschlüssel speichern, der bei der Registrierung des Anbieters zurückgegeben wird. Die Adresse des Registrierungsschlüssels wird vom phProviderKey von PxeProviderRegister empfangen. Der Anbieter empfängt ein Handle für denselben Schlüssel wie der hProviderKey-Parameter für seinen PxeProviderInitialize-Rückruf . Der Anbieter sollte die Adresse dieses Schlüssels speichern.

  • Installieren Sie immer die Anbieter-DLL (Provider Dynamic Link Library) im Ordner Programme des Servers.

Initialize

  • Schließen Sie eine DLL ein, die die Rückruffunktion PxeProviderInitialize im Anbieter exportiert. Jeder Anbieter erfordert einen PxeProviderInitialize-Rückruf . Wenn WDS einen Anbieter lädt, ruft er die PxeProviderInitialize-Funktion des Anbieters auf und übergibt ein Handle an denselben Schlüssel, der zum Speichern von Konfigurationsinformationen während der Anbieterregistrierung verwendet wird.
  • Wenn der PxeProviderInitialize-Rückruf zurückgibt und erfolgreich ist, sollte der Anbieter vollständig initialisiert und bereit für die Verarbeitung von Anforderungen sein.
  • Registrieren Sie jeden Rückruf im Anbieter während der Verarbeitung der PxeProviderInitialize-Funktion . Rückrufe sollten bei der Funktion PxeRegisterCallback registriert werden.
  • Initialisieren Sie alle internen Ressourcen des Anbieters innerhalb der Verarbeitung seiner PxeProviderInitialize-Funktion .

Shutdown

Verarbeiten von Anforderungspaketen

Implementieren Sie den PxeProviderRecvRequest-Rückruf für den Anbieter. Jeder Anbieter muss über einen PxeProviderRecvRequest-Rückruf verfügen. Wenn WDS eine Anforderung empfängt, wird der PxeProviderRecvRequest-Rückruf für den ersten Anbieter in der Liste der registrierten Anbieter aufgerufen.

  • Wenn der Anbieter diese Anforderung synchron verarbeitet, sollte die PxeProviderRecvRequest-Funktion den Wert ERROR_SUCCESS zurückgeben. Wenn der Anbieter diese Anforderung asynchron verarbeitet, sollte der PxeProviderRecvRequest-RückrufERROR_IO_PENDING zurückgeben und die PxeAsyncRecvDone-Funktion aufrufen, wenn die Anforderung verarbeitet wurde.

  • Der PxeProviderRecvRequest-Rückruf und die PxeAsyncRecvDone-Funktion geben die Adresse einer PXE_BOOT_ACTION Enum zurück, die die Aktion beschreibt, die vom Anbieter zur Verarbeitung der Anforderung ausgeführt wird.

    Es gibt vier Möglichkeiten für einen Anbieter, eine Anforderung zu verarbeiten:

    • Der Anbieter antwortet an den Client mit einem standardmäßigen DHCP-Antwortpaket, das einen Pfad zum Netzwerkstartprogramm enthält. Das Zurückgeben des PXE_BA_NBP Werts für die Enumeration bedeutet, dass der Anbieter das Anforderungspaket erfolgreich verarbeitet und die Anforderung abgeschlossen hat, indem er ein Antwortpaket sendet, indem er die Funktionen PxePacketAllocate und PxeSendReply aufruft .
    • Der Anbieter antwortet an den Client mit einem benutzerdefinierten Antwortpaket, das nicht dhcpkonform ist. Das Zurückgeben des PXE_BA_CUSTOM Werts für die Enumeration bedeutet, dass der Anbieter das Anforderungspaket erfolgreich verarbeitet und die Anforderung abgeschlossen hat, indem er ein benutzerdefiniertes Antwortpaket sendet, indem er die Funktionen PxePacketAllocate und PxeSendReply aufruft .
    • Der Anbieter legt fest, dass die Anforderung ignoriert werden soll. Das Zurückgeben des PXE_BA_IGNORE Werts für die Enumeration bedeutet, dass der Anbieter alle ressourcen freigegeben hat, die der Anforderung zugeordnet sind, und die Anforderung wird nicht an den nächsten Anbieter in der Liste der registrierten Anbieter übergeben. Anbieter können diese Option verwenden, wenn sie erkennen, dass ein Anforderungspaket ungültig ist.
    • Der Anbieter lehnt es ab, die Anforderung zu verarbeiten. Durch zurückgeben des PXE_BA_REJECT Werts für die Enumeration wird das System angewiesen, die Anforderung an den nächsten Anbieter in der Liste der registrierten Anbieter zu übergeben. Wenn dies der letzte Anbieter in der Liste war, werden alle Ressourcen freigegeben, die der Anforderung zugeordnet sind, und die Anforderung wird ignoriert.
    • Registrieren Sie den PxeProviderRecvRequest-Rückruf , indem Sie die PxeRegisterCallback-Funktion bei PXE_CALLBACK_RECV_REQUEST während der Verarbeitung des PxeProviderInitialize-Rückrufs aufrufen.

Generieren eines Antwortpakets

  • Verwenden Sie die API, um Anbieter zu schreiben, um DHCP-Anforderungen zu verarbeiten und Antwortpakete zu generieren.
  • Die PxeProviderSetAttribute-Funktion gibt die Attribute an, die vom Anbieter zum Filtern von Paketen verwendet werden. Die Attribute des Anbieters können angegeben werden, sodass der Anbieter alle Pakete anzeigt, der Anbieter nur DHCP-Pakete sieht oder der Anbieter nur DHCP-Pakete sieht, die die Option DHCP-Anbieterklassenbezeichner (60) als "PXEClient" angeben.
  • Die PxeDhcpIsValid-Funktion überprüft, ob ein Paket ein gültiges DHCP-Paket ist. Anbieter können die PxeDhcpIsValid-Funktion verwenden, um zu überprüfen, ob ein Paket vom Client ein DHCP-Paket ist, wenn der Filtersatz mit der PxeProviderSetAttribute-Funktion festgelegt ist, um alle Pakete zu empfangen, um zu bestimmen, ob ein angegebenes Paket ein gültiges DHCP-Paket ist.
  • Die PxeDhcpInitialize-Funktion initialisiert ein Antwortpaket als DHCP-Antwortpaket, das auf den Informationen in einem paket basiert, das vom Client empfangen wird. Die PxeProviderInitialize-Funktion übernimmt die Adresse eines gültigen DHCP-Pakets, das vom Client im PxeProviderRecvRequest-Rückruf empfangen wurde. Die PxeDhcpInitialize-Funktion verwendet einen Zeiger auf ein Antwortpaket, das der PxePacketAllocate-Funktion zugeordnet ist.
  • Die PxeDhcpGetOptionValue-Funktion ruft einen Optionswert aus einem DHCP-Paket ab. Die PxeDhcpGetVendorOptionValue-Funktion ruft einen Optionswert aus dem Feld Anbieterspezifische Informationen (43) eines DHCP-Pakets ab.
  • Der Anbieter kann dann das Antwortpaket mit Informationen auffüllen und die PxeSendReply-Funktion verwenden, um das Antwortpaket an den Client zu senden. Die PxeDhcpAppendOption-Funktion fügt eine DHCP-Option an das Antwortpaket an.
  • Ein Anbieter, der auf Clientanforderungen antwortet, indem er ein Paket sendet, muss das Antwortpaket mithilfe der PxePacketAllocate-Funktion zuordnen. Der Anbieter kann dann das Antwortpaket mit Informationen auffüllen und die PxeSendReply-Funktion verwenden, um das Antwortpaket an den Client zu senden.
  • Wenn der zugewiesene Arbeitsspeicher nicht mehr benötigt wird, sollte der Anbieter ihn mithilfe der PxePacketFree-Funktion freigeben.

Auflisten registrierter Anbieter

  • Verwenden Sie die API, um Anbieter zu schreiben, die andere registrierte Anbieter in der Liste auflisten und überprüfen.
  • Die PxeGetServerInfo-Funktion gibt Informationen zum PXE-Server zurück. Die PxeGetServerInfo-Funktion gibt eine BOOL zurück, die angibt, ob die Ablaufverfolgung für den Server aktiviert ist. TRUE gibt an, dass die Ablaufverfolgung aktiviert ist.
  • Die PxeProviderEnumFirst-Funktion startet eine Enumeration von Anbietern in der Liste der registrierten Anbieter. Die PxeProviderEnumFirst-Funktion startet die Enumeration und gibt die Adresse des Handles zurück, die beim Aufrufen der PxeProviderEnumNext-Funktion verwendet werden soll. Die PxeProviderEnumNext-Funktion gibt eine PXE_PROVIDER-Struktur zurück, die die Informationen zum Anbieter enthält. Die PxeProviderFreeInfo-Funktion gibt den Arbeitsspeicher frei, der für die PXE_PROVIDER-Struktur von der PxeProviderEnumNext-Funktion zugewiesen wurde. Die PxeProviderEnumClose-Funktion schließt die Enumeration der Anbieter in der Liste der registrierten Anbieter.

Behandeln von Dienststeuerungscodes

Hinzufügen von Ablaufverfolgungseinträgen zum PXE-Protokoll

  • Die PxeTrace-Funktion fügt dem PXE-Protokoll einen Ablaufverfolgungseintrag hinzu. WDSPXE bietet Ablaufverfolgung, um Administratoren bei der Problembehandlung zu unterstützen. Anbieter können Ablaufverfolgungseinträge mit unterschiedlichen Schweregraden protokollieren. Die Administratoren können WDSPXE so konfigurieren, dass nur Einträge für bestimmte Schweregrade protokolliert werden.

Informationen zur Windows-Bereitstellungsdienste-API

Verwenden der Client-API der Windows-Bereitstellungsdienste