E57Exception Class Reference

Object thrown by E57 Foundation API functions to communicate the conditions of an error. More...

List of all members.

Public Member Functions
virtual void	report (const char *reportingFileName=NULL, int reportingLineNumber=0, const char *reportingFunctionName=NULL, std::ostream &os=std::cout) const
	Print error information on a given output stream.
virtual ErrorCode	errorCode () const
	Get numeric ErrorCode associated with the exception.
virtual ustring	context () const
	Get human-readable string that describes the context of the error.
virtual const char *	what () const throw ()
	Get string description of exception category.
virtual const char *	sourceFileName () const
	Get name of source file where exception occurred, for debugging.
virtual const char *	sourceFunctionName () const
	Get name of function in source code where the error occurred , for debugging.
virtual int	sourceLineNumber () const
	Get line number in source code file where exception occurred, for debugging.

---

Detailed Description

Object thrown by E57 Foundation API functions to communicate the conditions of an error.

The E57Exception object communicates information about errors occuring in calls to the E57 Foundation API functions. The error information is communicated from the location in the E57 Foundation Implementation where the error was detected to the catch statement in the code of the API user. The state of E57Exception object has one mandatory field, the errorCode, and several optional fields that can be set depending on the debug level of the E57 Foundation Implementation. There are three optional fields that encode the location in the source code of the E57 Foundation Implementation where the error was detected: sourceFileName, sourceFunctionName, and sourceLineNumber. Another optional field is the context string that is human (or at least programmer) readable, which can capture some variable values that might be useful in debugging. The E57Exception class is derived from std::exception. So applications that only catch std::exceptions will detect E57Exceptions (but with no information about the origin of the error).

Many other APIs use error codes (defined integer constants) returned from the API functions to communicate success or failure of the requested command. In contrast, the E57 Foundation API uses the C++ exception mechanism to communicate failure (success is communicated by the return of the function without exception). E57Exception(E57_SUCCESS) is never thrown. The Foundation API ErrorCode is packaged inside the E57Exception. The documentation for each function in the Foundation API declares which ErrorCode values (inside an E57Exception) can possibly be thrown by the function. Some Foundation API functions do not throw any E57Exceptions, and this is documented by the designation "No E57Exceptions." in the "Exceptions:" section of the function documentation page.

If an API function does throw an E57Exception, the API user will rightfully be concerned about the state of all of the API objects. There are four categories of guarantee about the state of all objects that the API specifies.

1) All objects unchanged - all API objects are left in their original state before the API function was called. This is the default guarantee, so if there is no notation next to the ErrorCode in the "Exceptions:" section of the function documentation page, the this category is implied.

2) XXX object modified, but consistent - The given object (or objects) have been modified, but are left in a consistent state.

3) XXX object in undocumented state - The given object (or objects) may have been left in an inconsistent state, and the only safe thing to do with them is to call their destructor.

4) All objects in undocumented state - A very serious consistency error has been detected, and the state of all API objects is suspect. The only safe thing to do is to call their destructors.

Almost all of the API functions can throw the following two ErrorCodes: E57_ERROR_IMAGEFILE_NOT_OPEN and E57_ERROR_INTERNAL. In some E57 Foundation Implementations, the tree information may be stored on disk rather than in memory. If the disk file is closed, even the most basic information may not be available about nodes in the tree. So if the ImageFile is closed (by calling ImageFile::close), the API user must be ready for many of the API functions to throw E57Exception(E57_ERROR_IMAGEFILE_NOT_OPEN). Secondly, regarding the E57_ERROR_INTERNAL error, there is a lot of consistancy checking in the Reference Implementation, and there may be much more added. Even if some API routines do not now throw E57_ERROR_INTERNAL, they could some time in the future, or in different implementations. So the right to throw E57_ERROR_INTERNAL is reserved for every API function (except those that by design can't throw E57Exceptions).

It is strongly recommended that catch statements in user code that call API functions catch E57Exception by reference (i.e. catch (E57Exception& ex) and, if necessary, rethrow using the syntax that throws the currently active exception (i.e. throw;).

Exceptions other that E57Exception may be thrown by calls to API functions (e.g. std::bad_alloc). Production code will likely have catch handlers for these exceptions as well.

See also:

HelloWorld.cpp example