Calling SetupAPI Functions

This section provides guidelines that you should follow when you call the SetupAPI functions from a co-installer or a device installation application.

Rules for calling SetupAPI functions

Class installers and co-installers must not call the following SetupAPI functions:

  • SetupQueueCopy

  • SetupQueueCopyIndirect

  • SetupQueueCopySection

  • SetupQueueDefaultCopy

  • SetupQueueDelete

  • SetupQueueDeleteSection

  • SetupQueueRename

  • SetupQueueRenameSection

  • SetupScanFileQueue

    Note Class installers and co-installers are prohibited from calling SetupScanFileQueue only when the SPQ_SCAN_PRUNE_COPY_QUEUE flag is set in the Flags parameter.

Rules for calling the default DIF code handler functions

Default device installation function (DIF) code handler functions perform system-defined default operations for certain DIF codes. As described in Handling DIF Codes, SetupDiCallClassInstaller calls the default handler for a DIF request after the co-installer has first processed the DIF request, but before SetupDiCallClassInstaller calls the co-installers that registered for post-processing of the request.

Co-installers and device installation applications must not call the default DIF code handler functions. Direct calls to these handler functions bypass all registered co-installers and could invalidate any internal device state that these installers store.

The following table lists the DIF codes that have default DIF code handler functions.

DIF code Default DIF code handler function
DIF_PROPERTYCHANGE SetupDiChangeState
DIF_FINISHINSTALL_ACTION SetupDiFinishInstallAction
DIF_INSTALLDEVICE SetupDiInstallDevice
DIF_INSTALLINTERFACES SetupDiInstallDeviceInterfaces
DIF_INSTALLDEVICEFILES SetupDiInstallDriverFiles
DIF_REGISTER_COINSTALLERS SetupDiRegisterCoDeviceInstallers
DIF_REGISTERDEVICE SetupDiRegisterDeviceInfo
DIF_REMOVE SetupDiRemoveDevice
DIF_SELECTBESTCOMPATDRV SetupDiSelectBestCompatDrv
DIF_SELECTDEVICE SetupDiSelectDevice
DIF_UNREMOVE SetupDiUnremoveDevice