Error reporting and handling

Error codes

CBFS Connect API operates with error codes defined by Win32 API. These error codes are listed in WinError.h header file in Windows Platform SDK.

Error handling and reporting in callbacks

If your application needs to report some error when processing the callback, it should throw ECBFSConnectError exception (CBFSError in .NET) exception. The application must pass the error code with the exception by passing the error code as a parameter to ECBFSConnectError constructor. CBFS Connect API will catch ECBFSConnectError exception and extract the error code. The error code will be reported to the operating system.

Note that the error code reported by the callback is translated by CBFS Connect API to "NT Native" error code by the driver, which then passes this code to the OS. The OS performs opposite conversion of the error code to Win32 error code (the algorithm of this conversion is unknown and out of developers control). Due to lack of one-to-one mapping between NT Native error codes and Win32 error codes some codes can be converted incorrectly.

If some exception occurs when the callback is executed, the application must catch this exception and throw an instance of ECBFSConnectError instead. If you don't catch some exception in your code, the API will catch it for you. But in this case it will report "Internal error" error to the OS, and this doesn't look well for the OS and for the user.

Error handling when methods are called

Methods of CBFSConnect class either return a boolean value of success or throw an exception (this depends on API used and details of function implementation). For functions that return the boolean value of success you can call GetLastError() Windows API function in VCL and C++ API or Marshal.Marshal.GetLastWin32Error (in System.Runtime.InteropServices) for .NET API. To handle exceptions you need to wrap your calls with try/catch (try / except) and handle any exception that is reported.

Extended logging

Several methods of CBFSConnect class (namely Install(), CreateStorage() and MountMedia() methods and Install function of the installer DLL) write extended information about the reasons of the reported error to Windows event log. The user-mode part of CBFS Connect writes records to "Windows events \ Applications" folder of Windows event log. The kernel-mode part of CBFS Connect writes records to "Windows events \ System" folder of Windows event log.

The information written to the event log has meaning for CBFS Connect developers, not for the users. So if you or your customers have problems with installing CBFS Connect drivers, please, export the event log records, related to CBFS Connect, in native format, and send us the resulting file for analysis.

Logging to system event log is disabled by default. In order to enable it you need to create the value "Enabled" of type "dword" in "HKEY_LOCAL_MACHINE\SOFTWARE\CallbackTechnologies\EventLog" and reboot the system. To disable logging, delete the created "Enabled" value from "HKEY_LOCAL_MACHINE\SOFTWARE\CallbackTechnologies\EventLog".