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:

• ERROR_DI_DO_DEFAULT
  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.

  Note  Co-installers return NO_ERROR for unrecognized DIF codes, as described in Co-installer Interface.

• A Win32 error
  A class installer can return an appropriate Win32 error.

• NO_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.

 

 

Send comments about this topic to Microsoft