Codebeispiel: Finish-Install Actions in einem Klasseninstallationsprogramm

In diesem Beispiel führt ein Klasseninstallationsprogramm die folgenden Vorgänge aus, um Aktionen zum Abschließen der Installation zu unterstützen:

• Wenn der Klasseninstaller eine DIF_NEWDEVICEWIZARD_FINISHINSTALL-Anforderung empfängt, ruft er die vom Installationsprogramm bereitgestellte Funktion FinishInstallActionsNeeded auf , um zu bestimmen, ob Aktionen für die Abschlussinstallation ausgeführt werden müssen. (Der Code für die Funktion FinishInstallActionsNeeded wird in diesem Beispiel nicht angezeigt.)

  Wenn FinishInstallActionsNeededTRUE zurückgibt, ruft das Klasseninstallationsprogramm SetupDiGetDeviceInstallParams auf, um die Geräteinstallationsparameter für das Gerät abzurufen. Anschließend wird SetupDiSetDeviceInstallParams aufgerufen, um das FlagsEx-Element der SP_DEVINSTALL_PARAMS-Struktur für das Gerät mit dem flag DI_FLAGSEX_FINISHINSTALL_ACTION festzulegen. Das Festlegen dieses Flags bewirkt, dass Windows eine DIF_FINISHINSTALL_ACTION Anforderung an alle Klasseninstaller, Klassen-Co-Installer und Geräte-Co-Installer sendet, die an der Installation dieses Geräts beteiligt sind. Diese Anforderung wird gesendet, nachdem alle Installationsvorgänge mit Ausnahme der Aktionen zum Abschließen der Installation abgeschlossen sind.

• Wenn der Klasseninstaller eine DIF_FINISHINSTALL_ACTION-Anforderung empfängt, ruft er erneut FinishInstallActionsNeeded auf , um zu bestimmen, ob es aktionen für die Endinstallation auszuführen hat, und führt, falls ja, die Aktionen zum Abschließen der Installation aus. Der Klasseninstaller benachrichtigt den Benutzer darüber, dass Die Fertigstelleninstallationsaktionen ausgeführt werden, und wartet, bis die Aktionen für die fertige Installation abgeschlossen sind, bevor er von der Verarbeitung der DIF_FINISHINSTALL_ACTION-Anforderung zurückkehrt.

• Wenn die Aktionen zum Abschließen der Installation erfolgreich sind, benachrichtigt das Klasseninstallationsprogramm den Benutzer darüber, dass die Aktionen zum Abschließen der Installation erfolgreich waren.

• Wenn für die Aktionen zum Abschließen der Installation ein Neustart des Systems erforderlich war, um die Aktionen zum Abschließen der Installation abzuschließen, ruft das Klasseninstallationsprogramm SetupDiGetDeviceInstallParams auf, um die Geräteinstallationsparameter für das Gerät abzurufen, und ruft dann SetupDiSetDeviceInstallParams auf, um den Flags-Member der SP_DEVINSTALL_PARAMS-Struktur für ein Gerät mit dem DI_NEEDREBOOT-Flag festzulegen. Das Installationsprogramm benachrichtigt den Benutzer auch darüber, dass ein Systemneustart erforderlich ist.

• Wenn die Aktionen für die Fertiginstallation fehlschlagen, aber die Aktionen zur Endinstallation beim nächsten Aufzählen des Geräts erneut versucht werden sollen, benachrichtigt das Klasseninstallationsprogramm den Benutzer über diese Situation.

  Hinweis Ab Windows 8 wird eine Fertiginstallationsaktion nur einmal ausgeführt. Windows führt es nicht automatisch erneut aus, vor allem nicht beim nächsten Aufzählen des Geräts, da dies nicht der Zeitpunkt ist, an dem Aktionen zur Endinstallation ausgeführt werden.

• Wenn die Aktionen für die Abschlussinstallation fehlschlagen und der Klasseninstaller feststellt, dass die Aktionen für die Abschlussinstallation nicht erfolgreich sein können, benachrichtigt das Klasseninstallationsprogramm den Benutzer über diese Situation.

• Standardmäßig gibt der Klasseninstaller ERROR_DI_DO_DEFAULT als Antwort auf eine DIF_FINISHINSTALL_ACTION-Anforderung zurück, wenn die Abschlussinstallationsaktionen erfolgreich waren oder wenn die Aktionen für die Abschlussinstallation fehlgeschlagen sind und das Installationsprogramm feststellt, dass die Aktionen zum Abschließen der Installation nicht erneut versucht werden sollen. Das Installationsprogramm gibt nur dann einen Win32-Fehlercode zurück, wenn die Abschlussinstallationsaktionen fehlschlagen und die Aktionen zum Abschließen der Installation erneut versucht werden sollen, wenn das Gerät das nächste Mal im Kontext eines Administrators aufgezählt wird.

  Hinweis Ab Windows 8 wird eine Fertiginstallationsaktion nur einmal ausgeführt. Windows führt es nicht automatisch erneut aus, vor allem nicht beim nächsten Aufzählen des Geräts, da dies nicht der Zeitpunkt ist, an dem Aktionen zur Endinstallation ausgeführt werden.

Im folgenden Codebeispiel für den Klasseninstaller wird die grundlegende Struktur des Klasseninstallationsprogrammcodes veranschaulicht, der Aktionen für die Endinstallation implementiert:

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