Contains 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::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...

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)

size_t	utf8_to_wstr (const std::string &src, 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, 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 (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 (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 (LPCWCH src, std::string &dest)
	Converts a Windows API compatible wide string to an UTF-8 string. More...

void	wstr_to_utf8 (LPCWCH src, std::string &dest, omw::windows::ErrorCode &ec)
	Converts a Windows API compatible wide string to an UTF-8 string. More...

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

Detailed Description

Contains wraping and helper functions for the Windows API.

This namespace is only present on Windows platforms.

Also read the Strings section on the Main Page.

Get Resources

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 found
std::runtime_error if the resource could not be loaded or on C++ standard runtime errors

String Conversion Functions

The functions utf8_to_wstr() and wstr_to_utf8() are used to convert between UTF-8 char strings used by this library 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:

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

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

◆ 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 Get 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 Get 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

Can throw

◆ 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:

◆ 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 Get 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 Get 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 Get 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 Get 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 Get Resources.

◆ getTextResource() [2/2]

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

Parameters

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

Returns: Content of the text resource

◆ utf8_to_wstr() [1/2]

size_t omw::windows::utf8_to_wstr	(	const std::string &	src,
		LPWSTR	dest,
		size_t	destSize
	)

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

Parameters

	src	The input string
[out]	dest	Pointer to the output buffer
	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,
		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]	dest	Pointer to the output buffer
	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	(	LPCWCH	src,
		char *	dest,
		size_t	destSize
	)

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

Parameters

	src	The input string
[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	(	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
[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	(	LPCWCH	src,
		std::string &	dest
	)

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

Parameters

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

Throwing function, see String Conversion Functions.

◆ wstr_to_utf8() [4/4]

void omw::windows::wstr_to_utf8	(	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
[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).

Classes

Enumerations

Functions

Variables

Detailed Description

Get Resources

String Conversion Functions

Enumeration Type Documentation

◆ ERRORCODE

Function Documentation

◆ getBinaryResource() [1/2]

◆ getBinaryResource() [2/2]

◆ getEnvironmentVariable() [1/2]

◆ getEnvironmentVariable() [2/2]

◆ getResource() [1/4]

◆ getResource() [2/4]

◆ getResource() [3/4]

◆ getResource() [4/4]

◆ getTextResource() [1/2]

◆ getTextResource() [2/2]

◆ utf8_to_wstr() [1/2]

◆ utf8_to_wstr() [2/2]

◆ wstr_to_utf8() [1/4]

◆ wstr_to_utf8() [2/4]

◆ wstr_to_utf8() [3/4]

◆ wstr_to_utf8() [4/4]

Variable Documentation

◆ envVarValueMaxSize