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;
}
This class to capture error information from library function calls.
Definition Error.h:95
std::string message() const
Returns the error message.
Definition Error.h:198
Represents an opened video capture device, allowing device configuration and stream setup.
Definition Grabber.h:82
bool deviceOpen(const DeviceInfo &dev, Error &err=Error::Default())
Opens the video capture device specified by the passed device information object.
Definition Grabber.h:147
bool initLibrary(const InitLibraryConfig &config={})
This function must be used to initialize the library.
Definition InitLibrary.h:89

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::ErrorHandlerBehavior::Throw });
ic4::Grabber g;
 
g.deviceOpen("This is not a valid camera name"); // Will throw IC4Exception
@ Throw
Throws errors passed to ic4::Error::Default() as ic4::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::ErrorHandlerBehavior::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::ErrorHandlerBehavior::Throw });
ic4::Grabber g;
 
g.deviceOpen("This is not a valid camera name", ic4::Error::Ignore()); // Will NOT throw
static Error & Ignore()
An error handler that ignores all errors.
Definition Error.h:482

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
static Error & Throw()
An error handler that throws all errors.
Definition Error.h:477