e57::E57Exception Class Reference

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

#include <E57Exception.h>

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

Detailed Description

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

The E57Exception object communicates information about errors occurring in calls to the E57 API functions. The error information is communicated from the location in the E57 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 implementation. There are three optional fields that encode the location in the source code of the E57 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 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 API ErrorCode is packaged inside the E57Exception. The documentation for each function in the API declares which ErrorCode values (inside an E57Exception) can possibly be thrown by the function. Some 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 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 consistency 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

Member Function Documentation

context()

std::string e57::E57Exception::context

(

)

const

Get human-readable string that describes the context of the error.

The context string may include values in object state, or function arguments. The format of the context string is not standardized. However, in the Reference Implementation, many strings contain a sequence of " VARNAME=VARVALUE" fields.

Postcondition

No visible state is modified.

Returns

The human-readable string that describes the context of the error.

Exceptions

No	E57Exceptions.

See also

E57ExceptionsFunctions.cpp example

errorCode()

ErrorCode e57::E57Exception::errorCode

(

)

const

Get numeric ErrorCode associated with the exception.

Postcondition

No visible state is modified.

Returns

The numeric ErrorCode associated with the exception.

Exceptions

No	E57Exceptions.

See also

E57ExceptionFunctions.cpp example, E57Utilities::errorCodeToString, ErrorCode

report()

void e57::E57Exception::report	(	const char *	reportingFileName = nullptr,
		int	reportingLineNumber = 0,
		const char *	reportingFunctionName = nullptr,
		std::ostream &	os = std::cout
	)		const

Print error information on a given output stream.

Parameters

[in]	reportingFileName	Name of file where catch statement caught the exception. NULL if unknown.
[in]	reportingLineNumber	Number of source code line where catch statement caught the exception. 0 if unknown.
[in]	reportingFunctionName	String name of function containing catch statement that caught the exception. NULL if unknown.
[in]	os	Output string to print a summary of exception information and location of catch statement.

The amount of information printed to output stream may depend on whether the E57 implementation was built with debugging enabled.

Postcondition

No visible state is modified.

Exceptions

No	E57Exceptions.

See also

E57ExceptionFunctions.cpp example, ErrorCode, HelloWorld.cpp example

References e57::Utilities::errorCodeToString().

Referenced by femsolver.run.Check::check_geos_beamsection_and_shellthickness(), femsolver.run.Check::check_geos_beamsection_no(), femsolver.run.Check::check_geos_beamsection_single(), femsolver.run.Check::check_geos_shellthickness_no(), femsolver.run.Check::check_geos_shellthickness_single(), femsolver.run.Check::check_material_exists(), femsolver.run.Check::check_material_single(), femsolver.run.Check::check_mesh_exists(), femsolver.elmer.tasks.Check::checkEquations(), femsolver.elmer.tasks.Prepare::checkHandled(), femsolver.elmer.tasks.Check::checkMeshType(), femsolver.run.Check::checkSupported(), femsolver.calculix.tasks.Check::run(), femsolver.elmer.tasks.Prepare::run(), femsolver.elmer.tasks.Solve::run(), femsolver.elmer.tasks.Results::run(), femsolver.run.Machine::run(), and femsolver.task.Task::start().

sourceFileName()

const char * e57::E57Exception::sourceFileName

(

)

const

Get name of source file where exception occurred, for debugging.

May return the value of the macro variable FILE at the location where the E57Exception was constructed. May return the empty string ("") in some E57 implementations.

Postcondition

No visible state is modified.

Returns

The name of source file where exception occurred, for debugging.

Exceptions

No	E57Exceptions.

See also

E57ExceptionsFunctions.cpp example

sourceFunctionName()

const char * e57::E57Exception::sourceFunctionName

(

)

const

Get name of function in source code where the error occurred , for debugging.

May return the value of the macro variable FUNCTION at the location where the E57Exception was constructed. May return the empty string ("") in some E57 implementations.

Postcondition

No visible state is modified.

Returns

The name of source code function where the error occurred , for debugging.

Exceptions

No	E57Exceptions.

sourceLineNumber()

int e57::E57Exception::sourceLineNumber

(

)

const

Get line number in source code file where exception occurred, for debugging.

May return the value of the macro variable LINE at the location where the E57Exception was constructed. May return the empty string ("") in some E57 implementations.

Postcondition

No visible state is modified.

Returns

The line number in source code file where exception occurred, for debugging.

Exceptions

No	E57Exceptions.

what()

const char * e57::E57Exception::what ( ) const

overridenoexcept

Get string description of exception category.

Returns "E57 Exception" for all E57Exceptions, no matter what the errorCode.

Postcondition

No visible state is modified.

Returns

The string description of exception category.

Exceptions

No	E57Exceptions.

See also

E57ExceptionsFunctions.cpp example

---

The documentation for this class was generated from the following files:

• FreeCAD/src/3rdParty/libE57Format/include/E57Exception.h
• FreeCAD/src/3rdParty/libE57Format/src/E57Exception.cpp