Exemple de code : actions Finish-Install dans un programme d’installation de classe

Notes

Les fonctionnalités décrites dans cette section ne sont pas prises en charge dans les packages de pilotes universels ou mobiles. Consultez Utilisation d’un fichier INF universel.

Dans cet exemple, un programme d’installation de classe effectue les opérations suivantes pour prendre en charge les actions de fin-installation :

• Lorsque le programme d’installation de classe reçoit une demande de DIF_NEWDEVICEWIZARD_FINISHINSTALL , il appelle la fonction FinishInstallActionsNeededed fournie par le programme d’installation pour déterminer s’il existe des actions d’installation de fin à effectuer. (Le code de la fonction FinishInstallActionsNeeded n’est pas affiché dans cet exemple.)

  Si FinishInstallActionsNeeded renvoieTRUE, le programme d’installation de classe appelle SetupDiGetDeviceInstallParams pour récupérer les paramètres d’installation de l’appareil pour l’appareil. Il appelle ensuite SetupDiSetDeviceInstallParams pour définir le membre FlagsEx de la structure SP_DEVINSTALL_PARAMS de l’appareil avec l’indicateur DI_FLAGSEX_FINISHINSTALL_ACTION. La définition de cet indicateur entraîne l’envoi d’une demande de DIF_FINISHINSTALL_ACTION à tous les programmes d’installation de classe, co-programmes d’installation de classe et co-programmes d’installation d’appareils impliqués dans l’installation de cet appareil. Cette demande est envoyée une fois toutes les opérations d’installation terminées, à l’exception des actions de fin d’installation.

• Lorsque le programme d’installation de classe reçoit une demande de DIF_FINISHINSTALL_ACTION, il appelle à nouveau FinishInstallActionsNeeded pour déterminer s’il a des actions d’installation de fin à effectuer et, si c’est le cas, effectue les actions finish-install. Le programme d’installation de classe avertit l’utilisateur que les actions de fin d’installation sont en cours et attend que les actions de fin d’installation se terminent avant de revenir du traitement de la demande de DIF_FINISHINSTALL_ACTION.

• Si les actions de fin-installation réussissent, le programme d’installation de classe avertit l’utilisateur que les actions de fin d’installation ont réussi.

• Si les actions de fin-installation ont nécessité un redémarrage du système pour effectuer les actions de fin-installation, le programme d’installation de classe appelle SetupDiGetDeviceInstallParams pour récupérer les paramètres d’installation de l’appareil, puis appelle SetupDiSetDeviceInstallParams pour définir le membre Flags de la structure SP_DEVINSTALL_PARAMS d’un appareil avec l’indicateur DI_NEEDREBOOT. Le programme d’installation avertit également l’utilisateur qu’un redémarrage du système est nécessaire.

• Si les actions de fin d’installation échouent, mais que les actions de fin d’installation doivent être tentées à nouveau la prochaine fois que l’appareil est énuméré, le programme d’installation de classe avertit l’utilisateur de cette situation.

  Note À partir de Windows 8 une action terminer-installer n’est exécutée qu’une seule fois. Windows ne l’exécutera pas automatiquement à nouveau, surtout pas la prochaine fois que l’appareil sera énuméré, car ce n’est pas lors de l’exécution des actions de fin d’installation.

• Si les actions de fin-installation échouent et que le programme d’installation de classe détermine que les actions de fin-installation ne peuvent jamais réussir, le programme d’installation de classe avertit l’utilisateur de cette situation.

• Par défaut, le programme d’installation de classe retourne ERROR_DI_DO_DEFAULT en réponse à une demande de DIF_FINISHINSTALL_ACTION si les actions de fin-installation ont réussi ou si les actions de fin-installation ont échoué et que le programme d’installation détermine que les actions de fin-installation ne doivent pas être tentées à nouveau. Le programme d’installation retourne un code d’erreur Win32 uniquement si les actions de fin-installation échouent et que les actions de fin-installation doivent être tentées à nouveau la prochaine fois que l’appareil est énuméré dans le contexte d’un administrateur.

  Note À partir de Windows 8 une action terminer-installer n’est exécutée qu’une seule fois. Windows ne l’exécutera pas automatiquement à nouveau, surtout pas la prochaine fois que l’appareil sera énuméré, car ce n’est pas lors de l’exécution des actions de fin d’installation.

L’exemple de code du programme d’installation de classe suivant montre la structure de base du code du programme d’installation de classe qui implémente des actions de fin-installation :

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;
}