B.6 General WD_xxx Functions

B.6 General WD_xxx Functions
	Appendix B WinDriver USB PC Host API Reference

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


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 (windrvr6.sys/.dll/.o/.ko) 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`

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 (windrvr6.sys/.dll/.o/.ko) 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

Name	Type	Input/Output
hWD	HANDLE	Input
pVer	WD_VERSION*
• dwVer	DWORD	Output
• cVer	CHAR[128]	Output

DESCRIPTION

Name	Description
hWD	Handle to WinDriver's kernel-mode driver as received from `WD_Open` [B.6.2]
pVer	Pointer to a WinDriver version information structure:
• dwVer	The 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

Name	Type	Input/Output
hWD	HANDLE	Input

DESCRIPTION

Name	Description
hWD	Handle 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

Name	Type	Input/Output
hWD	HANDLE	Input
pDebug	WD_DEBUG*	Input
• dwCmd	DWORD	Input
• dwLevel	DWORD	Input
• dwSection	DWORD	Input
• dwLevelMessageBox	DWORD	Input
• dwBufferSize	DWORD	Input

DESCRIPTION

Name	Description
hWD	Handle to WinDriver's kernel-mode driver as received from `WD_Open` [B.6.2]
pDebug	Pointer 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

Name	Type	Input/Output
hWD	HANDLE	Input
pData	WD_DEBUG_ADD*
• dwLevel	DWORD	Input
• dwSection	DWORD	Input
• pcBuffer	CHAR[256]	Input

DESCRIPTION

Name	Description
hWD	Handle 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

Name	Type	Input/Output
hWD	HANDLE	Input
pDebug	WD_DEBUG_DUMP*	Input
• pcBuffer	PCHAR	Input/Output
• dwSize	DWORD	Input

DESCRIPTION

Name	Description
hWD	Handle 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

Name	Type	Input/Output
hWD	HANDLE	Input
pSleep	WD_SLEEP*
• dwMicroSeconds	DWORD	Input
• dwOptions	DWORD	Input

DESCRIPTION

Name	Description
hWD	Handle 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

Name	Type	Input/Output
hWD	HANDLE	Input
pLicense	WD_LICENSE*
• cLicense	CHAR[]	Input
• dwLicense	DWORD	Output
• dwLicense2	DWORD	Output

DESCRIPTION

Name	Description
hWD	Handle 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;
}


B.5 USB Data Types		B.7 User-Mode Utility Functions