B.8 User-Mode Utility Functions

B.8 User-Mode Utility Functions
	Appendix B 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.8.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.9 for a complete list of status codes and strings.

B.8.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.8.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.9].

B.8.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.8.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.9].

B.8.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.8.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.9].

B.8.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.9].

B.8.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.9].

B.8.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.9].

B.8.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.8.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.9].

B.8.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.9].

B.8.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.8.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.9].

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.8.17].

EXAMPLE

B.8.16 WD_LogStop

PURPOSE

• Closes a log file.

PROTOTYPE

VOID WD_LogStop(void);

RETURN VALUE

None

EXAMPLE

B.8.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.9].

EXAMPLE


B.7 Kernel PlugIn Structure Reference		B.9 WinDriver Status Codes