omw
0.2.0
|
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... | |
Wraping and helper functions for the Windows API.
This namespace is only present on Windows platforms.
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.
#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 smallstd::invalid_argument
when invalid arguments are passed to the function (such as null pointers)omw::windows::invalid_unicode
when src contains invalid unicode codepointsstd::runtime_error
on unexpected behaviour of underlaying functionSee 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
The overloads of getResource()
with the ErrorCode& ec
out parameter has only sucessfully performed if ec.good()
returns true
. Possible code values:
The other overloads can throw
omw::windows::resource_not_found
if the resource could not be foundstd::runtime_error
if the resource could not be loaded or on C++ standard runtime errors bool omw::windows::beep | ( | uint32_t | frequency, |
uint32_t | duration_ms, | ||
bool | blocking = false |
||
) |
frequency | In range [37, 32'767] |
duration_ms | |
blocking |
true
on success, false
otherwise bool omw::windows::consoleEnVirtualTermProc | ( | ) |
true
on success, false
otherwiseSee also SetConsoleMode() and ENABLE_VIRTUAL_TERMINAL_PROCESSING
uint32_t omw::windows::consoleGetInCodePage | ( | ) |
See Console Code Page.
uint32_t omw::windows::consoleGetOutCodePage | ( | ) |
See Console Code Page.
bool omw::windows::consoleSetCodePage | ( | uint32_t | cp | ) |
Sets the input and output code page of the console.
true
on success, false
otherwiseSee Console Code Page.
bool omw::windows::consoleSetCodePageUTF8 | ( | ) |
true
on success, false
otherwisePasses CP_UTF8
to consoleSetCodePage().
bool omw::windows::consoleSetInCodePage | ( | uint32_t | cp | ) |
true
on success, false
otherwiseSee Console Code Page.
bool omw::windows::consoleSetOutCodePage | ( | uint32_t | cp | ) |
true
on success, false
otherwiseSee Console Code Page.
std::vector< uint8_t > omw::windows::getBinaryResource | ( | int | idr | ) |
idr | Resource ID (16bit) |
Throwing function, see Getting Resources.
std::vector< uint8_t > omw::windows::getBinaryResource | ( | int | idr, |
omw::windows::ErrorCode & | ec | ||
) |
idr | Resource ID (16bit) | |
[out] | ec | See Getting Resources |
std::string omw::windows::getEnvironmentVariable | ( | const std::string & | varName | ) |
Gets the value of an environment variable.
varName | Name of the environment variable |
Exceptions
std::string omw::windows::getEnvironmentVariable | ( | const std::string & | varName, |
omw::windows::ErrorCode & | ec | ||
) |
Gets the value of an environment variable.
varName | Name of the environment variable | |
[out] | ec | Error code |
Possible ec.code()
values:
std::vector< uint8_t > omw::windows::getResource | ( | int | idr, |
int | type | ||
) |
idr | Resource ID (16bit) |
type | Resource type (16bit) |
Throwing function, see Getting Resources.
std::vector< uint8_t > omw::windows::getResource | ( | int | idr, |
int | type, | ||
omw::windows::ErrorCode & | ec | ||
) |
idr | Resource ID (16bit) | |
type | Resource type (16bit) | |
[out] | ec | See Getting Resources |
const uint8_t * omw::windows::getResource | ( | int | idr, |
int | type, | ||
size_t * | size | ||
) |
idr | Resource ID (16bit) | |
type | Resource type (16bit) | |
[out] | size | Number of bytes |
Throwing function, see Getting Resources.
const uint8_t * omw::windows::getResource | ( | int | idr, |
int | type, | ||
size_t * | size, | ||
omw::windows::ErrorCode & | ec | ||
) |
idr | Resource ID (16bit) | |
type | Resource type (16bit) | |
[out] | size | Number of bytes |
[out] | ec | See Getting Resources |
std::string omw::windows::getTextResource | ( | int | idr | ) |
idr | Resource ID (16bit) |
Throwing function, see Getting Resources.
std::string omw::windows::getTextResource | ( | int | idr, |
omw::windows::ErrorCode & | ec | ||
) |
idr | Resource ID (16bit) | |
[out] | ec | See Getting Resources |
int64_t omw::windows::perfCntrCalcTickCount | ( | double | t_s | ) |
t_s | Duration in seconds |
Calculates the number of ticks based on the frequency of the performance counter.
int64_t omw::windows::perfCntrCalcTickCount_ms | ( | uint32_t | t_ms | ) |
t_ms | Duration in milliseconds |
int64_t omw::windows::perfCntrCalcTickCount_s | ( | uint32_t | t_s | ) |
t_s | Duration in seconds |
int64_t omw::windows::perfCntrCalcTickCount_us | ( | uint32_t | t_us | ) |
t_us | Duration in microseconds |
|
inline |
[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 |
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_..()
.
|
inline |
Alias for queryPerformanceCounter().
std::vector< omw::string > omw::windows::queryDosDevice | ( | const std::string & | device | ) |
device |
Exceptions
omw::windows::utf8_to_wstr()
is called and may throw exceptions int64_t omw::windows::queryPerformanceCounter | ( | ) |
int64_t omw::windows::queryPerformanceFrequency | ( | ) |
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.
src | The input string | |
[out] | LPWSTR_dest | Pointer (LPWSTR ) to the output buffer (WCHAR[] ) |
destSize | Size of the destination buffer (number of WCHAR ) |
The src argument can also be of type const char*
(implicit std::string()
constructor).
Throwing function, see String Conversion Functions.
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.
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 |
The src argument can also be of type const char*
(implicit std::string()
constructor).
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.
src | The input string (LPCWCH ) | |
[out] | dest | Pointer to the output buffer |
destSize | Size of the destination buffer |
Throwing function, see String Conversion Functions.
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.
src | The input string (LPCWCH ) | |
[out] | dest | Pointer to the output buffer |
destSize | Size of the destination buffer | |
[out] | ec | See String Conversion Functions |
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.
src | The input string (LPCWCH ) | |
[out] | dest | Reference to the output string |
Throwing function, see String Conversion Functions.
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.
src | The input string (LPCWCH ) | |
[out] | dest | Reference to the output string |
[out] | ec | See String Conversion Functions |
|
constexpr |
Max buffer size (including terminating null) of an environment variables value.