ChsvExceptionByPosixCode() [3/4]

void Chusov::Exceptions::ChsvExceptionByPosixCode	(	errno_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 POSIX error code to the corresponding chsvlib error code. .

Template Parameters

fProcessSuccessCodeAsUnknownError	is a flag specifying if a zero POSIX 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 the POSIX standard. The function calls the standard C strerror function when trying matching it with the corresponding textual description. The POSIX errno codes can be defined in one of the included headers, or, otherwise, they are retrieved from the chsverr.h header.
[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 POSIX 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 POSIX error, passed to the function through the nCode parameter, or, more specifically, on the result of the translation of the POSIX error to the corresponding chsvlib error code. The accordance is established by the PosixErrorToChsvError 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 POSIX 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 errno_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 POSIX 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 POSIX error itself, which is a numeric value of the nCode parameter and a corresponding description, which is retrieved from a call to the standard strerror function. These tags are implemented by the PlatformException class template.

On the other hand, if the POSIX 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 PosixErrorToChsvError function, the caller may either use Chusov::Exceptions::ChsvExceptionByPosixCode(errno_t nCode) function, which always constructs correct and the most informative description, or throw specifically the PlatformException exception passing a pointer to the standard strerror function to its constructors.

Examples

chsvexception\chsv_list_of_exceptions.cpp, and chsvexception\nested_exceptions.cpp.