Root > Integral parts > Options > Advanced page > Code page > Hooks page

Hooks page

Previous pageReturn to chapter overviewNext page   

This is "Advanced/Code/Hooks" page in EurekaLog project's options.



Hooks code options


Each option includes hooks for specific cases (i.e. Pascal units). You should enable option to install hook (and invoke EurekaLog) or disable option to remove hook. See also: External tools options page.


"Console" - for console applications.
"VCL Forms" - for applications with Forms or VCL.Forms unit.
"Control Panel" - for applications with CtlPanel unit.
"NT Service" - for applications with SvcMgr unit.
"CGI" - for applications with CGIApp unit.
"ISAPI" - for applications with ISAPIApp unit.
"IntraWeb" - for applications with IntraWeb units.
"CLX" - for applications with QForms unit.
"FMX" - for applications with FMX.Forms unit.


Usually these settings are set by selecting type of your project. You rarely need to change them.


Additional hooks are not tied to specific project type and may be used in any project. However, all of these options installs code hook - thus, they may be incompatible with some EXE cryptors, packers, protectors. Additional hooks may be customized by you depending on your needs.


1. "Auto-handle TThread exceptions" - option enables backward-compatible EurekaLog 6 behavior for threads. When you enable this option - EurekaLog will automatically handle exception in TThread. Default behavior is not to handle exception, but allow it to be saved in TThread.FatalException property, which can be analyzed/handled by caller thread.


Warning: enabling this option may result in multiple error dialogs at the same time (if several exception occur in multiple threads).


Note: it's not recommended to use this option. You should implement proper error handling for threads instead.



2. "DLL callbacks to host" option allows DLL to use exception manager from main module. This option is used with "Lightweight DLL" profile when you need to call methods from exception manager (since there is no exception manager in DLL).


Warning: do not use this option for "Standalone DLL" profile or any other profiles except "Lightweight DLL".


This options is turned on automatically for lightweight DLL profile. Usually you don't need to manage it manually.


This option can be used without EurekaLog in current module.


For more information: see using EurekaLog with DLLs.



3. "Map OS errors to exception classes" option converts all exceptions of EOSError class to (new) exception classes (from EMapWin32 unit). For example, there will be EOSAccessDenied exception raised instead of EOSError with ErrorCode = 5. This option will replace exception classes globally in all application. Old filtering code (i.e. "on E: EOSError do") should still work, because all new exception classes descend from EOSError. You can use this option to create exception filters for OS errors.


It's recommended to keep this option enabled.


This option also can be used without EurekaLog in current module.



4. "Fix TObject.SafeCallException for hardware exceptions" option fixes bug from Quality Central bug report #81725.


TObject.SafeCallException works only for Delphi exceptions. If there is a hardware exception raised in safecall-method (like access violation or div by zero) - TObject.SafeCallException will be ignored, instead the fixed code of E_UNEXPECTED ($8000FFFF) will be used.


With current implementation it is impossible to alter this behaviour except of using ugly workarounds.


The problem seems to be in System._HandleAutoException routine. This routine does not call TObject.SafeCallException if exception in question is not Delphi exception.


Enable this option for COM applications or any other applications which use safecall-exceptions.


This option can be used without EurekaLog in current module.



This option has effect only for Win32 platform. It has no effect for 64bit code or other platforms.
You probably would want to enable "Handle every SafeCall exception" option for COM applications too.



5. "Low-level injection hooks" option allows or forbids using of low-level hooks. Low-level hooks use code injection (e.g. overwrite machine code with JMP CPU instruction).


Using low-level hooks allows EurekaLog to act automatically. Otherwise, you need to call EurekaLog manually. Additionally, using low-level hooks allows you to capture low-level information such as CPU state. Low-level hooks are also required for additional WER functionality.


It is recommended to keep this option enabled when possible. Disable it only for special cases.


Important Note: We do not recommend to change this option from default value ("Allow all") when compiling with LLVM.


Low-level hooks in external modules ("Allow all" or "Allow for external modules only"):

Installs hook for KiUserExceptionDispatcher (Windows 2000 only; Windows XP and above: EurekaLog uses VEH (Vectored Exception Handling)): allows EurekaLog to react on exceptions and collect CPU state;
Installs hook for CreateThread/ExitThread:
oallows EurekaLog to automatically track threads (see note below);
oallows EurekaLog to produce better multi-threading reports (e.g. indicate thread's creator, etc.);
Installs hook for RaiseException:
oallows EurekaLog to better track non-Delphi exceptions (see also "Capture stack only for exceptions from current module" option);
oallows EurekaLog to track thread name changes;
oallows EurekaLog to build proper call stacks for LLVM software exceptions.

Disable this option (set to "Disable all") if you are using software protection tool that monitors integrity of whole process.

Disable this option (set to "Allow for current module only") if you are loading and unloading several DLLs with EurekaLog in a different order (e.g. load A.dll, load B.dll, unload A.dll, unload B.dll).

Disable this option (set to "Allow for current module only") when there are conflicts with 3rd party hooks/exception tracers from external DLLs.

Important Note: Do not disable this option for application build with LLVM. Additionally, EurekaLog will not be able to track threads when this option is disabled. It is recommended to use BeginThreadEx/TThreadEx or (for any other thread) call SetEurekaLogStateInThread function to enable EurekaLog in thread and call EThreadsManager._NotifyThreadGone function to notify EurekaLog about thread's termination.


Low-level hooks in current module ("Allow all" or "Allow for current module only"):

Installs hook for TObject.Destroy:
oallows EurekaLog to track life time of exception objects (only for LLVM and Delphi 2007/C++ Builder 2007 and earlier; Delphi/C++ Builder 2009 and above (without LLVM): EurekaLog uses new SysUtils.Exception class);
oallows EurekaLog to make better reports for memory errors;
oallows EurekaLog to catch handled exceptions;
Installs hook for HandleSafeCallException: allows EurekaLog to automatically react on safecall exceptions;
Installs hook for TComponent.SetName: allows EurekaLog to track component names when reporting memory problems;
Installs hook for TThread.Execute: allows EurekaLog to automatically handle exceptions in TThread (obsolete feature);
Installs hook for System.@HandleAutoException: allows EurekaLog to fix issue #81725 ("TObject.SafeCallException can be not called in certain cases");
Installs various hooks for handle stage - as set in options (for example, VCL.Forms.TApplication.ShowException for VCL Forms application, VCL.SvcMgr.TApplication.DoHandleException for service application, etc.): allows EurekaLog to handle (process) exceptions automatically. Otherwise you will need to call EurekaLog manually.

Disable this option (set to "Allow for external modules only") if you are using software protection tool that monitors integrity of application (current module).

Important Note: Do not disable this option on Delphi/C++ Builder 2007 and earlier. Do not disable this option when compiling with LLVM. Otherwise EurekaLog will not be able to track life time of exceptions.



See also:

Send feedback... Build date: 2023-09-11
Last edited: 2023-07-12
The documentation team uses the feedback submitted to improve the EurekaLog documentation. We do not use your e-mail address for any other purpose. We will remove your e-mail address from our system after the issue you are reporting has been resolved. While we are working to resolve this issue, we may send you an e-mail message to request more information about your feedback. After the issues have been addressed, we may send you an email message to let you know that your feedback has been addressed.

Permanent link to this article: