B.7. 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.7.1. Stat2Str

Purpose

Retrieves the status string that corresponds to a status code.

Prototype
const char *Stat2Str(DWORD dwStatus);
Parameters
NameTypeInput/Output
dwStatusDWORDInput
Description
NameDescription
• dwStatusA 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
NameTypeInput/Output
phThreadHANDLE*Output
pFunc typedef void (*HANDLER_FUNC)(
  void *pData);
Input
pDataVOID*Input
Description
NameDescription
phThreadReturns 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.)
pDataPointer 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
NameTypeInput/Output
hThreadHANDLEInput
Description
NameDescription
hThreadThe 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
NameTypeInput/Output
phOsEventHANDLE*Output
Description
NameDescription
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
NameTypeInput/Output
hOsEventHANDLEInput
Description
NameDescription
hOsEventThe 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
NameTypeInput/Output
hOsEventHANDLEInput
dwSecTimeoutDWORDInput
Description
NameDescription
hOsEventThe 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
NameTypeInput/Output
hOsEventHANDLEInput
Description
NameDescription
hOsEventThe 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
NameTypeInput/Output
hOsEventHANDLEInput
Description
NameDescription
hOsEventThe 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
NameTypeInput/Output
phOsMutexHANDLE*Output
Description
NameDescription
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
NameTypeInput/Output
hOsMutexHANDLEInput
Description
NameDescription
hOsMutexThe 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
NameTypeInput/Output
hOsMutexHANDLEInput
Description
NameDescription
hOsMutexThe 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
NameTypeInput/Output
hOsMutexHANDLEInput
Description
NameDescription
hOsMutexThe 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
NameTypeInput/Output
dwLevelDWORDInput
dwSectionDWORDInput
formatconst char*Input
argument Input
Description
NameDescription
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.
formatFormat-control string
argumentOptional 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
NameTypeInput/Output
sFileNameconst char*Input
sModeconst char*Input
Description
NameDescription
sFileNameName 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
NameTypeInput/Output
sFormatconst char*Input
argument Input
Description
NameDescription
sFormatFormat-control string
argumentOptional format arguments
Return Value

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