Return Codes

ADTF provides a result code type tResult. This is used throughout most interface and class methods where things can go wrong. Please take a closer look at tResult class documentation for a complete overview of its functionality.

Do not create instances of tResult directly but prefer to use the helper macro RETURN_ERROR_DESC. This will capture the source location as well. To check if an operation went allright or wrong, use the IS_OK and IS_FAILED macros respectively. To forward an error from a call within a method use the RETURN_IF_FAILED_DESC macro. Use the basic RETURN_IF_FAILED macro only if you are sure that the error already contains all neccessary information to make sense of it.

Exceptions

The ADTF SDK is prepared to cope with exceptions within any of the graph objects methods, especially in your subclasses' constructors.

You are also free to throw exceptions (THROW_ERROR_DESC) in methods that return tResult error codes.

But if you call methods that return a tResult error code yourself, make sure to wrap them with the appropriate RETURN_IF_FAILED or THROW_IF_FAILED macros.

Errors during initialization

All errors that happen during the startup and initialization phase of an ADTF system are handled by the initiating component. Just make sure that you return meaningful error descriptions from the initialization and configuration methods of your service, streaming service, filter or trigger function with the help of the RETURN_ERROR_DESC macro. You are also advised to use the RETURN_IF_FAILED_DESC macro instead of the basic RETURN_IF_FAILED macro, as it allows you to annotate the original error with some context information.

Basically, any error that happens during a runlevel change, will revert the ADTF system back to the last stable runlevel. Below is a list that gives you hints when the methods of ADTF components are called:

Initialization

Runlevel Transition	System Service	Streaming Service	Filter	Trigger Function
RL_Shutdown -> RL_System	ServiceInit (if configured for this runlevel)	-	-	-
RL_System -> RL_Session	ServiceInit (if configured for this runlevel)	-	-	-
RL_Session -> RL_StreamingGraph	-	Construct, Init	-	-
RL_StreamingGraph -> RL_FilterGraph	-	-	Init(StageFirst), Init(StageNormal), Init(StageReady)	Constructor, Configure
RL_FilterGraph -> RL_Running	-	StartStreaming	Start	-

Deinitialization

Runlevel Transition	System Service	Streaming Service	Filter	Trigger Function
RL_Running -> RL_FilterGraph	-	StopStreaming	Stop	-
RL_FilterGraph -> RL_StreamingGraph	-	-	Shutdown(StageReady), Shutdown(StageNormal), Shutdown(StageFirst)	Destructor
RL_StreamingGraph -> RL_Session	-	Shutdown, Destruct	-	-
RL_Session -> RL_System	ServiceShutdown (if configured for this runlevel)	-	-	-
RL_System -> RL_Shutdown	ServiceShutdown (if configured for this runlevel)	-	-	-

Errors while the session is running

Errors, that occur while the ADTF session is in runlevel RL_Running, are handled via the adtf::base::elasto::IErrorHandling interface.

Mind that in most cases this is handled transparently for you when you set stream errors via the adtf::streaming::ant::cSampleReader::SetStreamError and adtf::streaming::ant::cSampleWriter::SetStreamError methods or if your callback to adtf::streaming::ant::cSampleReader::SetAcceptTypeCallback returns an error.

Also errors returned from one of your adtf::filter::ant::cTriggerFunction::Process methods will be handled for you. So if you're within a method that returns a tResult, you do not have to take any additional care.

If you need to inform the ADTF system about an error in any other location (i.e. a custom thread in a streaming service), get yourself an error handler via the adtf::base::elasto::create_error_handler() method. This will make sure that you always receive a valid handler, no matter if there is an actual error handling service available or not (i.e. during tests).