Codebeispiel: Finish-Install Actions in einem Co-Installer

In diesem Beispiel führt ein Co-Installer die folgenden Vorgänge aus, um Fertigstellen-Installationsaktionen zu unterstützen:

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

  Wenn FinishInstallActionsNeededTRUE zurückgibt, ruft das Co-Installationsprogramm SetupDiGetDeviceInstallParams auf, um die Geräteinstallationsparameter für das Gerät abzurufen, und ruft dann SetupDiSetDeviceInstallParams auf, um das FlagsEx-Element der SP_DEVINSTALL_PARAMS-Struktur für das Gerät mit dem DI_FLAGSEX_FINISHINSTALL_ACTION-Flag 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 Co-Installer eine DIF_FINISHINSTALL_ACTION-Anforderung empfängt, ruft das Co-Installationsprogramm erneut FinishInstallActionsNeeded auf , um zu bestimmen, ob die Ausführung von Finish-Install-Aktionen durchgeführt werden muss, und wenn ja, führt der Co-Installer die FinishInstallActionsNeeded-Aktionen aus. Das Co-Installationsprogramm benachrichtigt den Benutzer, dass die Aktionen zur Endinstallation 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 Co-Installationsprogramm 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 Systemneustart erforderlich war, um die Aktionen zum Abschließen der Installation abzuschließen, ruft das Co-Installationsprogramm SetupDiGetDeviceInstallParams auf, um die Geräteinstallationsparameter für das Gerät abzurufen, und ruft dann SetupDiSetDeviceInstallParams auf, um das Flags-Element der SP_DEVINSTALL_PARAMS-Struktur für das 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 und die Aktionen zur Endinstallation erneut versucht werden sollen, wenn das Gerät das nächste Mal aufgezählt wird, benachrichtigt das Co-Installationsprogramm 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 fertige Installation fehlschlagen und das Co-Installationsprogramm feststellt, dass die Aktionen für die Abschlussinstallation nicht erfolgreich sind, benachrichtigt das Co-Installationsprogramm den Benutzer über diese Situation.

• Standardmäßig gibt der Co-Installer NO_ERROR als Antwort auf eine DIF_FINISHINSTALL_ACTION-Anforderung zurück, wenn die Abschlussinstallationsaktionen erfolgreich waren oder wenn die Aktionen für die fertige Installation fehlgeschlagen sind und das Co-Installationsprogramm bestimmt, dass die Aktionen zum Abschließen der Installation nicht erneut versucht werden sollen. Das Co-Installationsprogramm gibt nur dann einen Win32-Fehlercode zurück, wenn die Aktionen für die Abschlussinstallation fehlschlagen und die Aktionen zum Beenden 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.

Das folgende Co-Installer-Codebeispiel zeigt die grundlegende Struktur des Co-Installer-Codes, der Aktionen für die Fertiginstallation implementiert:

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