Uso da API de servidor de Serviços de Implantação do Windows

  • Artigo

Em ambientes em que a solução padrão dos Serviços de Implantação do Windows (WDS) não pode ser usada, o servidor WDS expõe uma API que permite que os desenvolvedores escrevam plug-ins, conhecidos como provedores, para lidar com solicitações de PXE (ambiente de execução de pré-inicialização). Os desenvolvedores devem seguir as diretrizes a seguir ao escrever provedores PXE para WDS.

Instalar a função WDS no servidor

  • O WDS (Serviços de Implantação do Windows) é a versão revisada dos RIS (Serviços de Instalação Remota), você precisará da função de servidor WDS para implementar o servidor e os provedores PXE do WDS.
  • O WDS substitui o RIS como o componente padrão a partir do Windows Server 2008 e do Windows Server 2003 pelo Service Pack 2 (SP2).
  • Você deve atualizar o servidor RIS para o WDS no Windows Server 2003 com Service Pack 1 (SP1). Você pode instalar a função de servidor WDS com o WAIK (Kit de Instalação Automatizada do Windows).

Registrar provedores

  • Registre a DLL (biblioteca de vínculo dinâmico) do provedor durante sua instalação e insira o provedor na lista ordenada de provedores registrados.

    Observação

    Ao instalar um provedor novo ou modificado, você precisará reiniciar o serviço PXE do WDS para que as alterações entrem em vigor.

     

  • Use a função PxeProviderRegister para registrar o provedor e adicioná-lo à lista. Use a função PxeProviderUnRegister para cancelar o registro de um provedor registrado e removê-lo da lista.

  • Especifique a sequência do provedor na lista ordenada. O índice de um provedor na lista não pode ser garantido porque outro provedor pode ser registrado posteriormente antes dele. Para inserir o provedor na lista antes ou depois de outro provedor registrado, primeiro use a função PxeProviderQueryIndex para obter o índice do provedor registrado e, em seguida, registre o novo provedor ao especificar um valor de índice maior ou menor.

  • A instalação pode armazenar informações de configuração do provedor sob a chave do Registro retornada quando o provedor é registrado. O endereço da chave do Registro é recebido pelo phProviderKey de PxeProviderRegister. O provedor recebe um identificador para essa mesma chave que o parâmetro hProviderKey para seu retorno de chamada PxeProviderInitialize . O provedor deve armazenar o endereço dessa chave.

  • Sempre instale a DLL (biblioteca de vínculo dinâmico) do provedor na pasta Arquivos de Programas do servidor.

Initialize

  • Inclua uma DLL que exporta a função de retorno de chamada PxeProviderInitialize no provedor. Cada provedor requer um retorno de chamada PxeProviderInitialize . Quando o WDS carrega um provedor, ele chama a função PxeProviderInitialize do provedor e passa um identificador para a mesma chave usada para armazenar informações de configuração durante o registro do provedor.
  • Quando o retorno de chamada PxeProviderInitialize retorna e é bem-sucedido, o provedor deve ser totalmente inicializado e pronto para processar solicitações.
  • Registre cada retorno de chamada no provedor durante o processamento da função PxeProviderInitialize . Os retornos de chamada devem ser registrados com a função PxeRegisterCallback .
  • Inicialize todos os recursos internos do provedor no processamento de sua função PxeProviderInitialize .

Shutdown

  • Implemente o retorno de chamada PxeProviderShutdown . Cada provedor precisa ter um retorno de chamada PxeProviderShutdown.
  • A função de retorno de chamada PxeProviderShutdown deve desligar totalmente o provedor e liberar todos os seus recursos.
  • Depois que o retorno de chamada PxeProviderShutdown retorna, o identificador hProvider passado para a função PxeProviderInitialize não é mais válido e não deve ser usado para chamar o WDS.
  • Registre o retorno de chamada PxeProviderShutdown chamando a função PxeRegisterCallback com PXE_CALLBACK_SHUTDOWN durante o processamento do retorno de chamada PxeProviderInitialize . Não chame o retorno de chamada PxeProviderShutdown se a função PxeProviderInitialize falhar.

Manipular pacote de solicitação

Implemente o retorno de chamada PxeProviderRecvRequest para o provedor. Cada provedor precisa ter um retorno de chamada PxeProviderRecvRequest . Quando o WDS recebe uma solicitação, ele chama o retorno de chamada PxeProviderRecvRequest para o primeiro provedor na lista de provedores registrados.

  • Se o provedor processar essa solicitação de forma síncrona, a função PxeProviderRecvRequest deverá retornar um valor de ERROR_SUCCESS. Se e somente se o provedor processar essa solicitação de forma assíncrona, o retorno de chamada PxeProviderRecvRequest deverá retornar ERROR_IO_PENDING e chamar a função PxeAsyncRecvDone quando a solicitação for processada.

  • O retorno de chamada PxeProviderRecvRequest e a função PxeAsyncRecvDone retornam o endereço de uma enumeração PXE_BOOT_ACTION que descreve a ação executada pelo provedor para lidar com a solicitação.

    Há quatro maneiras de um provedor lidar com uma solicitação:

    • O provedor responde ao cliente com um pacote de resposta DHCP padrão que contém um caminho para o Programa de Inicialização de Rede. Retornar o valor PXE_BA_NBP para a enumeração significa que o provedor processou com êxito o pacote de solicitação e concluiu a solicitação enviando um pacote de resposta chamando as funções PxePacketAllocate e PxeSendReply .
    • O provedor responde ao cliente com um pacote de resposta personalizado que não está em conformidade com o DHCP. Retornar o valor PXE_BA_CUSTOM para a enumeração significa que o provedor processou com êxito o pacote de solicitação e concluiu a solicitação enviando um pacote de resposta personalizado chamando as funções PxePacketAllocate e PxeSendReply .
    • O provedor determina que a solicitação deve ser ignorada. Retornar o valor PXE_BA_IGNORE para a enumeração significa que o provedor liberou todos os recursos associados à solicitação e a solicitação não é passada para o próximo provedor na lista de provedores registrados. Os provedores poderão usar essa opção se detectarem que um pacote de solicitação é inválido.
    • O provedor se recusa a atender à solicitação. Retornar o valor PXE_BA_REJECT para a enumeração instrui o sistema a passar a solicitação para o próximo provedor na lista de provedores registrados. Se esse for o último provedor na lista, isso liberará todos os recursos associados à solicitação e a solicitação será ignorada.
    • Registre o retorno de chamada PxeProviderRecvRequest chamando a função PxeRegisterCallback com PXE_CALLBACK_RECV_REQUEST durante o processamento do retorno de chamada PxeProviderInitialize .

Gerar pacote de resposta

  • Use a API para gravar provedores para lidar com a solicitação DHCP e gerar pacotes de resposta.
  • A função PxeProviderSetAttribute especifica os atributos usados pelo provedor para filtrar pacotes. Os atributos do provedor podem ser especificados para que o provedor veja todos os pacotes, o provedor vê apenas pacotes DHCP ou o provedor vê apenas pacotes DHCP que especificam a opção identificador de classe de fornecedor DHCP (60) como "PXEClient".
  • A função PxeDhcpIsValid verifica se um pacote é um pacote DHCP válido. Os provedores podem usar a função PxeDhcpIsValid para marcar se um pacote do cliente é um pacote DHCP quando o conjunto de filtros com a função PxeProviderSetAttribute está definido para receber todos os pacotes para determinar se um pacote especificado é um pacote DHCP válido.
  • A função PxeDhcpInitialize inicializa um pacote de resposta como um pacote de resposta DHCP baseado nas informações em um pacote recebido do cliente. A função PxeProviderInitialize usa o endereço de um pacote DHCP válido recebido do cliente no retorno de chamada PxeProviderRecvRequest . A função PxeDhcpInitialize usa um ponteiro para um pacote de resposta alocado com a função PxePacketAllocate .
  • A função PxeDhcpGetOptionValue recupera um valor de opção de um pacote DHCP. A função PxeDhcpGetVendorOptionValue recupera um valor de opção do campo Informações Específicas do Fornecedor (43) de um pacote DHCP.
  • Em seguida, o provedor pode preencher o pacote de resposta com informações e usar a função PxeSendReply para enviar o pacote de resposta ao cliente. A função PxeDhcpAppendOption acrescenta uma opção DHCP ao pacote de resposta.
  • Um provedor que responde às solicitações do cliente enviando um pacote deve alocar o pacote de resposta usando a função PxePacketAllocate . Em seguida, o provedor pode preencher o pacote de resposta com informações e usar a função PxeSendReply para enviar o pacote de resposta ao cliente.
  • Quando a memória alocada não for mais necessária, o provedor deverá liberá-la usando a função PxePacketFree .

Enumerar provedores registrados

  • Use a API para gravar provedores que enumeram e marcar outros provedores registrados na lista.
  • A função PxeGetServerInfo retorna informações sobre o servidor PXE. A função PxeGetServerInfo retorna um BOOL que indica se o rastreamento está habilitado para o servidor. TRUE indica que o rastreamento está habilitado.
  • A função PxeProviderEnumFirst inicia uma enumeração de provedores na lista de provedores registrados. A função PxeProviderEnumFirst inicia a enumeração e retorna o endereço do identificador que deve ser usado ao chamar a função PxeProviderEnumNext . A função PxeProviderEnumNext retorna uma estrutura PXE_PROVIDER que contém as informações sobre o provedor. A função PxeProviderFreeInfo libera a memória alocada para a estrutura PXE_PROVIDER pela função PxeProviderEnumNext . A função PxeProviderEnumClose fecha a enumeração de provedores na lista de provedores registrados.

Manipular códigos de controle de serviço

Adicionar entradas de rastreamento ao log PXE

  • A função PxeTrace adiciona uma entrada de rastreamento ao log PXE. O WDSPXE fornece rastreamento para ajudar os administradores na solução de problemas. Os provedores podem registrar entradas de rastreamento de diferentes níveis de severidade. Os administradores podem configurar o WDSPXE apenas para registrar entradas em log para determinados níveis de severidade.

Sobre a API dos Serviços de Implantação do Windows

Uso da API de cliente de Serviços de Implantação do Windows