Пример кода: действия Finish-Install в совместном установщике

Примечание

Функции, описанные в этом разделе, не поддерживаются в универсальных или мобильных пакетах драйверов. См . раздел Использование универсального INF-файла.

В этом примере совместный установщик выполняет следующие операции для поддержки действий завершения установки:

• Когда совместный установщик получает запрос DIF_NEWDEVICEWIZARD_FINISHINSTALL , он вызывает предоставленную установщиком функцию FinishInstallActionsNeeded , чтобы определить, нужно ли выполнить действия завершения установки. (Код для функции FinishInstallActionsNeeded не показан в этом примере.

  Если Метод FinishInstallActionsNeeded возвращает значение TRUE, соинсталлятор вызывает SetupDiGetDeviceInstallParams для получения параметров установки устройства, а затем вызывает метод SetupDiSetDeviceInstallParams , чтобы задать элемент FlagsExструктуры SP_DEVINSTALL_PARAMS для устройства с флагом DI_FLAGSEX_FINISHINSTALL_ACTION. Установка этого флага приводит к тому, что Windows отправляет запрос DIF_FINISHINSTALL_ACTION всем установщикам классов, совместно установщикам классов и соустановкам устройств, участвующим в установке этого устройства. Этот запрос отправляется после завершения всех операций установки, за исключением действий завершения установки.

• Когда совместный установщик получает запрос на DIF_FINISHINSTALL_ACTION, соинсталлятор снова вызывает Метод FinishInstallActionsNeeded , чтобы определить, есть ли у него действия по завершению установки, и, если да, выполняет действия завершения установки. Совместный установщик уведомляет пользователя о выполнении действий по завершению установки и ожидает завершения действий по установке, прежде чем вернуться из обработки запроса DIF_FINISHINSTALL_ACTION.

• Если действия завершения установки выполнены успешно, соустановщик уведомляет пользователя о том, что действия по завершению установки выполнены успешно.

• Если для выполнения действий по завершению установки требуется перезагрузка системы для завершения установки, совместный установщик вызывает SetupDiGetDeviceInstallParams для получения параметров установки устройства, а затем вызывает Метод SetupDiSetDeviceInstallParams, чтобы задать элемент Flags структуры SP_DEVINSTALL_PARAMS для устройства с флагом DI_NEEDREBOOT. Установщик также уведомляет пользователя о необходимости перезагрузки системы.

• Если действия завершения установки завершаются сбоем и при следующем перечислении устройства необходимо повторить попытку завершения установки, совместный установщик уведомляет пользователя об этой ситуации.

  Примечание Начиная с Windows 8 действие завершения установки выполняется только один раз. Windows не будет автоматически запускать его снова, особенно при следующем перечислении устройства, так как это не происходит при выполнении действий завершения установки.

• Если действия завершения установки завершаются сбоем и соустановщик определяет, что действия завершения установки не могут быть успешными, совместный установщик уведомляет пользователя об этой ситуации.

• По умолчанию совместный установщик возвращает NO_ERROR в ответ на запрос DIF_FINISHINSTALL_ACTION, если действия по завершению установки были успешными или если действия завершения установки завершилися сбоем, а установщик определяет, что повторная попытка выполнения действий завершения установки не должна выполняться. Совместный установщик возвращает код ошибки Win32 только в том случае, если действия завершения установки завершаются сбоем и при следующем перечислении устройства в контексте администратора необходимо повторить попытку завершения установки.

  Примечание Начиная с Windows 8 действие завершения установки выполняется только один раз. Windows не будет автоматически запускать его снова, особенно при следующем перечислении устройства, так как это не происходит при выполнении действий завершения установки.

В следующем примере кода совместного установщика показана базовая структура кода совместного установщика, реализующего действия завершения установки:

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