Edit

Share via

Co-installer operation

  • Article

Note

Features described in this section are not supported and driver packages containing them will no longer receive a Microsoft signature. See Using a Universal INF File.

Co-installers are called by SetupAPI, as shown in the following figure.

Diagram illustrating how co-installers participate in device installation.

The unshaded boxes represent the components that the operating system supplies for the system-supplied device setup classes. The shaded boxes represent the components that you can provide. If you create a custom device setup class, you can also supply a class installer. However, you rarely need to create a new device setup class, because almost every device can be associated with one of the system-supplied device setup classes. For more information about Windows components, see Device and Driver Installation.

Co-installers can be provided for a specific device (device-specific co-installer) or for a device setup class (class co-installer). SetupAPI calls a device-specific co-installer only when installing the device for which the co-installer is registered. The operating system and vendors can register zero or more device-specific co-installers for a device. SetupAPI calls a class co-installer when installing any device of the device setup class for which the co-installer is registered. The operating system and vendors can register one or more class co-installers for a device setup class. In addition, a class co-installer can be registered for one or more setup classes.

Windows and custom device installation applications install devices by calling SetupDiCallClassInstaller with device installation function codes (DIF codes).

During GUI-mode setup, the operating system calls SetupDiCallClassInstaller with DIF codes to detect non-PnP devices that are present in the system. An independent hardware vendor (IHV) would typically provide a co-installer to perform this action for non-PnP devices that the IHV releases.

For each DIF request, SetupDiCallClassInstaller calls any class co-installers registered for the device's setup class, any device co-installers registered for the specific device, and then the Class Installer supplied by the system for the device's setup class, if there is one.

Custom device installation applications must call SetupDiCallClassInstaller rather than calling a co-installer or class installer directly. This function ensures that all registered co-installers are called appropriately.

Class co-installers are typically registered before device installation, and device-specific co-installers are registered as part of the device's installation. Class co-installers are therefore typically added to the co-installer list when they're first built and are called for all DIF requests during device installation.

The operating system adds device-specific co-installers to the co-installer list after a DIF_REGISTER_COINSTALLERS request completes for the device (or SetupDiRegisterCoDeviceInstallers is called). Device-specific co-installers don't participate in the following DIF requests:

Only a class co-installer (not a device-specific co-installer) can respond to the following DIF requests:

A device co-installer isn't appropriate in these contexts. A particular device isn't identified at this stage of installation, or the device co-installers aren't registered.

The following figure shows the order in which SetupDiCallClassInstaller calls co-installers and a class installer after any device-specific co-installers are registered.

Diagram of calling co-installers for diff request processing and postprocessing.

In the example illustrated by the previous figure, two class co-installers are registered for this device's setup class and one device-specific co-installer is registered for the device. The following steps correspond to the circled numbers in the previous figure:

  1. SetupDiCallClassInstaller calls the first class co-installer, specifying a DIF code that indicates the install request being processed (DIF_INSTALLDEVICE, in this example). The co-installer has the option of participating in the install request. In this example, the first registered class co-installer returns NO_ERROR.

  2. SetupDiCallClassInstaller, in turn, calls any other registered class co-installers. In this example, the second class co-installer returns ERROR_DI_POSTPROCESSING_REQUIRED, which requests that the co-installer be called later for postprocessing.

  3. SetupDiCallClassInstaller calls any registered device-specific co-installers.

  4. After all registered co-installers are called, SetupDiCallClassInstaller calls the system-supplied Class Installer, if there is one for the device's setup class. In this example, the class installer returns ERROR_DI_DO_DEFAULT, which is a typical return value for class installers.

  5. SetupDiCallClassInstaller calls the default handler for the installation request, if there is one. DIF_INSTALLDEVICE has a default handler, SetupDiInstallDevice, which is part of SetupAPI.

  6. SetupDiCallClassInstaller calls any co-installers that requested postprocessing. In this example, the second class co-installer requested postprocessing.

Co-installer postprocessing is similar to driver IoCompletion routines, except that the co-installer is called a second time at its single entry point. When SetupDiCallClassInstaller calls a co-installer for postprocessing, it sets PostProcessing to TRUE and InstallResult to the appropriate value in the Context parameter. In this example, Context.InstallResult is NO_ERROR because the default handler executed successfully.

For postprocessing, SetupDiCallClassInstaller calls co-installers in reverse order. If all the co-installers in the previous figure returned ERROR_DI_POSTPROCESSING_REQUIRED, SetupDiCallClassInstaller would call Device_Coinstaller_1 first for postprocessing, followed by Class_Coinstaller_2, and then Class_Coinstaller_1. Class Installers don't request postprocessing; only co-installers do.

A co-installer that requests postprocessing is called even if a previous co-installer failed the install request.