Suppose you have a custom USB device that's relatively simple. Maybe the device has a pair of bulk endpoints on it, and perhaps also an interrupt in endpoint. To make your device useful, all you really need to be able to do is allow a single application to read and write from those bulk endpoints and read from the interrupt endpoint. Performance isn't super-critical

In order to communicate with our device using the WinUSB DLL, we must get a WinUSB interface handle which will associate our device with WinUSB. This is performed via the call WinUsb_Initialize. The call takes as input the HANDLE we got when we called CreateFile, using the DevicePath returned from our call to SetupDiGetDeviceInterfaceDetail, and returns to us a WINUSB_INTERFACE_HANDLE that we will use on all our subsequent calls to the WinUSB DLL APIs.

In order to illustrate how easy it is to use WinUSB and the WinUSB API we decided to implement all the functionality provided by the full fledged, WDM

The WINUSB sample code that we're providing contains two CPP files, WinUsbApp.cpp and WinUsbDevice.cpp. WinUsbApp is a Windows console mode program which implements main and all routines necessary to format commands to implement the functionality that the OSR USB FX2 supports. WinUsbDevice implements the CWinUsbDevice class which encapsulates all the common functionality that a user of the WinUSB API would have to implement. The CWinUsbDevice class is defined Figure 4.

class CWinUsbDevice : public CObject
{
public:
 CWinUsbDevice(LPGUID Guid);
 virtual ~CWinUsbDevice();

 DWORD OpenUsbDevice(int MemberIndex=0);
 const CStringArray& GetDevices() { return m_DevicePath; };
 DWORD GetUsbDevices(int& Count);
 DWORD QueryUsbDeviceInformation(ULONG InformationType,
     PVOID Buffer,PULONG BufferLength);

 DWORD QueryUsbInterfaceSettings(int Limit,int& Count);
 const CArray<USB_INTERFACE_DESCRIPTOR,USB_INTERFACE_DESCRIPTOR>&
         GetUsbDeviceInterfaces(){
  return m_UsbInterfaceDescriptors;
 };

 DWORD QueryUsbPipeInformation(int Interface,int& Count);
 const CArray<WINUSB_PIPE_INFORMATION,WINUSB_PIPE_INFORMATION>&
               GetUsbDevicePipeInformation() {
  return m_UsbPipeInformation;
 };

 DWORD WriteToDevice(UCHAR PipeId,PUCHAR Buffer,ULONG BytesToWrite,
      ULONG& BytesWritten,LPOVERLAPPED POverlapped);
 DWORD ReadFromDevice(UCHAR PipeId,PUCHAR Buffer,ULONG BytesToRead,
      ULONG& BytesRead,LPOVERLAPPED POverlapped);
 DWORD DoControlTransfer(WINUSB_SETUP_PACKET& Packet,PUCHAR Buffer,ULONG BufferSize,
                 ULONG& BytesTransfered,LPOVERLAPPED POverlapped);

 DWORD FlushUsbPipe(UCHAR PipeId);
 DWORD AbortUsbPipe(UCHAR PipeId);
 DWORD ResetUsbPipe(UCHAR PipeId);

private:
 LPGUID   m_DeviceGuid;
 HANDLE   m_DeviceHandle;
 CStringArray m_DevicePath;
 HANDLE   m_WinUsbHandle;
 BOOL   m_bInitialized;
 int    m_InterfaceNumber;

 CArray<USB_INTERFACE_DESCRIPTOR,USB_INTERFACE_DESCRIPTOR> m_UsbInterfaceDescriptors;
 CArray<WINUSB_PIPE_INFORMATION,WINUSB_PIPE_INFORMATION> m_UsbPipeInformation;

 DWORD GetDevicePath();
};

Figure 4 - CWinUsbDevice Class

To use the class, a caller would do the following:

1. Instantiate an instance by calling the constructor CWinUsbDevice(GUID) passing in the GUID of the interface that will be associated with this instance of the class.
2. Call the member function GetUsbDevices(Count) which, upon successful completion, returns in Count the number of devices found that support the interface GUID that was specified when the class was instantiated.
3. If the more that one device was found by GetUsbDevices, Call GetDevices to get a list of all the devices found.
4. Once a device has been selected from the list, Call OpenUsbDevice passing in the index of an entry in the list returned by GetUsbDevices.
5. If the call to OpenUsbDevice succeeds, CWinUsbDevice has called WinUSB_Initialize and we have now successfully associated our device with WinUSB.

As we mentioned, at the completion of step 5, we have now associated our device with WinUSB. However as we stated in the section "Using the WinUSB API" we're not really ready to use the full potential of our device until we have selected the USB_INTERFACE_DESCRIPTOR to use and queried the pipes provided by that interface. So to continue we must do the following:

1. We must call QueryUsbInterfaceSettings(Limit,Count) in order to enumerate the interfaces supported by our USB device. This routine takes 2 parameters: Limit, which specifies the maximum number of interfaces we want to enumerate, and Count which upon successful return indicates the number of interfaces found.
2. If more than one interface was found, Call GetUsbDeviceInterfaces to get a list of interfaces to select from. Once an interface has been selected you are ready to get information about the pipes supported by the selected interface.
3. A list of all the pipes supported by a particular interface is generated by calling QueryUsbPipe Information(Interface,Pipe Count). This routine takes as input Interface the list index of the interfaces contained in the list retrieved by GetUsbDeviceInterfaces, and also PipeCount, which on successful return from QueryUsbPipeInformation contains the number of pipes found for the specified interface.
4. A list of the pipes supported for Interface can be retrieved by calling GetUsbDevicePipe Information.

Believe it or not, at this point we have all the information necessary to begin performing operations on our device. So for example, let's assume that what we would like to do is cycle the OSR USB FX2 device Bar Graph light. To do that we would do the operations contained within the ControlTheLights function in WinUsbApp. That function is shown in Figure 5.

//
// Control the lights on the fx2 board.   Toggle the lights
// in the LED Bar Graph for 10 iterations.
//
DWORD ControlTheLights(CWinUsbDevice& Device)
{
 WINUSB_SETUP_PACKET packet;
 UCHAR    lightBar;
 ULONG    bytesReturned;
 DWORD    status = ERROR_SUCCESS;

 packet.RequestType = 0;
 packet.Request = USBFX2LK_SET_BARGRAPH_DISPLAY;   // Command to set the bar lights.
 packet.Index = 0;
 packet.Length = sizeof(lightBar);
 packet.Value = 0;

 for(ULONG index = 0; index < 10; index++) {
  for(ULONG light = 0; light < 8; light++) {
   lightBar = 1 << light;

   status = Device.DoControlTransfer(packet,&lightBar,sizeof(lightBar),
      bytesReturned,NULL);

   if(status != ERROR_SUCCESS) {
    return status;
   }
   Sleep(500);
  }
 }

 return status;
}

Figure 5 - Control the OSR USB-FX2 Bar Graph Lights

Now we want to issue a command to read the state of the switch pack on the device. To do that we would perform all the operations contained within the ReadTheSwitches function in WinUsbApp. That function is shown in Figure 6.

//
// Read the OSR-FX2 Switch Pack switch settings.
//
DWORD ReadTheSwitches(CWinUsbDevice& Device)
{
 WINUSB_SETUP_PACKET packet;
    SWITCH_STATE  switchState;
 ULONG    bytesReturned;
 DWORD    status = ERROR_SUCCESS;
 USB_DEVICE_REQUEST request;

 //
 // Indicate to WinUSB that we are sending a vendor request
 // to the endpoint and there will be data returned to
 // the host.
 //
 request.Bits.Recipient = 2;  // Endpoint
 request.Bits.Type = 2; // Vendor
 request.Bits.DataDirection = 1; // Device to Host

 packet.RequestType = request.bmRequestType;
 packet.Request = USBFX2LK_READ_SWITCHES;   // Read the switches.
 packet.Index = 0;
 packet.Length = sizeof(switchState);
 packet.Value = 0;

    switchState.SwitchesAsUChar = 0;

 status = Device.DoControlTransfer(packet,(PUCHAR) &switchState,sizeof(switchState),
    bytesReturned,NULL);

 if(status != ERROR_SUCCESS) {
  return status;
 }

    _tprintf(_T("Switches: \n"));
    _tprintf(_T("    Switch8 is %s\n"), switchState.Switch8 ? _T("ON")  : _T( "OFF"));
    _tprintf(_T("    Switch7 is %s\n"), switchState.Switch7 ? _T("ON")  : _T( "OFF"));
    _tprintf(_T("    Switch6 is %s\n"), switchState.Switch6 ? _T("ON")  : _T( "OFF"));
    _tprintf(_T("    Switch5 is %s\n"), switchState.Switch5 ? _T("ON")  : _T( "OFF"));
    _tprintf(_T("    Switch4 is %s\n"), switchState.Switch4 ? _T("ON")  : _T( "OFF"));
    _tprintf(_T("    Switch3 is %s\n"), switchState.Switch3 ? _T("ON")  : _T( "OFF"));
    _tprintf(_T("    Switch2 is %s\n"), switchState.Switch2 ? _T("ON")  : _T( "OFF"));
    _tprintf(_T("    Switch1 is %s\n"), switchState.Switch1 ? _T("ON")  : _T( "OFF"));

 return status;
}

Figure 6 - ReadTheSwitches Function

Finally, let's look at how to transfer bulk data to and from your device. Since the OSR USB FX2 LK device firmware loops back whatever data has been written to the Bulk Input pipe, we have implemented a function in WinUsbApp that writes data to the Bulk Out Pipe and then reads the data back on the Bulk In Pipe. This functionality is demonstrated in the Figure 7.

//
// Perform Bulk I/O on the bulk in and out pipes.
//
DWORD DoBulkIo(CWinUsbDevice& Device)
{
 UCHAR inPipe = 0xFF;
 UCHAR outPipe = 0xFF;
 USHORT  in_maximumPacketSize;
 USHORT  out_maximumPacketSize;
 DWORD bytesWritten;
 DWORD bytesRead;
 DWORD status;
 DWORD iterations = 0;

 const CArray<WINUSB_PIPE_INFORMATION,WINUSB_PIPE_INFORMATION>&
  pipeList = Device.GetUsbDevicePipeInformation();

 for(int pipeIndex = 0; pipeIndex < pipeList.GetSize(); pipeIndex++) {
  if(inPipe == 0xFF && pipeList[pipeIndex].PipeType == UsbdPipeTypeBulk &&
   USB_ENDPOINT_DIRECTION_IN(pipeList[pipeIndex].PipeId)) {
   inPipe = pipeList[pipeIndex].PipeId;
   in_maximumPacketSize = pipeList[pipeIndex].MaximumPacketSize;
   _tprintf(_T("\tIn Pipe MaximumPacketSize: %d\n"),pipeList[pipeIndex].MaximumPacketSize);
  }
  if(outPipe == 0xFF && pipeList[pipeIndex].PipeType == UsbdPipeTypeBulk &&
   USB_ENDPOINT_DIRECTION_OUT(pipeList[pipeIndex].PipeId)) {
   outPipe = pipeList[pipeIndex].PipeId;
   out_maximumPacketSize = pipeList[pipeIndex].MaximumPacketSize;
   _tprintf(_T("\tOut MaximumPacketSize: %d\n"),pipeList[pipeIndex].MaximumPacketSize);
  }
 }

 if(inPipe == 0xFF || outPipe == 0xFF) {
  return ERROR_INVALID_PARAMETER;
 }

 Device.ResetUsbPipe(inPipe);
 Device.ResetUsbPipe(outPipe);
 Device.FlushUsbPipe(inPipe);
 Device.FlushUsbPipe(outPipe);

 PUCHAR pInBuffer = new UCHAR[min(out_maximumPacketSize,in_maximumPacketSize)];

 if(!pInBuffer) {
  return ERROR_NOT_ENOUGH_MEMORY;
 }

 DWORD  ioLength = min(out_maximumPacketSize,in_maximumPacketSize);

 _tprintf(_T("\tCalculated MaximumPacketSize: %d\n"),ioLength);

 PUCHAR pOutBuffer = new UCHAR[ioLength];

 if(!pOutBuffer) {
  delete []pInBuffer;
  return ERROR_NOT_ENOUGH_MEMORY;
 }

 _tprintf(_T("\n\tI/O Iterations [1-4294967295]: "));

 if (scanf ("%d", &iterations) <= 0) {
  _tprintf(_T("Error reading input!\n"));
  return 1;
 }

 for(ULONG index = 0; index < iterations; index++) {
  status = Device.WriteToDevice(outPipe,pOutBuffer,ioLength,bytesWritten,NULL);

  if(status != ERROR_SUCCESS) {
   _tprintf(_T("Error: Write interation %d status %d!\n"),iterations,status);
   break;
  }

  status = Device.ReadFromDevice(inPipe,pInBuffer,ioLength,bytesRead,NULL);

  if(status != ERROR_SUCCESS) {
   _tprintf(_T("Error: Read interation %d status %d!\n"),iterations,status);
   break;
  }

  if(bytesWritten != bytesRead) {
   _tprintf(_T("Error:Data Length issue iteration: %d status %d!\n"),iterations,status);
   status = ERROR_INVALID_BLOCK;
  }
 }

 delete []pInBuffer;
 delete []pOutBuffer;

 return status;
}

Figure 7 - Performing Bulk I/O

As you can see, performing Bulk I/O is rather simple. Allocate a buffer, fill it in and call WriteToDevice (which calls WinUSB_WritePipe) to output data on a specified output pipe, then call ReadFromDevice (which calls WinUsb_ReadPipe) to read data from the specified input pipe. It couldn't be any easier?