SetupDiRegisterDeviceInfo

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

SP_DEVINFO_DATA, SP_DEVINSTALL_PARAMS