Expand Minimize

SetupDiCreateDeviceInterface function

The SetupDiCreateDeviceInterface function registers a device interface on a local system or a remote system.

Syntax


BOOL SetupDiCreateDeviceInterface(
  _In_       HDEVINFO DeviceInfoSet,
  _In_       PSP_DEVINFO_DATA DeviceInfoData,
  _In_       const GUID *InterfaceClassGuid,
  _In_opt_   PCTSTR ReferenceString,
  _In_       DWORD CreationFlags,
  _Out_opt_  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Parameters

DeviceInfoSet [in]

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.

DeviceInfoData [in]

A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet.

InterfaceClassGuid [in]

A pointer to a class GUID that specifies the interface class for the new interface.

ReferenceString [in, optional]

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.

CreationFlags [in]

Reserved. Must be zero.

DeviceInterfaceData [out, optional]

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

Version

Available in Microsoft Windows 2000 and later versions of Windows.

Header

Setupapi.h (include Setupapi.h)

Library

Setupapi.lib

See also

SetupDiOpenDeviceInterfaceRegKey
SetupDiRemoveDeviceInterface

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.