Exemplo de código: ações de Finish-Install em um instalador de classe

Observação

Os recursos descritos nesta seção não têm suporte em pacotes de driver universal ou móvel. Consulte Usando um arquivo INF universal.

Neste exemplo, um instalador de classe executa as seguintes operações para dar suporte a ações de conclusão de instalação:

• Quando o instalador de classe recebe uma solicitação DIF_NEWDEVICEWIZARD_FINISHINSTALL , ele chama a função fornecida pelo instalador FinishInstallActionsNeeded para determinar se há ações de conclusão de instalação a serem executadas. (O código da função FinishInstallActionsNeeded não é mostrado neste exemplo.)

  Se FinishInstallActionsNeeded retornar TRUE, o instalador de classe chamará SetupDiGetDeviceInstallParams para recuperar os parâmetros de instalação do dispositivo para o dispositivo. Em seguida, ele chama SetupDiSetDeviceInstallParams para definir o membro FlagsEx da estrutura SP_DEVINSTALL_PARAMS para o dispositivo com o sinalizador DI_FLAGSEX_FINISHINSTALL_ACTION. Definir esse sinalizador faz com que o Windows envie uma solicitação de DIF_FINISHINSTALL_ACTION para todos os instaladores de classe, co-instaladores de classe e co-instaladores de dispositivo envolvidos na instalação deste dispositivo. Essa solicitação é enviada após todas as operações de instalação, exceto as ações de conclusão da instalação terem sido concluídas.

• Quando o instalador de classe recebe uma solicitação DIF_FINISHINSTALL_ACTION, ele chama FinishInstallActionsNeeded novamente para determinar se ele tem ações de instalação final para executar e, nesse caso, executa as ações de conclusão de instalação. O instalador de classe notifica o usuário de que as ações de conclusão da instalação estão em andamento e aguarda a conclusão das ações de conclusão da instalação antes de retornar do processamento da solicitação de DIF_FINISHINSTALL_ACTION.

• Se as ações concluir a instalação forem bem-sucedidas, o instalador de classe notificará o usuário de que as ações de conclusão de instalação foram bem-sucedidas.

• Se as ações de instalação final exigirem uma reinicialização do sistema para concluir as ações de instalação final, o instalador de classe chamará SetupDiGetDeviceInstallParams para recuperar os parâmetros de instalação do dispositivo para o dispositivo e, em seguida, chamará SetupDiSetDeviceInstallParams para definir o membro Flags da estrutura SP_DEVINSTALL_PARAMS para um dispositivo com o sinalizador DI_NEEDREBOOT. O instalador também notifica o usuário de que uma reinicialização do sistema é necessária.

• Se as ações de conclusão-instalação falharem, mas as ações de concluir a instalação deverão ser tentadas novamente na próxima vez que o dispositivo for enumerado, o instalador de classe notificará o usuário sobre essa situação.

  Nota Começando no Windows 8 uma ação de conclusão de instalação só é executada uma vez. O Windows não o executará automaticamente novamente, especialmente na próxima vez que o dispositivo for enumerado, pois não é quando as ações de instalação final são executadas.

• Se as ações de conclusão de instalação falharem e o instalador de classe determinar que as ações de conclusão-instalação não poderão ser bem-sucedidas, o instalador de classe notificará o usuário sobre essa situação.

• Por padrão, o instalador de classe retorna ERROR_DI_DO_DEFAULT em resposta a uma solicitação de DIF_FINISHINSTALL_ACTION se as ações de instalação de término tiverem sido bem-sucedidas ou se as ações de instalação final falharem e o instalador determinar que as ações de conclusão da instalação não devem ser tentadas novamente. O instalador retornará um código de erro Win32 somente se as ações de concluir a instalação falharem e as ações de conclusão da instalação forem tentadas novamente na próxima vez que o dispositivo for enumerado no contexto de um administrador.

  Nota Começando no Windows 8 uma ação de conclusão de instalação só é executada uma vez. O Windows não o executará automaticamente novamente, especialmente na próxima vez que o dispositivo for enumerado, pois não é quando as ações de instalação final são executadas.

O exemplo de código do instalador de classe a seguir mostra a estrutura básica do código do instalador de classe que implementa ações de instalação de término:

DWORD CALLBACK
SampleClassInstaller(
  IN DI_FUNCTION  InstallFunction,
  IN HDEVINFO  DeviceInfoSet,
  IN PSP_DEVINFO_DATA  DeviceInfoData,
  )
{
  SP_DEVINSTALL_PARAMS DeviceInstallParams;
  DWORD ReturnValue = ERROR_DI_DO_DEFAULT; // The default return value

  switch(InstallFunction)
  {
    case DIF_NEWDEVICEWIZARD_FINISHINSTALL:
      //
      // Processing for finish-install wizard pages
      // If the class installer has wizard pages,
      // set ReturnValue to NO_ERROR
      //
      // Processing for finish-install actions
      if (FinishInstallActionsNeeded())
      {
        // Obtain the device install parameters for the device
        // and set the DI_FLAGSEX_FINISHINSTALL_ACTION flag
        DeviceInstallParams.cbSize = sizeof(DeviceInstallParams);
        if (SetupDiGetDeviceInstallParams(DeviceInfoSet, DeviceInfoData, &DeviceInstallParams))
        {
          DeviceInstallParams.FlagsEx |= DI_FLAGSEX_FINISHINSTALL_ACTION;
          SetupDiSetDeviceInstallParams(DeviceInfoSet, DeviceInfoData, &DeviceInstallParams);
        }
      }
      break;

    case DIF_FINISHINSTALL_ACTION:
      // Processing for finish-install actions
      if (FinishInstallActionsNeeded())
      {
        //
        // Perform the finish-install actions,
        // notify the user that finish install actions
        // are in progress and wait for
        // the finish-install actions to complete
        //
        // If the finish-install actions succeed, notify the user
        //
        // If the finish install actions require a system restart: 
        // notify the user, call SetupDiGetDeviceInstallParams 
        // to obtain the device install parameters for the device in 
        // DeviceInstallParams, and call SetupDiSetInstallParams to set 
        // the DI_NEEDREBOOT flag in DeviceInstallParams.Flags
        // 
        // If the finish install actions failed, but
        // should be attempted again: clean up,
        // notify the user of the failure, and
        // set ReturnValue to an appropriate Win32 error code
        //
        // If the finish install actions failed and 
        // should not be attempted again: clean up and
        // notify the user of the failure
        //
        // Starting with Windows 8, a finish-install action
        // is only run once. Windows will not automatically
        // run it again, especially not the next time
        // the device is enumerated because that is not when
        // finish-install actions are run.
        //
      }
      break;
  }

  return ReturnValue;
}