Condividi tramite

Uso dell'API server di Servizi di distribuzione Windows

  • Articolo

Negli ambienti in cui la soluzione WDS (Windows Deployment Services) standard non può essere usata, il server WDS espone un'API che consente agli sviluppatori di scrivere plug-in, denominati provider, per gestire le richieste PXE (Preboot Execution Environment). Gli sviluppatori devono rispettare le linee guida seguenti quando si scrivono provider PXE per WDS.

Installare il ruolo WDS nel server

  • Servizi di distribuzione Windows (WDS) è la versione modificata di Servizi di installazione remota (RIS), sarà necessario il ruolo del server WDS per implementare il server e i provider WDS PXE.
  • WDS sostituisce RIS come componente standard a partire da Windows Server 2008 e Windows Server 2003 con Service Pack 2 (SP2).
  • È necessario aggiornare il server RIS a WDS in Windows Server 2003 con Service Pack 1 (SP1). È possibile installare il ruolo del server WDS con Windows Automated Installation Kit (WAIK).

Registrare i provider

  • Registrare la libreria di collegamento dinamico del provider durante l'installazione e inserire il provider nell'elenco ordinato di provider registrati.

    Nota

    Quando si installa un nuovo provider o modificato, è necessario riavviare il servizio WDS PXE per rendere effettive le modifiche.

     

  • Usare la funzione PxeProviderRegister per registrare il provider e aggiungerlo all'elenco. Usare la funzione PxeProviderUnRegister per annullare la registrazione di un provider registrato e rimuoverla dall'elenco.

  • Specificare la sequenza del provider nell'elenco ordinato. L'indice di un provider nell'elenco non può essere garantito perché un altro provider può essere registrato in un secondo momento prima. Per inserire il provider nell'elenco prima o dopo un altro provider registrato, usare prima la funzione PxeProviderQueryIndex per ottenere l'indice del provider registrato e quindi registrare il nuovo provider specificando un valore di indice più grande o minore.

  • L'installazione può archiviare le informazioni di configurazione del provider nella chiave del Registro di sistema restituita al momento della registrazione del provider. L'indirizzo della chiave del Registro di sistema viene ricevuto dal phProviderKey di PxeProviderRegister. Il provider riceve un handle per questa stessa chiave del parametro hProviderKey per il callback PxeProviderInitialize . Il provider deve archiviare l'indirizzo di questa chiave.

  • Installare sempre la libreria di collegamento dinamica del provider nella cartella Programmi del server.

Initialize

  • Includere una DLL che esporta la funzione di callback PxeProviderInitialize nel provider. Ogni provider richiede un callback PxeProviderInitialize . Quando WDS carica un provider, chiama la funzione PxeProviderInitialize del provider e passa un handle alla stessa chiave usata per archiviare le informazioni di configurazione durante la registrazione del provider.
  • Quando il callback PxeProviderInitialize restituisce e ha esito positivo, il provider deve essere completamente inizializzato e pronto per elaborare le richieste.
  • Registrare ogni callback nel provider durante l'elaborazione della funzione PxeProviderInitialize . I callback devono essere registrati con la funzione PxeRegisterCallback .
  • Inizializzare tutte le risorse interne del provider all'interno dell'elaborazione della funzione PxeProviderInitialize .

Shutdown

  • Implementare il callback PxeProviderShutdown . Ogni provider è necessario per avere un callback PxeProviderShutdown.
  • La funzione di callback PxeProviderShutdown deve arrestare completamente il provider e rilasciare tutte le relative risorse.
  • Dopo che il callback PxeProviderShutdown restituisce, l'handle hProvider passato alla funzione PxeProviderInitialize non è più valido e non deve essere usato per chiamare WDS.
  • Registrare il callback PxeProviderShutdown chiamando la funzione PxeRegisterCallback con PXE_CALLBACK_SHUTDOWN durante l'elaborazione del callback PxeProviderInitialize . Non chiamare il callback PxeProviderShutdown se la funzione PxeProviderInitialize ha esito negativo.

Gestire i pacchetti di richiesta

Implementare il callback PxeProviderRecvRequest per il provider. Ogni provider deve avere un callback PxeProviderRecvRequest . Quando WDS riceve una richiesta, chiama il callback PxeProviderRecvRequest per il primo provider nell'elenco dei provider registrati.

  • Se il provider elabora questa richiesta in modo sincrono, la funzione PxeProviderRecvRequest deve restituire un valore di ERROR_SUCCESS. Se e solo se il provider elabora questa richiesta in modo asincrono, il callback PxeProviderRecvRequest deve restituire ERROR_IO_PENDING e chiamare la funzione PxeAsyncRecvDone quando la richiesta è stata elaborata.

  • Il callback PxeProviderRecvRequest e la funzione PxeAsyncRecvDone restituisce l'indirizzo di un PXE_BOOT_ACTION enumerazione che descrive l'azione eseguita dal provider per gestire la richiesta.

    Esistono quattro modi per gestire una richiesta da parte di un provider:

    • Il provider risponde al client con un pacchetto di risposta DHCP standard che contiene un percorso al programma di avvio di rete. La restituzione del valore PXE_BA_NBP per l'enumerazione significa che il provider ha elaborato correttamente il pacchetto di richiesta e completato la richiesta inviando un pacchetto di risposta chiamando le funzioni PxePacketAllocate e PxeSendReply .
    • Il provider risponde al client con un pacchetto di risposta personalizzato che non è conforme a DHCP. La restituzione del valore di PXE_BA_CUSTOM per l'enumerazione significa che il provider ha elaborato correttamente il pacchetto di richiesta e completato la richiesta inviando un pacchetto di risposta personalizzato chiamando le funzioni PxePacketAllocate e PxeSendReply .
    • Il provider determina che la richiesta deve essere ignorata. La restituzione del valore PXE_BA_IGNORE per l'enumerazione indica che il provider ha rilasciato tutte le risorse associate alla richiesta e la richiesta non viene passata al provider successivo nell'elenco dei provider registrati. I provider possono usare questa opzione se rilevano che un pacchetto di richiesta non è valido.
    • Il provider rifiuta di eseguire il servizio della richiesta. La restituzione del valore di PXE_BA_REJECT per l'enumerazione indica al sistema di passare la richiesta al provider successivo nell'elenco dei provider registrati. Se si tratta dell'ultimo provider nell'elenco, questa rilascia tutte le risorse associate alla richiesta e la richiesta viene ignorata.
    • Registrare il callback PxeProviderRecvRequest chiamando la funzione PxeRegisterCallback con PXE_CALLBACK_RECV_REQUEST durante l'elaborazione del callback PxeProviderInitialize .

Generare pacchetti di risposta

  • Usare l'API per scrivere provider per gestire la richiesta DHCP e generare pacchetti di risposta.
  • La funzione PxeProviderSetAttribute specifica gli attributi usati dal provider per filtrare i pacchetti. Gli attributi del provider possono essere specificati in modo che il provider veda tutti i pacchetti, il provider vede solo pacchetti DHCP o il provider vede solo pacchetti DHCP che specificano l'opzione Identificatore classe fornitore DHCP (60) come "PXEClient".
  • La funzione PxeDhcpIsValid verifica che un pacchetto sia un pacchetto DHCP valido. I provider possono usare la funzione PxeDhcpIsValid per verificare se un pacchetto dal client è un pacchetto DHCP quando il set di filtri con la funzione PxeProviderSetAttribute è impostato per ricevere tutti i pacchetti per determinare se un pacchetto specificato è un pacchetto DHCP valido.
  • La funzione PxeDhcpInitialize inizializza un pacchetto di risposta come pacchetto di risposta DHCP basato sulle informazioni in un pacchetto ricevuto dal client. La funzione PxeProviderInitialize accetta l'indirizzo di un pacchetto DHCP valido ricevuto dal client nel callback PxeProviderRecvRequest . La funzione PxeDhcpInitialize accetta un puntatore a un pacchetto di risposta allocato con la funzione PxePacketAllocate .
  • La funzione PxeDhcpGetOptionValue recupera un valore di opzione da un pacchetto DHCP. La funzione PxeDhcpGetVendorOptionValue recupera un valore di opzione dal campo Informazioni specifiche del fornitore (43) di un pacchetto DHCP.
  • Il provider può quindi popolare il pacchetto di risposta con informazioni e usare la funzione PxeSendReply per inviare il pacchetto di risposta al client. La funzione PxeDhcpAppendOption aggiunge un'opzione DHCP al pacchetto di risposta.
  • Un provider che risponde alle richieste client inviando un pacchetto deve allocare il pacchetto di risposta usando la funzione PxePacketAllocate . Il provider può quindi popolare il pacchetto di risposta con informazioni e usare la funzione PxeSendReply per inviare il pacchetto di risposta al client.
  • Quando la memoria allocata non è più necessaria, il provider deve rilasciarlo usando la funzione PxePacketFree .

Enumerare i provider registrati

  • Usare l'API per scrivere provider che enumerare e controllare altri provider registrati nell'elenco.
  • La funzione PxeGetServerInfo restituisce informazioni sul server PXE. La funzione PxeGetServerInfo restituisce un valore BOOL che indica se la traccia è abilitata per il server. TRUE indica che la traccia è abilitata.
  • La funzione PxeProviderEnumFirst avvia un'enumerazioneof provider nell'elenco dei provider registrati. La funzione PxeProviderEnumFirst avvia l'enumerazione e restituisce l'indirizzo dell'handle che deve essere usato quando si chiama la funzione PxeProviderEnumNext . La funzione PxeProviderEnumNext restituisce una struttura PXE_PROVIDER contenente le informazioni sul provider. La funzione PxeProviderFreeInfo libera la memoria allocata per la struttura PXE_PROVIDER dalla funzione PxeProviderEnumNext . La funzione PxeProviderEnumClose chiude l'enumerazione dei provider nell'elenco dei provider registrati.

Gestire i codici di controllo del servizio

Aggiungere voci di traccia al log PXE

  • La funzione PxeTrace aggiunge una voce di traccia al log PXE. WDSPXE fornisce la traccia per aiutare gli amministratori a risolvere i problemi. I provider possono registrare voci di traccia di livelli di gravità diversi. Gli amministratori possono configurare WDSPXE per registrare solo le voci per determinati livelli di gravità.

Informazioni sull'API servizi di distribuzione Windows

Uso dell'API client di Servizi di distribuzione Windows