Class Installer Interface
Every class installer exports a class installer function. The default name for the function is ClassInstall. SetupAPI calls this function when it needs the class installer to do a specific installation task for a device of its setup class.
The prototype for the installer function is as follows:
typedef DWORD (CALLBACK* CLASS_INSTALL_PROC) ( IN DI_FUNCTION InstallFunction, IN HDEVINFO DeviceInfoSet, IN PSP_DEVINFO_DATA DeviceInfoData /* optional */ );
The class installer function receives two or three arguments:
InstallFunction supplies device installation function code (DIF code), which identifies the installation request to perform
DeviceInfoSet supplies a handle to a device information set
DeviceInfoSet supplies, optionally, a pointer to an SP_DEVINFO_DATA structure that contains information about the device to install
A class installer returns one of the following values:
A class installer typically returns ERROR_DI_DO_DEFAULT, which instructs Windows to perform the default action for the DIF request.
This return status is not really an error, just a valid return value. ERROR_DI_DO_DEFAULT indicates that the class installer possibly performed some actions that filter or augment the installation action. However, the class installer's actions do not replace the default action.
For example, a class installer might set some flags in response to a DIF_INSTALLDEVICE request and return ERROR_DI_DO_DEFAULT. In response to this return value, Windows performs the default action for DIF_INSTALLDEVICE (calls SetupDiInstallDevice) and then calls any co-installers that requested post processing.
If you know that a given DIF request has no default action, your class installer should still return ERROR_DI_DO_DEFAULT. The DIF request might have a default action in a future release of the operating system.
Class installers must return ERROR_DI_DO_DEFAULT for all unrecognized DIF codes.
- A Win32 error
A class installer can return an appropriate Win32 error.
A class installer only returns NO_ERROR if the installer successfully completes the device installation task, including calling any default handler. A class installer must call the default handler if, for example, the installer has to perform certain actions after the default handler has run. If a class installer calls the default handler, the installer must not return ERROR_DI_DO_DEFAULT. It must return NO_ERROR or a Win32 error. For more information about calling a default handler, see Calling the Default DIF Code Handlers.