The WinUSB user-mode library uses device interface classes to communicate with the kernel-mode USB stack. The INF file that loads winusb.sys specifies a device interface class GUID in the registry. When winusb.sys loads, it calls IoRegisterDeviceInterface to register a device interface that belongs to the device interface class that is specified in the registry.
User-mode software must call SetupDiGetClassDevs to enumerate the registered device interfaces that are associated with one of these device interface classes. The user-mode software must then pass the symbolic link of a device interface to the WinUsb_Initialize routine to obtain a WinUSB handle for the device interface.
The code example in this topic illustrates how user-mode software can enumerate device interfaces and obtain a WinUSB handle. For this example, assume that the INF file stores a device interface class GUID in the registry as follows.
HKR,,DeviceInterfaceGUIDs, 0x10000,"{058815B2-9805-47d3-B7D5-ABC464D3CA06}"
The example user-mode software calls SetupDiGetClassDevs to query for information about all of the registered device interfaces in the device interface class that is associated with this GUID. SetupDiGetClassDevs then returns a handle to a device information set that contains information about the device interfaces.
#include initguid.h
#include setupapi.h
// Example GUID definition. This GUID must match
// the GUID that was specified in the INF file
// that loaded winusb.sys.
DEFINE_GUID(InterfaceClassGuidConstant,0x058815B2, 0x9805, 0x47d3, 0xB7, 0xD5, 0xAB, 0xC4, 0x64, 0xD3, 0xCA, 0x06);
GUID InterfaceClassGuid = InterfaceClassGuidConstant;
// Define a handle to a device information set.
HDEVINFO hdevClassInfo;
// Retrieve a device information set.
hdevClassInfo = SetupDiGetClassDevs
(&InterfaceClassGuid, NULL, NULL,
DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
if (hdevClassInfo == INVALID_HANDLE_VALUE) {
// ERROR }
The call to SetupDiGetClassDevs in the preceding code
example requests registered device interfaces (DIGCF_DEVICEINTERFACE) for the
device interface class that the InterfaceClassGuid variable specifies.
Only device interfaces for presently installed devices (DIGCF_PRESENT) are
returned.
Next, the example application must iteratively call SetupDiEnumDeviceInterfaces
to determine how many elements are in the device information set.
// Initialize variables.
SP_DEVICE_INTERFACE_DATA DeviceData;
DeviceData.cbSize = sizeof(SP_INTERFACE_DEVICE_DATA);
for (nMemberIndex = 0; TRUE; nMemberIndex++) {
nStatus = SetupDiEnumDeviceInterfaces (hdevClassInfo, NULL,
(LPGUID)&InterfaceGuid, nMemberIndex,
&DeviceData);
if (nStatus != TRUE) break;
}
Now, the example application must enumerate the registered device interfaces
that are associated with the device interface class. The example application
calls SetupDiEnumDeviceInterfaces iteratively, once again; but
now it retrieves hardware identifiers (IDs) and symbolic links for each
registered interface. The application will use the symbolic links to obtain a
WinUSB device interface handle.
// Allocate array that will hold information about the devices that
// are associated with this interface class.
struct DeviceData {
TCHAR *HardwareId;
TCHAR *Path; // symbolic link
TCHAR *FriendlyName;
DWORD DeviceInstance;
} *DeviceList;
DeviceList = (struct DeviceData *) malloc
((nMemberIndex + 1) * sizeof(struct DeviceData));
if (DeviceList == NULL) { // ERROR }
// Enumerate devices that are associated with the interface.
for (i = 0; i < nMemberIndex; i++) {
nStatus = SetupDiEnumDeviceInterfaces
(hdevClassInfo, NULL,
(LPGUID)&InterfaceGuid, i,
&DeviceData);
if (nStatus != TRUE) break;
// Retrieve the size of the device data.
nStatus = SetupDiGetDeviceInterfaceDetail
(hdevClassInfo, &DeviceData,
NULL, 0, &nSize, NULL);
if (nStatus != TRUE) break;
// Allocate memory for the device detail buffer.
SP_DEVICE_INTERFACE_DATA pBuffer;
pBuffer = (PSP_INTERFACE_DEVICE_DETAIL_DATA)
malloc (nSize));
if (pBuffer == NULL) { // ERROR }
// Initialize variables.
DeviceData.cbSize =
sizeof(SP_INTERFACE_DEVICE_DATA);
nStatus = SetupDiGetDeviceInterfaceDetail
(hdevClassInfo, &DeviceData,
pBuffer, nSize, NULL,&DeviceData));
if (nStatus = FALSE)) { // ERROR }
//****************************************
// Save the device interface path:
// This path can be used to open
// the interface with CreateFile.
//****************************************
// Calculate the length of the path string.
// Add 1 for the terminating NULL character.
nLen = strlen(DeviceData.DevicePath) + 1;
DeviceList[i].Path =
(TCHAR *) malloc (nLen * sizeof(TCHAR));
StringCchCopy(DeviceList[i].Path, nLen,
DeviceData.DevicePath);
// Save the device instance.
DeviceList[i].DeviceInstance =
DeviceInfoData.DevInst;
//****************************************
// Retrieve registry values.
//****************************************
// Initialize variables that are used in registry
// operations.
SP_DEVINFO_DATA DevInfoData;
//****************************************
// Retrieve the device friendly name.
//****************************************
// Query for the size of the friendly name.
nStatus = SetupDiGetDeviceRegistryProperty
(hdevClassInfo, &DevnfoData,
SPDRP_FRIENDLYNAME, &dwRegType,
NULL, 0, &dwRegSize);
if (nStatus == FALSE) { // ERROR }
// Allocate buffer for the friendly name.
pBuffer = (TCHAR *) malloc
(dwRegSize * sizeof(TCHAR));
if (pBuffer = == NULL) { // ERROR }
// Retrieve the friendly name.
nStatus = SetupDiGetDeviceRegistryProperty
(hdevClassInfo, &DevInfoData,
SPDRP_FRIENDLYNAME, NULL,
(PBYTE) *pBuffer, dwRegSize, NULL);
if (nStatus == FALSE) { // ERROR }
// Store the friendly name for this device.
DeviceList[i].FriendlyName = pBuffer;
// ************************************
// Retrieve the hardware ID.
// ************************************
// Query for the size of the hardware ID.
nStatus = SetupDiGetDeviceRegistryProperty
(hdevClassInfo, &DevnfoData,
SPDRP_HARDWAREID, &dwRegType,
NULL, 0, &dwRegSize);
if (nStatus == FALSE) { // ERROR }
// Allocate a buffer for the hardware ID.
pBuffer = (TCHAR *) malloc
(dwRegSize * sizeof(TCHAR));
if (pBuffer = == NULL) { // ERROR }
// Retrieve the hardware ID.
nStatus = SetupDiGetDeviceRegistryProperty
(hdevClassInfo, &DevInfoData,
SPDRP_HARDWAREID, NULL,
(PBYTE) *pBuffer, dwRegSize, NULL);
if (nStatus == FALSE) { // ERROR }
// Store the hardware ID for this device.
DeviceList[i].HardwareId = pBuffer;
}
The example software next opens the first device interface in the device
interface list. The device interface must be opened with the overlapped
flag.
// Create a symbolic link to device interface
LPCTSTR Path;
HANDLE DeviceInterfaceHandle;
Path = DeviceList[0].Path;
DeviceInterfaceHandle = CreateFile (Path,
GENERIC_READ | GENERIC_WRITE,
FILE_SHARE_READ |
FILE_SHARE_WRITE,
NULL,
OPEN_EXISTING,
FILE_FLAG_OVERLAPPED,
NULL);
if (DeviceInterfaceHandle == INVALID_HANDLE_VALUE) { // ERROR }
After the example software opens the device interface, the application must
call WinUsb_Initialize to obtain a WinUSB handle.
WINUSB_INTERFACE_HANDLE WinUSBHandle;
nStatus = WinUsb_Initialize (DeviceInterfaceHandle, &WinUSBHandle);
if (nStatus = FALSE) { // ERROR }
The example software manages a composite USB device, whose first interface
(interface 0) contains bulk transfer endpoints. In the following code example,
the example software:
- Calls WinUsb_QueryInterfaceSettings to retrieve the
interface descriptor (USB_INTERFACE_DESCRIPTOR)
for interface 0.
- Calls WinUsb_QueryPipe to query for information (WINUSB_PIPE_INFORMATION) about the pipe for endpoint 0.
- Verifies that the pipe is a bulk transfer pipe.
- Calls WinUsb_SetPipePolicy to set the time-out
interval for the pipe.
// ********************************************
// The first interface is for bulk transfers.
// ********************************************
USB_INTERFACE_DESCRIPTOR interface;
nStatus = WinUsb_QueryInterfaceSettings
(WinUSBHandle, 0, &interface);
if (nStatus = FALSE) { // ERROR }
WINUSB_PIPE_INFORMATION pipe;
nStatus = WinUsb_QueryPipe (WinUSBHandle, 0,
(UCHAR) 0, &pipe);
if (nStatus == FALSE) { // ERROR }
Verify that the pipe type is set to the correct USBD_PIPE_TYPE
enumeration value before calling WinUsb_SetPipePolicy.
if (pipe.PipeType != UsbdPipeTypeBulk) { // ERROR }
// Set the transfer time-out interval for endpoint 0
// to 10000 milliseconds.
UCHAR timeout = 10000;
nStatus = WinUsb_SetPipePolicy (WinUSBHandle,
pipe.PipeId, PIPE_TRANSFER_TIMEOUT,
sizeof (timeout), &timeout);
if (nStatus == FALSE) { // ERROR }
The second interface (interface 1) contains interrupt transfer endpoints. In
the following code example, the example software
- Calls WinUsb_GetAssociatedInterface to obtain a
handle to interface 1.
- Calls WinUsb_QueryInterfaceSettings to retrieve the
interface descriptor for interface 1.
- Calls WinUsb_QueryPipe to query for information about the
pipe for endpoint 0.
- Verifies that the pipe is an interrupt transfer pipe.
// *************************************************
// The second interface is for interrupt transfers
// *************************************************
WINUSB_INTERFACE_HANDLE WinUSBHandleAlt;
nStatus = WinUsb_GetAssociatedInterface (WinUSBHandle, 0,
&WinUSBHandleAlt);
if (nStatus == FALSE) { // ERROR }
nStatus = WinUsb_QueryInterfaceSettings (WinUSBHandleAlt, 0,
&interface);
if (nStatus == FALSE) { // ERROR }
nStatus = WinUsb_QueryPipe (WinUSBHandleAlt, 0, (UCHAR) 0, &pipe);
if (nStatus == FALSE) { // ERROR }
if (pipe.PipeType != UsbdPipeTypeInterrupt) { // ERROR }
