Error reporting and handling

Basic exception class

In order to detect and report any errors that occured during the calls to OpenAL functions, OALplus consistently checks the result of the alGetError, alcGetError and alutGetError functions and if an error is indicated it throws an instance of an appropriate exception class. The exceptions (described below) contain a lot of useful information about the error and are highly configurable. See the chapter Error-related configuration options for more information.

Basic exception class

#include <oalplus/error/basic.hpp>

Error is an exception class for general OpenAL errors. Instances of this exception class are thrown whenever an error is detected during the execution of OpenAL API calls in the OALplus code. This class is derived from the standard runtime_error exception and thus the basic error message can be obtained by calling its what() member function. There are several other classes derived for more specific error types.

class Error
 : public std::runtime_error
{
public:
	static const char* Message(ALenum error_code); 

	Error(const char* message); 
	~Error(void) throw() { }

	ALenum Code(void) const; 

	const char* SourceFile(void) const; 
	const char* SourceFunc(void) const; 
	unsigned SourceLine(void) const; 

	const char* ALLib(void) const; 
	const char* ALFunc(void) const; 

	ALenum EnumParam(void) const; 
	const char* EnumParamName(void) const; 

	virtual ALenum ObjectType(void) const; 
	virtual ALint ObjectName(void) const; 
	virtual const std::string& ObjectDesc(void) const; 
};

	Returns a message for the specified `error_code`.
	Constructs a new instance of `Error` with the specified error `message`.
	Return the AL error code associated with this error.
	Returns the name of the OALplus source file where the error occured. The result of this function is also influenced by the __OALPLUS_ERROR_NO_FILE preprocessor configuration option. If set to zero, this function behaves as described above, otherwise it returns a `nullptr`.
	Returns the name of the OALplus function where the error occured. The result of this function is also influenced by the __OALPLUS_ERROR_NO_FUNC preprocessor configuration option. If set to zero, this function behaves as described above, otherwise it returns a `nullptr`.
	Returns the line of the OALplus source file where the error occured. The result of this function is also influenced by the __OALPLUS_ERROR_NO_LINE preprocessor configuration option. If set to zero, this function behaves as described above, otherwise it returns zero.
	This function returns the name of the AL library (`"al"`, `"alc"`, `"alut"`) where the error occured. The result of this function is also influenced by the __OALPLUS_ERROR_NO_AL_LIB preprocessor configuration option. If set to zero, this function behaves as described above, otherwise it returns `nullptr`.
	This function returns the name of the failed OpenAL function (without the `al` prefix) which is related to the error. The result of this function is also influenced by the __OALPLUS_ERROR_NO_AL_FUNC preprocessor configuration option. If set to zero, this function behaves as described above, otherwise it returns `nullptr`.
	Returns the value of the enumeration parameter related to the error. If no enum parameter is available, this function returns zero. The result of this function is also influenced by the __OALPLUS_ERROR_NO_AL_SYMBOL preprocessor configuration option. If set to zero, this function behaves as described above, otherwise it returns zero.
	Returns the name of the enumeration parameter related to the error. If the enum parameter name is not available, this function returns zero. The result of this function is also influenced by the __OALPLUS_ERROR_NO_AL_SYMBOL preprocessor configuration option. If set to zero, this function behaves as described above, otherwise it returns `nullptr`.
	If the error is related to a AL object, then an object type enumeration value is returned. Otherwise the result is zero.
	If the error is related to a AL object, then the numeric AL name of the object is returned. Otherwise the result is a negative integer.
	If the error is related to a AL object, then a std::string storing object description is returned. Otherwise the result is an empty std::string.

[oalplus_error_Error_2]