omw::windows Namespace Reference

Wraping and helper functions for the Windows API. More...

Classes
class	envVar_not_found
	An exception, indicating that the specified environment variable could not be found. More...
class	ErrorCode
class	invalid_unicode
	An exception, indicating the presence of an invalid unicode codepoint. More...
class	resource_not_found
	An exception, indicating that the specified resource could not be found. More...

Enumerations
enum	ERRORCODE {   EC_OK = 0, EC_ERROR, EC_INV_ARG, EC_INV_UNICODE,   EC_INTERNAL, EC_UNKNOWN_WIN, EC_ENVVAR_NOT_FOUND, EC_RESOURCE_NOT_FOUND,   EC_RESOURCE_NOT_LOADED, EC_STRCONV_DEST_BUFFER_SIZE }

Functions
std::vector< omw::string >	getAllDosDevices ()
std::vector< omw::string >	queryDosDevice (const std::string &device)
bool	beep (uint32_t frequency, uint32_t duration_ms, bool blocking=false)
Environment Variables
std::string	getEnvironmentVariable (const std::string &varName)
	Gets the value of an environment variable. More...
std::string	getEnvironmentVariable (const std::string &varName, omw::windows::ErrorCode &ec)
	Gets the value of an environment variable. More...
Resources
const uint8_t *	getResource (int idr, int type, size_t *size)
const uint8_t *	getResource (int idr, int type, size_t *size, omw::windows::ErrorCode &ec)
std::vector< uint8_t >	getResource (int idr, int type)
std::vector< uint8_t >	getResource (int idr, int type, omw::windows::ErrorCode &ec)
std::vector< uint8_t >	getBinaryResource (int idr)
std::vector< uint8_t >	getBinaryResource (int idr, omw::windows::ErrorCode &ec)
std::string	getTextResource (int idr)
std::string	getTextResource (int idr, omw::windows::ErrorCode &ec)
String Conversion
size_t	utf8_to_wstr (const std::string &src, void *LPWSTR_dest, size_t destSize)
	Converts an UTF-8 string to a Windows API compatible wide string. More...
size_t	utf8_to_wstr (const std::string &src, void *LPWSTR_dest, size_t destSize, omw::windows::ErrorCode &ec)
	Converts an UTF-8 string to a Windows API compatible wide string. More...
size_t	wstr_to_utf8 (const void *LPCWCH_src, char *dest, size_t destSize)
	Converts a Windows API compatible wide string to an UTF-8 string. More...
size_t	wstr_to_utf8 (const void *LPCWCH_src, char *dest, size_t destSize, omw::windows::ErrorCode &ec)
	Converts a Windows API compatible wide string to an UTF-8 string. More...
void	wstr_to_utf8 (const void *LPCWCH_src, std::string &dest)
	Converts a Windows API compatible wide string to an UTF-8 string. More...
void	wstr_to_utf8 (const void *LPCWCH_src, std::string &dest, omw::windows::ErrorCode &ec)
	Converts a Windows API compatible wide string to an UTF-8 string. More...
Performance Counter
int64_t	queryPerformanceCounter ()
int64_t	queryPerformanceFrequency ()
double	perfCntrCalcDuration (int64_t startTick, int64_t endTick)
uint32_t	perfCntrCalcDuration_s (int64_t startTick)
uint32_t	perfCntrCalcDuration_s (int64_t startTick, int64_t endTick)
uint32_t	perfCntrCalcDuration_ms (int64_t startTick)
uint32_t	perfCntrCalcDuration_ms (int64_t startTick, int64_t endTick)
uint32_t	perfCntrCalcDuration_us (int64_t startTick)
uint32_t	perfCntrCalcDuration_us (int64_t startTick, int64_t endTick)
int64_t	perfCntrCalcTickCount (double t_s)
int64_t	perfCntrCalcTickCount_s (uint32_t t_s)
int64_t	perfCntrCalcTickCount_ms (uint32_t t_ms)
int64_t	perfCntrCalcTickCount_us (uint32_t t_us)
void	perfCntrSleep (double t_s)
void	perfCntrSleep_s (uint32_t t_s)
void	perfCntrSleep_ms (uint32_t t_ms)
void	perfCntrSleep_us (uint32_t t_us)
int64_t	perfCntrGetTick ()
bool	perfCntrElapsed (int64_t &oldTick, int64_t tickDuration)
Console
bool	consoleEnVirtualTermProc ()
uint32_t	consoleGetInCodePage ()
uint32_t	consoleGetOutCodePage ()
bool	consoleSetInCodePage (uint32_t cp)
bool	consoleSetOutCodePage (uint32_t cp)
bool	consoleSetCodePage (uint32_t cp)
	Sets the input and output code page of the console. More...
bool	consoleSetCodePageUTF8 ()

Variables
constexpr size_t	envVarValueMaxSize = 32767
	Max buffer size (including terminating null) of an environment variables value. More...

Detailed Description

Wraping and helper functions for the Windows API.

This namespace is only present on Windows platforms.

Calling the Windows API

Calls to the Windows API should use the foobarW() functions and Microsofts WCHAR types to call the API. The String Conversion Functions can be used to convert string types.

An example can be seen in the sourcecode of the omw::windows::getEnvironmentVariable() function.

String Conversion Functions

#include <omw/windows/string.h>

The functions utf8_to_wstr() and wstr_to_utf8() are used to convert between UTF-8 char strings and WCHAR strings used in the Windows API. Both do have several overloads.

The overloads with the ErrorCode& ec out parameter has only sucessfully performed if ec.good() returns true. Possible code values:

• omw::windows::EC_OK
• omw::windows::EC_INV_ARG
• omw::windows::EC_INV_UNICODE
• omw::windows::EC_INTERNAL
• omw::windows::EC_UNKNOWN_WIN
• omw::windows::EC_STRCONV_DEST_BUFFER_SIZE

The other overloads can throw

• std::range_error if dest buffer is too small
• std::invalid_argument when invalid arguments are passed to the function (such as null pointers)
• omw::windows::invalid_unicode when src contains invalid unicode codepoints
• std::runtime_error on unexpected behaviour of underlaying function

Console Code Page

See the corresponding doc of the Windows API functions GetConsoleCP(), GetConsoleOutputCP(), SetConsoleCP() and SetConsoleOutputCP().
See also: List of code page identifier.

The setting of consoleSet..CodePage() functions is set for the current console window, and stays the same after termination of the application. Therefore the setting should be set back to the previous code page before returning from the main function.

Example main.cpp

#include <iostream>
 
#include <omw/omw.h>
#include <omw/windows/windows.h>
 
using std::cout;
using std::endl;
 
namespace
{
#ifdef OMW_PLAT_WIN
    void setCpBack(uint32_t cpIn, uint32_t cpOut)
    {
        if (!omw::windows::consoleSetInCodePage(cpIn)) cout << "faild to set in code page back to " << cpIn << endl;
        if (!omw::windows::consoleSetOutCodePage(cpOut)) cout << "faild to set out code page back to " << cpOut << endl;
    }
#endif
}
 
int main(int argc, char** argv)
{
    int r = 0;
 
#ifdef OMW_PLAT_WIN
    const uint32_t cpIn = omw::windows::consoleGetInCodePage();
    const uint32_t cpOut = omw::windows::consoleGetOutCodePage();
 
    if (!omw::windows::consoleSetCodePageUTF8())
    {
        cout << "faild to set code page to UTF-8" << endl;
        setCpBack(cpIn, cpOut);
    }
#endif
 
    // app code ...
    // ...
    // ...
 
#ifdef OMW_PLAT_WIN
    setCpBack(cpIn, cpOut);
#endif
 
    return r;
}

Getting Resources

The overloads of getResource() with the ErrorCode& ec out parameter has only sucessfully performed if ec.good() returns true. Possible code values:

• omw::windows::EC_OK
• omw::windows::EC_RESOURCE_NOT_FOUND
• omw::windows::EC_RESOURCE_NOT_LOADED

The other overloads can throw

• omw::windows::resource_not_found if the resource could not be found
• std::runtime_error if the resource could not be loaded or on C++ standard runtime errors

Enumeration Type Documentation

ERRORCODE

enum omw::windows::ERRORCODE

Enumerator
EC_OK	No error occured
EC_ERROR	General error
EC_INV_ARG	Invalid arguments
EC_INV_UNICODE	Invalid unicode codepoints are present
EC_INTERNAL	A linbrary internal error occured (bugfix in source needed)
EC_UNKNOWN_WIN	An unspecified Windows API error occurred
EC_ENVVAR_NOT_FOUND	The specified environment variable could not be found
EC_RESOURCE_NOT_FOUND	The specified resource could not be found
EC_RESOURCE_NOT_LOADED	The resource could not be loaded
EC_STRCONV_DEST_BUFFER_SIZE	dest buffer is too small

Function Documentation

beep()

bool omw::windows::beep	(	uint32_t	frequency,
		uint32_t	duration_ms,
		bool	blocking = false
	)

Parameters

frequency	In range [37, 32'767]
duration_ms
blocking

Returns

true on success, false otherwise

consoleEnVirtualTermProc()

bool omw::windows::consoleEnVirtualTermProc

(

)

Returns

true on success, false otherwise

See also SetConsoleMode() and ENABLE_VIRTUAL_TERMINAL_PROCESSING

consoleGetInCodePage()

uint32_t omw::windows::consoleGetInCodePage

(

)

Returns

The code page on success, 0 otherwise

See Console Code Page.

consoleGetOutCodePage()

uint32_t omw::windows::consoleGetOutCodePage

(

)

Returns

The code page on success, 0 otherwise

See Console Code Page.

consoleSetCodePage()

bool omw::windows::consoleSetCodePage

(

uint32_t

cp

)

Sets the input and output code page of the console.

Returns

true on success, false otherwise

See Console Code Page.

consoleSetCodePageUTF8()

bool omw::windows::consoleSetCodePageUTF8

(

)

Returns

true on success, false otherwise

Passes CP_UTF8 to consoleSetCodePage().

consoleSetInCodePage()

bool omw::windows::consoleSetInCodePage

(

uint32_t

cp

)

Returns

true on success, false otherwise

See Console Code Page.

consoleSetOutCodePage()

bool omw::windows::consoleSetOutCodePage

(

uint32_t

cp

)

Returns

true on success, false otherwise

See Console Code Page.

getBinaryResource() [1/2]

std::vector< uint8_t > omw::windows::getBinaryResource

(

int

idr

)

Parameters

idr	Resource ID (16bit)

Returns

Content of the resource

Throwing function, see Getting Resources.

getBinaryResource() [2/2]

std::vector< uint8_t > omw::windows::getBinaryResource	(	int	idr,
		omw::windows::ErrorCode &	ec
	)

Parameters

	idr	Resource ID (16bit)
[out]	ec	See Getting Resources

Returns

Content of the resource

getEnvironmentVariable() [1/2]

std::string omw::windows::getEnvironmentVariable

(

const std::string &

varName

)

Gets the value of an environment variable.

Parameters

varName

Name of the environment variable

Returns

Value of the environment variable

Exceptions

• omw::windows::envVar_not_found
• omw::windows::invalid_unicode
• std::runtime_error

getEnvironmentVariable() [2/2]

std::string omw::windows::getEnvironmentVariable	(	const std::string &	varName,
		omw::windows::ErrorCode &	ec
	)

Gets the value of an environment variable.

Parameters

	varName	Name of the environment variable
[out]	ec	Error code

Returns

Value of the environment variable

Possible ec.code() values:

• omw::windows::EC_OK
• omw::windows::EC_ENVVAR_NOT_FOUND
• omw::windows::EC_INV_UNICODE
• omw::windows::EC_INTERNAL
• omw::windows::EC_UNKNOWN_WIN

getResource() [1/4]

std::vector< uint8_t > omw::windows::getResource	(	int	idr,
		int	type
	)

Parameters

idr	Resource ID (16bit)
type	Resource type (16bit)

Returns

Content of the resource

Throwing function, see Getting Resources.

getResource() [2/4]

std::vector< uint8_t > omw::windows::getResource	(	int	idr,
		int	type,
		omw::windows::ErrorCode &	ec
	)

Parameters

	idr	Resource ID (16bit)
	type	Resource type (16bit)
[out]	ec	See Getting Resources

Returns

Content of the resource

getResource() [3/4]

const uint8_t * omw::windows::getResource	(	int	idr,
		int	type,
		size_t *	size
	)

Parameters

	idr	Resource ID (16bit)
	type	Resource type (16bit)
[out]	size	Number of bytes

Returns

Pointer to the byte array

Throwing function, see Getting Resources.

getResource() [4/4]

const uint8_t * omw::windows::getResource	(	int	idr,
		int	type,
		size_t *	size,
		omw::windows::ErrorCode &	ec
	)

Parameters

	idr	Resource ID (16bit)
	type	Resource type (16bit)
[out]	size	Number of bytes
[out]	ec	See Getting Resources

Returns

Pointer to the byte array

getTextResource() [1/2]

std::string omw::windows::getTextResource

(

int

idr

)

Parameters

idr	Resource ID (16bit)

Returns

Content of the text resource

Throwing function, see Getting Resources.

getTextResource() [2/2]

std::string omw::windows::getTextResource	(	int	idr,
		omw::windows::ErrorCode &	ec
	)

Parameters

	idr	Resource ID (16bit)
[out]	ec	See Getting Resources

Returns

Content of the text resource

perfCntrCalcTickCount()

int64_t omw::windows::perfCntrCalcTickCount

(

double

t_s

)

Parameters

t_s	Duration in seconds

Returns

The number of ticks which represent the duration

Calculates the number of ticks based on the frequency of the performance counter.

perfCntrCalcTickCount_ms()

int64_t omw::windows::perfCntrCalcTickCount_ms

(

uint32_t

t_ms

)

Parameters

t_ms	Duration in milliseconds

Returns

The number of ticks which represent the duration

See perfCntrCalcTickCount().

perfCntrCalcTickCount_s()

int64_t omw::windows::perfCntrCalcTickCount_s

(

uint32_t

t_s

)

Parameters

t_s	Duration in seconds

Returns

The number of ticks which represent the duration

See perfCntrCalcTickCount().

perfCntrCalcTickCount_us()

int64_t omw::windows::perfCntrCalcTickCount_us

(

uint32_t

t_us

)

Parameters

t_us	Duration in microseconds

Returns

The number of ticks which represent the duration

See perfCntrCalcTickCount().

perfCntrElapsed()

bool omw::windows::perfCntrElapsed ( int64_t &  oldTick, int64_t  tickDuration  )

inline

Parameters

[in,out]	oldTick	Reference to the variable that holds the last tick value
	tickDuration	The number of ticks which represent the duration between two elapsed events

Returns

true if the time has elapsed, otherwise false

The oldTick variable should be initialized with the return value of perfCntrGetTick(). The tickDuration should be calculated once by perfCntrCalcTickCount() or perfCntrCalcTickCount_..().

perfCntrGetTick()

int64_t omw::windows::perfCntrGetTick ( )

inline

Returns

Value of the performance counter

Alias for queryPerformanceCounter().

queryDosDevice()

std::vector< omw::string > omw::windows::queryDosDevice

(

const std::string &

device

)

Parameters

device

Returns

Exceptions

• omw::windows::utf8_to_wstr() is called and may throw exceptions

queryPerformanceCounter()

int64_t omw::windows::queryPerformanceCounter

(

)

Returns

Value of the performance counter

See QueryPerformanceCounter()

queryPerformanceFrequency()

int64_t omw::windows::queryPerformanceFrequency

(

)

Returns

Frequency of the performance counter

See QueryPerformanceFrequency()

utf8_to_wstr() [1/2]

size_t omw::windows::utf8_to_wstr	(	const std::string &	src,
		void *	LPWSTR_dest,
		size_t	destSize
	)

Converts an UTF-8 string to a Windows API compatible wide string.

Parameters

	src	The input string
[out]	LPWSTR_dest	Pointer (LPWSTR) to the output buffer (WCHAR[])
	destSize	Size of the destination buffer (number of WCHAR)

Returns

Number of wide chars written to dest (not including the terminating null character)

The src argument can also be of type const char* (implicit std::string() constructor).

Throwing function, see String Conversion Functions.

utf8_to_wstr() [2/2]

size_t omw::windows::utf8_to_wstr	(	const std::string &	src,
		void *	LPWSTR_dest,
		size_t	destSize,
		omw::windows::ErrorCode &	ec
	)

Converts an UTF-8 string to a Windows API compatible wide string.

Parameters

	src	The input string
[out]	LPWSTR_dest	Pointer (LPWSTR) to the output buffer (WCHAR[])
	destSize	Size of the destination buffer (number of WCHAR)
[out]	ec	See String Conversion Functions

Returns

Number of wide chars written to dest (not including the terminating null character)

The src argument can also be of type const char* (implicit std::string() constructor).

wstr_to_utf8() [1/4]

size_t omw::windows::wstr_to_utf8	(	const void *	LPCWCH_src,
		char *	dest,
		size_t	destSize
	)

Converts a Windows API compatible wide string to an UTF-8 string.

Parameters

	src	The input string (LPCWCH)
[out]	dest	Pointer to the output buffer
	destSize	Size of the destination buffer

Returns

Number of bytes written to dest (not including the terminating null character)

Throwing function, see String Conversion Functions.

wstr_to_utf8() [2/4]

size_t omw::windows::wstr_to_utf8	(	const void *	LPCWCH_src,
		char *	dest,
		size_t	destSize,
		omw::windows::ErrorCode &	ec
	)

Converts a Windows API compatible wide string to an UTF-8 string.

Parameters

	src	The input string (LPCWCH)
[out]	dest	Pointer to the output buffer
	destSize	Size of the destination buffer
[out]	ec	See String Conversion Functions

Returns

Number of bytes written to dest (not including the terminating null character)

wstr_to_utf8() [3/4]

void omw::windows::wstr_to_utf8	(	const void *	LPCWCH_src,
		std::string &	dest
	)

Converts a Windows API compatible wide string to an UTF-8 string.

Parameters

	src	The input string (LPCWCH)
[out]	dest	Reference to the output string

Throwing function, see String Conversion Functions.

wstr_to_utf8() [4/4]

void omw::windows::wstr_to_utf8	(	const void *	LPCWCH_src,
		std::string &	dest,
		omw::windows::ErrorCode &	ec
	)

Converts a Windows API compatible wide string to an UTF-8 string.

Parameters

	src	The input string (LPCWCH)
[out]	dest	Reference to the output string
[out]	ec	See String Conversion Functions

Variable Documentation

envVarValueMaxSize

constexpr size_t omw::windows::envVarValueMaxSize = 32767

constexpr

Max buffer size (including terminating null) of an environment variables value.

See GetEnvironmentVariable function (winbase.h).