Each API function has a return type

IDVE_StatusCode

and an optional argument that accepts a pointer to an output string buffer. When this argument is set, it must point to a buffer with a size greater than or equal to the

IDVE_EXT_STATUS_MSG_BUFFER_SIZE

value. Each function returns one of the documented status codes. If the string buffer is provided, the function additionally fills the string buffer with an extended status message. This may be the static descriptive text in the

IDVE.h

file or a more detailed explanation of the warning or error.

Each API function is overloaded with an additional argument of type

IDVEStatus

. The

IDVEStatus

argument can store an

IDVE_StatusCode

value and an extended status message.

You can call the API function overload with or without the

IDVEStatus

argument. When you call a Java or .NET function, it internally calls the corresponding C function and evaluates the

IDVE_StatusCode

and extended status message that it will return.

If the

IDVE_StatusCode

is of type error, critical error, or very critical error, then the function throws an exception of type

IDVEException

. When you capture the error, you can extract an object of type

IDVEStatus

from the exception that contains the

IDVE_StatusCode

value and the extended status message.

If the underlying C function returns a status code of OK or returns a warning-level status code, the optional

IDVEStatus

argument is filled with that information and the function returns normally. If you do not call the function overload with the

IDVEStatus

argument, then this information is lost and you will not see the warnings. Exceptions for errors are thrown regardless of whether you call the function overload.