FC++ Exceptions

The Unlimi-Tech Workflow/Spaces C++ API makes use of the Unlimi-Tech FileCatalyst C++ API, including the fc::Exception objects which are thrown when problems are detected.

Note

All Workflow/Spaces functions and fc::WS methods that detect significant problems will throw a fc::Exception object. This means checking status results after FC++ and WS++ API calls is generally unecessary. Instead, you'll want a try/catch block to prevent the stack from unwinding if an exception is thrown.

The fc::Exception class derives publicly from std::exception, and is defined in "FCException.hpp". Objects of type fc::Exception have the following:

• A single line text message, available via what(), same as any exception that derives from std::exception.
• A timestamp when the exception was created.
• The filename, function, and line number where the exception was created.
• A full call stack where the exeption was created.
• Various other fields.

In the most simple cases, you can catch a thrown fc::Exception object in your code like you would any other C++ exception. For example:

try
{
    do_something_here();
}
catch (const std::exception & e)
{
    std::cout << "Normal C++ exception caught:  " << e.what() << std::endl;
}

If you want the full set of exception details, including the call stack, filename, line number, etc, then you must catch fc::Exception:

try
{
    do_something_here();
}
catch (const fc::Exception & e)
{
    std::cout << "Fancy C++ exception caught:" << std::endl << e.to_string() << std::endl;
}
catch (const std::exception & e)
{
    std::cout << "Normal C++ exception caught:  " << e.what() << std::endl;
}

Calling fc::Exception::to_string() will return a multi-line text block with all the details of the exception. Here is an example of what that looks like:

Exception or error detected:  Network error (connection refused).
  2019-06-22 18:52:51.277075
  Pid 26467: ./fcws_client_test
  Errno 111: Connection refused
  connect(): FCClientConnect.cpp, line #53
  Call stack where the exception was created:
    1: fc::Exception::Exception()
    2: fc::Client::connect()
    3: fc::Control::upload()
    4: fc::Control::upload(fc::Local const&)
    5: main()
    6: __libc_start_main()
    7: _start()
  Additional information:
    1: Bandwidth: 2.00 Gbps
    2: Bandwidth Slow Start: 0 bps
    3: Block size: 5242880
    4: Build type: Linux-64-release
    5: ...

For more information on how to use fc::Exception, please see the official FC++ documentation.