ChsvExceptionByWin32Code() [4/4]

void Chusov::Win32::Exceptions::ChsvExceptionByWin32Code	(	DWORD	nCode,
		va_list	ap,
		const wchar_t *	pszDescription
	)

Creates an instance of the Chusov::Exceptions::ChsvCodeExceptionTempl class and throws it as an exception. The instantiation of the Chusov::Exceptions::ChsvCodeExceptionTempl class template is chosen depending on the result of translation of the specified Windows error code to the corresponding chsvlib error code, which is performed by the Chusov::Win32ErrorToChsvError function.

Template Parameters

fProcessSuccessCodeAsUnknownError

is a flag specifying if ERROR_SUCCESS should be interpreted as an unknown error. This means, that if the flag is set, and the error code has a value of ERROR_SUCCESS (or NO_ERROR), then the thrown exception is Chusov::Exceptions::UnknownException. Otherwise, it is ChsvCodeExceptionTempl<CHSVERROR_SUCCESS>.

Parameters

[in]	nCode	is a Windows error code. The function calls the Windows FormatMessage function when trying matching the code with the corresponding textual description.
[in]	ap	is a list of additional parameters defined with respect to the string pointed to by the pszDescription pointer as specified for the Chusov::String::PrintfW function.
[in]	pszDescription	is a pointer to a zero-terminated string specifying formatting rules used by the function during construction of the thrown exception. The formatting sequences are specified with respect to the Chusov::String::PrintfW function. Also, <CODE>, <DESCRIPTION> and, for some error codes, <PLATFORM_CODE> and <PLATFORM_DESCRIPTION> tags are allowed to be specified in the string to be replaced by a numeric value of the corresponding chsvlib error code, its description, a value of the Windows error code and its description respectively. See details for some important notes about using these tags in the description format string.

The function generates an exception of class that publicly inherits Chusov::Exceptions::Exception class, either directly or indirectly. A specific inheritor is determined based on the value of the Windows error code, passed to the function through the nCode parameter, or, more specifically, on the result of the translation of the Windows error code to the corresponding chsvlib error code. The accordance is established by the Chusov::Win32ErrorToChsvError translation function. The one returns either a specific chsvlib error code, which gives specific information about the error, or CHSVERROR_PLATFORM_ERROR, if the accordance of the Windows error code to the specific chsvlib error code is not established. In the latter case a class of the generated exception is of type that is an instantiation of the Chusov::Exceptions::PlatformException template with errno_t template parameter. The Chusov::Exceptions::PlatformException class template directly inherits the Chusov::Exceptions::ChsvCodeExceptionTempl <CHSVERROR_PLATFORM_ERROR> class.

Therefore, if the <CODE> and/or <DESCRIPTION> tags are specified in the formatting string, they can be replaced by an informative error code value and description only if accordance of the Windows error code to the specific chsvlib error code is established. Otherwise, they are replaced with a numeric value of CHSVERROR_PLATFORM_ERROR and a description, which corresponds to this value. In this case the caller can specify <PLATFORM_CODE> and <PLATFORM_DESCRIPTION> tags to get information about the value of the Windows error code, which is a numeric value of the nCode parameter and a corresponding description, which is retrieved from a call to the FormatMessage function. These tags are implemented by the Chusov::Exceptions::PlatformException class template.

On the other hand, if the Windows error code is mapped to a specific error code, the generated exception is of type that is one of the specific exception classes. These classes, which are the instantiations of the Chusov::Exceptions::ChsvCodeExceptionTempl class template, do not implement <PLATFORM_CODE> and <PLATFORM_DESCRIPTION> tags. Therefore, if they are specified in the format string, they are replaced with strings, saying that the substrings for the tags are not specified.

To avoid cares about these details on inheritance and the Chusov::Win32ErrorToChsvError function, the caller may either use ChsvExceptionByWin32Code(DWORD nCode) function, which always constructs correct, the most informative description, or throw specifically the Chusov::Exceptions::PlatformException class providing the get_win32_error_description function object to its constructors. The get_win32_error_description class is a helper element which is a wrap over the FormatMessage function created with conformance to the specific rules of the function objects generating descriptions.

Examples

chsvwinutilex\CreateDACL.cpp.