BOOLEAN
SetupDiRegisterDeviceInfo(
IN HDEVINFO DeviceInfoSet,
IN OUT PSP_DEVINFO_DATA DeviceInfoData,
IN DWORD Flags,
IN PSP_DETSIG_CMPPROC CompareProc, /* optional */
IN PVOID CompareContext, /* optional */
OUT PSP_DEVINFO_DATA DupDeviceInfoData /* optional */
);
SetupDiRegisterDeviceInfo registers a device instance with the Plug and Play Manager.
Parameters
DeviceInfoSet
Supplies a handle to the device information set that contains the device information element for this device instance.
DeviceInfoData
Supplies a pointer to the SP_DEVINFO_DATA structure for the device instance being registered. This is an IN OUT parameter because the DevInst field of the structure can be updated with a new handle value upon return.
Flags
Controls how the device is registered. Can be the following value:
SPRDI_FIND_DUPS
Search for a previously-existing device instance corresponding to the device information pointed to by DeviceInfoData. If this flag is not specified, the device instance is registered regardless of whether or not a device instance already exists for it.
CompareProc
Supplies a comparison callback function to use in duplicate detection. If specified, the function is called for each device instance that is of the same class as the device instance 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 CompareContext /* optional */
);
The compare function must return ERROR_DUPLICATE_FOUND if it finds that the two devices are duplicates. Otherwise it should return NO_ERROR. If some other error is encountered, the callback function should return the appropriate ERROR_* code to indicate the failure.
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 bootlog configuration.
CompareContext
Supplies a pointer to a caller-supplied context buffer that is passed into the callback function. This parameter is ignored if CompareProc is not specified.
DupDeviceInfoData
Supplies a pointer to a device information element that is initialized for the duplicate device instance, if any, discovered as a result of attempting to register this device. 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.
Return Value
The function returns TRUE if it is successful. Otherwise it returns FALSE and the logged error can be retrieved with a call to GetLastError.
Comments
After registering a device information element, the caller should refresh any stored copies of the DevInst handle associated with this device. This is necessary because the handle value might have changed during registration. The caller need not retrieve the SP_DEVINFO_DATA structure again because the DevInst field of the structure is updated to reflect the current value of the handle. The SP_DEVINSTALL_PARAMS structure should be retrieved because registering a device information element may require a system reboot (if the DI_NEEDREBOOT flag is set).
See Also