コード例: クラス インストーラーでのインストール完了アクション

Note

このセクションで説明する機能は、ユニバーサル ドライバー パッケージまたはモバイル ドライバー パッケージではサポートされていません。 「ユニバーサル INF ファイルの使用」を参照してください。

この例では、クラス インストーラーは、インストール完了アクションをサポートするために次の操作を実行します。

• クラス インストーラーは、DIF_NEWDEVICEWIZARD_FINISHINSTALL 要求を受け取ると、インストーラーによって提供される関数 FinishInstallActionsNeeded を呼び出して、実行すべきインストール完了アクションがあるかどうかを判断します。 (FinishInstallActionsNeeded 関数のコードは、この例では示されていません)。

  FinishInstallActionsNeeded が TRUE を返した場合、クラス インストーラーは SetupDiGetDeviceInstallParams を呼び出して、デバイスのデバイス インストール パラメーターを取得します。 次に、SetupDiSetDeviceInstallParams を呼び出して、デバイスの SP_DEVINSTALL_PARAMS 構造体の FlagsEx メンバーを DI_FLAGSEX_FINISHINSTALL_ACTION フラグで設定します。 このフラグをセットすると、Windows は、DIF_FINISHINSTALL_ACTION 要求を、このデバイスのインストールに関与しているすべてのクラス インストーラー、クラス共同インストーラー、およびデバイス共同インストーラーに送信します。 この要求は、インストール完了アクション以外のすべてのインストール操作が完了した後に送信されます。

• クラス インストーラーは、DIF_FINISHINSTALL_ACTION 要求を受け取ると、再び FinishInstallActionsNeeded を呼び出して、実行すべきインストール完了アクションがあるかどうかを判断し、あれば、インストール完了アクションを実行します。 クラス インストーラーは、インストール完了アクションが進行中であることをユーザーに通知し、インストール完了アクションが完了するのを待ってから、DIF_FINISHINSTALL_ACTION 要求の処理から戻ります。

• インストール完了アクションが成功した場合、クラス インストーラーは、インストール完了アクションが成功したことをユーザーに通知します。

• インストール完了アクションを完了するためにシステムの再起動が必要な場合、クラス インストーラーは SetupDiGetDeviceInstallParams を呼び出して、デバイスのデバイス インストール パラメーターを取得した後、SetupDiSetDeviceInstallParams を呼び出して、デバイスの SP_DEVINSTALL_PARAMS 構造体の Flags メンバーを DI_NEEDREBOOT フラグで設定します。 また、インストーラーは、システムの再起動が必要であることをユーザーに通知します。

• インストール完了アクションが失敗しても、次回デバイスが列挙されるときに、インストール完了アクションを再試行する必要がある場合、クラス インストーラーは、この状況をユーザーに通知します。

  注: Windows 8 以降では、インストール完了アクションは 1 回だけ実行されます。 Windows は自動的に再実行しません。特に、デバイスが次回列挙されるときは実行されません。これは、インストール完了アクションが実行されるときではないためです。

• インストール完了アクションが失敗し、インストール完了アクションを成功できないとクラス インストーラーが判断した場合、クラス インストーラーはユーザーにこの状況を通知します。

• 既定では、インストール完了アクションが成功した場合、またはインストール完了アクションが失敗し、インストーラーがインストール完了アクションを再試行すべきでないと判断した場合、クラス インストーラーは DIF_FINISHINSTALL_ACTION 要求に対して ERROR_DI_DO_DEFAULT を返します。 インストーラーが Win32 エラー コードを返すのは、インストール完了アクションが失敗し、管理者のコンテキストで次回デバイスが列挙されるときにインストール完了アクションを再試行する必要がある場合のみです。

  注: Windows 8 以降では、インストール完了アクションは 1 回だけ実行されます。 Windows は自動的に再実行しません。特に、デバイスが次回列挙されるときは実行されません。これは、インストール完了アクションが実行されるときではないためです。

次のクラス インストーラーのコード例は、インストール完了アクションを実装するクラス インストーラー コードの基本的な構造を示しています。

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