| AAX SDK 2.8.0 Avid Audio Extensions Development Kit

- Welcome
- Manual
- Classes
- Files
- Lists
- Support

- Class List
- Class Index
- Class Hierarchy
- Class Members

Loading...
Searching...
No Matches
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()
{
AAX_Result result = AAX_SUCCESS;
try {
AAX_CheckedResult cr;
cr = ResultFunc1();
cr = ResultFunc2();
}
catch (const AAX_CheckedResult::Exception& ex)
{
// handle exception; do not rethrow
result = ex.Result();
}
catch (...)
{
result = AAX_ERROR_UNKNOWN_EXCEPTION;
}
return result;
}
AAX_ERROR_UNKNOWN_EXCEPTION
@ 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:92
AAX_SUCCESS
@ AAX_SUCCESS
Definition: AAX_Errors.h:49
AAX_Result
int32_t AAX_Result
Definition: AAX.h:347
AAX_Exception.h
AAX SDK exception classes and utilities
AAX::Exception::ResultError
Definition: AAX_Exception.h:166
AAX::Exception::ResultError::Result
AAX_Result Result() const
Definition: AAX_Exception.h:200
AAX_CheckedResult
Definition: AAX_Exception.h:343

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"
AAX_Result GetEffectDescriptions( AAX_ICollection * outCollection )
{
AAX_CheckedResult cr;
cr = MyDescriptionSubroutine1();
cr = outCollection->AddEffect(...);
// etc.
return cr;
}
GetEffectDescriptions
AAX_Result GetEffectDescriptions(AAX_ICollection *inCollection)
The plug-in's static Description entrypoint.
AAX_ICollection
Interface to represent a plug-in binary's static description.
Definition: AAX_ICollection.h:64
AAX_ICollection::AddEffect
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()
{
AAX_CheckedResult cr;
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()
{
AAX_CheckedResult cr;
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();
}
AAX_SWALLOW
#define AAX_SWALLOW(...)
Executes X in a try/catch block that catches AAX_CheckedResult exceptions.
Definition: AAX_Exception.h:473
AAX_CheckedResult::LastError
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:416

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

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

## Public Types
typedef AAX::Exception::ResultError | Exception

## Public Member Functions
| ~AAX_CheckedResult ()
| AAX_CheckedResult ()
| Construct an AAX_CheckedResult in a success state.
| AAX_CheckedResult (AAX_Result inResult)
| Implicit conversion constructor from AAX_Result.
void | AddAcceptedResult (AAX_Result inResult)
| Add an expected result which will not result in a throw.
void | ResetAcceptedResults ()
AAX_CheckedResult & | operator= (AAX_Result inResult)
| Assignment to AAX_Result.
AAX_CheckedResult & | operator|= (AAX_Result inResult)
| bitwise-or assignment to AAX_Result
| operator AAX_Result () const
| Conversion to AAX_Result.
void | Clear ()
| Clears the current result state.
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.

## Member Typedef Documentation

## ◆ Exception

typedef AAX::Exception::ResultError AAX_CheckedResult::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:

- AAX_Exception.h