Error Reporting and Handling

Error Codes

The CBFS Connect class APIs communicate errors using the Win32 error codes defined in WinError.h, which is part of the Windows Platform SDK. The CBFS Connect system drivers, however, use NT native error codes, which don't have one-to-one mappings with Win32 error codes. The class includes logic for converting between the two as necessary, and that logic can be updated if there are any codes that are not covered.

Additionally, there are certain error codes which CBFS Connect uses in a special manner. For more information about such error codes, please refer to the Error Codes page.

Reporting Errors to the Class from Event Handlers

If the event has a ResultCode parameter, the event handler can use it to return the result code of the operation to the class. The ResultCode parameter is set to 0 by default, which indicates the operation was successful.

The actual return value of the event handler function must be 0 if it worked as expected (i.e., without internal errors), even if ResultCode was set to a non-zero value based on the application logic. Event handler functions should only return a non-zero value to indicate that an unexpected or catastrophic error prevented the event handler from executing properly.

How to Handle Errors Reported by the Class

The GetLastErrorCode and GetLastError functions can be queried to determine if an error occurred.

Extended Logging

Some class methods in CBFS Connect are capable of writing extended information about reported errors to the Windows event logs, which can be viewed using the system's eventvwr.exe tool. The user mode part of the class writes to the "Windows Logs \ Application" folder, while the kernel mode part writes to the "Windows Logs \ System" folder.

The information written in the extended logs is meaningful to the Callback Technologies development team, but not to end-users, so extended logging is disabled by default. If issues occur during the installation of the CBFS Connect system drivers, or while using the class, please do the following:

  1. Enable extended logging (see below).
  2. Replicate the issue.
  3. Using Event Viewer (eventvwr.exe), export the event log entries from the locations mentioned above in native format (please restrict the scope of the export to just those entries related to CBFS Connect).
  4. Submit an issue report that includes the exported file.

There are two ways to toggle extended logging for a class:

  1. By toggling the class's LoggingEnabled configuration setting.
  2. By adding a DWORD-typed value named Enabled to the HKEY_LOCAL_MACHINE\SOFTWARE\CallbackTechnologies\{ClassName}\EventLog registry key and setting it to 0 (disabled) or 1 (enabled).
    • Replace the {ClassName} part of the registry key path with the name of the applicable class.
    • If this registry key, one of its parents, or the value itself does not exist, please create it manually.

The system must be rebooted anytime extended logging is enabled or disabled to make the changes take effect.

 
 
Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 C++ Edition - Version 20.0 [Build 7545]