Error Handling

All functions in the Beast API return an element from the ILBStatus enumeration to indicate the result of the request. If the function returns ILB_ST_SUCCESS, you can be sure that the operation completed successfully. Other values may indicate that an error occurred during processing, that there was a problem with input parameters, etc. Not all values other than ILB_ST_SUCCESS indicate failure or errors; for example, when you look for an object in the cache, your function may return ILB_ST_UNKNOWN_OBJECT to indicate that the object is not in the cache.

Extended Error Information

In some cases, the ILBStatus return value does not give enough information to determine the problem. In these cases, you can call the ILBGetExtendErrorInformation() function to get more information about the last error. This function is specific to each thread, so it will always return details only on the last error to occur within the same thread. You must always call it from the same thread in which the error occurred.

Error Handling in C++

Many developers prefer to handle errors using exceptions rather than return codes. A simple way of mapping Beast errors to exceptions is to introduce a helper function that captures the return value and throws it as an exception:

class BeastException {
public:
   BeastException(ILBStatus s) : status(s) {}
   ILBStatus status;
};

inline void beastCall(ILBStatus s) {
   if(s != ILB_ST_SUCCESS) {
      throw BeastException(s);
   }
}

Now, you can wrap all your calls to Beast API functions within a call to beastCall() in order to generate exceptions. You can handle them using a standard try/catch block:

try {
   ...
   beastCall(ILBSetFov(cam, PI / 3.0f, .1f));
   ...
} catch(BeastException& ex) {
   ILBStringHandle errorString;
   ILBStringHandle extendedError;
   ILBErrorToString(ex.status, &errorString);
   ILBGetExtendErrorInformation(&extendedError);
   std::cout << "Error:" << convertBeastString(errorString) << std::endl;
   std::cout << "Info:" << convertBeastString(extendedError) << std::endl;
}

For example, this is done in the Beast example projects using the bex::apiCall function.

Crashes and unhandled exceptions

Errors of the type ILB_ST_UNHANDLED_EXCEPTION should never occur. If you receive a result of this type from a Beast API function, contact Autodesk Support immediately. See Support. Support engineers will do their best to diagnose and solve the problem quickly.

Crashes should not happen either, in normal circumstances. The most frequent cause of a crash is the use of an invalid or uninitialized object handle. If you encounter a crash, ensure that your code correctly sets up all handles before using them. See also Working With Object Handles.