Wrappers for common Windows functions. More...

#include <utf8/utf8.h>
#include <cassert>
#include <windows.h>

Functions
bool	utf8::find_first (const std::string &name, find_data &fdat)
	Searches a directory for a file or subdirectory with a name that matches a name (that can have wildcards).

bool	utf8::find_next (find_data &fdat)
	Continues a search started by find_first() function.

void	utf8::find_close (find_data &fdat)
	Closes a "search handle" opened by find_first() function.

int	utf8::MessageBox (HWND hWnd, const std::string &text, const std::string &caption, unsigned int type)
	Convenience wrapper for Windows MessageBox function.

bool	utf8::CopyFile (const std::string &from, const std::string &to, bool fail_exist)
	Convenience wrapper for Windows CopyFile function.

std::string	utf8::LoadString (UINT id, HINSTANCE hInst)
	Convenience wrapper for Windows LoadString function.

HINSTANCE	utf8::ShellExecute (const std::string &file, const std::string &verb, const std::string &parameters, const std::string &directory, HWND hWnd, int show)
	Convenience wrapper for Windows ShellExecute function.

std::string	utf8::GetTempPath ()
	Convenience wrapper for GetTempPath

std::string	utf8::GetTempFileName (const std::string &path, const std::string &prefix, UINT unique)
	Convenience wrapper for GetTempFileName

std::string	utf8::GetFullPathName (const std::string &rel_path)
	Convenience wrapper for GetFullPathName

bool	utf8::GetModuleFileName (HMODULE hModule, std::string &filename)
	Convenience wrapper for GetModuleFileName

std::string	utf8::GetModuleFileName (HMODULE hModule)
	Convenience wrapper for GetModuleFileName

bool	utf8::symlink (const char path, const char link, bool directory)
	Create a symbolic link.

bool	utf8::symlink (const std::string &path, const std::string &link, bool directory)
	Create a symbolic link.

bool	utf8::splitpath (const std::string &path, char drive, char dir, char fname, char ext)
	Breaks a path name into components.

bool	utf8::splitpath (const std::string &path, std::string &drive, std::string &dir, std::string &fname, std::string &ext)
	Breaks a path name into components.

bool	utf8::makepath (std::string &path, const std::string &drive, const std::string &dir, const std::string &fname, const std::string &ext)
	Creates a path from UTF-8 encoded components.

std::string	utf8::fullpath (const std::string &relpath)
	Returns the absolute (full) path of a filename.

std::string	utf8::getenv (const std::string &var)
	Retrieves the value of an environment variable.

char **	utf8::get_argv (int *argc)
	Converts wide byte command arguments to an array of pointers to UTF-8 strings.

void	utf8::free_argv (int argc, char **argv)
	Frees the memory allocated by get_argv(int *argc)

std::vector< std::string >	utf8::get_argv ()
	Converts wide byte command arguments to UTF-8 to a vector of UTF-8 strings.

LSTATUS	utf8::RegCreateKey (HKEY key, const std::string &subkey, HKEY &result, DWORD options, REGSAM sam, const SECURITY_ATTRIBUTES psa, DWORD disp)
	Convenience wrapper for RegCreateKeyEx

LSTATUS	utf8::RegOpenKey (HKEY key, const std::string &subkey, HKEY &result, REGSAM sam, bool link)
	Wrapper for RegOpenKeyEx

LSTATUS	utf8::RegDeleteKey (HKEY key, const std::string &subkey, REGSAM sam)
	Wrapper for RegDeleteKeyEx or RegDeleteKey

LSTATUS	utf8::RegDeleteValue (HKEY key, const std::string &value)
	Wrapper for RegDeleteValue

LSTATUS	utf8::RegDeleteTree (HKEY key, const std::string &subkey)
	Wrapper for RegDeleteTree

LSTATUS	utf8::RegRenameKey (HKEY key, const std::string &subkey, const std::string &new_name)
	Wrapper for RegRenameKey

LSTATUS	utf8::RegSetValue (HKEY key, const std::string &value, DWORD type, const void *data, DWORD size)
	Wrapper for RegSetValueEx

LSTATUS	utf8::RegSetValue (HKEY key, const std::string &value, const std::string &data)
	Convenience Wrapper for RegSetValueEx for string data.

LSTATUS	utf8::RegSetValue (HKEY key, const std::string &value, const std::vector< std::string > &data)
	Convenience Wrapper for RegSetValueEx for vector of string data.

LSTATUS	utf8::RegQueryValue (HKEY key, const std::string &value, DWORD type, void data, DWORD *size)
	Wrapper for RegQueryValueEx

LSTATUS	utf8::RegGetValue (HKEY key, const std::string &subkey, const std::string &value, DWORD flags, void data, DWORD size, DWORD *type)
	Wrapper for RegGetValue

LSTATUS	utf8::RegGetValue (HKEY key, const std::string &subkey, const std::string &value, std::string &data, bool expand)
	Retrieves a string from a registry key value using the RegGetValue function.

LSTATUS	utf8::RegGetValue (HKEY key, const std::string &subkey, const std::string &value, std::vector< std::string > &data)
	Retrieves a vector of strings from a registry key value using the RegGetValue function.

LSTATUS	utf8::RegEnumKey (HKEY key, DWORD index, std::string &name, DWORD maxlen, FILETIME *last_write_time)
	Wrapper for RegEnumKeyEx

LSTATUS	utf8::RegEnumKey (HKEY key, std::vector< std::string > &names)
	Enumerate all subkeys of a key.

LSTATUS	utf8::RegEnumValue (HKEY key, DWORD index, std::string &value, DWORD maxlen, DWORD type, void data, DWORD *data_len)
	Wrapper for RegEnumValue

LSTATUS	utf8::RegEnumValue (HKEY key, std::vector< std::string > &values)
	Enumerate all values of a key.

Detailed Description

Wrappers for common Windows functions.

Function Documentation

◆ CopyFile()

bool utf8::CopyFile	(	const std::string &	from,
		const std::string &	to,
		bool	fail_exist
	)

Convenience wrapper for Windows CopyFile function.

Parameters

from	Name of the existing file
to	Name of the new file
fail_exist

◆ find_first()

bool utf8::find_first	(	const std::string &	name,
		find_data &	fdat
	)

Searches a directory for a file or subdirectory with a name that matches a name (that can have wildcards).

Parameters

name	File name (or partial file name) to find
fdat	Information structure containing file name and attributes

Returns: true if a file was found or false otherwise.

Note: Wrapper for FindFirstFile Windows API function.

If successful, the function opens a "search handle" stored in the fdat structure. The handle has to be closed using find_close() function.

◆ find_next()

bool utf8::find_next ( find_data & fdat )

Continues a search started by find_first() function.

Parameters

fdat	search results structure containing file information

Returns: true if a file was found or false otherwise.

Note: Wrapper for FindNextFileW Windows API function.

If there are no more files, the function returns false and GetLastError function returns ERROR_NO_MORE_FILES

◆ free_argv()

void utf8::free_argv	(	int	argc,
		char **	argv
	)

Frees the memory allocated by get_argv(int *argc)

Parameters

argc	number of arguments
argv	array of pointers to arguments

◆ fullpath()

std::string utf8::fullpath ( const std::string & relpath )

Returns the absolute (full) path of a filename.

Parameters

relpath relative path

◆ get_argv() [1/2]

std::vector< std::string > utf8::get_argv ( )

Converts wide byte command arguments to UTF-8 to a vector of UTF-8 strings.

Returns: vector of UTF-8 strings. The vector is empty if an error occurred.

◆ get_argv() [2/2]

char ** utf8::get_argv ( int * argc )

Converts wide byte command arguments to an array of pointers to UTF-8 strings.

Parameters

argc	Pointer to an integer that contains number of parameters

Returns: array of pointers to each command line parameter or NULL if an error occurred.

The space allocated for strings and array of pointers should be freed by calling free_utf8argv()

◆ getenv()

std::string utf8::getenv ( const std::string & var )

Retrieves the value of an environment variable.

Parameters

var	name of environment variable

Returns: value of environment variable or an empty string if there is no such environment variable

◆ GetFullPathName()

std::string utf8::GetFullPathName ( const std::string & rel_path )

Convenience wrapper for GetFullPathName

Parameters

rel_path relative path name

Returns: full pathname or empty string if there is an error

◆ GetModuleFileName() [1/2]

std::string utf8::GetModuleFileName ( HMODULE hModule )

Convenience wrapper for GetModuleFileName

Parameters

hModule module handle for which path will be retrieved or NULL to retrieve path of current executable.

Returns: UTF-8 encoded module file name or empty string if an error occurred

◆ GetModuleFileName() [2/2]

bool utf8::GetModuleFileName	(	HMODULE	hModule,
		std::string &	filename
	)

Convenience wrapper for GetModuleFileName

Parameters

hModule	module handle for which path will be retrieved or NULL to retrieve path of current executable.
filename	UTF-8 encoded module file name

Returns: true if successful false otherwise

◆ GetTempFileName()

std::string utf8::GetTempFileName	(	const std::string &	path,
		const std::string &	prefix,
		UINT	unique
	)

Convenience wrapper for GetTempFileName

Parameters

path	directory path
prefix	filename prefix (up to 3 characters)
unique	integer value used to create filename

Returns: a filename with structure <path>\<prefix>nnnnn.tmp

◆ GetTempPath()

std::string utf8::GetTempPath ( )

Convenience wrapper for GetTempPath

Returns: path of the directory designated for temporary files.

◆ LoadString()

std::string utf8::LoadString	(	UINT	id,
		HINSTANCE	hInst
	)

Convenience wrapper for Windows LoadString function.

Parameters

id	String identifier
hInst	module handle of the module containing the string resource

Returns: UTF-8 resource string or an empty string if resource doesn't exist

◆ makepath()

bool utf8::makepath	(	std::string &	path,
		const std::string &	drive,
		const std::string &	dir,
		const std::string &	fname,
		const std::string &	ext
	)

Creates a path from UTF-8 encoded components.

Parameters

path	Resulting path (UTF-8 encoded)
drive	drive letter
dir	directory path
fname	filename
ext	extension

Returns: True if successful; false otherwise

If any required syntactic element (colon after drive letter, '\' at end of directory path, colon before extension) is missing, it is automatically added.

◆ MessageBox()

int utf8::MessageBox	(	HWND	hWnd,
		const std::string &	text,
		const std::string &	caption,
		unsigned int	type
	)

Convenience wrapper for Windows MessageBox function.

Parameters

hWnd	handle to the owner window
text	UTF-8 encoded message to be displayed
caption	UTF-8 encoded dialog box title
type	flags for content and behavior of the dialog box

◆ ShellExecute()

HINSTANCE utf8::ShellExecute	(	const std::string &	file,
		const std::string &	verb,
		const std::string &	parameters,
		const std::string &	directory,
		HWND	hWnd,
		int	show
	)

Convenience wrapper for Windows ShellExecute function.

Parameters

file	file or object on which to execute the specified verb
verb	action to be performed
parameters	parameters to be passed to the application
directory	default (working) directory
hWnd	handle to the parent window
show	parameter for the ShowWindow function

Returns: pseudo instance handle >32 if function succeeds.

◆ splitpath() [1/2]

bool utf8::splitpath	(	const std::string &	path,
		char *	drive,
		char *	dir,
		char *	fname,
		char *	ext
	)

Breaks a path name into components.

Parameters

path	UTF-8 encoded full path
drive	drive letter followed by colon (or NULL if not needed)
dir	directory path (or NULL if not needed)
fname	base filename (or NULL if not needed)
ext	file extension including the leading period (.) (or NULL if not needed)

Returns: true if successful, false otherwise Returned strings are converted to UTF-8.

◆ splitpath() [2/2]

bool utf8::splitpath	(	const std::string &	path,
		std::string &	drive,
		std::string &	dir,
		std::string &	fname,
		std::string &	ext
	)

Breaks a path name into components.

Parameters

path	UTF-8 encoded full path
drive	drive letter followed by colon
dir	directory path
fname	base filename
ext	file extension including the leading period (.)

Returned strings are converted to UTF-8.

◆ symlink() [1/2]

bool utf8::symlink	(	const char *	path,
		const char *	link,
		bool	directory
	)

Create a symbolic link.

Parameters

path	target path name
link	name of symbolic link
directory	`true` if link target is a directory

Returns: true if successful, false otherwise

◆ symlink() [2/2]

bool utf8::symlink	(	const std::string &	path,
		const std::string &	link,
		bool	directory
	)

Create a symbolic link.

Parameters

path	target path name
link	name of symbolic link
directory	`true` if link target is a directory

Returns: true if successful, false otherwise

Functions

Detailed Description

Function Documentation

◆ CopyFile()

◆ find_first()

◆ find_next()

◆ free_argv()

◆ fullpath()

◆ get_argv() [1/2]

◆ get_argv() [2/2]

◆ getenv()

◆ GetFullPathName()

◆ GetModuleFileName() [1/2]

◆ GetModuleFileName() [2/2]

◆ GetTempFileName()

◆ GetTempPath()

◆ LoadString()

◆ makepath()

◆ MessageBox()

◆ ShellExecute()

◆ splitpath() [1/2]

◆ splitpath() [2/2]

◆ symlink() [1/2]

◆ symlink() [2/2]