The SetupDiRegisterDeviceInfo function is the default handler for the DIF_REGISTERDEVICE request.
WINSETUPAPI BOOL SetupDiRegisterDeviceInfo( HDEVINFO DeviceInfoSet, PSP_DEVINFO_DATA DeviceInfoData, DWORD Flags, PSP_DETSIG_CMPPROC CompareProc, PVOID CompareContext, PSP_DEVINFO_DATA DupDeviceInfoData );
A handle to a device information set that contains a device information element that represents the device to register. The device information set must not contain any remote elements.
A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet. This is an IN-OUT parameter because DeviceInfoData.DevInst might be updated with a new handle value upon return.
A flag value that controls how the device is registered, which can be zero or the following value:
Search for a previously-existing device instance that corresponds to the device that is represented by DeviceInfoData. If this flag is not specified, the device instance is registered regardless of whether a device instance already exists for it.
If the caller supplies CompareProc, the caller must also set this flag.
A pointer to a comparison callback function to use in duplicate detection. This parameter is optional and can be NULL. If this parameter is specified, the callback function is called for each device instance that is of the same class as the device instance that is being registered. The prototype of the callback function is as follows:
typedef DWORD (CALLBACK* PSP_DETSIG_CMPPROC) ( IN HDEVINFO DeviceInfoSet, IN PSP_DEVINFO_DATA NewDeviceData, IN PSP_DEVINFO_DATA ExistingDeviceData, IN PVOID CompareContextOPTIONAL );
If CompareProc is not specified and duplication detection is requested, a default comparison behavior is used. The default is to compare the new device's detect signature with the detect signature of all other devices in the class. The detect signature is contained in the class-specific resource descriptor of the device's boot log configuration.
A pointer to a caller-supplied context buffer that is passed into the callback function. This parameter is ignored if CompareProc is not specified.
A pointer to an SP_DEVINFO_DATA structure to receive information about a duplicate device instance, if any, discovered as a result of attempting to register this device. This parameter is optional and can be NULL. If this parameter is specified, the caller must set DupDeviceInfoData.cbSize to sizeof(SP_DEVINFO_DATA). This will be filled in if the function returns FALSE, and GetLastError returns ERROR_DUPLICATE_FOUND. This device information element is added as a member of the specified DeviceInfoSet, if not already a member. If DupDeviceInfoData is not specified, the duplicate is not added to the device information set.
If you call this function when handling a DIF_REGISTERDEVICE request, the DupDeviceInfoData parameter must be NULL.
The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be retrieved with a call to GetLastError.
SetupDiRegisterDeviceInfo is primarily designed to register a non-PnP device with the Plug and Play (PnP) manager on a local computer. Although SetupDiRegisterDeviceInfo will not fail if the device information set is for a remote computer, the result is of limited use because the device information set cannot subsequently be used with DIF_Xxx installation requests or SetupDiXxx functions that do not support operations on a remote computer. For example, calling SetupDiCreateDevRegKey to execute an INF section for a newly registered device on a remote computer will fail.
Do not directly call this function for PnP device instances. PnP device instances are automatically registered by the operating system. However, you must register non-PnP device instances in one of the following ways:
- If your installation application uses a DIF_DETECT request to successfully detect a device, it should also use a DIF_REGISTERDEVICE request to register the device instance. The request should be handled in the default manner. (By default, SetupDiCallClassInstaller first calls the class installer and class co-installers to do duplicate detection and register the device instance. If these installers do not register the device instance, SetupDiCallClassInstaller calls SetupDiRegisterDeviceInfo to do duplicate detection and register the device instance.)
- If your installation application creates a device instance (for example, by calling SetupDiCreateDeviceInfo) but does not do duplicate detection, your installation application should use a DIF_REGISTERDEVICE request to register the device instance. The request should be handled in the default manner as described earlier.
If your installation application creates a new device and does duplicate detection, your installation application should use a DIF_REGISTERDEVICE request but should prevent SetupDiCallClassInstaller from calling SetupDiRegisterDeviceInfo. To prevent SetupDiCallClassInstaller from calling SetupDiRegisterDeviceInfo, set the DI_NODI_DEFAULTACTION flag in the Flags member of the SP_DEVINSTALL_PARAMS structure for the device instance.
If SetupDiCallClassInstaller returns TRUE for the DIF_REGISTERDEVICE request, the class installer or class co-installers registered the device instance. In this case, the installation application can continue to install the device.
If SetupDiCallClassInstaller returns FALSE for the DIF_REGISTERDEVICE request, the class installer or class co-installers did not register the device instance. In this case, the installation application should do one of the following, depending on the last error that GetLastError returns for the request:
- If the last error is ERROR_DI_DO_DEFAULT, the installation application can directly call SetupDiRegisterDeviceInfo and supply a CompareProc to do duplicate detection. If this call is successful and no duplicates are found, device installation can continue. If a duplicate is found, SetupDiRegisterDeviceInfo returns FALSE, and the installation application must terminate device installation.
- If the last error is not ERROR_DI_DO_DEFAULT, the installation application must terminate device installation.
|Windows version||Available in Microsoft Windows 2000 and later versions of Windows.|
|Header||setupapi.h (include Setupapi.h)|