Error Handling

This section contains information about how errors are reported by the IC Imaging Control 4 C++ Library.

Most library functions have an output parameter Error& err. If an error occurs, the error code and error message are passed to the error handler object referenced by err.

The err parameter is defaulted to ic4::Error::Default, which by default ignores alls errors.

Using any library function or class without calling ic4::initLibrary() first always throws an exception with the error code set to ic4::ErrorCode::LibraryNotInitialized.

Capturing Error Information

To capture the error information for a library function call, create a local ic4::Error object and pass it to the function being called. If the function indicates an error (for example by returning false), check the error message:

ic4::initLibrary();
ic4::Grabber g;
 
ic4::Error e;
if( !g.deviceOpen("Camera1", e) )
{
    std::cout << "Error: " << e.message() << std::endl;
}

Enabling Exceptions

Exceptions can be enabled globally or on a per-function basis.

Globally Enable Exceptions

To enable exceptions for all function calls, pass ic4::ErrorHandlerBehavior::Throw to ic4::initLibrary. This configures ic4::Error::Default() to throw exceptions:

ic4::initLibrary({ ic4::DefaultErrorBehavior::Throw });
ic4::Grabber g;
 
g.deviceOpen("This is not a valid camera name"); // Will throw IC4Exception

With exceptions enabled globally, it is still possible to capture the error of specific function calls into a local error variable. In this case, no exception is thrown:

ic4::initLibrary({ ic4::DefaultErrorBehavior::Throw });
ic4::Grabber g;
 
ic4::Error e;
if( !g.deviceOpen("This is not a valid camera name", e) ) // Will NOT throw
{
    std::cout << "Error: " << e.message() << std::endl;
}

If error information is not required for a specific function call, it is possible to ignore an error entirely.

ic4::initLibrary({ ic4::DefaultErrorBehavior::Throw });
ic4::Grabber g;
 
g.deviceOpen("This is not a valid camera name", ic4::Error::Ignore()); // Will NOT throw

Ignoring errors is generally only recommended when performing optional operations, such as initializing properties that are not necessarily present in all devices.

Enable Exceptions for a Specific Function Call

To enable exceptions for errors from a specific function call, pass ic4::Error::Throw() to its err argument:

ic4::initLibrary();
ic4::Grabber g;
 
g.deviceOpen("This is not a valid camera name", ic4::Error::Throw()); // Will throw IC4Exception