ChsvExceptionByPlatformCode() [3/4]

void Chusov::Exceptions::ChsvExceptionByPlatformCode	(	chsv_syserror_t	nCode,
		const char *restrict	pszDescription,
		DescriptionFormatParams ...	format_params
	)

Creates an instance of the ChsvCodeExceptionTempl class and throws it as an exception. The instantiation of the ChsvCodeExceptionTempl class template is chosen depending on the result of a translation of the specified operating system error code to the corresponding chsvlib error code.

Template Parameters

fProcessSuccessCodeAsUnknownError	is a flag specifying if a zero operating system error code should be interpreted as an unknown error. This means that if the flag is set, and the error code has a zero value, then the thrown exception is UnknownException. Otherwise, it is ChsvCodeExceptionTempl<CHSVERROR_SUCCESS>.
DescriptionFormatParams	Deduced types of additional arguments passed to the function to format the message.

Parameters

[in]	nCode	is an error code defined by operating system. The function makes a system call to produce the corresponding textual description.
[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::PrintfA function. Also, the <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 operating system error itself and its description respectively. See details for some important notes about using these tags in the description format string.
[in]	format_params	is a set of additional parameters defined with respect to the string pointed to by the pszDescription pointer as specified for the Chusov::String::PrintfA function.

The function generates an exception of class that publicly inherits Exception class, either directly or indirectly. A specific inheritor is determined based on the value of the operating system error, passed to the function through the nCode parameter, or, more specifically, on the result of the translation of the operating system error to the corresponding chsvlib error code. The accordance is established by the Chusov::SystemErrorToChsvError 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 operating system error 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 PlatformException template with chsv_syserror_t template parameter. The PlatformException class template directly inherits the 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 operating system 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 may specify <PLATFORM_CODE> and <PLATFORM_DESCRIPTION> tags to get information about operating system error itself, which is a numeric value of the nCode parameter and a corresponding description, produced from a call to the operating system. These tags are implemented by the PlatformException class template.

On the other hand, if the operating system 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 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 SystemErrorToChsvError(chsv_syserror_t err) function, the caller may either use ChsvExceptionByPlatformCode(chsv_syserror_t nCode) function, which always constructs correct and the most informative description, or throw specifically the PlatformException exception passing a pointer to the operating system to obtain the textual description.