Next: B.9 WinDriver Status Codes Up: B. API Reference Previous: B.7 Kernel PlugIn Structure Contents

Subsections

B.8 User-Mode Utility Functions

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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Retrieves the status string that corresponds to a status code.

PROTOTYPE

const char *Stat2Str(DWORD dwStatus);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ dwStatus DWORD Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ dwStatus	DWORD	Input

DESCRIPTION

Name Description

dwStatus A numeric status code

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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ 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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Creates a thread.

PROTOTYPE

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

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ phThread HANDLE* Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ pFunc HANDLER_FUNC Input

$\bgroup\color{NavyBlue}$\bullet$\egroup$ pData VOID* Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ phThread	HANDLE*	Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ pFunc	HANDLER_FUNC	Input
$\bgroup\color{NavyBlue}$\bullet$\egroup$ 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

pData Pointer to the data to be passed to the new thread

Name	Description
phThread	Returns the handle to the created thread
pFunc	Starting address of the code that the new thread is to execute
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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Waits for a thread to exit.

PROTOTYPE

void ThreadWait(HANDLE hThread);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ hThread HANDLE Input

DESCRIPTION

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ hThread	HANDLE	Input

Name Description

hThread The handle to the thread whose completion is awaited

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

RETURN VALUE

None

B.8.5 OsEventCreate()

PURPOSE

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Creates an event object.

PROTOTYPE

DWORD OsEventCreate(HANDLE *phOsEvent);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ phOsEvent HANDLE* Output

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ phOsEvent	HANDLE*	Output

DESCRIPTION

Name Description

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

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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Closes a handle to an event object.

PROTOTYPE

void OsEventClose(HANDLE hOsEvent);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsEvent HANDLE Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsEvent	HANDLE	Input

DESCRIPTION

Name Description

hOsEvent The handle to the event object to be closed

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

RETURN VALUE

None

B.8.7 OsEventWait()

PURPOSE

$\bgroup\color{NavyBlue}$\bullet$\egroup$ 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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsEvent HANDLE Input

$\bgroup\color{NavyBlue}$\bullet$\egroup$ dwSecTimeout DWORD Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsEvent	HANDLE	Input
$\bgroup\color{NavyBlue}$\bullet$\egroup$ dwSecTimeout	DWORD	Input

DESCRIPTION

Name Description

hOsEvent The handle to the event object

dwSecTimeout Time-out interval of the event, in seconds.
A time-out value of zero signifies an infinite wait.

Name	Description
hOsEvent	The handle to the event object
dwSecTimeout	Time-out interval of the event, in seconds. A time-out value of zero signifies an infinite wait.

RETURN VALUE

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

B.8.8 OsEventSignal()

PURPOSE

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Sets the specified event object to the signaled state.

PROTOTYPE

DWORD OsEventSignal(HANDLE hOsEvent);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsEvent HANDLE Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsEvent	HANDLE	Input

DESCRIPTION

Name Description

hOsEvent The handle to the event object

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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Resets the specified event object to the non-signaled state.

PROTOTYPE

DWORD OsEventReset(HANDLE hOsEvent);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsEvent HANDLE Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsEvent	HANDLE	Input

DESCRIPTION

Name Description

hOsEvent The handle to the event object

RETURN VALUE

Name	Description
hOsEvent	The handle to the event object

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

B.8.10 OsMutexCreate()

PURPOSE

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Creates a mutex object.

PROTOTYPE

DWORD OsMutexCreate(HANDLE *phOsMutex);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ phOsMutex HANDLE* Output

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ phOsMutex	HANDLE*	Output

DESCRIPTION

Name Description

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

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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Closes a handle to a mutex object.

PROTOTYPE

void OsMutexClose(HANDLE hOsMutex);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsMutex HANDLE Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsMutex	HANDLE	Input

DESCRIPTION

Name Description

hOsMutex The handle to the mutex object to be closed

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

RETURN VALUE

None

B.8.12 OsMutexLock()

PURPOSE

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Locks the specified mutex object.

PROTOTYPE

DWORD OsMutexLock(HANDLE hOsMutex);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsMutex HANDLE Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsMutex	HANDLE	Input

DESCRIPTION

Name Description

hOsMutex The handle to the mutex object to be locked

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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Releases (unlocks) a locked mutex object.

PROTOTYPE

DWORD OsMutexUnlock(HANDLE hOsMutex);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsMutex HANDLE Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ hOsMutex	HANDLE	Input

DESCRIPTION

Name Description

hOsMutex The handle to the mutex object to be unlocked

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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Sends debug messages to the debug monitor.

PROTOTYPE

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

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ dwLevel DWORD Input

$\bgroup\color{NavyBlue}$\bullet$\egroup$ dwSection DWORD Input

$\bgroup\color{NavyBlue}$\bullet$\egroup$ format const char* Input

$\bgroup\color{NavyBlue}$\bullet$\egroup$ argument Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ dwLevel	DWORD	Input
$\bgroup\color{NavyBlue}$\bullet$\egroup$ dwSection	DWORD	Input
$\bgroup\color{NavyBlue}$\bullet$\egroup$ format	const char*	Input
$\bgroup\color{NavyBlue}$\bullet$\egroup$ 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

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

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Opens a log file.

PROTOTYPE

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

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ sFileName const char* Input

$\bgroup\color{NavyBlue}$\bullet$\egroup$ sMode const char* Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ sFileName	const char*	Input
$\bgroup\color{NavyBlue}$\bullet$\egroup$ 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).

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

B.8.16 WD_LogStop()

PURPOSE

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Closes a log file.

PROTOTYPE

VOID WD_LogStop(void);

RETURN VALUE

None

B.8.17 WD_LogAdd()

PURPOSE

$\bgroup\color{NavyBlue}$\bullet$\egroup$ Adds user printouts into log file.

PROTOTYPE

VOID DLLCALLCONV WD_LogAdd(
    const char *sFormat
    ...);

PARAMETERS

Name Type Input/Output

$\bgroup\color{NavyBlue}$\bullet$\egroup$ sFormat const char* Input

$\bgroup\color{NavyBlue}$\bullet$\egroup$ argument Input

Name	Type	Input/Output
$\bgroup\color{NavyBlue}$\bullet$\egroup$ sFormat	const char*	Input
$\bgroup\color{NavyBlue}$\bullet$\egroup$ argument		Input

DESCRIPTION

Name Description

sFormat Format-control string

argument Optional format arguments

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

Next: B.9 WinDriver Status Codes Up: B. API Reference Previous: B.7 Kernel PlugIn Structure Contents