B.7. User-Mode Utility Functions


	Appendix B. WinDriver USB Host API Reference

This section describes a number of user-mode utility functions you will find useful for implementing various tasks. These utility functions are multi-platform, implemented on all operating systems supported by WinDriver.

B.7.1. Stat2Str

Purpose

Retrieves the status string that corresponds to a status code.

Prototype

const char *Stat2Str(DWORD dwStatus);

Parameters

Name	Type	Input/Output
dwStatus	DWORD	Input

Description

Name	Description
• dwStatus	A numeric status code

Return Value

Returns the verbal status description (string) that corresponds to the specified numeric status code.

Remarks

See Section B.8 for a complete list of status codes and strings.

B.7.2. get_os_type

Purpose

Retrieves the type of the operating system.

Prototype

OS_TYPE get_os_type(void);

Return Value

Returns the type of the operating system.
If the operating system type is not detected, returns OS_CAN_NOT_DETECT.

B.7.3. ThreadStart

Purpose

Creates a thread.

Prototype

DWORD ThreadStart(
    HANDLE *phThread,
    HANDLER_FUNC pFunc,
    void *pData);

Parameters

Name	Type	Input/Output
phThread	HANDLE*	Output
pFunc	typedef void (HANDLER_FUNC)( void pData);	Input
pData	VOID*	Input

Description

Name	Description
phThread	Returns the handle to the created thread
pFunc	Starting address of the code that the new thread is to execute. (The handler's prototype — `HANDLER_FUNC` — is defined in utils.h).
pData	Pointer to the data to be passed to the new thread

Return Value

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

B.7.4. ThreadWait

Purpose

Waits for a thread to exit.

Prototype

void ThreadWait(HANDLE hThread);

Parameters

Name	Type	Input/Output
hThread	HANDLE	Input

Description

Name	Description
hThread	The handle to the thread whose completion is awaited

Return Value

None

B.7.5. OsEventCreate

Purpose

Creates an event object.

Prototype

DWORD OsEventCreate(HANDLE *phOsEvent);

Parameters

Name	Type	Input/Output
phOsEvent	HANDLE*	Output

Description

Name	Description
phOsEvent	The pointer to a variable that receives a handle to the newly created event object

Return Value

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

B.7.6. OsEventClose

Purpose

Closes a handle to an event object.

Prototype

void OsEventClose(HANDLE hOsEvent);

Parameters

Name	Type	Input/Output
hOsEvent	HANDLE	Input

Description

Name	Description
hOsEvent	The handle to the event object to be closed

Return Value

None

B.7.7. OsEventWait

Purpose

Waits until a specified event object is in the signaled state or the time-out interval elapses.

Prototype

DWORD OsEventWait(
    HANDLE hOsEvent,
    DWORD dwSecTimeout);

Parameters

Name	Type	Input/Output
hOsEvent	HANDLE	Input
dwSecTimeout	DWORD	Input

Description

Name	Description
hOsEvent	The handle to the event object
dwSecTimeout	Time-out interval of the event, in seconds. For an infinite wait, set the timeout to `INFINITE`.

Return Value

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

B.7.8. OsEventSignal

Purpose

Sets the specified event object to the signaled state.

Prototype

DWORD OsEventSignal(HANDLE hOsEvent);

Parameters

Name	Type	Input/Output
hOsEvent	HANDLE	Input

Description

Name	Description
hOsEvent	The handle to the event object

Return Value

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

B.7.9. OsEventReset

Purpose

Resets the specified event object to the non-signaled state.

Prototype

DWORD OsEventReset(HANDLE hOsEvent);

Parameters

Name	Type	Input/Output
hOsEvent	HANDLE	Input

Description

Name	Description
hOsEvent	The handle to the event object

Return Value

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

B.7.10. OsMutexCreate

Purpose

Creates a mutex object.

Prototype

DWORD OsMutexCreate(HANDLE *phOsMutex);

Parameters

Name	Type	Input/Output
phOsMutex	HANDLE*	Output

Description

Name	Description
phOsMutex	The pointer to a variable that receives a handle to the newly created mutex object

Return Value

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

B.7.11. OsMutexClose

Purpose

Closes a handle to a mutex object.

Prototype

void OsMutexClose(HANDLE hOsMutex);

Parameters

Name	Type	Input/Output
hOsMutex	HANDLE	Input

Description

Name	Description
hOsMutex	The handle to the mutex object to be closed

Return Value

None

B.7.12. OsMutexLock

Purpose

Locks the specified mutex object.

Prototype

DWORD OsMutexLock(HANDLE hOsMutex);

Parameters

Name	Type	Input/Output
hOsMutex	HANDLE	Input

Description

Name	Description
hOsMutex	The handle to the mutex object to be locked

Return Value

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

B.7.13. OsMutexUnlock

Purpose

Releases (unlocks) a locked mutex object.

Prototype

DWORD OsMutexUnlock(HANDLE hOsMutex);

Parameters

Name	Type	Input/Output
hOsMutex	HANDLE	Input

Description

Name	Description
hOsMutex	The handle to the mutex object to be unlocked

Return Value

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

B.7.14. PrintDbgMessage

Purpose

Sends debug messages to the Debug Monitor.

Prototype

void PrintDbgMessage(
    DWORD dwLevel,
    DWORD dwSection,
    const char *format
    [, argument]...);

Parameters

Name	Type	Input/Output
dwLevel	DWORD	Input
dwSection	DWORD	Input
format	const char*	Input
argument		Input

Description

Name	Description
dwLevel	Assigns the level in the Debug Monitor, in which the data will be declared. If 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 zero, `S_MISC` will be declared. For more details please refer to DEBUG_SECTION in windrvr.h.
format	Format-control string
argument	Optional arguments, limited to 256 bytes

Return Value

None

B.7.15. WD_LogStart

Purpose

Opens a log file.

Prototype

DWORD WD_LogStart(
    const char *sFileName,
    const char *sMode);

Parameters

Name	Type	Input/Output
sFileName	const char*	Input
sMode	const char*	Input

Description

Name	Description
sFileName	Name of log file to be opened
sMode	Type of access permitted. For example, NULL or w opens an empty file for writing, and if the given file exists, its contents are destroyed; a opens a file for writing at the end of the file (i.e., append).

Return Value

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

Remarks

Once a log file is opened, all API calls are logged in this file.
You may add your own printouts to the log file by calling WD_LogAdd() [B.7.17].

B.7.16. WD_LogStop

Purpose

Closes a log file.

Prototype

VOID WD_LogStop(void);

Return Value

None

B.7.17. WD_LogAdd

Purpose

Adds user printouts into log file.

Prototype

VOID DLLCALLCONV WD_LogAdd(
    const char *sFormat
    [, argument ]...);

Parameters

Name	Type	Input/Output
sFormat	const char*	Input
argument		Input

Description

Name	Description
sFormat	Format-control string
argument	Optional format arguments

Return Value

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


B.6. General WD_xxx Functions		B.8. WinDriver Status Codes