Plugging a Device into the Simulated USB 2.0 Controller

  • 项目

There are two ways to plug a device directly into a simulated USB 2.0 controller:

Typically, the test application will plug the device simulator into the controller but the simulator could optionally be designed to plug itself into the controller. If the test application plugs in the device, the test application will need access to its SoftUSBDevice object or to its DSFDevice object. Each object is accessible from the other. Consider the following VBScript code example.

Set DSFDevice = SoftUSBDevice.DSFDevice

const IID_ISoftUSBDevice = "{9AC61697-81AE-459A-8629-BF5D5A838519}"
Set SoftUSBDevice = DSFDevice.Object(IID_ISoftUSBDevice)

If the simulated device is implemented as a COM object, the DSFDevice object or the SoftUSBDevice object can be exposed as a property. For example, the DSF USB Loopback Device Simulation exposes the DSFDevice object through the LoopbackDevice::DSFDevice property.

The IDSF::HotPlug method takes two parameters: the name of the bus and the simulated device's DSFDevice object. The bus name for the EHCI controller simulator is "USB2.0". HotPlug returns a DSFBus object (IDSFBus) that you can use later to unplug the device. For example, (from the RunLoopbackSample.wsf loopback sample script that is installed with DSF runtime in the \Program Files\dsf\USBLoopback folder), consider the following code example:

Dim LoopbackDev    : Set LoopbackDev = WScript.CreateObject("SoftUSBLoopback.LoopbackDevice", "LoopbackEvent_")
Dim LoopbackDSFDev : Set LoopbackDSFDev = LoopbackDev.DSFDevice
Dim DSF : Set DSF = CreateObject("DSF.DSF")
Dim Bus : Set Bus = DSF.HotPlug(LoopbackDSFDev, "USB2.0")

... use the loopback device ...
Bus.UnPlug LoopbackDSFDev

To use SoftEHCIRootHubPort::HotPlug, you must access the EHCI controller simulator. You can gain access to this simulator by searching IDSF::Devices property for the controller, as shown in the following sample scripts in the EnumSimulatedDevices routine.

'/////////////////////////////////////////////////////////////////////////////
' Function EnumSimulatedDevices
'
' This function searches the collection of simulated devices
' referenced by DSF.Devices for a device that exposes an ancillary
' object from DSFDevice.Object with the specified GUID. If found it returns the
' DSFDevice object otherwise it returns Nothing.
'/////////////////////////////////////////////////////////////////////////////
const IID_IDSFBus = "{E927C266-5364-449E-AE52-D6A782AFDA9C}"
Dim CtrlrDev : Set CtrlrDev = EnumSimulatedDevices(IID_IDSFBus)
...
Private Function EnumSimulatedDevices(SearchObjectGUID)

    Dim DevSought : Set DevSought = Nothing
    Dim Dev       : Set Dev = Nothing
    Dim DSF       : Set DSF = CreateObject("DSF.DSF")
    Dim ObjSought : Set ObjSought = Nothing

    For Each Dev in DSF.Devices
        If Dev.HasObject(SearchObjectGUID) Then
            Set ObjSought = Dev.Object(SearchObjectGUID)
            If Not ObjSought Is Nothing Then
                Set DevSought = Dev
  Exit For
            End If
        End If
    Next

    Set EnumSimulatedDevices = DevSought

End Function

If you are using multiple simulated EHCI controllers and need to look for a particular controller by device instance ID, you can modify the preceding EnumSimulatedDevices example function to check for the device instance ID by examining the InstanceID property of each device within the loop, as the following code example shows.

      For Each Dev in DSF.Devices
        If Dev.HasObject(SearchObjectGUID) And (Dev.InstanceID = SearchID) Then
            Set ObjSought = Dev.Object(SearchObjectGUID)
            If Not ObjSought Is Nothing Then
                Set DevSought = Dev
  Exit For
            End If
        End If
    Next

The root hub port object is available from the EHCI controller's port collection. The following code example shows how to get the object for port 1 of the root hub.

Dim CtrlrObj : Set CtrlrObj = CtrlrDev.Object(IID_EHCICtrlrObj)
Dim RootHubPorts : Set RootHubPorts = CtrlrObj.Ports
Dim RootHubPort1 : Set RootHubPort1 = RootHubPorts(1)

The first line extracts the SoftEHCICtrlr object from the controller's DSFDevice object. The second line gets the root hub ports collection and the third line gets the SoftEHCIRootHubPort object for port 1.

The final step is to plug the device simulator into the root hub port by using the device simulator's SoftUSBDevice object. For example, consider the following code example for the loopback device.

const IID_ISoftUSBDevice = "{9AC61697-81AE-459A-8629-BF5D5A838519}"
RootHubPort1.HotPlug LoopbackDevice.DSFDevice.Object(IID_ISoftUSBDevice)

To remove the device, run RootHubPort1.Unplug.

If you call SoftEHCIRootHubPort::Unplug or IDSFBus::UnPlug, the target system sees the calls as a surprise remove and as functionally equivalent to removing a USB cable from a root hub port without first initiating the removal in software (for example, by using the Safely Remove Hardware icon).

 

 

Send comments about this topic to Microsoft

Build date: 9/21/2010