Return Codes

ADTF provides a result code type tResult. This is used throughout most interface and class methods where things can go wrong.

Remarks: 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 and Runtime 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.

Remarks: 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.

Overview of Error Types

These error types can be used as return codes and within exceptions:

Error Code	Error String
`0`	`ERR_NOERROR`
`-2`	`ERR_UNKNOWN`
`-3`	`ERR_UNEXPECTED`
`-4`	`ERR_POINTER`
`-5`	`ERR_INVALID_ARG`
`-6`	`ERR_INVALID_FUNCTION`
`-7`	`ERR_INVALID_ADDRESS`
`-8`	`ERR_INVALID_HANDLE`
`-9`	`ERR_INVALID_FLAGS`
`-10`	`ERR_INVALID_INDEX`
`-11`	`ERR_INVALID_FILE`
`-12`	`ERR_MEMORY`
`-13`	`ERR_TIMEOUT`
`-14`	`ERR_OUT_OF_SYNC`
`-15`	`ERR_RESOURCE_IN_USE`
`-16`	`ERR_NOT_IMPL`
`-17`	`ERR_NO_INTERFACE`
`-18`	`ERR_NO_CLASS`
`-19`	`ERR_NOT_SUPPORTED`
`-20`	`ERR_NOT_FOUND`
`-21`	`ERR_CANCELED`
`-22`	`ERR_RETRY`
`-23`	`ERR_FILE_NOT_FOUND`
`-24`	`ERR_PATH_NOT_FOUND`
`-25`	`ERR_ACCESS_DENIED`
`-26`	`ERR_NOT_READY`
`-27`	`ERR_OPEN_FAILED`
`-28`	`ERR_IO_INCOMPLETE`
`-29`	`ERR_IO_PENDING`
`-30`	`ERR_NOACCESS`
`-31`	`ERR_BAD_DEVICE`
`-32`	`ERR_DEVICE_IO`
`-33`	`ERR_DEVICE_NOT_READY`
`-34`	`ERR_DEVICE_IN_USE`
`-35`	`ERR_NOT_CONNECTED`
`-36`	`ERR_UNKNOWN_FORMAT`
`-37`	`ERR_NOT_INITIALIZED`
`-38`	`ERR_FAILED`
`-39`	`ERR_END_OF_FILE`
`-40`	`ERR_INVALID_STATE`
`-41`	`ERR_EXCEPTION_RAISED`
`-42`	`ERR_INVALID_TYPE`
`-43`	`ERR_EMPTY`
`-44`	`ERR_INVALID_VERSION`
`-45`	`ERR_INVALID_LICENSE`
`-46`	`ERR_SERVICE_NOT_FOUND`
`-47`	`ERR_DAU`
`-48`	`ERR_IDLE_NOWAIT`
`-49`	`ERR_OUT_OF_RANGE`
`-50`	`ERR_KNOWN_PROBLEM`
`-51`	`ERR_INVALID_INTERFACE`

Errors at Runtime

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, or filter with the help of the RETURN_ERROR_DESC macro.

Remarks: 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:

Errors during Initialization

From	To	Service	Streaming Service	Filter
`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)`
`RL_FilterGraph`	`RL_Running`	-	`StartStreaming`	`Start`

Errors during Deinitialization

From	To	Service	Streaming Service	Filter
`RL_Running`	`RL_FilterGraph`	-	`StopStreaming`	`Stop`
`RL_FilterGraph`	`RL_StreamingGraph`	-	-	`Shutdown(StageReady)`, `Shutdown(StageNormal)`, `Shutdown(StageFirst)`
`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 Running

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

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

If you're within a method that returns a tResult, you do not have to take any additional care.

Remarks: If you need to inform the ADTF System about an error in any other location (i.e. a custom thread in a streaming service), use the default log handler with LOG_REPORT_FATAL(), LOG_REPORT_FATAL_IF_FAILED(), LOG_REPORT_RECOVERABLE() and LOG_REPORT_RECOVERABLE_IF_FAILED().

Table of Contents