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.

Requirements

See also

SetupDiOpenDeviceInterfaceRegKey

SetupDiRemoveDeviceInterface