Ejemplo de código: acciones de Finish-Install en un instalador de clase

Nota:

Las características descritas en esta sección no se admiten en paquetes de controladores universales o móviles. Consulte Uso de un archivo INF universal.

En este ejemplo, un instalador de clase realiza las siguientes operaciones para admitir acciones de instalación de finalización:

• Cuando el instalador de clase recibe una solicitud de DIF_NEWDEVICEWIZARD_FINISHINSTALL , llama a la función proporcionada por el instalador FinishInstallActionsNeeded para determinar si hay acciones de instalación de finalización para realizar. (El código de la función FinishInstallActionsNeeded no se muestra en este ejemplo).

  Si FinishInstallActionsNeeded devuelve TRUE, el instalador de clase llama a SetupDiGetDeviceInstallParams para recuperar los parámetros de instalación del dispositivo para el dispositivo. A continuación, llama a SetupDiSetDeviceInstallParams para establecer el miembro FlagsEx de la estructura de SP_DEVINSTALL_PARAMS para el dispositivo con la marca DI_FLAGSEX_FINISHINSTALL_ACTION. Establecer esta marca hace que Windows envíe una solicitud de DIF_FINISHINSTALL_ACTION a todos los instaladores de clase, coinstaladores de clase y coinstaladores de dispositivo implicados en la instalación de este dispositivo. Esta solicitud se envía después de que se hayan completado todas las operaciones de instalación excepto las acciones de finalización de la instalación.

• Cuando el instalador de clase recibe una solicitud de DIF_FINISHINSTALL_ACTION, llama de nuevo a FinishInstallActionsNeeded para determinar si tiene acciones de instalación finalizadas para realizar y, si es así, realiza las acciones de instalación de finalización. El instalador de clase notifica al usuario que las acciones de finalización de la instalación están en curso y espera a que finalicen las acciones de instalación antes de volver a procesar la solicitud de DIF_FINISHINSTALL_ACTION.

• Si las acciones de instalación de finalización se realizan correctamente, el instalador de clase notifica al usuario que las acciones de finalización de la instalación se realizaron correctamente.

• Si las acciones de instalación de fin requieren un reinicio del sistema para completar las acciones de instalación de finalización, el instalador de clase llama a SetupDiGetDeviceInstallParams para recuperar los parámetros de instalación del dispositivo y, a continuación, llama a SetupDiSetDeviceInstallParams para establecer el miembro Flags de la estructura SP_DEVINSTALL_PARAMS para un dispositivo con la marca DI_NEEDREBOOT. El instalador también notifica al usuario que se requiere un reinicio del sistema.

• Si se produce un error en las acciones de instalación de finalización, pero las acciones de instalación de finalización deben intentarse de nuevo la próxima vez que se enumera el dispositivo, el instalador de clase notifica al usuario de esta situación.

  Nota A partir de Windows 8 una acción de instalación finalizada solo se ejecuta una vez. Windows no lo volverá a ejecutar automáticamente, especialmente no la próxima vez que se enumere el dispositivo porque no es cuando se ejecutan acciones de instalación de finalización.

• Si se produce un error en las acciones de instalación de finalización y el instalador de clase determina que las acciones de instalación de fin no se pueden realizar correctamente, el instalador de clase notifica al usuario de esta situación.

• De forma predeterminada, el instalador de clase devuelve ERROR_DI_DO_DEFAULT en respuesta a una solicitud de DIF_FINISHINSTALL_ACTION si las acciones de finalización de la instalación se realizaron correctamente o si las acciones de instalación de fin han fallado y el instalador determina que las acciones de instalación de fin no deben intentarse de nuevo. El instalador devuelve un código de error win32 solo si se produce un error en las acciones de instalación de finalización y las acciones de instalación de finalización deben intentarse de nuevo la próxima vez que se enumera el dispositivo en el contexto de un administrador.

  Nota A partir de Windows 8 una acción de instalación finalizada solo se ejecuta una vez. Windows no lo volverá a ejecutar automáticamente, especialmente no la próxima vez que se enumere el dispositivo porque no es cuando se ejecutan acciones de instalación de finalización.

En el ejemplo de código del instalador de clase siguiente se muestra la estructura básica del código del instalador de clase que implementa acciones de instalación de finalización:

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