B.6  General WD_xxx Functions

B.6.1  Calling Sequence WinDriver – General Use

The following is a typical calling sequence for the WinDriver API.

Figure B.3  WinDriver API Calling Sequence

WinDriver API Calling Sequence

[Note]
  • We recommend calling the WinDriver function WD_Version() [B.6.3] after calling WD_Open() [B.6.2] and before calling any other WinDriver function. Its purpose is to return the WinDriver kernel module version number, thus providing the means to verify that your application is version compatible with the WinDriver kernel module.
  • WD_DebugAdd() [B.6.6] and WD_Sleep() [B.6.8] can be called anywhere after WD_Open()

B.6.2  WD_Open

Purpose

• Opens a handle to access the WinDriver kernel module. The handle is used by all WinDriver APIs, and therefore must be called before any other WinDriver API is called.

Prototype
HANDLE WD_Open(void);
Return Value

The handle to the WinDriver kernel module.
If device could not be opened, returns INVALID_HANDLE_VALUE.

Remarks

If you are a registered user, please refer to the documentation of WD_License() [B.6.9] for an example of how to register your WinDriver license.

Example
 HANDLE hWD;

hWD = WD_Open();
if (hWD == INVALID_HANDLE_VALUE)
{
    printf("Cannot open WinDriver device\n");
}

B.6.3  WD_Version

Purpose

• Returns the version number of the WinDriver kernel module currently running.

Prototype
DWORD WD_Version(
    HANDLE hWD,
    WD_VERSION *pVer);
Parameters
NameTypeInput/Output
hWDHANDLEInput
pVerWD_VERSION* 
• dwVerDWORDOutput
• cVerCHAR[128]Output
Description
NameDescription
hWDHandle to WinDriver's kernel-mode driver as received from WD_Open() [B.6.2]
pVerPointer to a WinDriver version information structure:
• dwVerThe version number
• cVer Version information string.
The version string's size is limited to 128 characters (including the NULL terminator character).
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.8].

Example
WD_VERSION ver;

BZERO(ver);
WD_Version(hWD, &ver);
printf("%s\n", ver.cVer);
if (ver.dwVer < WD_VER)
{
    printf("Error - incorrect WinDriver version\n");
}

B.6.4  WD_Close

Purpose

• Closes the access to the WinDriver kernel module.

Prototype
void WD_Close(HANDLE hWD);
Parameters
NameTypeInput/Output
hWDHANDLEInput
Description
NameDescription
hWDHandle to WinDriver's kernel-mode driver as received from WD_Open() [B.6.2]
Return Value

None

Remarks

This function must be called when you finish using WinDriver kernel module.

Example
WD_Close(hWD);

B.6.5  WD_Debug

Purpose

• Sets debugging level for collecting debug messages.

Prototype
DWORD WD_Debug(
    HANDLE hWD,
    WD_DEBUG *pDebug);
Parameters
NameTypeInput/Output
hWDHANDLEInput
pDebugWD_DEBUG*Input
• dwCmdDWORDInput
• dwLevelDWORDInput
• dwSectionDWORDInput
• dwLevelMessageBoxDWORDInput
• dwBufferSizeDWORDInput
Description
NameDescription
hWDHandle to WinDriver's kernel-mode driver as received from WD_Open() [B.6.2]
pDebugPointer to a debug information structure:
• dwCmd Debug command: Set filter, Clear buffer, etc.
For more details please refer to DEBUG_COMMAND in windrvr.h.
• dwLevel Used for dwCmd=DEBUG_SET_FILTER. Sets the debugging level to collect: Error, Warning, Info, Trace.
For more details please refer to DEBUG_LEVEL in windrvr.h.
• dwSection Used for dwCmd=DEBUG_SET_FILTER. Sets the sections to collect: I/O, Memory, Interrupt, etc. Use S_ALL for all.
For more details please refer to DEBUG_SECTION in windrvr.h.
• dwLevelMessageBox Used for dwCmd=DEBUG_SET_FILTER. Sets the debugging level to print in a message box.
For more details please refer to DEBUG_LEVEL in windrvr.h.
• dwBufferSize Used for dwCmd=DEBUG_SET_BUFFER. The size of buffer in the kernel.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.8].

Example
WD_DEBUG dbg;

BZERO(dbg);
dbg.dwCmd = DEBUG_SET_FILTER;
dbg.dwLevel = D_ERROR;
dbg.dwSection = S_ALL;
dbg.dwLevelMessageBox = D_ERROR;

WD_Debug(hWD, &dbg);

B.6.6  WD_DebugAdd

Purpose

• Sends debug messages to the debug log. Used by the driver code.

Prototype
DWORD WD_DebugAdd(
    HANDLE hWD,
    WD_DEBUG_ADD *pData);
Parameters
NameTypeInput/Output
hWDHANDLEInput
pDataWD_DEBUG_ADD* 
• dwLevelDWORDInput
• dwSectionDWORDInput
• pcBufferCHAR[256]Input
Description
NameDescription
hWDHandle to WinDriver's kernel-mode driver as received from WD_Open() [B.6.2]
pData Pointer to an additional debug information structure:
• dwLevel Assigns the level in the Debug Monitor, in which the data will be declared.
If dwLevel is zero, D_ERROR will be declared.
For more details please refer to DEBUG_LEVEL in windrvr.h.
• dwSection Assigns the section in the Debug Monitor, in which the data will be declared.
If dwSection is zero, S_MISC section will be declared.
For more details please refer to DEBUG_SECTION in windrvr.h.
• pcBuffer The string to copy into the message log.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.8].

Example
WD_DEBUG_ADD add;

BZERO(add);
add.dwLevel = D_WARN;
add.dwSection = S_MISC;
sprintf(add.pcBuffer, "This message will be displayed in "
    "the Debug Monitor\n");
WD_DebugAdd(hWD, &add);

B.6.7  WD_DebugDump

Purpose

• Retrieves debug messages buffer.

Prototype
DWORD WD_DebugDump(
    HANDLE hWD,
    WD_DEBUG_DUMP *pDebugDump);
Parameters
NameTypeInput/Output
hWDHANDLEInput
pDebugWD_DEBUG_DUMP*Input
• pcBufferPCHARInput/Output
• dwSizeDWORDInput
Description
NameDescription
hWDHandle to WinDriver's kernel-mode driver as received from WD_Open() [B.6.2]
pDebugDump Pointer to a debug dump information structure:
• pcBuffer Buffer to receive debug messages
dwSize Size of buffer in bytes
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.8].

Example
char buffer[1024];
WD_DEBUG_DUMP dump;
dump.pcBuffer=buffer;
dump.dwSize = sizeof(buffer);
WD_DebugDump(hWD, &dump);

B.6.8  WD_Sleep

Purpose

• Delays execution for a specific duration of time.

Prototype
DWORD WD_Sleep(
    HANDLE hWD,
    WD_SLEEP *pSleep);
Parameters
NameTypeInput/Output
hWDHANDLEInput
pSleepWD_SLEEP* 
• dwMicroSecondsDWORDInput
• dwOptionsDWORDInput
Description
NameDescription
hWDHandle to WinDriver's kernel-mode driver as received from WD_Open() [B.6.2]
pSleep Pointer to a sleep information structure:
• dwMicroSeconds Sleep time in microseconds – 1/1,000,000 of a second.
• dwOptions A bit-mask, which can be set to either of the following:
Zero (0) – Busy sleep (default)
OR:
SLEEP_NON_BUSY – Delay execution without consuming CPU resources. (Not relevant for under 17,000 micro seconds. Less accurate than busy sleep).
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.8].

Remarks

Example usage: to access slow response hardware.

Example
WD_Sleep slp;

BZERO(slp);
slp.dwMicroSeconds = 200;
WD_Sleep(hWD, &slp);

B.6.9  WD_License

Purpose

• Transfers the license string to the WinDriver kernel module and returns information regarding the license type of the specified license string.

[Note]
When using the WDU USB APIs [B.2] your WinDriver license registration is done via the call to WDU_Init() [B.4.1], so you do not need to call WD_License() directly from your code.
Prototype
DWORD WD_License(
    HANDLE hWD,
    WD_LICENSE *pLicense);
Parameters
NameTypeInput/Output
hWDHANDLEInput
pLicenseWD_LICENSE* 
• cLicenseCHAR[]Input
• dwLicenseDWORDOutput
• dwLicense2DWORDOutput
Description
NameDescription
hWDHandle to WinDriver's kernel-mode driver as received from WD_Open() [B.6.2]
pLicense Pointer to a WinDriver license information structure:
• cLicense A buffer to contain the license string that is to be transferred to the WinDriver kernel module. If an empty string is transferred, then WinDriver kernel module returns the current license type to the parameter dwLicense.
• dwLicense Returns the license type of the specified license string (cLicnese). The return value is a bit-mask of license flags, defined as an enum in windrvr.h. Zero signifies an invalid license string. Additional flags for determining the license type are returned in dwLicense2, if needed.
• dwLicense2 Returns additional flags for determining the license type, if dwLicense cannot hold all the relevant information (otherwise – zero)
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.8].

Remarks

When using a registered version, this function must be called before any other WinDriver API call, apart from WD_Open() [B.6.2], in order to register the license from the code.

Example

Example usage: Add registration routine to your application:

DWORD RegisterWinDriver()
{
    HANDLE hWD;
    WD_LICENSE lic;
    DWORD dwStatus = WD_INVALID_HANDLE;

    hWD = WD_Open();
    if (hWD!=INVALID_HANDLE_VALUE)
    {
        BZERO(lic);
        /* Replace the following string with your license string: */
        strcpy(lic.cLicense, "12345abcde12345.CompanyName");
        dwStatus = WD_License(hWD, &lic);
        WD_Close(hWD);
    }

    return dwStatus;
}