SetupDiCreateDeviceInfo

The SetupDiCreateDeviceInfo function creates a new device information element and adds it as a new member to the specified device information set.

WINSETUPAPI BOOL WINAPI
  SetupDiCreateDeviceInfo(
    IN HDEVINFO  DeviceInfoSet,
    IN PCTSTR  DeviceName,
    IN LPGUID  ClassGuid,
    IN PCTSTR  DeviceDescription,  OPTIONAL
    IN HWND  hwndParent,  OPTIONAL
    IN DWORD  CreationFlags,
    OUT PSP_DEVINFO_DATA  DeviceInfoData  OPTIONAL
    );

Parameters

DeviceInfoSet

Supplies a handle to the device information set for the local machine.

DeviceName

Supplies either a full device instance ID (for example, Root\*PNP0500\0000) or a root-enumerated device ID without the Enum branch prefix and instance ID suffix (for example, *PNP0500). The root-enumerated device ID can be used only if the DICD_GENERATE_ID flag is specified in the CreationFlags parameter.

ClassGuid

Supplies a pointer to the GUID for this device's class. If the class is not known, this value should be GUID_NULL.

DeviceDescription

Supplies a textual description of the device.

hwndParent

Supplies the window handle of the top-level window to use for any user interface related to installing the device.

CreationFlags

Controls how the device information element is created. Can be a combination of the following values:

DICD_GENERATE_ID

If this flag is specified, DeviceName contains only a Root-enumerated device ID and the system creates a unique device instance key for it. This unique device instance key is generated as:

Enum\Root\DeviceName\InstanceID
where InstanceID is a four-digit, base-10 number that is unique among all subkeys under Enum\Root\DeviceName. Call SetupDiGetDeviceInstanceId to find out what ID was generated for this device information element.

DICD_INHERIT_CLASSDRVS

If this flag is specified, the resulting device information element inherits the class driver list, if any, associated with the device information set. In addition, if there is a selected driver for the device information set, that same driver is selected for the new device information element.

DeviceInfoData

Optionally supplies a pointer to an SP_DEVINFO_DATA structure to receive the new device information element. If this parameter is not NULL, the caller must set cbSize to sizeof(SP_DEVINFO_DATA).

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.

Headers

Declared in setupapi.h. Include setupapi.h.

Comments

The caller of this function must be a member of the Administrators group.

If this device instance is being added to a set that has an associated class, the device class must be the same or the call fails. In this case, a call to GetLastError returns ERROR_CLASS_MISMATCH.

If the specified device instance is the same as an existing device instance key in the registry, the call fails. In this case, a call to GetLastError returns ERROR_DEVINST_ALREADY_EXISTS. This occurs only if the DICD_GENERATE_ID flag is not set.

If the new device information element was successfully created but the caller-supplied DeviceInfoData buffer is invalid, the function returns FALSE. In this case, a call to GetLastError returns ERROR_INVALID_USER_BUFFER. However, the device information element will have been added as a new member of the set already.

The DeviceInfoSet must only contain elements on the local machine.

See Also

SetupDiDeleteDeviceInfo, SetupDiEnumDeviceInfo, SetupDiOpenDeviceInfo, SP_DEVINFO_DATA