Question

How to handle COM errors in SDK products?

Answer

In FineReader Engine, FlexiCapture Engine and FlexiCapture SDK interface methods and properties return a value of the HRESULT type. The HRESULT (for result handle) is a way of returning success, warning, and error values. HRESULTs are not handles to anything; they are only 32-bit values with several fields encoded in the value. A zero result indicates success and a non-zero result indicates failure.

Note: Please do not handle exceptions that may be thrown during the work of the FineReader Engine interface methods, because these exceptions are handled within FineReader Engine. 

If a method or property call was not successful, this method or property returns an HRESULT code that indicates the failure. Besides, it initializes the IErrorInfo object with a more detailed description of the error. Visual Basic users may access the HRESULT code through the Number property of the Err object. Other attributes of the Err object are initialized with the information from the IErrorInfo. Please refer to the documentation on COM for the detailed description of error handling. The most general tips for it are as follows:

• Visual Basic. Error handling here is performed with the use of the On Error statement. If the On Error Resume Next statement is not used, any run-time error that occurs can cause an error message from the IErrorInfo object to be displayed and code execution stopped.
• C#. Automatically generated wrappers for COM interfaces detect errors and translate them to standard exceptions. Enclose a sequence of FineReader Engine methods by the statements:
  

  try
  {
      ...
  }
  catch( Exception e )
  {
      ...
  }

• Raw C++. FineReader Engine interface methods and properties cannot throw exceptions but return HRESULTs. The most important means for handling these return codes are SUCCEEDED and FAILED macros. They test the HRESULT value and deduce from it what was the result of the operation — success or failure. To get a pointer to the IErrorInfo object's interface, use the GetErrorInfo API function.
• C++ with the Native COM support. The Native COM support technology translates the HRESULT codes of interface functions into exceptions of a special type (_com_error) and automatically uses information from the IErrorInfo object. Thus, a sequence of FineReader Engine methods may be enclosed by the statements:

try {
    ...
}
catch (_com_error e) {
    ...
}

• If any method or property that was called from inside the try-catch block returns an error code, this leads to throwing an exception, the code after the erroneous statement is not executed, and control is transferred to the code after the catch statement. Generally, error handling with the Native COM support may be performed in a way standard for any C++ code, using functions that may throw exceptions.

List of COM error codes and description is at Standard Return Codes (COM)