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

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 co-programme d’installation effectue les opérations suivantes pour prendre en charge les actions de fin-installation :

• Lorsque le co-programme d’installation 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 FinishInstallActionsNeededed retourne TRUE, le co-programme d’installation appelle SetupDiGetDeviceInstallParams pour récupérer les paramètres d’installation de l’appareil pour l’appareil, puis appelle 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 que toutes les opérations d’installation, à l’exception des actions de fin-installation, sont terminées.

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

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

• Si les actions de fin d’installation ont nécessité un redémarrage du système pour effectuer les actions de fin-installation, le co-programme d’installation appelle SetupDiGetDeviceInstallParams pour récupérer les paramètres d’installation de l’appareil, puis appelle SetupDiSetDeviceInstallParams pour définir le membre Indicateurs de la structure SP_DEVINSTALL_PARAMS de l’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-installation échouent et que les actions de fin-installation doivent être tentées à nouveau la prochaine fois que l’appareil est énuméré, le co-programme d’installation 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 d’installation échouent et que le co-programme d’installation détermine que les actions de fin-installation ne peuvent pas réussir, le co-programme d’installation avertit l’utilisateur de cette situation.

• Par défaut, le co-programme d’installation retourne NO_ERROR 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 co-programme d’installation détermine que les actions de fin-installation ne doivent pas être tentées à nouveau. Le co-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 de co-programme d’installation suivant montre la structure de base du code de co-programme d’installation qui implémente des actions de fin d’installation :

DWORD CALLBACK
SampleCoInstaller(
  IN DI_FUNCTION  InstallFunction,
  IN HDEVINFO  DeviceInfoSet,
  IN PSP_DEVINFO_DATA  DeviceInfoData,
  IN OUT PCOINSTALLER_CONTEXT_DATA  Context
  )
{
  SP_DEVINSTALL_PARAMS DeviceInstallParams;
  DWORD ReturnValue = NO_ERROR; // The default return value

  switch(InstallFunction)
  {
    case DIF_NEWDEVICEWIZARD_FINISHINSTALL:
      //
      // Processing for finish-install wizard pages
      //
      // 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:
      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;
}