B.2. WinDriver USB (WDU) Library Overview

This section provides a general overview of WinDriver's USB Library (WDU), including

The WDU library's interface is found in the WinDriver/include/wdu_lib.h and WinDriver/include/windrvr.h header files, which should be included from any source file that calls the WDU API. (wdu_lib.h already includes windrvr.h).

B.2.1. Calling Sequence for WinDriver USB

The WinDriver WDU_xxx USB API is designed to support event-driven transfers between your user-mode USB application and USB devices. This is in contrast to earlier versions, in which USB devices were initialized and controlled using a specific sequence of function calls.

You can implement the three user callback functions specified in the next section: WDU_ATTACH_CALLBACK [B.3.1], WDU_DETACH_CALLBACK [B.3.2] and WDU_POWER_CHANGE_CALLBACK [B.3.3] (at the very least WDU_ATTACH_CALLBACK). These functions are used to notify your application when a relevant system event occurs, such as the attaching or detaching of a USB device. For best performance, minimal processing should be done in these functions.

Your application calls WDU_Init() [B.4.1] and provides the criteria according to which the system identifies a device as relevant or irrelevant. The WDU_Init() function must also pass pointers to the user callback functions.

Your application then simply waits to receive a notification of an event. Upon receipt of such a notification, processing continues. Your application may make use of any functions defined in the high- or low-level APIs below. The high-level functions, provided for your convenience, make use of the low-level functions, which in turn use IOCTLs to enable communication between the WinDriver kernel module and your user-mode application.

When exiting, your application calls WDU_Uninit() [B.4.7] to stop listening to devices matching the given criteria and to unregister the notification callbacks for these devices.

The following figure depicts the calling sequence described above. Each vertical line represents a function or process. Each horizontal arrow represents a signal or request, drawn from the initiator to the recipient. Time progresses from top to bottom.

Figure B.1. WinDriver USB Calling Sequence

WinDriver USB Calling Sequence

The following piece of meta-code can serve as a framework for your user-mode application's code:

attach()
{
    ...
    if this is my device
        /*
        Set the desired alternate setting ;
        Signal main() about the attachment of this device
        */

        return TRUE;
    else
        return FALSE;
}

detach()
{
    ...
    signal main() about the detachment of this device
    ...
}

main()
{
    WDU_Init(...);

    ...
    while (...)
    {
        /* wait for new devices */

        ...

        /* issue transfers */

        ...
    }
    ...
    WDU_Uninit();
}

B.2.2. Upgrading from the WD_xxx USB API to the WDU_xxx API

The WinDriver WDU_xxx USB API, provided beginning with version 6.00, is designed to support event-driven transfers between your user-mode USB application and USB devices. This is in contrast to earlier versions, in which USB devices were initialized and controlled using a specific sequence of function calls.

As a result of this change, you will need to modify your USB applications that were designed to interface with earlier versions of WinDriver to ensure that they will work with WinDriver v6.X on all supported platforms and not only on Microsoft Windows.
You will have to reorganize your application's code so that it conforms with the framework illustrated by the piece of meta-code provided in Section B.2.1.

In addition, the functions that collectively define the USB API have been changed. The new functions, described in the next few sections, provide an improved interface between user-mode USB applications and the WinDriver kernel module. Note that the new functions receive their parameters directly, unlike the old functions, which received their parameters using a structure.

The table below lists the legacy functions in the left column and indicates in the right column which function or functions replace(s) each of the legacy functions. Use this table to quickly determine which new functions to use in your new code.

ProblemSolution
High Level API
Previous FunctionNew Function
WD_Open()
WD_Version()
WD_UsbScanDevice()
WDU_Init() [B.4.1]
WD_UsbDeviceRegister()WDU_SetInterface() [B.4.2]
WD_UsbGetConfiguration()WDU_GetDeviceInfo() [B.4.5]
WD_UsbDeviceUnregister()WDU_Uninit() [B.4.7]
Low Level API
Previous FunctionNew Function
WD_UsbTransfer() WDU_Transfer() [B.4.8.1]
WDU_TransferDefaultPipe() [B.4.8.3]
WDU_TransferBulk() [B.4.8.4]
WDU_TransferIsoch() [B.4.8.5]
WDU_TransferInterrupt() [B.4.8.6]
USB_TRANSFER_HALT optionWDU_HaltTransfer() [B.4.8.2]
WD_UsbResetPipe()WDU_ResetPipe() [B.4.10]
WD_UsbResetDevice()
WD_UsbResetDeviceEx()
WDU_ResetDevice() [B.4.11]