SetupDiCreateDeviceInterfaceA function (setupapi.h)
The SetupDiCreateDeviceInterface function registers a device interface on a local system or a remote system.
Syntax
WINSETUPAPI BOOL SetupDiCreateDeviceInterfaceA(
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in] const GUID *InterfaceClassGuid,
[in, optional] PCSTR ReferenceString,
[in] DWORD CreationFlags,
[out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);
Parameters
[in] DeviceInfoSet
A handle to a device information set. This set contains a device information element that represents the device for which to register an interface. This handle is typically returned by SetupDiGetClassDevs.
[in] DeviceInfoData
A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet.
[in] InterfaceClassGuid
A pointer to a class GUID that specifies the interface class for the new interface.
[in, optional] ReferenceString
A pointer to a NULL-terminated string that supplies a reference string. This pointer is optional and can be NULL. Reference strings are used only by a few bus drivers that use device interfaces as placeholders for software devices that are created on demand.
[in] CreationFlags
Reserved. Must be zero.
[out, optional] DeviceInterfaceData
A pointer to a caller-initialized SP_DEVICE_INTERFACE_DATA structure to receive information about the new device interface. This pointer is optional and can be NULL. If the structure is supplied, the caller must set the cbSize member of this structure to sizeof(SP_DEVICE_INTERFACE_DATA) before calling this function. For more information, see the following Remarks section.
Return value
SetupDiCreateDeviceInterface returns TRUE if the function completed without error. If the function completed with an error, it returns FALSE and the error code for the failure can be retrieved by calling GetLastError.
Remarks
The caller of this function must be a member of the Administrators group.
SetupDiCreateDeviceInterface registers an interface for a device. If a device has more than one interface, call this function once for each interface being registered.
If this function successfully registers an interface for the device that corresponds to the specified device information element, it also adds the interface to the interface list that is associated with the device information element in the specified device information set.
Before a registered interface can be used by applications and other system components the interface must be enabled by the driver for the device.
This function creates a registry key for the new device interface. Callers of this function can access nonvolatile storage under this key using SetupDiOpenDeviceInterfaceRegKey.
If SetupDiCreateDeviceInterface successfully creates a new device interface, but the caller-supplied buffer in the DeviceInterfaceData parameter is invalid, this function will return FALSE and a subsequent call to GetLastError will return ERROR_INVALID_USER_BUFFER. However, the function does create and register the new device interface.
Note
The setupapi.h header defines SetupDiCreateDeviceInterface as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Microsoft Windows 2000 and later versions of Windows. |
| Target Platform | Desktop |
| Header | setupapi.h (include Setupapi.h) |
| Library | Setupapi.lib |