AAX SDK  2.4.1
Avid Audio Extensions Development Kit
List of all members | Public Types | Public Member Functions
AAX_CheckedResult Class Reference

#include <AAX_Exception.h>

Description

Error checker convenience class for AAX_Result

Implicitly convertable to an AAX_Result.

Provides an overloaded operator=() which will throw an AAX::Exception::ResultError if assigned a non-success result.

Warning
Never use this class outside of an exception catch scope

If the host supports AAX_TRACE tracing, a log is emitted when the exception is thrown. A stacktrace is added if the host's trace priority filter level is set to kAAX_Trace_Priority_Lowest

When an error is encountered, AAX_CheckedResult throws an AAX_CheckedResult::Exception exception and clears its internal result value.

#include "AAX_Exception.h"
AAX_Result SomeCheckedMethod()
{
try {
cr = ResultFunc1();
cr = ResultFunc2();
}
catch (const AAX_CheckedResult::Exception& ex)
{
// handle exception; do not rethrow
result = ex.Result();
}
catch (...)
{
}
return result;
}
int32_t AAX_Result
Definition: AAX.h:337
@ AAX_ERROR_UNKNOWN_EXCEPTION
An AAX plug-in should return this to the host if an unknown exception is caught. Exceptions should ne...
Definition: AAX_Errors.h:82
@ AAX_SUCCESS
Definition: AAX_Errors.h:39
AAX SDK exception classes and utilities
Definition: AAX_Exception.h:147
AAX_Result Result() const
Definition: AAX_Exception.h:174
Definition: AAX_Exception.h:317
Note
The AAX Library method which calls GetEffectDescriptions() on the plug-in includes an appropriate exception handler, so AAX_CheckedResult objects may be used within a plug-in's describe code without additional catch scopes.
#include "AAX_Exception.h"
{
cr = MyDescriptionSubroutine1();
cr = outCollection->AddEffect(...);
// etc.
return cr;
}
AAX_Result GetEffectDescriptions(AAX_ICollection *inCollection)
The plug-in's static Description entrypoint.
Interface to represent a plug-in binary's static description.
Definition: AAX_ICollection.h:54
virtual AAX_Result AddEffect(const char *inEffectID, AAX_IEffectDescriptor *inEffectDescriptor)=0
Add an Effect description to the collection.

It is assumed that the exception handler will resolve any error state and that the AAX_CheckedResult may therefore continue to be used from a clean state following the exception catch block.

If the previous error value is required then it can be retrieved using AAX_CheckedResult::LastError().

// in this example, the exception is handled and
// success is returned from MyFunc1()
AAX_Result MyFunc1()
{
try {
cr = MethodThatReturnsError();
} catch (const AAX::Exception::ResultError& ex) {
// exception is fully handled here
}
// cr now holds a success value
return cr;
}
// in this example, MyFunc2() returns the first
// non-successful value which was encountered
AAX_Result MyFunc2()
{
try {
AAX_SWALLOW(cr = MethodThatMayReturnError1());
AAX_SWALLOW(cr = MethodThatMayReturnError2());
cr = MethodThatMayReturnError3();
} catch (const AAX::Exception::ResultError& ex) {
// exception might not be fully handled
}
// pass the last error on to the caller
return cr.LastError();
}
#define AAX_SWALLOW(...)
Executes X in a try/catch block that catches AAX_CheckedResult exceptions.
Definition: AAX_Exception.h:447
AAX_Result LastError() const
Get the last non-success result which was stored in this object, or AAX_SUCCESS if no non-success res...
Definition: AAX_Exception.h:390

It is possible to add one or more accepted non-success values to an AAX_CheckedResult so that these values will not trigger exceptions:

try {
cr.AddAcceptedResult(AcceptableErrCode);
cr = MethodThatReturnsAcceptedError();
cr = MethodThatReturnsAnotherError();
} catch (const AAX::Exception::ResultError& ex) {
// handle the exception
}
void AddAcceptedResult(AAX_Result inResult)
Add an expected result which will not result in a throw.
Definition: AAX_Exception.h:348

Public Types

typedef AAX::Exception::ResultError Exception
 

Public Member Functions

 ~AAX_CheckedResult ()
 
 AAX_CheckedResult ()
 Construct an AAX_CheckedResult in a success state. More...
 
 AAX_CheckedResult (AAX_Result inResult)
 Implicit conversion constructor from AAX_Result. More...
 
void AddAcceptedResult (AAX_Result inResult)
 Add an expected result which will not result in a throw. More...
 
void ResetAcceptedResults ()
 
AAX_CheckedResultoperator= (AAX_Result inResult)
 Assignment to AAX_Result. More...
 
AAX_CheckedResultoperator|= (AAX_Result inResult)
 bitwise-or assignment to AAX_Result More...
 
 operator AAX_Result () const
 Conversion to AAX_Result. More...
 
void Clear ()
 Clears the current result state. More...
 
AAX_Result LastError () const
 Get the last non-success result which was stored in this object, or AAX_SUCCESS if no non-success result was ever stored in this object. More...
 

Member Typedef Documentation

◆ Exception

Constructor & Destructor Documentation

◆ ~AAX_CheckedResult()

AAX_CheckedResult::~AAX_CheckedResult ( )
inline

◆ AAX_CheckedResult() [1/2]

AAX_CheckedResult::AAX_CheckedResult ( )
inline

Construct an AAX_CheckedResult in a success state.

◆ AAX_CheckedResult() [2/2]

AAX_CheckedResult::AAX_CheckedResult ( AAX_Result  inResult)
inline

Implicit conversion constructor from AAX_Result.

Implicit conversion is OK in order to support AAX_CheckedResult cr = SomeFunc()

Member Function Documentation

◆ AddAcceptedResult()

void AAX_CheckedResult::AddAcceptedResult ( AAX_Result  inResult)
inline

Add an expected result which will not result in a throw.

It is acceptable for some methods to return certain non-success values such as AAX_RESULT_PACKET_STREAM_NOT_EMPTY or AAX_RESULT_NEW_PACKET_POSTED

◆ ResetAcceptedResults()

void AAX_CheckedResult::ResetAcceptedResults ( )
inline

References AAX_SUCCESS.

◆ operator=()

AAX_CheckedResult& AAX_CheckedResult::operator= ( AAX_Result  inResult)
inline

Assignment to AAX_Result.

Referenced by operator|=().

Here is the caller graph for this function:

◆ operator|=()

AAX_CheckedResult& AAX_CheckedResult::operator|= ( AAX_Result  inResult)
inline

bitwise-or assignment to AAX_Result

Sometimes used in legacy code to aggregate results into a single AAX_Result value

References operator=().

Here is the call graph for this function:

◆ operator AAX_Result()

AAX_CheckedResult::operator AAX_Result ( ) const
inline

Conversion to AAX_Result.

◆ Clear()

void AAX_CheckedResult::Clear ( )
inline

Clears the current result state.

Does not affect the set of accepted results

References AAX_SUCCESS.

◆ LastError()

AAX_Result AAX_CheckedResult::LastError ( ) const
inline

Get the last non-success result which was stored in this object, or AAX_SUCCESS if no non-success result was ever stored in this object.


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