The EurekaLog Developer Guide

Appendix A - Functions

Use this appendix when you know the operation and need its calling contract: arguments, defaults, result, allocation lifetime and failure behavior. For workflow examples, start with chapters 6, 12-18 and 3.

Defaults appear only where a declaration or an option description supplies them. A missing exception list is not a no-throw guarantee; use each entry's return values, requirements and remarks. A declaration does not establish thread safety or transfer ownership unless the accompanying contract says so. Internal, unstable and unimplemented surfaces remain visibly marked.

Names are grouped by declaring unit, then by type or class. Member headings retain the owner name. Cross-references to appendices A-D refer to this book; no external help is needed. Same-name declarations in different units are qualified so their contracts cannot be confused. Syntax blocks are declarations for lookup, not standalone programs.

Unit map: EAppDLL, EAppType, EBase, ECallStack, EConfig, EDebugInfo, EDialog, EDisAsm, EDNS, EEncrypt, EEvents, EExceptionManager, EFonts, EFreeze, EHash, ELogBuilder, ELogging, ELowLevel, EMemLeaks, EModules, EResLeaks, EResourceStrings, EScreenShot, ESend, ESignature, ESysInfo, EThreadsManager, EWCT, EWER, ExceptionLog7, EZip.

Encryption ownership at a glance. DataProtect, DataUnprotect, MemProtect and MemUnprotect each provide pointer, string and TEncryptBuffer forms. Pointer outputs are owned buffers; release them, preferably with the matching EEncrypt.SecureFree overload. In-place record inputs must be AllocMem-allocated and are replaced with a differently sized result; release record buffers with EncryptBufferFree or SecureFree. A managed string result is not a pointer to pass to FreeMem. MemProtect is process-lifetime protection, not persistent storage. These entries do not document an exhaustive failure/exception contract; never infer successful allocation merely from a procedure return type.

EAppDLL

Exception2HRESULT

Converts an exception into HRESULT value to be returned from DLL.

function Exception2HRESULT(
  const AExceptObject: TObject;
  const AExceptAddr: Pointer;
  const AClassName: String = '';
  const AInvokeEurekaLog: Boolean = True;
  const ASafecall: Boolean = True
): HRESULT;

Return value.

HRESULT value to be returned to the caller.

Remarks.

Helper for implementing a safecall-style HRESULT boundary. Chapter 16 gives the calling pattern and a separately labelled implementation note for EurekaLog 7.15.0.0. No version-independent public parameter contract is specified for AInvokeEurekaLog or ASafecall; the version-local implementation note is not a guarantee for every build.

Parameter detail unavailable: no public parameter-by-parameter contract is specified beyond the declaration and the behavior described here. Parameter names and defaults alone are not additional behavioral guarantees.

EAppType

GetApplicationWnd

Returns application window (if applicable).

function GetApplicationWnd: HWND;

Return value.

Handle of application's window.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

By default it's 0.

Plugin can specify a way to get handle by installing a _GetAppWnd handler.

Note. Typically this is Application.Handle.

GetMainWnd

Returns main window of application (if applicable).

function GetMainWnd: HWND;

Return value.

Handle of main application's window.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

By default it's 0.

Plugin can specify a way to get handle by installing a _GetMainWnd handler.

Note. Typically this is Application.MainForm.Handle.

GetModuleType

Returns type of loaded executable module, based on analyzing its file header.

function GetModuleType(
  const AInstance: HMODULE = 0
): TModuleType;

Parameters.

AInstance [in, optional] — Module handle to analyze. Default (0) means current module.

Be careful with using 0 in packaged application. It's always better to explicitly specify required module.

Return value.

Type of the AInstance module. It is TModuleType.mtProgram (appendix B), TModuleType.mtLibrary (appendix B) or TModuleType.mtPackage (appendix B) on success and TModuleType.mtUnknown (appendix B) on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This function analyzes PE header of loaded executable and return its type: EXE, DLL or BPL.

Function doesn't cache results and perform checking on each call.

There are also simple wrappers for more easy access. For example, IsEXE (appendix A), IsDLL (appendix A) and so on. See EAppType (appendix C) unit for more info.

GetParentWnd

Returns active or top-most window, which can be used as a parent window for modal dialogs.

function GetParentWnd: HWND;

Return value.

Handle of an active/top-most window.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

Use this function to get window of application for functions like Windows.MessageBox or ShellAPI.ShellExecute, which require a window handle.

By default it's 0.

Plugin can specify a way to get handle by installing a _GetParentWnd handler.

Note. Typically this is Application.ActiveFormHandle.

GetTaskBarWnd

Returns window of application, which creates a taskbar button (if applicable).

function GetTaskBarWnd: HWND;

Return value.

Handle of application's taskbar window.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

By default it's 0.

Plugin can specify a way to get handle by installing a _GetTaskBarWnd handler.

Note. Typically this is Application.MainForm.Handle for modern applications and Application.Handle for old applications.

IsAppType

Checks if application is of specified type.

function IsAppType(
  const AAppType: TAppType
): Boolean;

Parameters.

AAppType

Type of application to test. Usually this is one of ETypes.atXXX constants - like atVCL, atConsole and so on.

Return value.

True if some code (plugin) has marked application as being of AAppType type. False - otherwise.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

Application may have more than one type in some cases. For example, it can be both console and CGI.

Application type is generic qualifier that affects EurekaLog behaviour. For example, VCL application intercepts Application.ShowException and uses window error dialog.

Code can call this routine to check if certain support plugin was installed. For example, EAppVCL calls this as SetAppType(atVCL) - indicating that application is VCL application.

Plugins can use SetAppType (appendix A) procedure to indicate that they are installed.

There are also simple wrappers for more easy access. For example, IsVCL (appendix A), IsConsole (appendix A) and so on. See EAppType (appendix C) unit for more info.

IsBPL

Checks if specified module is BPL file.

function IsBPL(
  const AInstance: HMODULE = 0
): Boolean;

Parameters.

AInstance

Module handle to analyze. Optional. Default (0) means current module.

Return value.

Returns True if AInstance module is BPL file. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

IsCGI

Checks if application is CGI application.

function IsCGI: Boolean;

Return value.

Returns True if application is CGI application of any type. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

IsCGIConsole

Checks if application is CGI console application.

function IsCGIConsole: Boolean;

Return value.

Returns True if application is CGI console application (not includes CGI Windows application). False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This is a wrapper for IsAppType (appendix A) function.

Returns "IsCGI and IsConsole".

If this function returns True, then IsCGI (appendix A) also returns True. Opposite is not correct.

IsCGIWin

Checks if application is CGI Windows application.

function IsCGIWin: Boolean;

Return value.

Returns True if application is CGI Windows application (not includes CGI console application). False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This is a wrapper for IsAppType (appendix A) function.

Returns "IsCGI and (not IsConsole)".

If this function returns True, then IsCGI (appendix A) also returns True. Opposite is not correct.

IsCLX

Checks if application is CLX application.

function IsCLX: Boolean;

Return value.

Returns True if application is CLX application. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This is a wrapper for IsAppType (appendix A) function.

CLX application is Qt cross-platform application in Delphi/C++ Builder 6 and 7.

IsConsole

Checks if application is console application.

function IsConsole: Boolean;

Return value.

Returns True if application is console application. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

IsCPL

Checks if application is control panel application.

function IsCPL: Boolean;

Return value.

Returns True if application is CPL application. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This is a wrapper for IsAppType (appendix A) function.

CPL application is a DLL applet for Control Panel with .cpl extension.

IsDLL

Checks if specified module is DLL file.

function IsDLL(
  const AInstance: HMODULE = 0
): Boolean;

Parameters.

AInstance [in, optional] — Module handle to analyze. Default (0) means current module.

Return value.

Returns True if AInstance module is DLL file, but not BPL. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

IsEXE

Checks if specified module is EXE file.

function IsEXE(
  const AInstance: HMODULE = 0
): Boolean;

Parameters.

AInstance [in, optional] — Module handle to analyze. Default (0) means current module.

Return value.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

Remarks.

This is a wrapper for GetModuleType (appendix A) function.

IsFMX

Checks if application is FMX application.

function IsFMX: Boolean;

Return value.

Returns True if application is FMX application. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This is a wrapper for IsAppType (appendix A) function.

FMX is a FireMonkey/FM cross-platform application in Delphi/C++Builder XE2+; EurekaLog 7 detects it in Win32 and Win64 applications.

IsGUI

Checks if application is GUI application.

function IsGUI: Boolean;

Return value.

Returns True if application is GUI application. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This is a wrapper for IsAppType (appendix A) function.

GUI application is VCL, CLX, VCLX or CPL application.

Returns "IsVCL or IsCLX or IsFMX or IsCPL".

IsIntraWeb

Checks if application is IntraWeb application.

function IsIntraWeb: Boolean;

Return value.

Returns True if application is IntraWeb application. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

IsISAPI

Checks if application is ISAPI application.

function IsISAPI: Boolean;

Return value.

Returns True if application is ISAPI application. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

IsModuleLibrary

Checks if specified module is DLL or BPL file.

function IsModuleLibrary(
  const AInstance: HMODULE = 0
): Boolean;

Parameters.

AInstance

Module handle to analyze. Optional. Default (0) means current module.

Return value.

Returns True if AInstance module is DLL file (it could be a BPL too). False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

IsService

Checks if application is a win32 service application.

function IsService: Boolean;

Return value.

Returns True if application is a service. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This is a wrapper for IsAppType (appendix A) function.

Service application can contain one or more Win32 services.

IsVCL

Checks if application is VCL application.

function IsVCL: Boolean;

Return value.

Returns True if application is VCL application. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This is a wrapper for IsAppType (appendix A) function.

VCL is default usual application in Delphi/C++ Builder for Win32.

IsWeb

Checks if application is web application.

function IsWeb: Boolean;

Return value.

Returns True if application is web application. False - otherwise or on error.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

This is a wrapper for IsAppType (appendix A) function.

Web application is CGI, ISAPI or IntraWeb application.

Returns "IsCGI or IsISAPI or IsIntraWeb".

SetAppType

Set a type of this application.

procedure SetAppType(
  const AAppType: TAppType
);

Parameters.

AAppType

Type of application to set. This is one of ETypes.atXXX constants. Like atVCL, atConsole and so on.

Remarks.

Tip. This is routine from low-level unit. Do not use this unit unless you need to extend or alter EurekaLog behavior.

Examples of application's type are: VCL, CLX, VCLX, console, service, CGI, IntraWeb and so on.

An application type is arbitrary non-empty string.

Application may have more than one type in some cases. For example, it can be both console and CGI.

Application type is generic qualifier that affects EurekaLog behaviour. For example, VCL application intercepts Application.ShowException and uses window error dialog.

EurekaLog plugins can call this routine to indicate that they're installed. For example, EAppVCL calls this as SetAppType(atVCL) - indicating that application is VCL application.

You can use IsAppType (appendix A) function to check application for being of a known type.

There are also simple wrappers for more easy access. For example, IsVCL (appendix A), IsConsole (appendix A) and so on. See EAppType (appendix C) unit for more info.

EBase

BeginThreadEx

Spawns a separate thread of execution.

function BeginThreadEx(
  SecurityAttributes: Pointer;
  StackSize: LongWord;
  ThreadFunc: TThreadFunc;
  Parameter: Pointer;
  CreationFlags: LongWord;
  var ThreadId: TThreadID;
  const AThreadName: String = '';
  const AEnableEL: Boolean = Boolean(2
)): Integer;

Parameters.

ThreadAttributes [in, opt] — A pointer to a SECURITY_ATTRIBUTES record that determines whether the returned handle can be inherited by child processes. If ThreadAttributes is nil, the handle cannot be inherited.

The lpSecurityDescriptor member of the ThreadAttributes record specifies a security descriptor for the new thread. If ThreadAttributes is nil, the thread gets a default security descriptor. The ACLs in the default security descriptor for a thread come from the primary token of the creator.

StackSize [in, opt] — The initial size of the stack, in bytes. The system rounds this value to the nearest page. If this parameter is zero, the new thread uses the default size for the executable. For more information, see Thread Stack Size.
ThreadFunc [in] — A pointer to the application-defined function to be executed by the thread. This pointer represents the starting address of the thread.
Parameter [in, opt] — A pointer to a variable to be passed to the thread.
CreationFlags [in, opt] — Set of bits OR'ed together that are drawn from the following: CREATE_SUSPENDED: The thread is created in a suspended state, and does not run until the ResumeThread function is called. STACK_SIZE_PARAM_IS_A_RESERVATION: The StackSize parameter specifies the initial reserve size of the stack. If this flag is not specified, StackSize specifies the commit size.
ThreadId [out] — Receives the thread identifier (TID).
AThreadName [in, opt] — Defines thread's name. Thread name is arbitrary text string which can contain any combination of characters. Thread name will be visible in IDE's debugger. It also will be used by EurekaLog in bug reports. Default is empty name (no name; TID will be used to identify this thread).
AEnableEL [in, opt] — Defines EurekaLog status in created thread. This argument is ignored if you compile your application without EurekaLog. Default is the same state as current thread.

Return value.

If the function succeeds, the return value is a handle to the new thread. The handle must be closed via CloseHandle.

If the function fails, the return value is 0. To get extended error information, call GetLastError.

Note. BeginThreadEx may succeed even if ThreadFunc points to data, code, or is not accessible. If the start address is invalid when the thread runs, an exception occurs, and the thread terminates. Thread termination due to a invalid start address is handled as an error exit for the thread's process. This behavior is similar to the asynchronous nature of CreateProcess, where the process is created even if it refers to invalid or missing dynamic-link libraries (DLLs).

Remarks.

BeginThreadEx is EurekaLog's replacement for BeginThread function. BeginThreadEx offers two additional arguments, which allows you to control thread's name and EurekaLog's state in this thread.

EurekaLog will automatically handle any unhandled exception inside ThreadFunc (assuming that you did not set AEnableEL to False).

Use this routine or a TThreadEx (appendix D) object to spawn separate threads of execution. BeginThreadEx spawns a new thread of execution and sets the global IsMultiThread variable, thereby making the heap thread-safe.

The number of threads a process can create is limited by the available virtual memory. By default, every thread has one megabyte of stack space. Therefore, you can create at most 2,048 threads. If you reduce the default stack size, you can create more threads. However, your application will have better performance if you create one thread per processor and build queues of requests for which the application maintains the context information. A thread would process all requests in a queue before processing requests in the next queue.

The new thread handle is created with the THREAD_ALL_ACCESS access right. If a security descriptor is not provided when the thread is created, a default security descriptor is constructed for the new thread using the primary token of the process that is creating the thread. When a caller attempts to access the thread with the OpenThread function, the effective token of the caller is evaluated against this security descriptor to grant or deny access.

The newly created thread has full access rights to itself when calling the GetCurrentThread function.

If the thread is created in a runnable state (that is, if the CREATE_SUSPENDED flag is not used), the thread can start running before BeginThreadEx returns and, in particular, before the caller receives the handle and identifier of the created thread.

The thread execution begins at the function specified by the ThreadFunc parameter. If this function returns, the DWORD return value is used to terminate the thread in an implicit call to the ExitThread function. Use the GetExitCodeThread function to get the thread's return value.

The thread is created with a thread priority of THREAD_PRIORITY_NORMAL. Use the GetThreadPriority and SetThreadPriority functions to get and set the priority value of a thread.

When a thread terminates, the thread object attains a signaled state, satisfying any threads that were waiting on the object.

The thread object remains in the system until the thread has terminated and all handles to it have been closed through a call to CloseHandle.

EndThreadEx

Terminates the execution of a thread.

procedure EndThreadEx(
  const AExitCode: Integer = 0
);

Parameters.

AExitCode [in, opt] — An optional thread exit code (thread termination status).

Return value.

The function does NOT return.

Remarks.

Warning. We do not recommend to use any of the following functions: EndThreadEx, EndThread, ExitThread. Just exit from thread's proc normally to ensure proper cleanup of allocated resources. Using any of the mentioned functions can cause memory leaks if you don't know what you are doing.

You can use this function instead of EndThread function inside threads created with BeginThreadEx.

EndThreadEx notifies EurekaLog about thread's termination and terminates the execution of a thread with the specified ExitCode.

Note. On Windows, EndThreadEx calls the ExitThread WinAPI with the specified ExitCode.

ErrorCodeToStr

Converts send response to a human-readable error code.

function ErrorCodeToStr(
  const AResponse: TResponse
): String;

Parameters.

AResponse [in] — A response from sending.

Return value.

A human-readable error code. For example, '42'.

Remarks.

When sending fails, the response encodes a error code for the failure. This function can be used to convert encoded value into a human-readable string. The encoding is needed because different senders use different formats of error codes.

The function will return an empty string when if there is no error code. Please note that missing error code is not the same as successful send. Sending can fail, but do not provide an error code back. If you need to check if sending has failed - use if Failed(Ord(Response.SendResult)) then.

ExceptionMessage

Retrieves error message for an exception.

function ExceptionMessage(
  const E: TObject
): String;

Parameters.

E [in] — Exception object to get its .Message property.

Return value.

Error message for the specified exception.

Remarks.

Use this function to get error message for any given exception, even if it is not Exception class.

GetExceptionErrorCode

Converts an exception into Cardinal value to be returned from DLL.

function GetExceptionErrorCode(
  const AExceptObject: TObject
): Cardinal;

Return value.

A Cardinal value to be returned to the caller - possibly via SetLastError.

Remarks.

This is a helper function, which can be used to return value as GetLastError or ExitCode for thread/process.

Important. Be sure to cast the returned Cardinal value to Integer when necessary! For example, old Delphi IDEs declare SetLastError/GetLastError using an Integer argument (while modern IDEs declare these function using Cardinal). The same is true when assigning the returned value to Delphi's exit codes - which use Integer as opposed to Cardinal exit codes in Windows.

HandleException

Handles exception.

function HandleException(
  const E: TObject = nil;
  const AExpected: Boolean = False;
  const AHandler: String = '';
  const AExceptionAddress: Pointer = nil
): Integer;

Parameters.

E [in, optional] — Exception object to process. Default is nil. If this parameter is not specified, the return value of ExceptObject will be used. Does nothing for EAbort.

Return value.

Error code for the E argument. You can use this code to specify failure reason for thread, process, etc. This code is never equals 0, unless there is no exception.

Remarks.

Handles (processes) the specified exception. It is usually means saving bug report, displaying EurekaLog's exception dialog, sending bug report, etc.

Note. If EurekaLog is installed - this function will redirect to ExceptionManager.Handle (appendix D, TExceptionManager.Handle).

If EurekaLog is not installed - this function will show simple message box by using ApplicationShowException function (if it is not installed - then HandleException will show its own message box for Exception child classes and use ShowException for non-Exception classes).

IsEurekaLogActive

Indicates if EurekaLog is active or disabled in this application.

function IsEurekaLogActive: Boolean;

Return value.

True if EurekaLog is active, False - otherwise.

Remarks.

EurekaLog is considered to be active if EurekaLog should do its work. You can control EurekaLog activation by calling SetEurekaLogState (appendix A) procedure.

If EurekaLog was not installed - then it's always disabled (not active).

This is a global status for all application. If you want to check per-thread activation status - use IsEurekaLogActiveInThread (appendix A) function.

If you want to change activation status (enable or disable EurekaLog) - use SetEurekaLogState (appendix A) for global status and SetEurekaLogStateInThread (appendix A) for per-thread status.

By default, EurekaLog is active at startup (if was installed).

Caution!

This function doesn't respect per-thread activation status. Thus, if EurekaLog was disabled in one thread only - this function will still returns True.

This function respects "installed" status, so there is no need for additional call to IsEurekaLogInstalled (appendix A) function.

IsEurekaLogActiveInThread

Indicates if EurekaLog is active or disabled in the specified thread.

function IsEurekaLogActiveInThread(
  const AThreadID: Cardinal = 0
): Boolean;

Parameters.

AThreadID [in, optional] — TID - thread ID which EurekaLog's status should be checked. Use 0 (default) for current thread.

Return value.

True if EurekaLog is active in the specified thread, False - otherwise.

Remarks.

This is per-thread version of the IsEurekaLogActive (appendix A) function.

This is a per-thread status. If you want to check global activation status - use the IsEurekaLogActive (appendix A) function.

If you want to change activation status (enable or disable EurekaLog) - use SetEurekaLogState (appendix A) for global status and SetEurekaLogStateInThread (appendix A) for per-thread status.

Caution!

This function doesn't respect global activation status.

IsEurekaLogInstalled

Indicates if EurekaLog is installed in this application.

function IsEurekaLogInstalled: Boolean;

Return value.

True if EurekaLog is installed, False - otherwise

Remarks.

EurekaLog is considered to be installed if:

its source code was included into application (see unit (appendix C, ExceptionLog7));
executable was processed by EurekaLog expert or command-line compiler (ECC32/EMAKE);

I.e. EurekaLog is installed if both true: source code is included AND options is included.

Debug information (which is required to build human-readable call stack) can be included or not - this doesn't matter for installation. EurekaLog can function without debug information.

Alternative to this function can be using of conditional directives.

EurekaLog defines the following conditional symbols:

EUREKALOG
EUREKALOG7

IsExpected

Checks if exception is an expected exception.

function IsExpected(
  const AException: TObject
): Boolean; overload;
function IsExpected(
  const AException: TObject;
  out AContextNumber: Integer;
  out AURL: String;
  out ABugID: TBugID
): Boolean; overload;

Parameters.

AException [in] — Exception object to check.
AContextNumber [out, optional] — Help context number for this exception.
AURL [out, optional] — URL to the web-page for this exception.
ABugID [out, optional] — BugID for this exception.

Return value.

True if AException is an expected exception, False otherwise.

Remarks.

Exception can be marked as "expected" by various ways. This function checks if the exception was marked as an expected exception.

IssueIDToStr

Converts send response to a human-readable ticket/issue ID.

function IssueIDToStr(
  const AResponse: TResponse
): String;

Parameters.

AResponse [in] — A response from sending.

Return value.

A human-readable ID of the posted ticket/issue. For example, '42'.

Remarks.

Sending a bug report may create a ticket/issue/bug in a bug tracker. The response encodes ID of assigned ticket/issue/bug. This function can be used to convert encoded value into a human-readable string. The encoding is needed because different bug trackers use different formats of ticket/issue IDs.

The function will return an empty string when the response comes from a sending method which does not support feedback. For example, e-mail sending or FTP sending.

MarkExpected

Marks exception as expected exception.

procedure MarkExpected(
  const AException: TObject;
  const AContextNumber: Integer = -1;
  const ABugID: TBugID = 0
); overload;
procedure MarkExpected(
  const AException: TObject;
  const AURL: String;
  const ABugID: TBugID = 0
); overload;

Parameters.

AException [in] — Exception object to mark as expected.
AContextNumber [in, optional] — Help context number for this exception.
ABugID [in, optional] — BugID for this exception.
AURL [in, optional] — URL for this exception.

Remarks.

Marks exception as "expected". Additionally, sets ExpectedNumber/ ExpectedURL (appendix D, TEurekaExceptionInfo.ExpectedURL) and BugID (appendix D, TEurekaExceptionInfo.BugID) properties.

NameThread

Names thread for debugging.

procedure NameThread(
  const AName: String;
  const AThreadID: Cardinal = 0
);

Parameters.

AName [in] — A thread name and/or description to be set for the thread identified via AThreadID argument. Can be arbitrary string. Thread name does not have to be unique.
AThreadID [in, optional] — Thread ID (TID) of the thread which name has to be set.

Remarks.

The name (description) of a thread can be set more than once; the most recently set value is used. You can retrieve the description of a thread via TEurekaThreadData.Name (appendix D).

Note. It is recommended to use EurekaLog's naming routines instead of RTL (and possibly other frameworks), because EurekaLog supports Get/SetThreadDescription API, while RTL does not.

NameThreadForDebugging

Alias for NameThread (appendix A), this overrides System.Classes.TThread.NameThreadForDebugging.

procedure NameThreadForDebugging(
  const AName: String;
  const AThreadID: Cardinal = 0
);

Parameters.

AName [in] — Thread's name.
AThreadID [in, optional] — TID (Thread ID) of the thread to set new name.

Remarks.

See NameThread (appendix A) for a detailed description. NameThreadForDebugging is the same function as NameThread.

RaiseExpected

Raises expected exception.

procedure RaiseExpected(
  const AException: TObject;
  const AContextNumber: Integer = -1;
  const ABugID: TBugID = 0
); overload;
procedure RaiseExpected(
  const AException: TObject;
  const AURL: String;
  const ABugID: TBugID = 0
); overload;

Parameters.

AException [in] — Exception object to raise.
AContextNumber [in, optional] — Help context number for this exception.
ABugID [in, optional] — BugID for this exception.
AURL [in, optional] — URL for this exception.

Remarks.

Raises exception and marks it as "expected". Additionally, it sets ExpectedNumber/ ExpectedURL (appendix D, TEurekaExceptionInfo.ExpectedURL) and BugID (appendix D, TEurekaExceptionInfo.BugID) properties.

RaiseOuterException

Raises an exception and captures the current one.

procedure RaiseOuterException(
  const E: TObject
);

Parameters.

E [in] — Exception object to raise.

Remarks.

Call RaiseOuterException from within an except block to raise a new exception and preserve the current one. RaiseOuterException raises a new exception and sets the current one as an inner exception. RaiseOuterException is useful when creating exception chains.

Note. The RaiseOuterException function is the same as Exception.RaiseOuterException or Exception.ThrowOuterException, except it works on any exception object.

Note. Consider using the function (appendix A, RaiseOuterExceptionExpected) instead.

RaiseOuterExceptionExpected

Raises expected exception and captures the current one.

procedure RaiseOuterExceptionExpected(
  const AException: TObject;
  const AContextNumber: Integer = -1;
  const ABugID: TBugID = 0
); overload;
procedure RaiseOuterExceptionExpected(
  const AException: TObject;
  const AURL: String;
  const ABugID: TBugID = 0
); overload;

Parameters.

AException [in] — Exception object to raise.
AContextNumber [in, optional] — Help context number for this exception.
ABugID [in, optional] — BugID for this exception.
AURL [in, optional] — URL for this exception.

Remarks.

RaiseOuterException raises exception and marks it as "expected". Additionally, it sets ExpectedNumber/ ExpectedURL (appendix D, TEurekaExceptionInfo.ExpectedURL) and BugID (appendix D, TEurekaExceptionInfo.BugID) properties.

SetEurekaLogState

Enables or disables EurekaLog in this application.

function SetEurekaLogState(
  const AActivate: Boolean
): Boolean;

Parameters.

AActivate [in] — True - if you want to enable EurekaLog, False - if you want to disable EurekaLog.

Return value.

Previous EurekaLog state: True if EurekaLog was active, False - otherwise.

Remarks.

You can use this procedure to manually enable and disable EurekaLog in your application.

EurekaLog is considered to be active if it should do its work. You can get EurekaLog activation status by calling IsEurekaLogActive (appendix A) procedure.

If EurekaLog is not installed - then it's always disabled (not active).

This function changes global status for all application. If you want to change activation status on per-thread basis - use the SetEurekaLogStateInThread (appendix A) procedure.

SetEurekaLogStateInThread

Enables or disables EurekaLog in the specified thread.

function SetEurekaLogStateInThread(
  const AThreadID: Cardinal;
  const AActivate: Boolean
): Boolean;

Parameters.

AThreadID [in, optional] — TID - thread ID which EurekaLog's status should be checked. Use 0 (default) for current thread.
AActivate [in] — True - if you want to enable EurekaLog, False - if you want to disable EurekaLog.

Return value.

Previous EurekaLog state: True if EurekaLog was active, False - otherwise.

Remarks.

You can use this procedure to manually enable and disable EurekaLog in the specified thread.

EurekaLog is considered to be active if it should do its work. You can get per-thread EurekaLog activation status by calling the IsEurekaLogActiveInThread (appendix A) procedure.

This function changes per-thread activation status. If you want to change global activation status - use the SetEurekaLogState (appendix A) procedure.

SetExceptionMessage

Sets or changes error message for an exception.

procedure SetExceptionMessage(
  const E: TObject;
  const AMessage: String
);

Parameters.

E [in] — Exception object to change its .Message property.
AMessage [in] — An error message to assign to the specified exception object.

Remarks.

EurekaLog captures exception's information when EurekaLog first encounters it. If you change exception's properties manually later - EurekaLog have no way of knowing that. This function allows you to set .Message property of the exception object and notify EurekaLog about this change.

ShowExpected

Shows expected exception.

procedure ShowExpected(
  const AException: TObject;
  const AContextNumber: Integer = -1;
  const ABugID: TBugID = 0
); overload;
procedure ShowExpected(
  const AException: TObject;
  const AURL: String;
  const ABugID: TBugID = 0
); overload;
procedure ShowExpected(
  const AMessage: String;
  const AContextNumber: Integer = -1;
  const ABugID: TBugID = 0
); overload;
procedure ShowExpected(
  const AMessage: String;
  const AURL: String;
  const ABugID: TBugID = 0
); overload;

Parameters.

AException [in] — Exception object to show.
AContextNumber [in, optional] — Help context number for this exception.
ABugID [in, optional] — BugID for this exception.
AURL [in, optional] — URL for this exception.
AMessage [in] — Exception message.

Remarks.

This is equal to RaiseExpected, except the exception will be immediately handled (processed). Which usually result in showing error dialog.

Note. For overloaded ShowExpected with AMessage - a EPlannedException object will be constructed with the specified message.

ECallStack

CurrentAddress

Returns address of current code/instruction.

function CurrentAddress: Pointer;

Return value.

A pointer to currently executing CPU opcode.

Remarks.

Use this function to obtain a pointer to current location, which you can use to either build a call stack or obtain a human-readable description.

GetTracer

Get stack tracing class by number.

function GetTracer(
  const ATracerNo: Integer
): TEurekaBaseStackList;

Parameters.

ATracerNo [in] — Number of stack tracer. Numbers are listed as TracerXYZ constants in EStackTracing (appendix C) unit. Some examples are: TracerRawEurekaLogV7 TracerRawEurekaLogV6 TracerRawEurekaLog TracerRawJCL TracerRawMadExcept TracerLeaksRAW TracerFramesEurekaLogV7 TracerFramesRecovered TracerFramesEurekaLog TracerFramesJCL TracerLeaksFrame TracerWindows Any other TracerXYZ value...

Return value.

Initialized stack tracing class instance (object). Object is created and initialized, but call stack is not build yet.

Remarks.

Use this function to get call stack class for specific tracer of your choice.

Tip. Use EurekaCallStackClass (appendix C).Create when you don't know which class do you need.

Tip. This function is preferred over GetTracerClass (appendix A) function.

GetTracerClass

Get stack tracing class by number.

function GetTracerClass(
  const ATracerNo: Integer
): TEurekaCallStackClass;

Parameters.

ATracerNo [in] — Number of stack tracer. Numbers are listed as TracerXYZ constants in EStackTracing (appendix C) unit. Some examples are: TracerRawEurekaLogV7 TracerRawEurekaLogV6 TracerRawEurekaLog TracerRawJCL TracerRawMadExcept TracerLeaksRAW TracerFramesEurekaLogV7 TracerFramesRecovered TracerFramesEurekaLog TracerFramesJCL TracerLeaksFrame TracerWindows Any other TracerXYZ value...

Return value.

Stack tracing class. You can create object by using Create constructor.

Remarks.

Use this function to get call stack class for specific tracer of your choice.

Tip. Use EurekaCallStackClass (appendix C) when you don't know which class do you need.

Tip. Use GetTracer (appendix A) function instead (when possible).

ReturnAddress

Returns address of caller function.

function ReturnAddress: Pointer;

Return value.

A pointer to CPU opcode following instruction which called the current function.

Remarks.

Use this function to obtain a pointer to the caller of the current location, which you can use to either build a call stack or obtain a human-readable description.

EConfig

ConfigDelete

Deletes a key from the specified section.

procedure ConfigDelete(
  const ASection, AName: String
);

Parameters.

ASection

Section name to delete a key from. Can't be empty. Can't contain '' or '/'.

AName

Key name to delete. Can't be empty.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

This routine deletes a key from the section in EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

ConfigFileName

Returns .ini-file name to store EurekaLog configuration.

function ConfigFileName: String;

Return value.

.ini-file name.

Exceptions.

System.SysUtils.EAssertionFailed

If called when ConfigIsRegistry is True.

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

Returns information about EurekaLog configuration storage location.

Returns .ini-file name to store EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

Code may change this value by calling SetupConfig (appendix A) procedure.

Use this routine to implement custom ConfigReadXXX-like or ConfigWriteXXX-like routines.

ConfigIsRegistry

Indicates if EurekaLog configuration is stored in the registry or in .ini-file.

function ConfigIsRegistry: Boolean;

Return value.

True - EurekaLog configuration is stored in the registry. Use ConfigKeyPath (appendix A) to get registry key name.

False - EurekaLog configuration is stored in the .ini-file. Use ConfigFileName (appendix A) to get .ini-file name.

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

Returns information about EurekaLog configuration storage location.

Indicates if EurekaLog configuration is stored in the registry or in .ini-file.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

Code may change this value by calling SetupConfig (appendix A) procedure.

Use this routine to implement custom ConfigReadXXX-like or ConfigWriteXXX-like routines.

ConfigKeyPath

Returns registry key name to store EurekaLog configuration.

function ConfigKeyPath: String;

Return value.

Registry key name with leading and trailing '' delimiters.

Exceptions.

System.SysUtils.EAssertionFailed

If called when ConfigIsRegistry is False.

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

Returns information about EurekaLog configuration storage location.

Returns registry key name to store EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

Code may change this value by calling SetupConfig (appendix A) procedure.

Use this routine to implement custom ConfigReadXXX-like or ConfigWriteXXX-like routines.

ConfigReadBool

Reads boolean value from specified key and section.

function ConfigReadBool(
  const ASection, AName: String;
  const ADefault: Boolean = False
): Boolean;

Parameters.

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

ADefault

Default value, if key or section doesn't exits or key's value have a wrong format. Optional.

Return value.

Returns key's value on success or ADefault in case of non-existent key or section or wrong value's format.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Reads boolean value from EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

This function is a wrapper for ConfigReadString (appendix A) function.

ConfigReadFloat

Reads float value from specified key and section.

function ConfigReadFloat(
  const ASection, AName: String;
  const ADefault: Extended = 0
): Extended;

Parameters.

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

ADefault

Default value, if key or section doesn't exits or key's value have a wrong format. Optional.

Return value.

Returns key's value on success or ADefault in case of non-existent key or section or wrong value's format.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Reads float value from EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

This function is a wrapper for ConfigReadString (appendix A) function.

ConfigReadInteger

Reads integer value from specified key and section.

function ConfigReadInteger(
  const ASection, AName: String;
  const ADefault: Int64 = 0
): Int64;

Parameters.

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

ADefault

Default value, if key or section doesn't exits or key's value have a wrong format. Optional.

Return value.

Returns key's value on success or ADefault in case of non-existent key or section or wrong value's format.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Reads integer value from EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

This function is a wrapper for ConfigReadString (appendix A) function.

ConfigReadString

Reads string value from specified key and section.

function ConfigReadString(
  const ASection, AName: String;
  const ADefault: String = ''
): String;

Parameters.

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

ADefault

Default value, if key or section doesn't exits. Optional.

Return value.

Returns key's value on success or ADefault in case of non-existent key or section.

This value can hold arbitrary bytes, you don't need to decode it in any way.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Reads string value from EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

ConfigWriteBool

Writes boolean value to specified key and section.

procedure ConfigWriteBool(
  const ASection, AName: String;
  const AValue: Boolean
);

Parameters.

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

AValue

Value to write. Mandatory. If you need to delete value - use ConfigDelete (appendix A) procedure instead.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Writes boolean value to EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

This function is a wrapper for ConfigWriteString (appendix A) function.

ConfigWriteFloat

Writes float value to specified key and section.

procedure ConfigWriteFloat(
  const ASection, AName: String;
  const AValue: Extended
);

Parameters.

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

AValue

Value to write. Mandatory. If you need to delete value - use ConfigDelete (appendix A) procedure instead.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Writes float value to EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

This function is a wrapper for ConfigWriteString (appendix A) function.

ConfigWriteInteger

Writes integer value to specified key and section.

procedure ConfigWriteInteger(
  const ASection, AName: String;
  const AValue: Int64
);

Parameters.

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

AValue

Value to write. Mandatory. If you need to delete value - use ConfigDelete (appendix A) procedure instead.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Writes integer value to EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

This function is a wrapper for ConfigWriteString (appendix A) function.

ConfigWriteString

Writes string value to specified key and section.

procedure ConfigWriteString(
  const ASection, AName: String;
  const AValue: String
);

Parameters.

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

AValue

Value to write. Mandatory, but can be an empty string. If you need to delete value - use ConfigDelete (appendix A) procedure instead. Writing empty string will not delete value.

Do not encode this value. It can hold arbitrary bytes and they all will be stored properly.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Writes string value to EurekaLog configuration.

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

DecodeConfigValue

Low-level routine to decode data after reading from configuration storage.

function DecodeConfigValue(
  const AValue: String
): String;

Parameters.

AValue

Encoded data, which was retrieved from configuration storage. This data should be processed by EncodeConfigValue (appendix A) before saving to storage.

Return value.

Original raw data.

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

Decodes data which was previosly encoded by EncodeConfigValue (appendix A).

Usually you don't need to use this function, because you're encouraged to use ConfigReadString (appendix A) or it's wrapper. These ConfigReadXYZ functions perform such decoding automatically.

EncodeConfigValue

Low-level routine to encode data before saving to configuration storage.

function EncodeConfigValue(
  const AValue: String
): String;

Parameters.

AValue

A data to encode.

Return value.

Encoded data. Exact encoded format is unspecified.

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

Encodes data by escaping special characters (like #0, line breaks, trailing spaces, etc).

Usually you don't need to use this function, because you're encouraged to use ConfigWriteString (appendix A) or it's wrapper. These ConfigWriteXYZ functions perform such encoding automatically.

IniReadString

Reads string from .ini file.

function IniReadString(
  const AFileName: String;
  const ASection, AName: String;
  const ADefault: String = ''
): String; deprecated'Consider using ConfigWriteXXX/ConfigReadXXX routines';

Parameters.

AFileName

A full absolute path to file name.

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

ADefault

Default value, if key or section doesn't exits. Optional.

Return value.

Returns key's value on success or ADefault in case of non-existent key or section.

Returned value needs to be decoded by DecodeConfigValue (appendix A).

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

IniWriteString

Writes string to .ini file.

procedure IniWriteString(
  const AFileName: String;
  const ASection, AName, AValue: String
); deprecated'Consider using ConfigWriteXXX/ConfigReadXXX routines';

Parameters.

AFileName

A full absolute path to file name. If file doesn't exist - it'll be created (as unicode .ini file).

ASection

Section name. Can't be empty. Can't contain '' or '/'.

AName

Key name. Can't be empty.

AValue

A value to write. Mandatory, but can be an empty string. Writing empty string will delete the value.

This value needs to be encoded by EncodeConfigValue (appendix A), if you want to preserve special characters.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

RegKeyCheck

Checks registry key for existing.

function RegKeyCheck(
  const ARoot: HKey;
  const AKey: String
): Boolean;

Parameters.

ARoot

One of predefined HKEY_XYZ constants. Usually it's HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE.

AKey

A full absolute path to key.

Return value.

True, if specified key exists (i.e. you have a minimum a read access), False - otherwise.

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

RegKeyRead

Reads string from registry key.

function RegKeyRead(
  const ARoot: HKey;
  const AKey, AName: String;
  const ADefault: String = ''
): String;

Parameters.

ARoot

One of predefined HKEY_XYZ constants. Usually it's HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE.

AKey

A full absolute path to key.

AName

A name of value to read.

ADefault

Optional default value.

Return value.

Actual value from registry key, if it's exists. ADefault value - if there is error (no access, value or key do not exist).

Returned value does not need to be decoded by DecodeConfigValue (appendix A), because registry can hold exact binary copy of data itself.

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

RegKeyWrite

Writes string to registry key.

procedure RegKeyWrite(
  const ARoot: HKey;
  const AKey, AName, AValue: String
); overload;

Parameters.

ARoot

One of predefined HKEY_XYZ constants. Usually it's HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE.

AKey

A full absolute path to key.

AName

A name of value to write.

AValue

A value to write. Mandatory, but can be an empty string. Writing empty string will not delete value.

This value does not need to be encoded by EncodeConfigValue (appendix A), because registry can hold exact binary copy of data itself.

Exceptions.

System.SysUtils.EOSError

Raises this exception on failure.

Remarks.

Warning. This is low-level routine. Use it only to implement your own custom high-level wrapper.

Use ConfigReadString (appendix A) or ConfigWriteString (appendix A) (or their equivalents) to read and write configurations.

SetupConfig

Changes EurekaLog configuration storage.

procedure SetupConfig(
  const AUseRegistry: Boolean;
  const AKeyPathOrFileName: String = ''
);

Parameters.

AUseRegistry

True - use registry, False - use .ini-file.

AKeyPathOrFileName

If AUseRegistry is True then this parameter specifies registry key to store configuration.

If AUseRegistry is False then this parameter specifies .ini-file name to store configuration.

Remarks.

Allows code to change default configuration storage location.

This function should be called only once at application's startup (preferably in unit's initialization section).

See EConfig (appendix C) unit description for basic desciption of EurekaLog configuration.

EDebugInfo

FILE

Returns source file name of the current code.

function __FILE__: String;

Return value.

Source name for the caller. For example: 'Unit1.pas', 'Unit1.cpp', 'Code.inc'.

Remarks.

This function is a simple combination of GetLocationInfo (appendix A) and GetCaller functions.

Note. Source name may be different from unit name. For example, if you add an include file with code, then unit name will be something like 'Unit1', while source name will be 'Code.inc' for all code inside the include file. The same is true for generics. Unit name may be 'Unit1.pas', while source could be 'System.Generics.Collections.pas'.

FUNCTION

Returns function or method name of the current code.

function __FUNCTION__: String;

Return value.

Routine name for the caller. For example: 'DoSomething' (for functions and procedures), 'TMyClass.DoSomething' (for methods).

Remarks.

This function is a simple combination of GetLocationInfo (appendix A) and GetCaller functions.

LINE

Returns line number of the current code.

function __LINE__: Integer;

Return value.

Line number for the caller. For example: 42.

Remarks.

This function is a simple combination of GetLocationInfo (appendix A) and GetCaller functions.

Note. Please note that line number belongs to source code, not the unit. While these are the same most of the time, it is not always so. For example, if you add an include file with code, then unit name will be something like 'Unit1', while line numbers will be from Code.inc for all code inside the include file. The same is true for generics. Unit name may be 'Unit1.pas', while line numbers will be taken from System.Generics.Collections.pas.

LOCATION

Returns human-readable description of the current location.

function __LOCATION__: String;

Return value.

Current location. For example: 'Unit1.TMyClass.DoSomething 42'.

Remarks.

This function is a simple combination of GetLocationInfo (appendix A) and GetCaller functions.

MODULE

Returns executable module name of the current code.

function __MODULE__: String;

Return value.

Module name for the caller. For example: 'Project1.exe'.

Remarks.

This function is a simple combination of GetLocationInfo (appendix A) and GetCaller functions.

UNIT

Returns unit name of the current code.

function __UNIT__: String;

Return value.

Unit name for the caller. For example: 'Unit1'.

Remarks.

This function is a simple combination of GetLocationInfo (appendix A) and GetCaller functions.

Note. It may be a good idea to use function (appendix A, FILE) instead. That is because line numbers belongs to source code, not unit. For example, if you add an include file with code, then unit name will be something like 'Unit1', while line numbers will be from Code.inc for all code inside the include file. The same is true for generics. Unit name may be 'Unit1.pas', while line numbers will be taken from System.Generics.Collections.pas.

GetLocationInfo

Returns human-readable information about code location.

function GetLocationInfo(
  const Addr: Pointer
): TELLocationInfo; overload;
function GetLocationInfo(
  const Addr: Pointer;
  var Info: TELLocationInfo
): Boolean; overload;

Parameters.

Addr [in] — A pointer to a code (method, function, line, etc.)
Info [out] — A human-readable description of the code (unit, class, rouitne, line, offsets).

Return value.

A human-readable description of the code (unit, class, rouitne, line, offsets), or success / failure state.

Remarks.

Use this function to retrieve location information about code instruction. EurekaLog will load debug information (if any available) and look it up for the specified address.

GetLocationInfoStr

Returns human-readable information about code location.

function GetLocationInfoStr(
  const Addr: Pointer
): String; overload;
function GetLocationInfoStr(
  const Addr: Pointer;
  out Info: String
): Boolean; overload;

Parameters.

Addr [in] — A pointer to a code (method, function, line, etc.)
Info [out] — A human-readable description of the code (unit, class, rouitne, line, offsets). For example: '(003BDD73){Project1.exe} [007BDD73] Unit1.TForm1.Button1Click (Line 32, "Unit1.pas") + $5'

Return value.

A human-readable description of the code (unit, class, rouitne, line, offsets), or success / failure state. For example: '(003BDD73){Project1.exe} [007BDD73] Unit1.TForm1.Button1Click (Line 32, "Unit1.pas") + $5'

Remarks.

This function is a simple combination of GetLocationInfo (appendix A) and LocationToStr (appendix A) functions.

LocationToStr

Converts location information to single line string.

function LocationToStr(
  const AInfo: TELLocationInfo;
  const AIncludeModuleName: Boolean = True;
  const AIncludeAddressOffset: Boolean = True;
  const AIncludeStartProcLineOffset: Boolean = False;
  const AIncludeVAddress: Boolean = True;
  const AIncludePointer: Boolean = True;
  const AIncludeLine: Boolean = True;
  const AUseParent: TELUseParent = eupNone
): String;

Parameters.

AInfo [in] — A location information to be converted to string. It can be retrieved from GetLocationInfo (appendix A) function.
AIncludeModuleName [in, optional] — Specifies if result should include module name.
AIncludeAddressOffset [in, optional] — Specifies if result should include offset from the routine.
AIncludeStartProcLineOffset [in, optional] — Specifies if result should include offset from the line.
AIncludeVAddress [in, optional] — Specifies if result should include offset from module.
AIncludePointer [in, optional] — Specifies if result should include RAW pointer.
AIncludeLine [in, optional] — Specifies if result should include line number.
AUseParent [in, optional] — Specifies if result should include information about parent or child units (for includes only).

Return value.

A human-readable single line string.

Remarks.

This function converts location information record into single string, which can be shown to user.

EDialog

FindDialogClass

Searches dialog class by name.

function FindDialogClass(
  const AClassName: String
): TBaseDialogClass;

Parameters.

AClassName [in] — Name of dialog class. For example: 'TMessageBoxDialog'.

Return value.

Registered dialog class or nil if no class was found.

Remarks.

Functions looks for registered dialog class with the specified name and return first found class. Dialog class registration is performed by RegisterDialogClass (appendix A) and RegisterDialogClassFirst (appendix A) functions.

RegisterDialogClass

Registers dialog class.

procedure RegisterDialogClass(
  const AClass: TBaseDialogClass
);

Parameters.

AClass [in] — Dialog class to register.

Remarks.

Function registers the specified dialog class into global list of available dialog classes. Each dialog class must be registered before using. Once registered, dialog class can be used (selected) via ExceptionDialogType property of TEurekaModuleOptions (appendix D).

Note. This function adds dialog class to the end of the list.

Note. Once registered, dialog class can not be unregistered.

Note. There is no limitation to register different dialog classes with the same class name. Double-registering the same class will have no effect.

RegisterDialogClassFirst

Registers dialog class.

procedure RegisterDialogClassFirst(
  const AClass: TBaseDialogClass
);

Parameters.

AClass [in] — Dialog class to register.

Remarks.

Note. This function adds dialog class to the beginning of the list.

Note. Once registered, dialog class can not be unregistered.

Note. There is no limitation to register different dialog classes with the same class name. Double-registering the same class will have no effect.

EDisAsm

DecodeInstruction

Decodes a single CPU instruction.

function DecodeInstruction(
  Address: PAddress;
  const AExternalProcess: Boolean = False
): TInstruction;

Parameters.

Address [in] — A pointer to CPU instruction to decode.

Return value.

Decoded CPU instruction at Address. The complete TInstruction layout is CPU-specific; no public layout declaration is specified here, and the record must not be treated as a portable binary layout.

Remarks.

This is low-level disassembler routine which decodes a single CPU instruction and stores detailed information into TInstruction record. The decoded information includes prefixes, opcode, MOD/SIB bytes, displacement and immediate values - plus evaluated information: such as pointer to next instruction, flags, sizes of various data, etc. The complete TInstruction layout is CPU-specific; no public layout declaration is specified here, and the record must not be treated as a portable binary layout.

The decoded information can be used "as is" or it can be converted into textual representation by InstructionToString (appendix A) function.

Note. You can use DisasmInstruction (appendix A) function if you need to disassemble a single CPU instruction into textual representation and you don't need decoded information (TInstruction record).

DisasmInstruction

Disassebles a single CPU instruction.

function DisasmInstruction(
  var Address: PAddress;
  const AEncrypt: Boolean = False
): String;

Parameters.

Address [in, out] — A pointer to CPU instruction. On input: a pointer to CPU instruction to disassemble. On output: a pointer to the next CPU instruction.

Return value.

Textual representation of disassemled CPU instruction. This includes Address, RAW bytes, instruction itself and optional comments.

Remarks.

Function disassembles a single CPU instruction, returns its textual representation and advances Address to the next instruction. The last can be used to walk through code while diassembling it.

Sample output:

006989A2 E805C2F8FF CALL -$073DFB ; ($00624BB0) Unit1.TForm1.CheckVisible

First part ("006989A2" in the above example) repeats Address and it's always 8 hex characters for 32-bit process and 16 hex characters for 64-bit process.
Second part ("E805C2F8FF" in the above example) indicate RAW instruction bytes. Its size varies from 2 characters (1 byte) up to 30 characters (15 bytes) for x86-32 - depending on actual CPU instruction. These bytes includes any prefix, opcode, MOD/RM byte, SIB byte, displacement bytes, immediate value bytes.
Third part ("CALL -$073DFB" in the above example) shows actual textual representation of disassembled instruction.
Fourth part ("; ($00624BB0) Unit1.TForm1.CheckVisible" in the above example; optional) contains an optional comment for the instruction (such as call/jmp destination or string data dump).

Note. This hi-level function is a simple combination of low-level DecodeInstruction (appendix A) and InstructionToString (appendix A). This function is used as base for DisasmFunction (appendix A) function.

GetAsmSize

Returns size of a single machine opcode.

function GetAsmSize(
  const AStart: Pointer;
  var ASize: Byte
): Boolean;

Parameters.

AStart

A pointer to code.

ASize

(out) A size of instruction at AStart (in bytes).

Return value.

True if operation was successful. False - otherwise.

Exceptions.

System.SysUtils.EAccessViolation

Invalid pointer or invalid code.

Remarks.

GetAsmSize tries to determinate size of one machine instruction in bytes.

This function is used as base of GetFunctionSize. It's also used in hooks and disassembler-related code.

Note. If AStart points to JMP-stub, GetAsmSize will return size of the stub, not the size of first function instruction.

GetFunctionSize

Returns size of the function in bytes.

function GetFunctionSize(
  const AAddr: Pointer;
  const AMaxSize: Cardinal
): Cardinal;

Parameters.

AAddr

A pointer to function.

AMaxSize

Maximum possible size to scan. Use this to limit scan area and prevent unlimited reading.

Return value.

Size of function at AAddr in bytes. This value is always in range 0..AMaxSize.

Exceptions.

System.SysUtils.EAccessViolation

Invalid address or invalid code.

Remarks.

GetFunctionSize scans machine code at AAddr address up to AAddr + AMaxSize. It stops at first ret instrution and returns distance between AAddr and end of ret.

This function is used in hooks and disassembler-related code.

Note. Make sure that you pass a pointer to a real function. Not to some arbitrary code or function's stub.

Use to get pointer to real code from stub.

Warning. This is heuristic function. Results are not 100% reliable.

InstructionToString

Converts decoded CPU instruction to string represenstation.

function InstructionToString(
  const AInstr: TInstruction;
  const AEncrypt: Boolean = False
): String;

Parameters.

AInstr [in] — Decoded CPU instruction to convert. Usually this value comes from DecodeInstruction function. The complete TInstruction layout is CPU-specific; no public layout declaration is specified here, and the record must not be treated as a portable binary layout.

Return value.

Textual representation of AInstr.

Remarks.

This function converts already decoded CPU instruction to string.

Sample output:

006989A2 E805C2F8FF CALL -$073DFB ; ($00624BB0) Unit1.TForm1.CheckVisible

First part ("006989A2" in the above example) repeats Address and it's always 8 hex characters for 32-bit process and 16 hex characters for 64-bit process.
Second part ("E805C2F8FF" in the above example) indicate RAW instruction bytes. Its size varies from 2 characters (1 byte) up to 30 characters (15 bytes) for x86-32 - depending on actual CPU instruction. These bytes includes any prefix, opcode, MOD/RM byte, SIB byte, displacement bytes, immediate value bytes.
Third part ("CALL -$073DFB" in the above example) shows actual textual representation of disassembled instruction.
Fourth part ("; ($00624BB0) Unit1.TForm1.CheckVisible" in the above example; optional) contains an optional comment for the instruction (such as call/jmp destination or string data dump).

EDNS

GetMXServerFromEmail

Retrieves mail server for e-mail address.

function GetMXServerFromEmail(
  const EMail: String
): String;

Parameters.

EMail [in] — A valid e-mail address, such as 'reports@example.com'.

Return value.

Host or IP address of a mail server discovered through the recipient domain's MX records. This is a destination for incoming mail to that domain, not discovery of your provider's authenticated SMTP submission server. For the SMTP Client setup in chapter 3, use the server, port and authentication settings supplied by the reporting account's provider.

Exceptions.

EDNS.EDNSError (appendix D, EDNSError)

Raised when DnsQuery function fails.

Remarks.

This function sends a DNS query about host from e-mail address (e.g. "example.com"). DNS query asks about MX-entry.

EEncrypt

DataProtect

Encrypts data.

procedure DataProtect(
  const AData: Pointer;
  const ADataSize: Cardinal;
  out AProtectedData: Pointer;
  out AProtectedDataSize: Cardinal;
  const ASameMachine: Boolean = False
); overload;
function DataProtect(
  const AData: RawByteString;
  const ASameMachine: Boolean = False
): RawByteString; overload;
procedure DataProtect(
  var AData: TEncryptBuffer;
  const ASameMachine: Boolean = False
); overload;
procedure DataProtect(
  const AData: TEncryptBuffer;
  out AProtectedData: TEncryptBuffer;
  const ASameMachine: Boolean = False
); overload;

Parameters.

AData [in] — Sensitive data to encrypt.
ADataSize [in] — Size of AData.
AProtectedData [out] — Encrypted data. Can be deleted by FreeMem function (but we recommend to use SecureFree (appendix A, EEncrypt.SecureFree) function instead).
AProtectedDataSize [out] — Size of AProtectedData.
ASameMachine [in, optional] — False (default) - encrypt data using currently logged in user; True - encrypt data using computer info only.
AData [in] — Sensitive data to encrypt.
AData [in, out] — On input: sensitive data to encrypt. Must be allocated with AllocMem function.

On output: encrypted data (size will be different). Can be deleted by EncryptBufferFree (appendix A) or SecureFree (appendix A, EEncrypt.SecureFree) functions.

AProtectedData [out] — Encrypted data (size will be different). Delete this data by EncryptBufferFree (appendix A) or SecureFree (appendix A, EEncrypt.SecureFree) functions.

Return value.

Encrypted data (size will be different).

Remarks.

This function encrypts data. Typically, only a user with the same logon credential as the user who encrypted the data can decrypt the data (when ASameMachine is False). In addition, the encryption and decryption usually must be done on the same computer.

You can use this function to save data that you want to decrypt later. If you want to protect sensitive data in your process memory while running - use MemProtect (appendix A) function.

Call the DataUnprotect (appendix A) function to decrypt data encrypted with the DataProtect function. When you have finished using the sensitive information, clear it from memory by calling the FillChar function.

The function creates a session key to perform the encryption. The session key is derived again when the data is to be decrypted.

The function also adds a Message Authentication Code (MAC) (keyed integrity check) to the encrypted data to guard against data tampering.

DataUnprotect

Decrypts data.

procedure DataUnprotect(
  const AProtectedData: Pointer;
  const AProtectedDataSize: Cardinal;
  out AData: Pointer;
  out ADataSize: Cardinal
); overload;
function DataUnprotect(
  const AProtectedData: RawByteString
): RawByteString; overload;
procedure DataUnprotect(
  var AProtectedData: TEncryptBuffer
); overload;
procedure DataUnprotect(
  const AProtectedData: TEncryptBuffer;
  out AData: TEncryptBuffer
); overload;

Parameters.

AProtectedData [in] — Encrypted data to decrypt.
AProtectedDataSize [in] — Size of AProtectedData.
AData [out] — Decrypted sensitive data. Can be deleted by FreeMem function (but we recommend to use SecureFree (appendix A, EEncrypt.SecureFree) function instead).
ADataSize [out] — Size of AData.
AProtectedData [in] — Encrypted data to decrypt.
AProtectedData [in, out] — On input: encrypted data to decrypt. Must be allocated with AllocMem function.

On output: unencrypted sensitive data (size will be different). Can be deleted by EncryptBufferFree (appendix A) or SecureFree (appendix A, EEncrypt.SecureFree) functions.

AData [out] — Unencrypted sensitive data (size will be different). Delete this data by EncryptBufferFree (appendix A) or SecureFree (appendix A, EEncrypt.SecureFree) functions.

Return value.

Unencrypted sensitive data (size will be different).

Remarks.

DataUnprotect function decrypts memory that was encrypted using the DataProtect (appendix A) function.

Scope is selected when DataProtect encrypts the input: its default is user-bound; ASameMachine=True selects machine scope. The general same-user/same-computer restriction must be read in conjunction with that documented DataProtect option, not as a restriction that eliminates machine scope.

When you have finished using the sensitive information, clear it from memory by calling the FillChar function.

EncryptBufferFree

Releases the encryption buffer.

procedure EncryptBufferFree(
  var AData: TEncryptBuffer
);

Parameters.

AData [in] — Encryption buffer to release.

Remarks.

This function will erase content of AData buffer (zero memory), then release the buffer, and set AData.pbData to nil, AData.cbData to 0.

Warning. AData buffer must be allocated via AllocMem function or be returned by any function from EEncrypt (appendix C) unit.

InitSalt

Generates random salt.

function InitSalt: TSalt;

Return value.

Random salt.

You do not need to free/release/dispose this value - it does not contain any allocated memory. However, it is strongly recommended to call SecureFree (appendix A, EEncrypt.SecureFree) function once you have finished working with salt - to erase it with zeros.

This value is never the same.

Remarks.

This function generates new random salt for TEADeriveKey (appendix A) function and TwofishDeriveKey (appendix A) function.

Important. Do not use RTL's Random function to create random salt manually. RTL implementation is a simple pseudo-random generator and it does not generate cryptographically-strong random data.

Note. In cryptography, a salt is random data that is used as an additional input to a one-way function that hashes a password. The primary function of salts is to defend against dictionary attacks versus a list of password hashes and against pre-computed rainbow table attacks.

MemProtect

Encrypts process memory.

procedure MemProtect(
  const AData: Pointer;
  const ADataSize: Cardinal;
  out AProtectedData: Pointer;
  out AProtectedDataSize: Cardinal
); overload;
function MemProtect(
  const AData: RawByteString
): RawByteString; overload;
procedure MemProtect(
  var AData: TEncryptBuffer
); overload;
procedure MemProtect(
  const AData: TEncryptBuffer;
  out AProtectedData: TEncryptBuffer
); overload;

Parameters.

AData [in] — Sensitive data to encrypt.
ADataSize [in] — Size of AData.
AProtectedData [out] — Encrypted data. Can be deleted by FreeMem function (but we recommend to use SecureFree (appendix A, EEncrypt.SecureFree) function instead).
AProtectedDataSize [out] — Size of AProtectedData.
AData [in] — Sensitive data to encrypt.
AData [in, out] — On input: sensitive data to encrypt. Must be allocated with AllocMem function.

On output: encrypted data (size will be different). Can be deleted by EncryptBufferFree (appendix A) or SecureFree (appendix A, EEncrypt.SecureFree) functions.

AProtectedData [out] — Encrypted data (size will be different). Delete this data by EncryptBufferFree (appendix A) or SecureFree (appendix A, EEncrypt.SecureFree) functions.

Return value.

Encrypted data (size will be different).

Remarks.

Encrypts sensitive data while a process is running, reducing exposure of the encrypted buffer, including when memory is paged out. This does not secure all copies or plaintext intervals.

Using MemProtect and MemUnprotect for password encryption is not secure because the data exists as plaintext in memory before it is encrypted and at any time the caller decrypts it for use.

Typically, you use the MemProtect function to encrypt sensitive information that you are going to decrypt while your process is running. Do not use this function to save data that you want to decrypt later; you will not be able to decrypt the data if the process or computer is restarted. To save encrypted data to a file to decrypt later, use the DataProtect (appendix A), TEAEncrypt (appendix A), or RSAEncrypt (appendix A) functions.

Call the MemUnprotect (appendix A) function to decrypt memory encrypted with the MemProtect function. When you have finished using the sensitive information, clear it from memory by calling the FillChar function.

Typically, only a user with the same logon credential as the user who encrypted the data can decrypt the data. In addition, the encryption and decryption usually must be done on the same computer. Moreover, decryption usually must be done within the same process.

The function creates a session key to perform the encryption. The session key is derived again when the data is to be decrypted.

The function also adds a Message Authentication Code (MAC) (keyed integrity check) to the encrypted data to guard against data tampering.

MemUnprotect

Decrypts process memory.

procedure MemUnprotect(
  const AProtectedData: Pointer;
  const AProtectedDataSize: Cardinal;
  out AData: Pointer;
  out ADataSize: Cardinal
); overload;
function MemUnprotect(
  const AProtectedData: RawByteString
): RawByteString; overload;
procedure MemUnprotect(
  var AProtectedData: TEncryptBuffer
); overload;
procedure MemUnprotect(
  const AProtectedData: TEncryptBuffer;
  out AData: TEncryptBuffer
); overload;

Parameters.

AProtectedData [in] — Encrypted data to decrypt.
AProtectedDataSize [in] — Size of AProtectedData.
AData [out] — Decrypted sensitive data. Can be deleted by FreeMem function (but we recommend to use SecureFree (appendix A, EEncrypt.SecureFree) function instead).
ADataSize [out] — Size of AData.
AProtectedData [in] — Encrypted data to decrypt.
AProtectedData [in, out] — On input: encrypted data to decrypt. Must be allocated with AllocMem function.

On output: unencrypted sensitive data (size will be different). Can be deleted by EncryptBufferFree (appendix A) or SecureFree (appendix A, EEncrypt.SecureFree) functions.

AData [out] — Unencrypted sensitive data (size will be different). Delete this data by EncryptBufferFree (appendix A) or SecureFree (appendix A, EEncrypt.SecureFree) functions.

Return value.

Unencrypted sensitive data (size will be different).

Remarks.

MemUnprotect function decrypts memory that was encrypted using the MemProtect (appendix A) function.

Using MemProtect and MemUnprotect for password encryption is not secure because the data exists as plaintext in memory before it is encrypted and at any time the caller decrypts it for use.

You must encrypt and decrypt the memory during the same boot session. If the computer is restarted before you call the MemUnprotect function, you will not be able to decrypt the data.

When you have finished using the sensitive information, clear it from memory by calling the FillChar function.

RSADecrypt

Decrypts encrypted data by using RSA cipher.

procedure RSADecrypt(
  const AKey: TRSAKey;
  const AEncryptedData: Pointer;
  out AData: Pointer;
  var ADataSize: Cardinal
); overload;
function RSADecrypt(
  const AKey: TRSAKey;
  const AEncryptedData: RawByteString
): RawByteString; overload;
procedure RSADecrypt(
  const AKey: TRSAKey;
  var AInPlaceData: TEncryptBuffer
); overload;

Parameters.

AKey [in] — A key for decryption. Comes from RSAGenKey (appendix A) function or RSALoadPrivateKey (appendix A) function. A private key will be used.
AEncryptedData [in] — A data to decrypt. Must be in little-endian format.
AData [out] — A decrypted AEncryptedData's "clear text" data. Must be deleted with FreeMem function (but we recommend to use SecureFree (appendix A, EEncrypt.SecureFree) function instead). Will have different size from AData.
ADataSize [in] — On input: size of AEncryptedData.

On output: size of AData.

AEncryptedData [in] — Encrypted data (in string form) to decrypt. Must be in little-endian format.
AInPlaceData [in, out] — On input: encrypted buffer to decrypt. Must be in little-endian format.

On output: "clear text" buffer (same size).

Return value.

Decrypted "clear text" data.

Remarks.

This function decrypts data previosly encrypted with RSAEncrypt (appendix A) function with private key of asymmetric RSA cipher. The encrypted data is passed in AEncryptedData parameter. The function outputs decrypted data back to AData parameter. AData expected to have different size from AEncryptedData. In other words, asymmetric decryption with RSA does change the size of the data.

The overload variant with RawByteString decrypts AEncryptedData parameter and outputs decrypted data as function's result.

The overload variant with AInPlaceData decrypts data "in place".

Important. Asymmetric chipers are slow. Therefore, they are not designed to encrypt/decrypt large amount of data. The usual approach is to use asymmetric chiper to encrypt/decrypt another key - a key for some symmetric cipher, and then use (fast) symmetric cipher to encrypt/decrypt large amounts of data.

Tip. You always use public key for encryption and private key for decryption with asymmetric cipher - and not the other way around. You should use digital signing and verification for reversed order. I.e. you sign data by using your private key and verify signature by using your public key.

RSADestroyKey

Deletes RSA key.

procedure RSADestroyKey(
  var AKey: TRSAKey
); overload;
procedure RSADestroyKey(
  var AKeyPart: TEncryptBuffer
); overload;

Parameters.

AKey [in] — RSA key to be released.
AKeyPart [in] — Public or private key to be released.

Remarks.

This function deletes RSA key allocated by RSAGenKey (appendix A) or RSALoadPublicKey (appendix A)/RSALoadPrivateKey (appendix A) functions.

Call this function to release RSA key once you have finished working with it.

RSAEncrypt

Encrypts "clear text" data by using RSA cipher.

procedure RSAEncrypt(
  const AKey: TRSAKey;
  const AData: Pointer;
  out AEncryptedData: Pointer;
  var ADataSize: Cardinal
); overload;
function RSAEncrypt(
  const AKey: TRSAKey;
  const AData: RawByteString
): RawByteString; overload;
procedure RSAEncrypt(
  const AKey: TRSAKey;
  var AInPlaceData: TEncryptBuffer
); overload;

Parameters.

AKey [in] — A key for encryption. Comes from RSAGenKey (appendix A) function or RSALoadPublicKey (appendix A) function. A public key will be used.
AData [in] — A data to encrypt.
AEncryptedData [out] — An encrypted AData's data. Must be deleted with FreeMem function (but we recommend to use SecureFree (appendix A, EEncrypt.SecureFree) function instead). Will have different size from AData. Data is returned in little-endian format.
ADataSize [in, out] — On input: size of AData.

On output: size of AEncryptedData (will be different).

AData [in] — String "clear text" data to encrypt.
AInPlaceData [in, out] — On input: "clear text" buffer to encrypt.

On output: encrypted buffer (same size, little-endian).

Return value.

Encrypted AData's data in a string form. Data is returned in little-endian format.

Remarks.

This function encrypts data passed in AData parameter with public key of asymmetric RSA cipher and outputs encrypted data back to AEncryptedData parameter. AEncryptedData expected to have different size from original AData. In other words, asymmetric encryption with RSA does change the size of the data.

The overload variant with RawByteString encrypts AData parameter and outputs encrypted data as function's result.

The overload variant with AInPlaceData encrypts data "in place".

RSAGenKey

Creates new RSA key.

function RSAGenKey(
  const AKeyBitSize: Cardinal = 4096
): TRSAKey;

Parameters.

AKeyBitSize [in, opt] — Size of new key in bits. Default is 4096. Minimum is 384. Maximum is 16384. Must be a factor of 8.

Return value.

Generated RSA key.

Delete this key by using RSADestroyKey (appendix A) function.

Remarks.

This function generates a new RSA key (public/private keys pair). The returned key must be deleted by RSADestroyKey (appendix A) function once you have finished working with it.

Resulting key may be used for encryption using RSAEncrypt (appendix A) function or for digital signature using RSASign (appendix A) function.

Resulting key may be exported by using RSASavePublicKey (appendix A) and RSASavePrivateKey (appendix A) functions.

You may import previosly created key instead of generating new key. Use RSALoadPublicKey (appendix A) and/or RSALoadPrivateKey (appendix A) functions.

RSA is one of the first practical public-key cryptosystems and is widely used for secure data transmission. RSA is a relatively slow algorithm, and because of this it is less commonly used to directly encrypt user data. More often, RSA passes encrypted shared keys for symmetric key cryptography which in turn can perform bulk encryption-decryption operations at much higher speed.

Important. It is currently recommended that key size be at least 2048 bits long for security reasons.

RSALoadPrivateKey

Imports private key.

function RSALoadPrivateKey(
  const AFileName: String;
  const AType: TRSAImport;
  const APassword: String = ''
): TRSAKey; overload;
function RSALoadPrivateKey(
  const AStream: Classes.TStream;
  const AType: TRSAImport;
  const APassword: String = ''
): TRSAKey; overload;

Parameters.

AFileName [in] — A fully qualified absolute file name. File must exist. The file is usually obtained from RSASavePrivateKey (appendix A) function.
AType [in] — AFileName/AStream's type. It must match type specified in RSASavePrivateKey (appendix A) when exporting the key.
AStream [in] — A stream to load private key.

Return value.

RSA private key. Public key part will be unassigned. This key must be released with RSADestroyKey (appendix A) function.

Remarks.

This function loads private key from given file or stream.

RSALoadPublicKey

Imports public key.

function RSALoadPublicKey(
  const AFileName: String;
  const AType: TRSAImport
): TRSAKey; overload;
function RSALoadPublicKey(
  const AStream: Classes.TStream;
  const AType: TRSAImport
): TRSAKey; overload;

Parameters.

AFileName [in] — A fully qualified absolute file name. File must exist. The file is usually obtained from RSASavePublicKey (appendix A) function.
AType [in] — AFileName/AStream's type. It must match type specified in RSASavePublicKey (appendix A) when exporting the key.
AStream [in] — A stream to load public key.

Return value.

RSA public key. Private key part will be unassigned. This key must be released with RSADestroyKey (appendix A) function.

Remarks.

This function loads public key from given file or stream.

RSASavePrivateKey

Exports private key.

procedure RSASavePrivateKey(
  const AKey: TRSAKey;
  const AFileName: String;
  const AType: TRSAExport;
  const APassword: String = ''
); overload;
procedure RSASavePrivateKey(
  const AKey: TRSAKey;
  const AStream: Classes.TStream;
  const AType: TRSAExport;
  const APassword: String = ''
); overload;

Parameters.

AKey [in] — RSA key to export. Must come from RSAGenKey (appendix A) or RSALoadPrivateKey (appendix A) functions.
AFileName [in] — A fully qualified absolute file name. New file will be created. Recommended file's extensions are '.blob', '.der', or 'pem'.
AType [in] — AFileName/AStream's type.
APassword [in, opt] — Optional password to encrypt private key before exporting.
AStream [in] — A stream to save private key.

Remarks.

This function saves private key from given RSA key to file or stream.

Key can be imported later with RSALoadPrivateKey (appendix A) function.

RSASavePublicKey

Exports public key.

procedure RSASavePublicKey(
  const AKey: TRSAKey;
  const AFileName: String;
  const AType: TRSAExport
); overload;
procedure RSASavePublicKey(
  const AKey: TRSAKey;
  const AStream: Classes.TStream;
  const AType: TRSAExport
); overload;

Parameters.

AKey [in] — RSA key to export. Must come from RSAGenKey (appendix A) or RSALoadPublicKey (appendix A) functions.
AFileName [in] — A fully qualified absolute file name. New file will be created. Recommended file's extensions are '.blob', '.der', or 'pem'.
AType [in] — AFileName/AStream's type.
AStream [in] — A stream to save public key.

Remarks.

This function saves public key from given RSA key to file or stream.

Key can be imported later with RSALoadPublicKey (appendix A) function.

RSASign

Signs data.

function RSASign(
  const AKey: TRSAKey;
  const AData: Pointer;
  const ADataSize: Cardinal
): TRSASignature; overload;
function RSASign(
  const AKey: TRSAKey;
  const AData: TEncryptBuffer
): TRSASignature; overload;
function RSASign(
  const AKey: TRSAKey;
  const AData: RawByteString
): TRSASignature; overload;

Parameters.

AKey [in] — A key for digital signing. Comes from RSAGenKey (appendix A) function or RSALoadPrivateKey (appendix A) function. A private key will be used.
AData [in] — Data to be signed.
ADataSize [in] — Size of AData in bytes.

Return value.

Digital signature (little-endian). Release it with SecureFree (appendix A, EEncrypt.SecureFree) function.

Remarks.

This function digitally signs the specified data and returns digital signature. Digital signature is a small RAW bytes value, which can be freely copied and/or exported/imported.

Your private key will be used for digital signing.

You can verify the returned signature with RSAVerify (appendix A) function.

Note. Internally RSASign will calculate SHA-1 hash of AData and sign (encrypt) resulting hash with RSA and private key. EMSA-PKCS1-v1_5 scheme is used for padding.

Important. The resulting signature bytes are in little-endian order. You must reverse bytes order if you want to verify this signature with other tools which requires big-endian order (such as .NET or OpenSSL).

RSAVerify

Verifies digital signature.

function RSAVerify(
  const AKey: TRSAKey;
  const AData: Pointer;
  const ADataSize: Cardinal;
  const ASignature: Pointer;
  const ASignatureSize: Cardinal
): Boolean; overload;
function RSAVerify(
  const AKey: TRSAKey;
  const AData: TEncryptBuffer;
  const ASignature: TRSASignature
): Boolean; overload;
function RSAVerify(
  const AKey: TRSAKey;
  const AData: RawByteString;
  const ASignature: TRSASignature
): Boolean; overload;

Parameters.

AKey [in] — A key for verification. Comes from RSAGenKey (appendix A) function or RSALoadPublicKey (appendix A) function. Must match the key used in RSASign (appendix A) function to sign AData. A public key will be used.
AData [in] — Data to be verified (the same data as the one passed to RSASign (appendix A) function). Must be unmodified (otherwise function will return False).
ADataSize [in] — Size of AData in bytes.
ASignature [in] — Signature to be verified (the same signature as the one returned by RSASign (appendix A) function). Little-endian.
ASignatureSize [in] — Size of ASignature in bytes.

Return value.

True - if digital signature is OK, False - if digital signature is broken (i.e. AData is not the same/was changed; or wrong key is used).

Remarks.

This function verifies digital signature created by RSASign (appendix A) function.

Your public key will be used for verification.

Important. The signature bytes must be in little-endian order. You must reverse bytes order (before calling RSAVerify) if you want to verify signature generated by other tools which produce big-endian order signatures (such as .NET or OpenSSL).

EEncrypt.SecureFree

Wipes and releases memory.

procedure SecureFree(
  var P: Pointer;
  const ADataSize: Cardinal
); overload;
procedure SecureFree(
  var Str: String
); overload;
procedure SecureFree(
  var Str: RawByteString
); overload;
procedure SecureFree(
  var AStream: Classes.TMemoryStream
); overload;
procedure SecureFree(
  var AStream: Classes.TCustomMemoryStream
); overload;
procedure SecureFree(
  var AList: TStringList
); overload;
procedure SecureFree(
  var IV: TTwofishInitVector
); overload;
procedure SecureFree(
  var AKey: TTwofishRAWKey
); overload;
procedure SecureFree(
  var AKey: TTEAKey
); overload;
procedure SecureFree(
  var AKey: TRSAKey
); overload;
procedure SecureFree(
  var ABuffer: TEncryptBuffer
); overload;

Remarks.

Set of SecureFree functions takes different arguments, erases memory's content with zeros, then finally releases the memory. It is an analog of ZeroMemory (or FillChar) + FreeMem.

TEADecrypt

Decrypts encrypted data by using TEA cipher.

procedure TEADecrypt(
  const AKey: TTEAKey;
  const AEncryptedData, AData: Pointer;
  const ADataSize: Cardinal
); overload;
function TEADecrypt(
  const AKey: TTEAKey;
  const AEncryptedData: RawByteString
): RawByteString; overload;
procedure TEADecrypt(
  const AKey: TTEAKey;
  AInPlaceData: TEncryptBuffer
); overload;

Parameters.

AKey [in] — A key for decryption from TEADeriveKey (appendix A) function.
AEncryptedData [in] — A data to decrypt. Must not contain salt (see TEADeriveKey (appendix A)). Must be in little-endian format.
AData [out] — A decrypted AEncryptedData's "clear text" data. Must have the same size as AEncryptedData.
ADataSize [in] — Size of AEncryptedData/AData.
AEncryptedData [in] — Encrypted data (in string form) to decrypt. Must not contain salt (see TEADeriveKey (appendix A)). Must be in little-endian format.
AInPlaceData [in, out] — On input: encrypted buffer to decrypt. Must not contain salt (see TEADeriveKey (appendix A)). Must be in little-endian format.

On output: "clear text" buffer (same size).

Return value.

Decrypted "clear text" data.

Remarks.

This function decrypts data previosly encrypted with TEAEncrypt (appendix A) function by symmetric TEA cipher. The encrypted data is passed in AEncryptedData parameter. The function outputs decrypted data back to AData parameter. AData expected to have the same size as AEncryptedData. In other words, symmetric decryption with TEA does not change the size of the data.

Note. AData value can also point to the same place as AEncryptedData - to make "in place" decryption, but it is better to use overloaded variant of TEADecrypt with AInPlace parameter.

The overload variant with RawByteString decrypts AEncryptedData parameter and outputs decrypted data as function's result.

The overload variant with AInPlaceData decrypts data "in place".

Tip. Using salt in TEADeriveKey (appendix A) function means that final size of encrypted/decrypted data will change - because salt must be stored with encrypted data. If you do not use salt - the data size will be the same. However, data size for TEADecrypt function is never changed (even if salt is used).

Tiny Encryption Algorithm (TEA) is a block cipher notable for its simplicity of description and implementation, typically a few lines of code. TEA operates on two 32-bit unsigned integers (could be derived from a 64-bit data block) and uses a 128-bit key.

Important. TEA has a few weaknesses. Most notably, it suffers from equivalent keys—each key is equivalent to three others, which means that the effective key size is only 126 bits. As a result, TEA is especially bad as a cryptographic hash function. TEA is also susceptible to a related-key attack which requires 2^23 chosen plaintexts under a related-key pair, with 2^32 time complexity.

TEADefaultKey

Returns pre-initialized default key for TEA.

function TEADefaultKey: TTEAKey;

Return value.

Key derived from empty password.

Remarks.

This function returns the same value as TEADeriveKey('', nil).

Unlike TEADeriveKey (appendix A) function, TEADefaultKey does not perform any calculations and simply uses pre-initialized value. Thus, you should use this function to improve performance.

Note. Encrypting data with empty password does not mean that data will be unencrypted (e.g. not changed). It will be encrypted, but anyone will be able to decrypt it back, as password is empty. Salt is not needed for the same reason (as password is known).

Tip. Since default password is always stored in memory - there is not much meaning to wipe default key (with TEADestroyKey (appendix A)) after using it.

TEADeriveKey

Initializes TEA key from password.

function TEADeriveKey(
  const APassword: String;
  const ASalt: PSalt = nil
): TTEAKey; overload;
function TEADeriveKey(
  const AData: Pointer;
  const ADataSize: Cardinal;
  const ASalt: PSalt = nil
): TTEAKey; overload;

Parameters.

APassword [in, opt] — User password.
ASalt [in, opt] — Optional salt value. It is recommended to always use/specify salt when possible - to defend against dictionary and pre-computed rainbow table attacks. Use InitSalt (appendix A) function to create new salt for encryption and store salt with encrypted data. Use stored salt to decrypt data.
AData [in] — Pointer to binary password to initialize the key.
ADataSize [in] — Size of AData in bytes.

Return value.

TEA key derived from APassword and (optionally) ASalt.

You do not need to free/release/dispose this key - it does not contain any allocated memory. However, it is strongly recommended to call TEADestroyKey (appendix A) function once you have finished working with key - to erase it with zeros.

This value is always the same for the same APassword (and same ASalt).

Remarks.

This function converts APassword to UTF-8, attaches ASalt (if specified), then uses the resulting RAW binary string to initialize the key. This function uses MD5(ASalt + APassword) to derive key.

You do not need to call this function if you already have RAW binary TEA key (TTEAKey (appendix B)).

Overloaded variant lets you initialize key from any binary password. It is usually used in conjunction with asymmetric cipher when generating random passwords for symmetric cipher.

Warning. TEADeriveKey and TEADeriveKeyHMAC use different algorithms to derive the key. E.g. key created by the TEADeriveKey will be different from the key created by the TEADeriveKeyHMAC function. In other words, if you use some function on sending side - then you must use the same function on receiving side. If you do not have compatibility requirements with external code - we recommend to use TEADeriveKeyHMAC function.

Tip. APassword can also be an empty string. Encrypting data with empty password does not mean that data will be unencrypted (e.g. not changed). It will be encrypted, but anyone will be able to decrypt it back, as password is empty. It is strongly recommended not to use empty passwords. There is no need to specify salt for empty password. It is better to use TEADefaultKey (appendix A) function in this case.

Important. Empty salt (zeroed) is not the same as no salt. Use InitSalt (appendix A) function to create new random salt. Once created, salt must be stored with encrypted data and then passed to TEADeriveKey for decryption.

Tip. Using salt means that size of encrypted/decrypted data will change - because salt must be stored with encrypted data. If you do not use salt - the data size will not change during encryption/decryption.

TEADeriveKeyHMAC

Initializes TEA key from password via MD5 HMAC.

function TEADeriveKeyHMAC(
  const APassword: String;
  const ASalt: TSalt
): TTEAKey; overload;

Parameters.

APassword [in] — User password.
ASalt [in] — Salt value. Use InitSalt (appendix A) function to create new salt for encryption and store salt with encrypted data. Use stored salt to decrypt data.

Return value.

TEA key derived from APassword and ASalt using MD5 HMAC.

This value is always the same for the same APassword and same ASalt.

Remarks.

This function converts APassword to UTF-8 and then uses MD5HMAC(ASalt, APassword) to derive the key using the specified salt.

You do not need to call this function if you already have RAW binary TEA key (TTEAKey (appendix B)).

TEADestroyKey

Fills TEA key with zeros.

procedure TEADestroyKey(
  var AKey: TTEAKey
);

Parameters.

AKey [in] — TEA key to be wiped.

Remarks.

While calling this function is not strictly required (as TEA key does not hold any allocated resources which would require cleanup), but we strongly recommend to call this function for every TEA key once you have finished working with it.

Tip. Since default password (returned by TEADefaultKey (appendix A)) is always stored in memory - there is not much meaning to wipe default key after using it.

TEAEncrypt

Encrypts "clear text" data by using TEA cipher.

procedure TEAEncrypt(
  const AKey: TTEAKey;
  const AData, AEncryptedData: Pointer;
  const ADataSize: Cardinal
); overload;
function TEAEncrypt(
  const AKey: TTEAKey;
  const AData: RawByteString
): RawByteString; overload;
procedure TEAEncrypt(
  const AKey: TTEAKey;
  AInPlaceData: TEncryptBuffer
); overload;

Parameters.

AKey [in] — A key for encryption from TEADeriveKey (appendix A) function.
AData [in] — A data to encrypt.
AEncryptedData [out] — An encrypted AData's data. Must have the same size as AData. Data is returned in little-endian format.
ADataSize [in] — Size of AData/AEncryptedData.
AData [in] — String "clear text" data to encrypt.
AInPlaceData [in, out] — On input: "clear text" buffer to encrypt.

On output: encrypted buffer (same size, lettle-endian).

Return value.

Encrypted AData's data in a string form. Data is returned in little-endian format.

Remarks.

This function encrypts data passed in AData parameter by symmetric TEA cipher and outputs encrypted data back to AEncryptedData parameter. AEncryptedData expected to have the same size as AData. In other words, symmetric encryption with TEA does not change the size of the data.

Note. AEncryptedData value can also point to the same place as AData - to make "in place" encryption, but it is better to use overloaded variant of TEAEncrypt with AInPlace parameter.

The overload variant with RawByteString encrypts AData parameter and outputs encrypted data as function's result.

The overload variant with AInPlaceData encrypts data "in place".

Tip. Using salt in TEADeriveKey (appendix A) function means that final size of encrypted/decrypted data will change - because salt must be stored with encrypted data. If you do not use salt - the data size will be the same. However, data size for TEAEncrypt function is never changed (even if salt is used).

TEAInitSessionKey

Generates random TEA key.

function TEAInitSessionKey: TTEAKey;

Return value.

Random TEA key.

This value is never the same.

Remarks.

This function generates random TEA key. This key can be used as session key for asymmetric encryption. See description of RSAEncrypt (appendix A) for more details.

Important. Do not use RTL's Random function to create random TEA key manually. RTL implementation is a simple pseudo-random generator and it does not generate cryptographically-strong random data.

Use TEADeriveKey (appendix A) function to derive symmetric TEA key from string password or any other arbitrary "seed" data.

TwofishDecrypt

Decrypts encrypted data by using Twofish cipher.

procedure TwofishDecrypt(
  const AKey: TTwofishKey;
  const AEncryptedData: Pointer;
  out AData: Pointer;
  var ADataSize: Cardinal;
  const AInitVector: PTwofishInitVector = nil
); overload;
function TwofishDecrypt(
  const AKey: TTwofishKey;
  const AEncryptedData: RawByteString;
  const AInitVector: PTwofishInitVector = nil
): RawByteString; overload;

Parameters.

AKey [in] — A key for decryption. Comes from TwofishDeriveKey (appendix A) function or TwofishInitKey (appendix A) function.
AEncryptedData [in] — A data to decrypt. Must be in little-endian format.
AData [out] — A decrypted AEncryptedData's "clear text" data. Must be deleted with FreeMem function (but we recommend to use SecureFree (appendix A, EEncrypt.SecureFree) function instead). Will have different size from AData. PKCS#5 padding will be removed.
ADataSize [in, out] — On input: size of AEncryptedData.

On output: size of AData.

AInitVector [in, opt] — An optional initialization vector (IV). This value must be the same as the one passed to TwofishEncrypt (appendix A) function during encryption.
AEncryptedData [in] — Encrypted data (in string form) to decrypt. Must not contain salt (see TwofishDeriveKey (appendix A)). Must be in little-endian format.

Return value.

Decrypted "clear text" data. PKCS#5 padding will be removed.

Remarks.

This function decrypts data previosly encrypted with TwofishEncrypt (appendix A) function with key of symmetric Twofish cipher. The encrypted data is passed in AEncryptedData parameter. The function outputs decrypted data back to AData parameter. AData expected to have different size from AEncryptedData. In other words, symmetric decryption with Twofish does change the size of the data.

The overload variant with RawByteString decrypts AEncryptedData parameter and outputs decrypted data as function's result.

Important. Zero-filled IV is not the same as not specified IV. Not specified IV means using ECB mode. Specified IV means using CBC mode (even if IV is empty/zero filled).

Tip. TwofishEncrypt/TwofishDecrypt use PKCS#5 filling scheme for both ECB and CBC modes. That is: data size will be increased (during encryption) to closest block boundary (block size is 16 bytes/128 bit), the unused space (padding) will be filled with its own size (e.g. 1..16). If source data size is exactly N * 16 bytes, then one full block (16 bytes) will be added (and filled with byte = 16). On decryption data size will be simply decreased by a value specified in the last byte.

TwofishDeriveKey

Initializes Twofish key from password.

function TwofishDeriveKey(
  const APassword: String;
  const ASalt: PSalt = nil
): TTwofishKey; overload;
function TwofishDeriveKey(
  const AData: Pointer;
  const ADataSize: Cardinal;
  const ASalt: PSalt = nil
): TTwofishKey; overload;

Parameters.

APassword [in, opt] — User password.
ASalt [in, opt] — Optional salt value. It is recommended to always use/specify salt when possible - to defend against dictionary and pre-computed rainbow table attacks. Use InitSalt (appendix A) function to create new salt for encryption and store salt with encrypted data. Use stored salt to decrypt data.
AData [in] — Pointer to binary password to initialize the key.
ADataSize [in] — Size of AData in bytes.

Return value.

Precalculated 256-bit Twofish key derived from APassword and (optionally) ASalt using SHA256Hash(ASalt + APassword).

Delete this key by using TwofishDestroyKey (appendix A) function.

This value is always the same for the same APassword (and same ASalt).

Important. This is not RAW key derived from password. This is precalculated array of subkeys and SBox keys for Twofish cipher. Precalculation speed ups encryption/decryption. Use TwofishInitKey (appendix A) to precalculate key from RAW key.

Remarks.

This function converts APassword to UTF-8, attaches ASalt (if specified), then uses the resulting RAW binary string to initialize the key. This function uses SHA256Hash(ASalt + APassword) to derive the key. Therefore the key has size of 256 bits.

Important. The returned value of this function is not RAW key derived from password. The returned value is precalculated/cached array of subkeys and SBox keys for Twofish cipher. Precalculation speed ups encryption/decryption. Use TwofishInitKey (appendix A) to precalculate key from RAW key.

Delete the returned value by using TwofishDestroyKey (appendix A) function when you have finished working with key.

Overloaded variant lets you initialize key from any binary password.

Warning. TwofishDeriveKey and TwofishDeriveKeyHMAC use different algorithms to derive the key. E.g. key created by the TwofishDeriveKey will be different from the key created by the TwofishDeriveKeyHMAC function. In other words, if you use some function on sending side - then you must use the same function on receiving side. If you do not have compatibility requirements with external code - we recommend to use TwofishDeriveKeyHMAC function.

Important. Empty salt (zeroed) is not the same as no salt. Use TwofishInitSessionKey function to create new random salt. Once created, salt must be stored with encrypted data and then passed to TwofishDeriveKey for decryption.

Twofish is a symmetric key block cipher with a block size of 128 bits and key sizes up to 256 bits. It was one of the five finalists of the Advanced Encryption Standard (AES) contest, but it was not selected for standardization. Twofish's distinctive features are the use of pre-computed key-dependent S-boxes, and a relatively complex key schedule. Twofish cipher has not been patented. As a result, the Twofish algorithm is free for anyone to use without any restrictions whatsoever. However, Twofish has seen less widespread usage than Blowfish, which has been available longer.

TwofishDeriveKeyHMAC

Initializes Twofish key from password using SHA-256 HMAC.

function TwofishDeriveKeyHMAC(
  const APassword: String;
  const ASalt: TSalt
): TTwofishKey;

Parameters.

APassword [in] — User password.
ASalt [in] — Salt value. Use InitSalt (appendix A) function to create new salt for encryption and store salt with encrypted data. Use stored salt to decrypt data.

Return value.

Precalculated 256-bit Twofish key derived from APassword and ASalt using SHA256HMAC(ASalt, APassword).

Delete this key by using TwofishDestroyKey (appendix A) function.

This value is always the same for the same APassword and same ASalt.

Remarks.

This function converts APassword to UTF-8 and then uses SHA256HMAC(ASalt, APassword) to derive the key. Therefore the key has size of 256 bits.

Important. The returned value of this function is not RAW key derived from password/salt. The returned value is precalculated/cached array of subkeys and SBox keys for Twofish cipher. Precalculation speed ups encryption/decryption. Use TwofishInitKey (appendix A) to precalculate key from RAW key.

Delete the returned value by using TwofishDestroyKey (appendix A) function when you have finished working with key.

TwofishDestroyKey

Deletes Twofish key.

procedure TwofishDestroyKey(
  var AKey: TTwofishKey
);

Parameters.

AKey [in] — Twofish key to be released.

Remarks.

This function deletes Twofish key allocated by TwofishDeriveKey (appendix A) or TwofishInitKey (appendix A) functions.

Call this function to release Twofish key once you have finished working with it.

TwofishEncrypt

Encrypts "clear text" data by using Twofish cipher.

procedure TwofishEncrypt(
  const AKey: TTwofishKey;
  const AData: Pointer;
  out AEncryptedData: Pointer;
  var ADataSize: Cardinal;
  const AInitVector: PTwofishInitVector = nil
); overload;
function TwofishEncrypt(
  const AKey: TTwofishKey;
  const AData: RawByteString;
  const AInitVector: PTwofishInitVector = nil
): RawByteString; overload;

Parameters.

AKey [in] — A key for encryption. Comes from TwofishDeriveKey (appendix A) function or TwofishInitKey (appendix A) function.
AData [in] — A data to encrypt. Data will be padded with PKCS#5.
AEncryptedData [out] — An encrypted AData's data. Must be deleted with FreeMem function (but we recommend to use SecureFree (appendix A, EEncrypt.SecureFree) function instead). Will have different size from AData. Data is returned in little-endian format.
ADataSize [in, out] — On input: size of AData.

On output: size of AEncryptedData (will be different).

AInitVector [in, opt] — An optional initialization vector (IV) from TwofishInitIV (appendix A) function.

Default is nil - which means using ECB encryption mode (not recommended).

Specified (non-nil) value means using CBC encryption mode.

AData [in] — String "clear text" data to encrypt. Data will be padded with PKCS#5.

Return value.

Encrypted AData's data in a string form. Data is returned in little-endian format.

Remarks.

This function encrypts data passed in AData parameter with key of symmetric Twofish cipher and outputs encrypted data back to AEncryptedData parameter. AEncryptedData expected to have different size from original AData. In other words, symmetric encryption with Twofish does change the size of the data.

The overload variant with RawByteString encrypts AData parameter and outputs encrypted data as function's result.

Important. Zero-filled IV is not the same as not specified IV. Not specified IV means using ECB mode. Specified IV means using CBC mode (even if IV is empty/zero filled).

TwofishInitIV

Creates new IV.

function TwofishInitIV: TTwofishInitVector;

Return value.

Random initialization vector.

Remarks.

This function creates new random initialization vector (IV). Pass the returned value to TwofishEncrypt (appendix A) function to use CBC mode.

Important. Do not pass the returned value to TwofishDecrypt (appendix A) function. IV for decryption must match the IV used for encryption. In other words, you must store IV with encrypted data.

Important. Do not use RTL's Random function to create random salt manually. RTL implementation is a simple pseudo-random generator and it does not generate cryptographically-strong random data.

Note. Initialization vector (IV) is a fixed-size input to a cryptographic primitive that is typically required to be random or pseudorandom. Randomization is crucial for encryption schemes to achieve semantic security, a property whereby repeated usage of the scheme under the same key does not allow an attacker to infer relationships between segments of the encrypted message.

TwofishInitKey

"Imports" (precalculates) Twofish key from RAW key value.

function TwofishInitKey(
  const AKey: TTwofishRAWKey
): TTwofishKey;

Parameters.

AKey [in] — 256-bit RAW Twofish key.

Return value.

Twofish key precalculated from AKey.

Delete this key by using TwofishDestroyKey (appendix A) function.

This value is always the same for the same AKey.

Remarks.

EurekaLog uses precalculated/cached array of subkeys and SBox keys for Twofish cipher. It improves performance of encryption/decryption. Use this function to obtain precalculated key from given RAW key value.

Use TwofishDeriveKey (appendix A) function to derive key from password.

Delete the returned value by using TwofishDestroyKey (appendix A) function when you have finished working with key.

EEvents

AddCustomDataToBugReport

Adds static data to bug report.

procedure AddCustomDataToBugReport(
  const AName, AValue: String
);

Parameters.

AName [in] — Custom field name. Can be arbitrary text of your choice.
AValue [in, optional] — Custom field value. If this value is empty, custom field will be deleted/cleared. If this value is set, custom field will be assigned.

Remarks.

This function can be used to add custom fields to all EurekaLog bug reports. The field's value is set when this function is called. Therefore, this function can only be used to set a static value.

Tip. Use the RegisterEventCustomDataRequest (appendix A) function to register your custom code to supply a dynamic value for custom bug report fields.

AddCustomWebField

Adds static data to web requests.

procedure AddCustomWebField(
  const AName, AValue: String
);

Parameters.

AName [in] — Custom web field name. Can be arbitrary text of your choice.
AValue [in, optional] — Custom web field value. If this value is empty, custom web field will be deleted/cleared. If this value is set, custom web field will be assigned.

Remarks.

This function can be used to add custom fields to all EurekaLog web requests. The field's value is set when this function is called. Therefore, this function can only be used to set a static value.

Tip. Use the RegisterEventCustomWebFieldsRequest (appendix A) function to register your custom code to supply a dynamic value for custom web fields.

RegisterEventAttachedFilesRequest

Registers OnAttachedFilesRequest event handler.

procedure RegisterEventAttachedFilesRequest(
  const AHandler: TELEvAttachedFilesRequestMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventAttachedFilesRequest(
  const ACustom: Pointer;
  const AHandler: TELEvAttachedFilesRequestProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventBeginReportGen

Registers OnBeginReportGen event handler.

procedure RegisterEventBeginReportGen(
  const AHandler: TELEvReportGenMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventBeginReportGen(
  const ACustom: Pointer;
  const AHandler: TELEvReportGenProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventCustomBugID

Registers OnCustomBugID event handler.

procedure RegisterEventCustomBugID(
  const AHandler: TELEvCustomBugIDMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventCustomBugID(
  const ACustom: Pointer;
  const AHandler: TELEvCustomBugIDProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventCustomButtonClick

Registers OnCustomButtonClick event handler.

procedure RegisterEventCustomButtonClick(
  const AHandler: TELEvCustomButtonClickMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventCustomButtonClick(
  const ACustom: Pointer;
  const AHandler: TELEvCustomButtonClickProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventCustomDataRequest

Registers OnCustomDataRequest event handler.

procedure RegisterEventCustomDataRequest(
  const AHandler: TELEvCustomDataRequestMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventCustomDataRequest(
  const ACustom: Pointer;
  const AHandler: TELEvCustomDataRequestProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventCustomFileName

Registers OnCustomFileName event handler.

procedure RegisterEventCustomFileName(
  const AHandler: TELEvCustomFileNameMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventCustomFileName(
  const ACustom: Pointer;
  const AHandler: TELEvCustomFileNameProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventCustomWebFieldsRequest

Registers OnCustomWebFieldRequest event handler.

procedure RegisterEventCustomWebFieldsRequest(
  const AHandler: TELEvCustomWebFieldsRequestMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventCustomWebFieldsRequest(
  const ACustom: Pointer;
  const AHandler: TELEvCustomWebFieldsRequestProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventEndReportGen

Registers OnEndReportGen event handler.

procedure RegisterEventEndReportGen(
  const AHandler: TELEvReportGenMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventEndReportGen(
  const ACustom: Pointer;
  const AHandler: TELEvReportGenProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventExceptionAction

Registers OnExceptionAction event handler.

procedure RegisterEventExceptionAction(
  const AHandler: TELEvExceptionActionMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventExceptionAction(
  const ACustom: Pointer;
  const AHandler: TELEvExceptionActionProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventExceptionError

Registers OnExceptionError event handler.

procedure RegisterEventExceptionError(
  const AHandler: TELEvExceptionErrorMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventExceptionError(
  const ACustom: Pointer;
  const AHandler: TELEvExceptionErrorProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventExceptionNotify

Registers OnExceptionNotify event handler.

procedure RegisterEventExceptionNotify(
  const AHandler: TELEvExceptionNotifyMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventExceptionNotify(
  const ACustom: Pointer;
  const AHandler: TELEvExceptionNotifyProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventHelpButtonClick

Registers OnHelpButtonClick event handler.

procedure RegisterEventHelpButtonClick(
  const AHandler: TELEvHelpButtonClickMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventHelpButtonClick(
  const ACustom: Pointer;
  const AHandler: TELEvHelpButtonClickProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventPasswordRequest

Registers OnPasswordRequest event handler.

procedure RegisterEventPasswordRequest(
  const AHandler: TELEvPasswordRequestMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventPasswordRequest(
  const ACustom: Pointer;
  const AHandler: TELEvPasswordRequestProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventRaise

Registers OnRaise event handler.

procedure RegisterEventRaise(
  const AHandler: TELEvRaiseMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventRaise(
  const ACustom: Pointer;
  const AHandler: TELEvRaiseProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventReproduceRequest

Registers OnReproduceRequest event handler.

procedure RegisterEventReproduceRequest(
  const AHandler: TELEvReproduceRequestMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventReproduceRequest(
  const ACustom: Pointer;
  const AHandler: TELEvReproduceRequestProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

RegisterEventZippedFilesRequest

Registers OnZippedFilesRequest event handler.

procedure RegisterEventZippedFilesRequest(
  const AHandler: TELEvZippedFilesRequestMeth;
  const AFirst: Boolean = False
); overload;
procedure RegisterEventZippedFilesRequest(
  const ACustom: Pointer;
  const AHandler: TELEvZippedFilesRequestProc;
  const AFirst: Boolean = False
); overload;

Parameters.

AHandler [in] — Event handler to register. Must be assigned.
AFirst [in, optional] — True - insert handler as first, False - insert handler as last (default).
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

This pointer is not used by EurekaLog, so you can use it for your own goals.

Can be nil if not used.

Remarks.

The corresponding handler type is described under EEvents in appendix B.

Registration and callback dispatch are described under EEvents in appendix C.

Tip. It's best to call this routine in object's constructor (for method event handlers) or unit's initialization section (for procedural event handlers).

UnRegisterEventAttachedFilesRequest

Unregisters previously registered OnAttachedFilesRequest event handler.

procedure UnRegisterEventAttachedFilesRequest(
  const AHandler: TELEvAttachedFilesRequestMeth
); overload;
procedure UnRegisterEventAttachedFilesRequest(
  const ACustom: Pointer;
  const AHandler: TELEvAttachedFilesRequestProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventBeginReportGen

Unregisters previously registered OnBeginReportGen event handler.

procedure UnRegisterEventBeginReportGen(
  const AHandler: TELEvReportGenMeth
); overload;
procedure UnRegisterEventBeginReportGen(
  const ACustom: Pointer;
  const AHandler: TELEvReportGenProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventCustomBugID

Unregisters previously registered OnCustomBugID event handler.

procedure UnRegisterEventCustomBugID(
  const AHandler: TELEvCustomBugIDMeth
); overload;
procedure UnRegisterEventCustomBugID(
  const ACustom: Pointer;
  const AHandler: TELEvCustomBugIDProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventCustomButtonClick

Unregisters previously registered OnCustomButtonClick event handler.

procedure UnRegisterEventCustomButtonClick(
  const AHandler: TELEvCustomButtonClickMeth
); overload;
procedure UnRegisterEventCustomButtonClick(
  const ACustom: Pointer;
  const AHandler: TELEvCustomButtonClickProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventCustomDataRequest

Unregisters previously registered OnCustomDataRequest event handler.

procedure UnRegisterEventCustomDataRequest(
  const AHandler: TELEvCustomDataRequestMeth
); overload;
procedure UnRegisterEventCustomDataRequest(
  const ACustom: Pointer;
  const AHandler: TELEvCustomDataRequestProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventCustomFileName

Unregisters previously registered OnCustomFileName event handler.

procedure UnRegisterEventCustomFileName(
  const AHandler: TELEvCustomFileNameMeth
); overload;
procedure UnRegisterEventCustomFileName(
  const ACustom: Pointer;
  const AHandler: TELEvCustomFileNameProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventCustomWebFieldsRequest

Unregisters previously registered OnCustomWebFieldRequest event handler.

procedure UnRegisterEventCustomWebFieldsRequest(
  const AHandler: TELEvCustomWebFieldsRequestMeth
); overload;
procedure UnRegisterEventCustomWebFieldsRequest(
  const ACustom: Pointer;
  const AHandler: TELEvCustomWebFieldsRequestProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventEndReportGen

Unregisters previously registered OnEndReportGen event handler.

procedure UnRegisterEventEndReportGen(
  const AHandler: TELEvReportGenMeth
); overload;
procedure UnRegisterEventEndReportGen(
  const ACustom: Pointer;
  const AHandler: TELEvReportGenProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventExceptionAction

Unregisters previously registered OnExceptionAction event handler.

procedure UnRegisterEventExceptionAction(
  const AHandler: TELEvExceptionActionMeth
); overload;
procedure UnRegisterEventExceptionAction(
  const ACustom: Pointer;
  const AHandler: TELEvExceptionActionProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventExceptionError

Unregisters previously registered OnExceptionError event handler.

procedure UnRegisterEventExceptionError(
  const AHandler: TELEvExceptionErrorMeth
); overload;
procedure UnRegisterEventExceptionError(
  const ACustom: Pointer;
  const AHandler: TELEvExceptionErrorProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventExceptionNotify

Unregisters previously registered OnExceptionNotify event handler.

procedure UnRegisterEventExceptionNotify(
  const AHandler: TELEvExceptionNotifyMeth
); overload;
procedure UnRegisterEventExceptionNotify(
  const ACustom: Pointer;
  const AHandler: TELEvExceptionNotifyProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventHelpButtonClick

Unregisters previously registered OnHelpButtonClick event handler.

procedure UnRegisterEventHelpButtonClick(
  const AHandler: TELEvHelpButtonClickMeth
); overload;
procedure UnRegisterEventHelpButtonClick(
  const ACustom: Pointer;
  const AHandler: TELEvHelpButtonClickProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventPasswordRequest

Unregisters previously registered OnPasswordRequest event handler.

procedure UnRegisterEventPasswordRequest(
  const AHandler: TELEvPasswordRequestMeth
); overload;
procedure UnRegisterEventPasswordRequest(
  const ACustom: Pointer;
  const AHandler: TELEvPasswordRequestProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventRaise

Unregisters previously registered OnRaise event handler.

procedure UnRegisterEventRaise(
  const AHandler: TELEvRaiseMeth
); overload;
procedure UnRegisterEventRaise(
  const ACustom: Pointer;
  const AHandler: TELEvRaiseProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventReproduceRequest

Unregisters previously registered OnReproduceRequest event handler.

procedure UnRegisterEventReproduceRequest(
  const AHandler: TELEvReproduceRequestMeth
); overload;
procedure UnRegisterEventReproduceRequest(
  const ACustom: Pointer;
  const AHandler: TELEvReproduceRequestProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

UnRegisterEventZippedFilesRequest

Unregisters previously registered OnZippedFilesRequest event handler.

procedure UnRegisterEventZippedFilesRequest(
  const AHandler: TELEvZippedFilesRequestMeth
); overload;
procedure UnRegisterEventZippedFilesRequest(
  const ACustom: Pointer;
  const AHandler: TELEvZippedFilesRequestProc
); overload;

Parameters.

AHandler [in] — Event handler to unregister.
ACustom [in, optional] — (for procedural event handlers only)

Custom pointer to be passed into handler.

Must be the same pointer which was passed to event registration routine.

Remarks.

If the specified event handler wasn't registered - does nothing. Otherwise handler is removed and it will be no longer be invoked.

Tip. It's best to call this routine in object's destructor (for method event handlers) or unit's finalization section (for procedural event handlers).

EExceptionManager

ExceptionManager

Gives access to EurekaLog's global exception manager.

function ExceptionManager: TExceptionManager;

Return value.

Instance of exception manager.

Remarks.

This is global access method for the exception manager. Use it to invoke routines of exception manager. Exception manager provides methods for working with exception information objects.

Exception manager instance is created and deleted automatically. You don't need to manually control life-time of this object. Do not create instances of TExceptionManager class.

See TExceptionManager (appendix D) for more information.

Note. This function is the same as TExceptionManager (appendix D).Instance (appendix D, TExceptionManager.Instance).

EFonts

GUIFont

Returns font for GUI applications.

function GUIFont: TFont;

Return value.

Variable-pitch (proportional space) system font.

Remarks.

This function returns font from SystemParametersInfo(SPI_GETNONCLIENTMETRICS).lfMessageFont.

MonoFont

Returns fixed-width font.

function MonoFont: TFont;

Return value.

Fixed-pitch (monospace) system font.

Remarks.

This function returns font from GetStockObject(ANSI_FIXED_FONT).

EFreeze

DoneCheckFreeze

Stops background freeze detection thread.

procedure DoneCheckFreeze;

Remarks.

This function will stop running background freeze detection thread launched by InitCheckFreeze (appendix A). This function will do nothing if no such thread is running.

Use this function to completely stop freeze detection.

Important. This function should be called from main thread.

Tip. Use PauseFreezeCheck (appendix A) to temporarily turn off freeze detection - without full stop/re-initialization.

FreezeNotifyStillAlive

Lets EurekaLog know that your main thread is still working.

procedure FreezeNotifyStillAlive;

Remarks.

This function will temporarily stop freeze detection without shutdowning background freeze detection thread.

EurekaLog tries to send messages to main thread from time to time. If your main thread is busy or hang - it will not process the messages, therefore EurekaLog will trigger "The thread appears to be frozen" error. Calling this function will skip a single check for main thread's responsivness, so EurekaLog will know that your thread is OK, even though it is not processing messages.

Warning. FreezeNotifyStillAlive should be called frequently. Imagine you have notified our freeze checks that your thread is alive. OK, sure: our checks will receive the message and skip a single check. Next, your thread will do something long. Now you are not sending "I am still alive" messages. Our checks will trigger immediately on the next closest check, because your thread is not responding for messages nor we did not receive "I'm still alive" notification.

Tip. For the above reason we recommend to use PauseFreezeCheck (appendix A) instead.

Prefer keeping the main thread responsive rather than repeatedly bypassing its responsiveness check. If the work cannot process messages safely, move it to a worker and define a timeout policy; chapter 14 explains the freeze-detection workflow. A liveness notification is not a substitute for monitoring whether the work is making progress.

Important. FreezeNotifyStillAlive can be called only by main thread.

InitCheckFreeze

Starts checking for freezes and hangs.

procedure InitCheckFreeze(
  const AThreadID: Cardinal = 0;
  const AMainWnd: HWND = 0;
  const AThreadHandle: THandle = 0;
  const ATimeout: Cardinal = 4;
  const AAntiFreezeMsg: String = '';
  const AAntiFreezeWCTMsg: String = ''
);

Parameters.

AThreadID [in, optional] — Thread ID to detect hangs inside this thread. Usually this is MainThreadID. Default is 0 - which means "use MainThreadID". This value can be ignored by some checks. For example, Wait Chain Traversal (WCT) check detects deadlocks in any EurekaLog-enabled threads - thus it does not need thread ID.
AMainWnd [in, optional] — A handle of main application form. Default is 0 - which means autodetection. This value can be ignored by some checks. For example, Wait Chain Traversal (WCT) check detects deadlocks in any EurekaLog-enabled threads - thus it does not need window handle.
AThreadHandle [in, optional] — A handle of thread identified by AThreadID.
ATimeout [in, optional] — A timeout in seconds. Default is 4. It is recommended to pass CurrentEurekaLogOptions.FreezeTimeout here.
AAntiFreezeMsg [in, optional] — A message for freeze exception. Default is 'The application seems to be frozen.'. It is recommended to pass CurrentEurekaLogOptions.CustomizedExpandedTexts[mtException_AntiFreeze] here.
AAntiFreezeWCTMsg [in, optional] — Alternative message for freeze exception. Default is 'A deadlock was detected in thread %d.'. It is recommended to pass CurrentEurekaLogOptions.CustomizedExpandedTexts[mtException_AntiFreezeWCT] here.

Remarks.

This function creates a background freeze detection thread. Thread will use current EurekaLog options.

The function will use FreezeThreadClass (appendix C) global variable to determinate which class should be used as background freeze detection thread.

Important. This function should be called from main thread.

Note. This function is called automatically during initialization of EurekaLog. You can call it manually to re-create/re-initialize freeze detection checks. For example, if you want to change timeout at run-time.

The function will not be called automatically if hang detection is disabled in EurekaLog project options.

Warning. This function do nothing if freeze detection thread is already running. Use DoneCheckFreeze (appendix A) to stop background freeze detection thread.

Note. This function will do nothing if your current settings blocks freeze detection. For example, if your settings indicate that freeze detection should not be active during debugging, and you currently run application under debugging - then this call will do nothing.

IsFreezeCheckEnabled

Indicate if freeze detection is currently active.

function IsFreezeCheckEnabled: Boolean;

Return value.

True if freeze detection is working, False otherwise (freeze detection is not enabled or paused).

Remarks.

This function indicate if freeze detection was paused by a call of PauseFreezeCheck (appendix A)/ResumeFreezeCheck (appendix A)eFreezeCheckEFreeze.PauseFreezeCheck) guarded with try/except block.

Note. IsFreezeCheckEnabled can be called from any thread.

IsFreezeCheckInstalled

Indicate if freeze detection was initialized.

function IsFreezeCheckInstalled: Boolean;

Return value.

True if freeze detection is installed, False otherwise.

Remarks.

This function indicate if freeze detection was installed by a call of PauseFreezeCheck (appendix A, InitCheckFreeze) function.

Note. We do not recommend to use this function, because freeze checks state may be changed by another thread right after call to this function. We recommend to use paired calls (DoneCheckFreeze (appendix A)/InitCheckFreeze (appendix A)heckFreezeEFreeze.DoneCheckFreeze) when you want to reinitialize freeze detection.

Note. IsFreezeCheckInstalled can be called from any thread.

PauseFreezeCheck

Temporarily disables freeze checks.

procedure PauseFreezeCheck;

Remarks.

This function will temporarily stop freeze detection without shutdowning background freeze detection thread.

Use this function to temporarily turn off freeze detection during executing long lasting blocking code.

Warning. Each call to PauseFreezeCheck must be paired with a call to ResumeFreezeCheck (appendix A).

Tip. PauseFreezeCheck can be called multiple times by the same thread.

Note. PauseFreezeCheck can be called from any thread.

RaiseFreezeException

Raises freeze/hang/deadlock exception for the specified thread.

procedure RaiseFreezeException(
  const AThreadID: Cardinal = 0;
  const AThreadHandle: THandle = 0;
  const AAntiFreezeMsg: String = ''
);

Parameters.

AThreadID [in, optional] — Thread ID to raise exception for. Default is 0 - which means "use MainThreadID".
AThreadHandle [in, optional] — A handle of thread identified by AThreadID.
AAntiFreezeMsg [in, optional] — A message for the exception. Default is 'The application seems to be frozen.'. It is recommended to pass CurrentEurekaLogOptions.CustomizedExpandedTexts[mtException_AntiFreeze] here.

Remarks.

Function will construct EFrozenApplication exception, build call stack for the thread identified by AThreadID (and AThreadHandle), and then invokes standard EurekaLog processing (i.e. create bug report, show error dialog, send report, etc.).

Note. This function is used by freeze detection thread to raise exception when freeze is detected.

Note. RaiseFreezeException can be called from any thread.

ResumeFreezeCheck

Enables freeze checks back.

procedure ResumeFreezeCheck;

Remarks.

This function will enable freeze detection previously disabled by a call to PauseFreezeCheck (appendix A).

Note. Freeze detection is not necessary enabled after a call to this function. For example, if PauseFreezeCheck was called twice - then freeze detection checks will be enabled only after second call to ResumeFreezeCheck.

Note. ResumeFreezeCheck can be called from any thread.

EHash

CRC16Hash

Calculates CRC-16 checksum.

function CRC16Hash(
  const AData: Pointer;
  const ADataSize: Cardinal
): TCRC16Hash; overload;
function CRC16Hash(
  const AData: RawByteString
): TCRC16Hash; overload;

Parameters.

AData [in] — A data to calculate checksum.
ADataSize [in] — Size of AData in bytes.

Return value.

CRC-16 checksum of the specified AData.

Remarks.

A cyclic redundancy check (CRC) is an error-detecting code commonly used in digital networks and storage devices to detect accidental changes to raw data. CRCs are based on the theory of cyclic error-correcting codes. CRCs are popular because they are simple to implement in binary hardware, easy to analyze mathematically, and particularly good at detecting common errors caused by noise in transmission channels.

Important. Unlike cryptographic hash functions (like MD5 or SHA1), CRC is an easily reversible function, which makes it unsuitable for use in digital signatures.

Numerous varieties of cyclic redundancy checks have been incorporated into technical standards. CRC16Hash function uses CRC-16-CCITT algorithm. Polynomial is $1021. Starting value is $FFFF.

Note. This routine is used to calculate BugID from string source.

CRC32Hash

Calculates CRC-32 checksum.

function CRC32Hash(
  const AData: Pointer;
  const ADataSize: Cardinal
): TCRC32Hash; overload;
function CRC32Hash(
  const AData: RawByteString
): TCRC32Hash; overload;

Parameters.

AData [in] — A data to calculate checksum.
ADataSize [in] — Size of AData in bytes.

Return value.

CRC-32 checksum of the specified AData.

Remarks.

Important. Unlike cryptographic hash functions (like MD5 or SHA1), CRC is an easily reversible function, which makes it unsuitable for use in digital signatures.

Numerous varieties of cyclic redundancy checks have been incorporated into technical standards. CRC32Hash function uses CRC-32-IEEE 802.3 algorithm. Polynomial is $EDB88320. Starting value is $FFFFFFFF. For example, this implementation matches PHP's implementation of CRC-32.

MD5Hash

Calculates MD5 hash.

function MD5Hash(
  const AData: Pointer;
  const ADataSize: Cardinal
): TMD5Hash; overload;
function MD5Hash(
  const AData: RawByteString
): TMD5Hash; overload;

Parameters.

AData [in] — A data to calculate hash.
ADataSize [in] — Size of AData in bytes.

Return value.

MD5 hash of the specified AData.

Remarks.

The MD5 message-digest algorithm is a widely used cryptographic hash function producing a 128-bit (16-byte) hash value, typically expressed in text format as a 32 digit hexadecimal number. MD5 has been utilized in a wide variety of cryptographic applications, and is also commonly used to verify data integrity.

Important. The security of the MD5 hash function is severely compromised. As of 2010, the CMU Software Engineering Institute considers MD5 "cryptographically broken and unsuitable for further use".

Note. This routine is used for generating encryption keys from password for TEA cipher (password-protected debug information).

MD5HMAC

Calculates HMAC-MD5.

function MD5HMAC(
  const AData: Pointer;
  const ADataSize: Cardinal;
  const APassword: Pointer;
  const APasswordSize: Cardinal
): TMD5Hash; overload;
function MD5HMAC(
  const AData, APassword: RawByteString
): TMD5Hash; overload;

Parameters.

AData [in] — A data to calculate value ("text", "message").
ADataSize [in] — Size of AData in bytes.
APassword [in] — A common shared secret ("password", "key").
APasswordSize [in] — Size of APassword in bytes.

Return value.

MD5 HMAC value of the specified AData and APassword.

Remarks.

A Keyed-Hash Message Authentication Code (HMAC) is a specific type of Message Authentication Code (MAC) involving a cryptographic hash function and a secret cryptographic key. It may be used to simultaneously verify both the data integrity and the authentication of a message, as with any MAC.

Any cryptographic hash function, such as MD5, SHA-1, or SHA-256, may be used in the calculation of an HMAC; the resulting MAC algorithm is termed HMAC-MD5, HMAC-SHA1, or HMAC-SHA256 accordingly. The cryptographic strength of the HMAC depends upon the cryptographic strength of the underlying hash function, the size of its hash output, and on the size and quality of the key.

SDBMHash

Calculates SDBM hash.

function SDBMHash(
  const AData: Pointer;
  const ADataSize: Cardinal
): TSDBMHash; overload;
function SDBMHash(
  const AData: RawByteString
): TSDBMHash; overload;

Parameters.

AData [in] — A data to calculate hash.
ADataSize [in] — Size of AData in bytes.

Return value.

SDBM hash of the specified AData.

Remarks.

SDBM hash is good general hashing function with good distribution. It was found to do well in scrambling bits, causing better distribution of the keys and fewer splits. This is one of the algorithms used in the Berkeley DB. EurekaLog uses SDBM as general-purpose hash for hashed lists.

EHash.SecureFree

procedure SecureFree(
  var AHash: TCRC16Hash
); overload;
procedure SecureFree(
  var AHash: TCRC32Hash
); overload;
procedure SecureFree(
  var AHash: TMD5Hash
); overload;
procedure SecureFree(
  var AHash: TSHA1Hash
); overload;
procedure SecureFree(
  var AHash: TSHA256Hash
); overload;
procedure SecureFree(
  var AHash: TSDBMHash
); overload;

SHA1Hash

Calculates SHA-1 hash.

function SHA1Hash(
  const AData: Pointer;
  const ADataSize: Cardinal
): TSHA1Hash; overload;
function SHA1Hash(
  const AData: RawByteString
): TSHA1Hash; overload;

Parameters.

AData [in] — A data to calculate hash.
ADataSize [in] — Size of AData in bytes.

Return value.

SHA-1 hash of the specified AData.

Remarks.

SHA-1 (Secure Hash Algorithm 1) is a cryptographic hash function. SHA-1 produces a 160-bit (20-byte) hash value known as a message digest. A SHA-1 hash value is typically rendered as a hexadecimal number, 40 digits long.

SHA-1 forms part of several widely used security applications and protocols, including TLS and SSL, PGP, SSH, S/MIME, and IPsec. SHA-1 hashing is also used in distributed revision control systems like Git, Mercurial, and Monotone to identify revisions, and to detect data corruption or tampering.

Important. SHA-1 is considered insecure against well-funded opponents. It is recommended to use SHA-2 or SHA-3 instead. Microsoft, Google and Mozilla have all announced that their respective browsers will stop accepting SHA-1 SSL certificates by 2017. Windows XP SP2 and earlier, and Android 2.2 and earlier, do not support SHA2 certificates.

SHA1HMAC

Calculates HMAC-SHA1.

function SHA1HMAC(
  const AData: Pointer;
  const ADataSize: Cardinal;
  const APassword: Pointer;
  const APasswordSize: Cardinal
): TSHA1Hash; overload;
function SHA1HMAC(
  const AData, APassword: RawByteString
): TSHA1Hash; overload;

Parameters.

AData [in] — A data to calculate value ("text", "message").
ADataSize [in] — Size of AData in bytes.
APassword [in] — A common shared secret ("password", "key").
APasswordSize [in] — Size of APassword in bytes.

Return value.

SHA1 HMAC value of the specified AData and APassword.

Remarks.

SHA256Hash

Calculates SHA-2/SHA-256 hash.

function SHA256Hash(
  const AData: Pointer;
  const ADataSize: Cardinal
): TSHA256Hash; overload;
function SHA256Hash(
  const AData: RawByteString
): TSHA256Hash; overload;

Parameters.

AData [in] — A data to calculate hash.
ADataSize [in] — Size of AData in bytes.

Return value.

SHA-256 hash of the specified AData.

Remarks.

SHA-2 (Secure Hash Algorithm 2) is a set of cryptographic hash functions. The SHA-2 family consists of six hash functions with digests (hash values) that are 224, 256, 384 or 512 bits: SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256. SHA-256 and SHA-512 are novel hash functions computed with 32-bit and 64-bit words, respectively. They use different shift amounts and additive constants, but their structures are otherwise virtually identical, differing only in the number of rounds.

The SHA-2 hash function is implemented in some widely used security applications and protocols, including TLS and SSL, PGP, SSH, S/MIME, and IPsec.

Important. SHA-2 is considered to be more secure than SHA-1.

SHA256HMAC

Calculates HMAC-SHA256.

function SHA256HMAC(
  const AData: Pointer;
  const ADataSize: Cardinal;
  const APassword: Pointer;
  const APasswordSize: Cardinal
): TSHA256Hash; overload;
function SHA256HMAC(
  const AData, APassword: RawByteString
): TSHA256Hash; overload;

Parameters.

AData [in] — A data to calculate value ("text", "message").
ADataSize [in] — Size of AData in bytes.
APassword [in] — A common shared secret ("password", "key").
APasswordSize [in] — Size of APassword in bytes.

Return value.

SHA256 HMAC value of the specified AData and APassword.

Remarks.

ELogBuilder

BuildBugReport

Builds bug report from exception information.

function BuildBugReport(
  const AExceptionInfo: TEurekaExceptionInfo;
  const ALogBuilderClass: TBaseLogBuilderClass = nil
): String;

Parameters.

AExceptionInfo [in] — Information about exception to build bug report.
ALogBuilderClass [in, optional] — Specifies the class to build bug report. Default is nil - which means using the class specified in the LogBuilderClass (appendix C) variable.

Return value.

Textual representation of bug report. Exact value depends on used log builder class. Default log builder class is TLogBuilder (appendix D). Builder class can be changed either via the ALogBuilderClass argument or via the LogBuilderClass (appendix C) global variable.

Remarks.

This function builds bug report for the specified exception information by using the default or the specified log builder class. This function can be used to re-create bug reports or create bug reports on demand.

Note. Please note that normally you don't have to call this function to get bug report for exceptions caught by EurekaLog as you can access exception's bug report at any time via TBaseDialog.BugReport property.

DisasmFunction

Disasms function.

function DisasmFunction(
  const Address: Pointer;
  const AExceptionAddress: Pointer = nil;
  const ASize: Integer = 0;
  const ALines: Integer = 0;
  const AOptions: TEurekaModuleOptions = nil;
  const AEncrypt: Boolean = False;
  const AContext: PContext = nil
): String;

Parameters.

Address [in] — A pointer to beginning of the function. Size of the function is determinated from AExceptionAddress, ASize, ALines or virtual region side if neither param is specified.
AExceptionAddress [in, optional] — A pointer to exception address inside function. If this argument is specified then the function will mark corresponding line in disassembly output as "< Exception Here". Function size will also be increased to include this address (if necessary).
ASize [in, optional] — Function's size in bytes. If this argument is set then the function will stop disassebmling only after specified number of bytes. Otherwise it will stop at first RET instruction or if ALines, AExceptionAddress or end of virtual region is reached.
ALines [in, optional] — Maximum number of lines (i.e. instructions) to disassemble after AExceptionAddress. Have no effect if AExceptionAddress is not specified.

Return value.

A textual representation of disassembled function including comments, marks, addresses, RAW bytes and decoded instructions.

Remarks.

This function is used to generate disasm view in bug reports. This function uses EDisAsm (appendix C) unit.

Note. When neither of AExceptionAddress, ASize and ALines arguments are specified: this function will disassemble machine code to the end of the allocated memory region or until RET instruction is encountered.

This function can be used to disassemble arbitrary block of machine code. Address does not have to point to beginning of some function. It can point to any CPU instruction. One can use FindLowAddress (appendix A) to obtain starting address from known AExceptionAddress value. Return value of FindLowAddress can be used as Address param.

Note. When this function is used with FindLowAddress (appendix A): it's recommended that FindLowAddress's ALines argument equals to DisasmFunction's ALines argument.

FindLowAddress

Tool function to obtain starting address to disassemble code block around known address.

function FindLowAddress(
  const AExceptionAddress: Pointer;
  const ALines: Integer
): Pointer;

Parameters.

AExceptionAddress [in] — A known code pointer.
ALines [in] — How many lines (instructions) should be before AExceptionAddress.

Return value.

A pointer to beginning of some CPU instruction. The returned instruction will be exactly ALines instructions before AExceptionAddress.

Remarks.

This is auxilary function for DisasmFunction (appendix A). It's used to find some starting address to begin disassebling code block. Usually you know exception address (i.e. some pointer to code), but don't know exact starting address of the function.

Note. When this function is used with DisasmFunction (appendix A): it's recommended that FindLowAddress's ALines argument equals to DisasmFunction's ALines argument.

ELogging

ELog

Creates a new log entry.

function ELog: IEurekaLogger;
overload;
procedure ELog(
  const AMsg: String
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: String
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: PChar
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: Char
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: Integer
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: Word
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: LongWord;
  const AAsHex: Boolean = False
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: UInt64;
  const AAsHex: Boolean = False
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: Int64
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: Extended;
  const ADigits: Integer = 2
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: Boolean
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: TPoint
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: TSmallPoint
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: TRect
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: TGUID
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: TObject
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: TExceptionPointers
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: TExceptionRecord
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: TContext
); overload;
procedure ELog(
  const AMsg: String;
  const AValue: TResponse
); overload;

Parameters.

AMsg [in] — A message to log.
AValue [in] — A value to log.
AAsHex [in] — Indicate is value should be logged in hex format (like '0045FDA0'). Default is false.
ADigits [in] — Indicate how many digits should be listed after decimal separator (e.g. 2 means '0.00'). Default is 2.

Return value.

Returns interface to manupulate new log entry.

Remarks.

This function adds a new log entry. Use this function to add entries to log. You may alter created log entry (for example, change category, color, etc.) via methods of returned IEurekaLogger (appendix D) interface.

There are several overloads: The overload without arguments will not log anything immediately - instead it returns IEurekaLogger logger to add customized entries. The overload with a single AMsg argument will log text "as is". The overload with AMsg and AValue will log text as "AMsg = AValue".

ELogAddCheckPoint

Logs a checkpoint.

procedure ELogAddCheckPoint;

Remarks.

Increments checkpoint counter and add new checkpoint entry to the log.

ELogAddResetSeparator

Resets identation and adds a separator to the log.

procedure ELogAddResetSeparator;

Remarks.

Same as ELogAddSeparator (appendix A), except it additionally resets all current identation back to zero.

Note. Calling this function inside any of logged function will broke a flow of called functions, because each logged call increases identation.

ELogAddSeparator

Adds a separator to the log.

procedure ELogAddSeparator;

Remarks.

This function adds a simple separation line to visually indicate separation between log blocks.

ELogAssigned

Checks if object is assigned and logs result.

function ELogAssigned(
  const AMsg: String;
  const AValue: TObject
): Boolean;

Parameters.

AMsg [in] — A name of the object.
AValue [in] — An object to log.

Return value.

Returns True is AValue is assigned, False otherwise.

Remarks.

This functions adds an object status to the log. A value of NIL will be logged as "not assigned", everything else will be logged as "assigned".

ELogAssignedPtr

Checks if pointer is assigned and logs result.

function ELogAssignedPtr(
  const AMsg: String;
  const AValue: Pointer
): Boolean;

Parameters.

AMsg [in] — A name of the pointer.
AValue [in] — A pointer to log.

Return value.

Returns True is AValue is assigned, False otherwise.

Remarks.

This functions adds a pointer status to the log. A value of NIL will be logged as "not assigned", everything else will be logged as "assigned".

ELogClear

Clears log file.

procedure ELogClear;

Remarks.

Erases all content of the log file. Use this function to clear log of old entries.

ELogCurrency

ELog for Currency type.

procedure ELogCurrency(
  const AMsg: String;
  const AValue: Currency
);

Parameters.

AMsg [in] — A message to log.
AValue [in] — A value to log.

Remarks.

Same as ELog (appendix A). The separate function is required to avoid issues with overloads resolving.

ELogDateTime

ELog for TDateTime type.

procedure ELogDateTime(
  const AMsg: String;
  const AValue: TDateTime
);

Parameters.

AMsg [in] — A message to log.
AValue [in] — A value to log.

Remarks.

Same as ELog (appendix A). The separate function is required to avoid issues with overloads resolving.

ELogEnter

Creates a new log entry about entering method/function/procedure.

function ELogEnter(
  const AFuncName: String = ''
): IEurekaLoggerParams; overload;
function ELogEnter(
  const ASelf: TObject;
  const AMethodName: String = ''
): IEurekaLoggerParams; overload;
function ELogEnter(
  const ASelf: TClass;
  const AMethodName: String = ''
): IEurekaLoggerParams; overload;

Parameters.

AFuncName

Name of the logged function or procedure.

ASelf

Object or class which method is called.

AMethodName

Name of the logged method. Must belong to ASelf.

Return value.

Returns created log entry.

Remarks.

Use this function to add entries to log when entering sub-routine. The call to this function must be the first call in the sub-routine.

EurekaLog will log exit from sub-routine automatically. However, if you want to manually log early exit or specify a result - use Ret (appendix D, IEurekaLoggerParams.Ret) method.

You may alter created log entry (for example, change category, color, etc.) via methods of IEurekaLogger (appendix D) interface.

Important. You have to call either D (appendix D, IEurekaLoggerParams.D) or C (appendix D, IEurekaLoggerParams.C) method on the returned IEurekaLoggerParams (appendix D) interface. Otherwise nested log entries may have wrong identation in the resulting log file.

ELogError

Adds an error to log file.

procedure ELogError(
  const AMsg: String
);

Parameters.

AMsg [in] — An error text.

Remarks.

Same as ELog (appendix A), but adds an error instead of a normal text message.

ELogException

ELog for Exception type.

procedure ELogException(
  const E: TObject;
  const AMsg: String = ''
);

Parameters.

E [in] — An exception to log.
AMsg [in, optional] — A name of exception.

Remarks.

Same as ELog (appendix A). The separate function is required to avoid issues with overloads resolving.

ELogFlush

Flushes log to disk.

procedure ELogFlush(
  const ACloseAllFunctions: Boolean = False
);

Remarks.

This function will write all cached log entries to a file on the disk. Call this function before terminating application unexpectedly. This function will do nothing if log caching is not enabled;

ELogIf

Adds a new log entry only if condition is true.

procedure ELogIf(
  const AExpression: Boolean;
  const AMsg: String
); overload;
procedure ELogIf(
  const AExpression: Boolean;
  const AMsg: String;
  const AValue: String
); overload;
procedure ELogIf(
  const AExpression: Boolean;
  const AMsg: String;
  const AValue: Integer
); overload;
procedure ELogIf(
  const AExpression: Boolean;
  const AMsg: String;
  const AValue: TObject
); overload;

Parameters.

AExpression [in] — An expression to check.
AMsg [in] — A message to log.
AValue [in] — A value to log.

Remarks.

AExpression is False: the function does nothing. AExpression is True: the function acts as ELog (appendix A).

ELogIfDateTime

ELogIf for TDateTime type.

procedure ELogIfDateTime(
  const AExpression: Boolean;
  const AMsg: String;
  const AValue: TDateTime
);

Parameters.

AExpression [in] — An expression to check.
AMsg [in] — A message to log.
AValue [in] — A value to log.

Remarks.

Same as ELogIf (appendix A). The separate function is required to avoid issues with overloads resolving.

ELogInterval

Add a new time measurement to log file.

procedure ELogInterval(
  const AMsg: String;
  const AStart: Int64
);

Parameters.

AMsg [in] — A message to log.
AStart [in] — A return value of GetPerformanceCount (appendix A) function.

Remarks.

This function will act as ELog (appendix A) where AValue is replaced with time interval, starting at AStart and ending at current time.

ELogMemoryAsHex

Adds a memory dump to log.

procedure ELogMemoryAsHex(
  const AMsg: String;
  const ABuffer: Pointer;
  ASize: Integer
);

Parameters.

AMsg [in] — A message to log.
ABuffer [in] — A value to log.
ASize [in] — A size of ABuffer in bytes.

Remarks.

Dumps memory from ABuffer to log file.

ELogNote

Adds a note to log file.

procedure ELogNote(
  const AMsg: String
);

Parameters.

AMsg [in] — A note text.

Remarks.

Same as ELog (appendix A), but adds a note instead of a normal text message.

ELogOpen

Creates new log file.

procedure ELogOpen(
  const AFileName: String = '';
  const ABufferSize: Cardinal = 1024*1024
);

Parameters.

AFileName [in, opt] — An absolute full file name for the new log file. We recommend to use .csl file extension.
ABufferSize [in, opt] — Size of the buffer in bytes. Default is 1 Mb. Set to 0 to disable buffering.

Remarks.

This function creates new log file. Add subsequent calls to ELog (appendix A)-like functions will write to AFileName.

A call to this function should be the first call in your application (e.g. before you call any of other logging routines).

If non-zero ABufferSize is specified: logging will write into a buffer. Buffer will be flushed to disk from time to time, or you can flush the buffer to disk at any time by calling the ELogFlush (appendix A) function.

If ABufferSize is 0: buffering will be disabled, logging will write directly to the file on disk. Application's performance may be sighnificantly reduced.

Note. If you call any of ELog (appendix A) function before calling this function - log entries will be added to internal log. Internal log will be copied to real log file once you call ELogOpen.

If you do not want old entries created earlier - call ELogClear (appendix A) before calling ELogOpen.

Note. A call to this function may be ignored, if application is already streaming into log file, which is owned by other module (exe/DLL) in application.

ELogPointer

ELog for Pointer type.

procedure ELogPointer(
  const AMsg: String;
  const AValue: Pointer
);

Parameters.

AMsg [in] — A message to log.
AValue [in] — A value to log.

Remarks.

Same as ELog (appendix A). The separate function is required to avoid issues with overloads resolving.

ELogReminder

Adds a reminder to log file.

procedure ELogReminder(
  const AMsg: String
);

Parameters.

AMsg [in] — A reminder text.

Remarks.

Same as ELog (appendix A), but adds a reminder instead of a normal text message.

ELogResetCheckPoint

Resets checkpoint counter.

procedure ELogResetCheckPoint;

Remarks.

Resets checkpoint counter, so the following calls to ELogAddCheckPoint (appendix A) start over.

ELogWarning

Adds a warning to log file.

procedure ELogWarning(
  const AMsg: String
);

Parameters.

AMsg [in] — A warning text.

Remarks.

Same as ELog (appendix A), but adds a warning instead of a normal text message.

ELogWindowHandle

ELog for window handle.

procedure ELogWindowHandle(
  const AMsg: String;
  const AValue: HWND
);

Parameters.

AMsg [in] — A message to log.
AValue [in] — A value to log.

Remarks.

Same as ELog (appendix A). The separate function is required to avoid issues with overloads resolving.

ELogWinError

ELog for system error codes.

procedure ELogWinError(
  const AMsg: String;
  const ALastError: TSysErrorCode = TSysErrorCode(0
));

Parameters.

AMsg [in] — A message to log.
AValue [in] — A value to log.

Remarks.

Same as ELog (appendix A). The separate function is required to avoid issues with overloads resolving.

GetPerformanceCount

Returns timestamp.

function GetPerformanceCount: Int64;

Return value.

A timestamp to be passed to ELogInterval (appendix A) function.

Remarks.

This function returns current date-time as timestamp. The return value of this function could be passed to ELogInterval (appendix A) function.

ELowLevel

__initialize_security_cookie

Initializes a stack guard cookie.

procedure __initialize_security_cookie(
  out ASecurityCookie: Pointer
);

Parameters.

ASecurityCookie [out] — Returns transparent "magic" value. This must be a local variable in the function. The local variable must be listed first.

Remarks.

This function initializes ASecurityCookie argument with some "magic" value, which is supposed to stay unchanged during execution of current routine. If stack corruption occurs (e.g. buffer overflow damages the stack) - then this value will be changed. This change can be detected later by the __security_check_cookie (appendix A) function.

This function also protects against overwrites of return address. In other words, if function's return address will be changed/corrupted/overwritten between calls to the __security_check_cookie/__security_check_cookie functions - an error will be triggered.

__security_check_cookie

Checks the stack for corruption caused by a buffer overflow.

procedure __security_check_cookie(
  var ASecurityCookie: Pointer;
  const ALocation: PChar = nil
);

Parameters.

ASecurityCookie [in] — The variable initialized by the __initialize_security_cookie (appendix A) function.
ALocation [in, optional] — An optional human-readable description of the caller. For example, a function's name. This description will be used only if stack corruption is detected and an error is thrown.

Remarks.

This function ensures that there was no stack corruption inside current routine. If ASecurityCookie was changed - then the stack was corrupted. The function will trigger EurekaLog crash report in this case. If EurekaLog is disabled - then run-time error is triggerred. If error is unhandled - the process is terminated with $C0000409 (STATUS_STACK_BUFFER_OVERRUN) exit code.

Tip. EurekaLog's crash report for stack buffer overflow may not display full call stack - that is because stack corruption will damage stack frames and return addresses, so damaged part of the stack will be skipped. There may be no call stack at all in some (rare) cases. However, there always will be "error" entry on the stack - e.g. the one corresponding to the routine in which the corruption was detected.

Note. If current routine calls other routines - these routines may also corrupt the stack. If corruption happens inside a sub-routine - then it may happen that the execution flow will be unable to return to the current routine. This means that __security_check_cookie (in the current routine) will not be executed, thus it will be unable to detect stack's corruption. For this reason one should place __initialize_security_cookie/__security_check_cookie in all available routines.

_resetstkoflw

Recovers from stack overflow.

function _resetstkoflw: Boolean;

Return value.

True if the function succeeds, False if it fails.

Remarks.

The _resetstkoflw function recovers from a stack overflow condition, allowing a program to continue instead of failing with a fatal exception error. If the _resetstkoflw function isn't called, there are no guard pages after the previous exception. The next time that there's a stack overflow, there are no exceptions at all and the process terminates without warning.

If a thread in an application causes an EStackOverflow exception, the thread has left its stack in a damaged state. This is in contrast to other exceptions such as EAccessViolation or EDivByZero, where the stack isn't damaged. The stack is set to an arbitrarily small value when the program is first loaded. The stack then grows on demand to meet the needs of the thread. This is implemented by placing a page with PAGE_GUARD access at the end of the current stack. For more information, see Creating Guard Pages.

When the code causes the stack pointer to point to an address on this page, an exception occurs and the system does the following three things: Removes the PAGE_GUARD protection on the guard page so that the thread can read and write data to the memory. Allocates a new guard page that is located one page below the last one. Reruns the instruction that raised the exception. In this way, the system can increase the size of the stack for the thread automatically. Each thread in a process has a maximum stack size. The stack size is set at compile time by the "Project" -≤ "Options" -≤ "Linking" -≤ "Maximum Stack Size", or by the {$MAXSTACKSIZE number} statement in the source code file of the project.

When this maximum stack size is exceeded, the system does the following three things: Removes the PAGE_GUARD protection on the guard page, as previously described. Tries to allocate a new guard page below the last one. However, this fails because the maximum stack size has been exceeded. Raises an exception so that the thread can handle it in the exception block. At that point, the stack no longer has a guard page. The next time that the program grows the stack all the way to the end, where there should be a guard page, the program writes beyond the end of the stack and causes an access violation.

Call _resetstkoflw to restore the guard page whenever recovery is done after a stack overflow exception. This function can be called from inside the main body of an except block or outside except block. However, there are some restrictions on when it should be used. _resetstkoflw shouldn't be called from: An except block. A finally block. Any type of exception hook or filter function. At these points, the stack isn't yet sufficiently unwound.

It isn't safe to call _resetstkoflw in an except block. In this case, the stack space isn't freed and the stack pointer isn't reset until outside the except block. This function shouldn't be called until the stack space is freed and the stack pointer has been reset. Therefore, it should be called only after exiting the except block. As little stack space as possible should be used in the except block.

There are situations where _resetstkoflw can fail even if used in a correct location. If, even after unwinding the stack, there's still not enough stack space left to execute _resetstkoflw without writing into the last page of the stack, _resetstkoflw fails to reset the last page of the stack as the guard page and returns False, indicating failure. Safe usage of this function should include checking the return value instead of assuming that the stack is safe to use.

AllocatePageAlign

Allocates memory with alignment on current memory's page size boundary.

function AllocatePageAlign(
  const ASize: Cardinal;
  out AHolder: Pointer
): Pointer;

Parameters.

ASize [in] — Size of memory block to allocate in bytes.
AHolder [out] — a pointer to backbone storage. This is the pointer which must be passed to FreeMem to release this memory block.

Return value.

A pointer to memory block of ASize bytes aligned at page boundary.

Exceptions.

System.SysUtils.EOutOfMemory

Not enought memory to perform request.

Remarks.

This function is the same as AllocMem except it also aligns result on memory's page size boundary.

That's it, if memory's page size is 4 Kb - then result is always aligned on 4 Kb (i.e. have 12 zeros at low part of pointer when represented in binary).

Thus, this function have an overhead of maximum 2 size of memory's page. For example, if memory's page size is 4 Kb - then this function will allocate 12 Kb for ASize less than 4 Kb, 16 Kb - for ASize less than 8 Kb and so on.

You shouldn't pass returned pointer to any memory releasing routines (like FreeMem). Instead, call FreeMem for AHolder.

Note. Page size may be different on different platforms. Do not make any assumptions about it.

You can get current page size by calling PageSize (appendix A).

AllocationGranularity

Returns current memory's allocation granularity.

function AllocationGranularity: Cardinal;
inline;

Return value.

Allocation granularity in bytes. Default is 64 Kb (65'536).

Remarks.

The granularity for the starting address at which virtual memory can be allocated. For more information, see the VirtualAlloc function.

This is a dwAllocationGranularity field from the GetSystemInfo function.

CanCallMemWipeStack

Indicates if the MemWipeStack function should be called.

function CanCallMemWipeStack(
  const ASkipEurekaLogActivationCheck: Boolean = False
): Boolean;

Return value.

True if the MemWipeStack function should be called, <\ False otherwise.

Remarks.

Function returns True if the following conditions are met:

The "Wipe Stack" option is enabled;
Current thread has EurekaLog enabled;
Current thread is not about to exhaust the stack space;
Current thread is not in a "weird" state (for example: invalid StackLimit value);

CheckELMagicCode

Checks double word for being one of the known EurekaLog's "magic codes" (signatures).

function CheckELMagicCode(
  const ACode: DWord
): Boolean;

Parameters.

ACode [in] — A value to check.

Return value.

True if ACode is MagicNumber7, MagicNumber6 or MagicNumber5 constants. False - otherwise.

Remarks.

"Magic code" is just a 4 bytes signature, which is used to indicate EurekaLog's data in executable.

Each version of EurekaLog uses its own magic code.

Magic code is also used to determinate correctness of password for encrypted debug information.

This routine is primary used in EDebugEL (appendix C) unit, but also used in some other places where you need to check if this is valid EurekaLog's data or not.

ConvertAddress

Convert address to code to real address of code.

function ConvertAddress(
  const AAddr: Pointer
): Pointer;

Parameters.

AAddr [in] — Address to code. Usually points to routine.

Return value.

Adjusted address to code. See remarks. Can be the same value as AAddr.

Remarks.

This routine is used for hooks.

If you have an address to routine - it can points to code itself or to JMP instruction to code. Typical example is import table.

This function takes address and checks if there is a JMP instruction at this address.

If there is no JMP - then function returns value unchanged.
If there is JMP opcode - then function returns target of that JMP.

Function doesn't raise access violation in case of unavailable memory.

ConvertRetAddr

Convert return address to instruction pointer.

function ConvertRetAddr(
  const AReturnAddr: Pointer
): Pointer;

Parameters.

AReturnAddr [in] — Return address. It is usually obtained by analyzing call stack or via ReturnAddress.

Return value.

Pointer to CALL opcode. This value is always less than AReturnAddr.

Remarks.

This routine is used for hooks.

If you have a return address and want to show/indicate caller - then you can use this function to convert return address to instruction pointer in caller's source. This function is needed because return address points to the next line in source file.

Function doesn't raise access violation in case of unavailable memory.

Warning. Function does NOT check if the AReturnAddr is a valid return address. Do not pass arbitrary pointers, pass return addresses only.

Note. This is a wrapper for EDisAsm.GetAddrByRetAddr function.

CurrentInstance

Returns current instance.

function CurrentInstance: HINST;

Return value.

Current instance. See remarks.

Remarks.

This function returns current instance (i.e. module handle).

It's used as replacement for HInstance variable.

"Current instance" means instance with EurekaLog which corresponds to caller of this function. Usually this is HInstance of the module, since often caller and EurekaLog's resides in the same executable module.

However, it can be a different value in case of packaged application (EurekaLog's code may reside in package which is not the same module as caller).

Important. Do not use HInstance when working with EurekaLog. Use CurrentInstance instead.

DebugBreak

Causes a breakpoint exception to occur in the current process.

procedure DebugBreak;

Remarks.

This routine is used to break into debugger. This allows the calling thread to signal the debugger - for example to handle the exception.

If you are running your project under debugger and the debugger stops inside this function - this means that EurekaLog is notifying debugger about a problem (possibly about a fatal one). You can the check call stack to understand what this problem is, and possibly investigate the issue before default handling/processing will take place. You can also continue the execution to let EurekaLog handle the problem. Naturally, this "break into debugger" behaviour does not happen outside of the debugger.

Warning. This function raises exception! If there is no debugger attached - then the exception will go into your exception handlers, which can cause unwanted error dialogs or even termination of the process. Always check if debugger is present before calling this function.

EnsureThreadStack

Sets the minimum size of the stack associated with the calling thread or fiber that will be available during any stack overflow exceptions. This is useful for handling stack overflow exceptions; the application can safely use the specified number of bytes during exception handling.

function EnsureThreadStack: Boolean;

Return value.

If the function succeeds, the return value is True. If the function fails, the return value is False. To get extended error information, call GetLastError.

Remarks.

You can specify the reserved stack space by setting the _resetstkoflw (appendix C, _ThreadStackGuarantee)tstkoflw functionELowLevel._ThreadStackGuarantee.

To set the stack guarantee for a fiber, you must first call the SwitchToFiber function to execute the fiber. After you set the guarantee for this fiber, it is used by the fiber no matter which thread executes the fiber.

GetReadableSize

Verifies that the caller has specified access to the specified range of memory.

function GetReadableSize(
  const AAddress: Pointer;
  const ASize: Cardinal;
  const AAttributes: Cardinal = 0
): Cardinal;

Parameters.

AAddress [in] — A pointer to the first byte of the memory block.
ASize [in] — The size of the memory block, in bytes. If this parameter is zero, the return value is zero.
AAttributes [in, optional] — Set of PAGE_XYZ flags, which indicate access to check.

Optional. Default is to check for any read access (0 means PAGE_READONLY or PAGE_READWRITE or PAGE_EXECUTE_READ or PAGE_EXECUTE_READWRITE or PAGE_WRITECOPY or PAGE_EXECUTE_WRITECOPY).

Return value.

If the caller has the specified read access to all bytes in the specified memory range, the return value is ASize.

If the caller does not have the specified read access to all bytes in the specified memory range, the return value is less than ASize. It may be 0.

Remarks.

This function is typically used when working with pointers, where you cannot determine the memory management behavior.

Threads in a process are expected to cooperate in such a way that one will not free memory that the other needs. Use of this function does not negate the need to do this. If this is not done, the application may fail in an unpredictable manner.

Dereferencing potentially invalid pointers can disable stack expansion in other threads. A thread exhausting its stack, when stack expansion has been disabled, results in the immediate termination of the parent process, with no pop-up error window or diagnostic information.

If the calling process has read access to some, but not all, of the bytes in the specified memory range, the return value is in range 0..ASize - 1.

In a preemptive multitasking environment, it is possible for some other thread to change the process's access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

Note. By passing appropriate flags, this function can be used to verify write access to memory.

Note. This function is based on VirtualQuery function. Thus, it doesn't have some of the bad effects of IsBadReadPtr function.

However, other caveats still appy.

Warning. Use this routine with caution. It's heuristic. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory - because other thread may release this memory between checking and actual access.

IfElse

A replacement for ternary if operator.

function IfElse(
  const AOK: Boolean;
  const AStr1: String;
  const AStr2: String = ''
): String;

Parameters.

AOK [in] — Condition.
AStr1 [in] — Result for True.
AStr2 [in, optional] — Result for False.

Return value.

Returns AStr1 if AOK is True.

Returns AStr2 if AOK is False.

Remarks.

Warning. Both arguments (AStr1 and AStr2) are calculated. This is different from the real ternary if operator like AOK ? AStr1 : AStr2 in C++.

IntoIDE

Detects if we're running inside IDE.

function IntoIDE(
  const AVirtualize: Boolean = True
): Boolean;

Return value.

True if current process is development IDE (Delphi, C++ Builder and so on), False - otherwise.

Remarks.

This function is used to disable EurekaLog functionality in IDE expert.

The check is based on .exe file name.

IsCBuilder

Indicates if current project was compiled by C++ Builder.

function IsCBuilder: Boolean;

Return value.

True if project was compiled by C++ Builder; False otherwise (e.g. compiled by Delphi).

Remarks.

This function is used to determinate if you are running C++ Builder project or Delphi project. This is useful if you need to take C++ Builder specifics into account.

Note. Note that this is not the same as compiler for units. For example, the unit can be compiled by Delphi, but be included/used in C++ Builder project. This function will return True for such case, while any compile-time check inside the unit will return False.

IsCompiledWithPackages

Checks if this module is compiled with packages.

function IsCompiledWithPackages: Boolean;

Return value.

True for packaged module, False - otherwise.

Remarks.

This function is used to switch EurekaLog's behaviour between packaged and normal mode.

IsDebugged

Determines whether the calling process is being debugged by a user-mode debugger.

function IsDebugged: Boolean;

Return value.

If the current process is running in the context of a debugger, the return value is True.

If the current process is not running in the context of a debugger, the return value is False.

Remarks.

This function allows an application to determine whether or not it is being debugged, so that it can modify its behavior.

For example, an application could provide additional information using the OutputDebugString function if it is being debugged or execute a int 3 breakpoint at critical errors (see also DebugBreak (appendix A) function).

IsDynamicRTL

Indicates if current project was compiled with dynamic RTL DLL.

function IsDynamicRTL: Boolean;

Return value.

True if project was compiled by C++ Builder with dynamic RTL DLL; False otherwise (e.g. compiled by Delphi or without dynamic RTL).

Remarks.

This function is used to determinate if you was compiled with dynamicr RTL DLL or not.

Note. This value is always False for Delphi projects. Only C++ Builder projects can be compiled with RTL DLL.

IsLLVM

Indicates if current project is compiled by "new" C++ Builder compiler (e.g. LLVM).

function IsLLVM: Boolean;

Return value.

True if project was compiled by LLVM Builder; False otherwise (e.g. compiled by Delphi or classic C++ Builder).

Remarks.

This function is used to determinate if you are running under LLVM. This is useful if you need to take LLVM specifics into account.

IsReadableFile

Verifies that the caller has read access to the specified file.

function IsReadableFile(
  const AFileName: String
): Boolean;

Parameters.

AFileName [in] — A full absolute file name.

Return value.

If the current process have a GENERIC_READ access to AFileName file, the return value is True.

If the current process doesn't have a GENERIC_READ access to AFileName file, the return value is False.

Remarks.

This function tries to open specified file with GENERIC_READ access. If this operation succeeds - the function returns True, otherwise - False.

Thus, function returns False, if file doesn't exist at all.

IsRTLCompiledWithStackFrames

Determines whether the RTL was compiled with Stack Frames option enabled.

function IsRTLCompiledWithStackFrames: Boolean;

Return value.

If RTL was compiled with Stack Frames option, the return value is True.

If RTL was compiled without Stack Frames option, the return value is False.

Remarks.

This is a simple wrapper for IsStackFramesProc (appendix A) with arbitrary simple function from RTL.

Warning. This is heuristic function.

IsStackFramesProc

Determines whether the specified function has a stack frame.

function IsStackFramesProc(
  const AAddr: Pointer
): Boolean;

Parameters.

AAddr [in] — A pointer to function.

Return value.

If specified function has a stack frame, the return value is True.

If specified function doesn't have a stack frame, the return value is False.

Remarks.

Note. Make sure that you pass a pointer to a real function. Not to some arbitrary code or function's stub.

Use to get pointer to real code from stub.

Warning. This is heuristic function.

IsValidBlockAddr

Verifies that the caller has read access to the specified range of memory.

function IsValidBlockAddr(
  const Address: Pointer;
  const Size: Cardinal
): Boolean;

Parameters.

Address [in] — A pointer to the first byte of the memory block.
Size [in] — The size of the memory block, in bytes. If this parameter is zero, the return value is True.

Return value.

If the caller has any read access to all bytes in the specified memory range, the return value is True.

If the caller does not have a read access to all bytes in the specified memory range, the return value is False.

Remarks.

This is the simple wrapper for GetReadableSize (appendix A) function.

See GetReadableSize (appendix A) for more information.

IsValidClass

Verifies that the specified pointer is a valid class.

function IsValidClass(
  ClassType: TClass
): Boolean;

Parameters.

ClassType [in] — A class pointer.

Return value.

If ClassType is a real class, the return value is True.

If ClassType is not a class, the return value is False.

Remarks.

This function performs many complex checks on passed value to determinate if this is a valid class reference.

Warning. Use this routine with caution. It's heuristic.

IsValidCodeAddr

Verifies that the caller has execute access to the specified range of memory.

function IsValidCodeAddr(
  const AAddress: Pointer;
  const ASize: Cardinal
): Boolean;

Parameters.

AAddress [in] — A pointer to the first byte of the memory block.
ASize [in] — The size of the memory block, in bytes. If this parameter is zero, the return value is True.

Return value.

If the caller has any execute access to all bytes in the specified memory range, the return value is True.

If the caller does not have a execute access to all bytes in the specified memory range, the return value is False.

Remarks.

This is the simple wrapper for GetReadableSize (appendix A) function.

See GetReadableSize (appendix A) for more information.

Warning. Use this routine with caution. It's heuristic. Even when the function indicates that the process has execute access to the specified memory, you should use structured exception handling when attempting to access the memory - because other thread may release this memory between checking and actual access.

IsValidHandle

Verifies that this is a valid kernel handle.

function IsValidHandle(
  const AHandle: THandle
): Boolean;

Parameters.

AHandle [in] — A handle to check.

Return value.

If the AHandle is a valid kernel handle, the return value is True.

If the AHandle is not a valid kernel handle, the return value is False.

Remarks.

This function uses GetHandleInformation and DuplicateHandle to verify handle.

Warning. Use this routine with caution. It's heuristic.

Even when the function indicates that the handle is valid, a handle may be immediately closed by another thread.

IsValidObject

Verifies that the specified pointer is a valid object.

function IsValidObject(
  const AObj: TObject;
  const AStrict: Boolean
): Boolean;

Parameters.

AObj [in] — An object pointer.
AStrict [in, optional] — Default is True. Indicates if object must be compatible with current language (default). Or if it can be just a valid object from a different IDE/compiler version. For example, if AStrict is True - then the function returns False when called on a valid Delphi 2007 object while being called from Delphi 2009.

Return value.

If AObj is a real object, the return value is True.

If AObj is not an object, the return value is False.

Remarks.

This function performs many complex checks on passed value to determinate if this is a valid object reference.

Warning. Use this routine with caution. It's heuristic.

IsVirtualized

Checks if application was instrumented/virtualized.

function IsVirtualized: Boolean;

Return value.

If the current process is instrumented or virtualized (for example, running by AQTime), the return value is True.

If the current process is running as usual, the return value is False.

Remarks.

This is informational routine.

Warning. EurekaLog may not operate with full features when application is instrumented. That is because code instrumentation introduces dynamically generated code, as well as changes callers of the code - which makes various things impossible to hook.

IsWritableFile

Verifies that the caller has write access to the specified file.

function IsWritableFile(
  const AFileName: String
): Boolean;

Parameters.

AFileName [in] — A full absolute file name.

Return value.

If the current process have a GENERIC_WRITE access to AFileName file, the return value is True.

If the current process doesn't have a GENERIC_WRITE access to AFileName file, the return value is False.

Remarks.

This function tries to open specified file with GENERIC_WRITE access. If this operation succeeds - the function returns True, otherwise - False.

If file doesn't exists, function tries to create it. However, file is deleted after the check.

IsWritableFolder

Verifies that the caller has write access to the specified folder.

function IsWritableFolder(
  const AFolderName: String;
  const ACanCreateFolder: Boolean = True
): Boolean;

Parameters.

AFolderName [in] — A full absolute folder name.
ACanCreateFolder [in, optional] — Indicates if it is OK to create the folder specified in the AFolderName parameter. Default is True.

Return value.

If the current process have a GENERIC_WRITE access to AFolderName folder, the return value is True.

If the current process doesn't have a GENERIC_WRITE access to AFolderName file (or if the specified folder does not exist and the ACanCreateFolder parameter is False) the return value is False.

Remarks.

This function tries to create a test file in the specified folder. If this operation succeeds - the function returns True, otherwise - False.

MainThreadTopOfStack

Returns top of the stack for the main thread.

function MainThreadTopOfStack: Pointer;

Return value.

Pointer to top of the main thread's stack.

Remarks.

Main thread for DLL is a thread which loaded DLL.

MemWipeStack

Clears unused stack of the current thread.

procedure MemWipeStack;

Remarks.

This function wipes (clears) the content of the unused part of the stack. The wipe is performed with debug pattern ($CCCCCCCC).

This means that when execution goes further - the uninitialized local variables will have non-0, non-nil, unaccessible value. This can help catch use of uninitialized variables.

Additionally, clearing stack can help to reduce number of false-positive entries with RAW stack tracing.

We recommend to call this function from time to time. For example, when application is idle, or about to do some heavy work.

Warning. It is highly recommended to call the function (appendix A, CanCallMemWipeStack) first to determinate if the MemWipeStack function should be called.

Caution!

This function clears the entire unused stack to the end. E.g. if you use 1 Mb stack (default) - then 1 Mb of memory will be written (except the busy part of the stack). Therefore, do not call this function too frequently, otherwise your performance will suffer.

Use with caution when stack size is greatly increased.

PageSize

Returns current memory's page size.

function PageSize: Cardinal;
inline;

Return value.

Page size in bytes. Default is 4Kb (4096).

Remarks.

The page size and the granularity of page protection and commitment. This is the page size used by the VirtualAlloc function.

This is a dwPageSize field from the GetSystemInfo function.

PrimaryInstance

The same as MainInstance. See remarks for more info.

function PrimaryInstance: HINST;

Return value.

The instance handle for the main executable.

Remarks.

This is a replacement for MainInstance. In some rare cases MainInstance may be 0 instead of actual value. PrimaryInstance can be used as workaround for such cases.

Do not use MainInstance when working with EurekaLog. Use PrimaryInstance instead.

ReserveLowerMemory

Reserves lower 2 Gb (32-bit app) or 4 Gb (64-bit app) of address space.

procedure ReserveLowerMemory;

Remarks.

This function reserves lower part of address space. This would cause memory allocations to get memory from higher addresses, thus helping you to catch bugs in your code (like Integer-Pointer conversion, using signed Integers, etc).

This function does not allocate any memory. Address space is simply reserved. Therefore, your application will not allocate any additional memory when using this function. However, the available address space will be decreased, so your code may run out of memory.

We recommend to always call this function in all 64-bit applications, as it has plenty free address space.

Warning. Do not call this function in a 32-bit app without marking your app as "large address awared". Otherwise your application will have no memory to run!

Caution!

Please note that your 32-bit large address awared application will have just 1 Gb (when run on 32-bit system) or 2 Gb (when run on 64-bit system) of memory after calling this function.

For this reason - we recommend to call this function for 32-bit apps only when debugging, not in production.

SafeExec

Executes routine with exception handling. Any exception is handled as fatal exception.

procedure SafeExec(
  const AProc: ETypes.TProcedure;
  const ASection: String
);

Parameters.

AProc [in] — A procedure to execute.

Must not throw exceptions as normal operation. Any exception inside this procedure is considered as fatal.

ASection [in] — Fully qualified name of procedure. Must have form 'UnitName.ProcName'.

ProcName must be either 'Init' or 'Done'.

Remarks.

This routine is used to wrap code from initialization / finalization sections for safe executing.

Passed procedure is either Init or Done procedures, which performs code which should be in initialization and finalization sections. See examples for exact pattern of usage.

Any exception inside specified procedure is considered as fatal exception and triggers an internal EurekaLog's error.

Note. The names of routines ('Init' and 'Done') are important, because this procedure also changes IntoInitialization and IntoFinalization variables.

Any exception inside this procedure is handled by _InitDoneErrorHandler (if assigned).

EMemLeaks

AllocMemCountEx

Represents the total number of allocated memory blocks in a Delphi application.

function AllocMemCountEx: Int64;

Return value.

Number of allocated memory blocks via EurekaLog's memory filter. Returns 0 if filter is not installed, no allocations were made, or all allocations were released.

Remarks.

AllocMemCountEx is the number of currently allocated blocks of memory that were requested by the user. AllocMemCountEx is incremented each time a block of memory is allocated and is decremented each time a block of memory is freed. Use AllocMemCountEx to find out how many unfreed blocks of memory remain.

Tip. Unlike AllocMemCount, AllocMemCountEx is not deprecated and always returns actual information.

AllocMemCountMax

Represents the maximum number of allocated memory blocks.

function AllocMemCountMax: Int64;

Return value.

Maximum of allocated memory blocks via EurekaLog's memory filter. Returns 0 if filter is not installed, or no allocations were made. This value is always equals or greater than AllocMemCountEx (appendix A).

Remarks.

AllocMemCountMax returns maximum of AllocMemCountEx (appendix A). Use AllocMemCountMax to find maximum memory usage of your application.

Tip. Unlike AllocMemCount, AllocMemCountMax is not deprecated and always returns actual information.

AllocMemSizeEx

Represents the total size of requested memory blocks.

function AllocMemSizeEx: Int64;

Return value.

Size in bytes of all requested memory blocks via EurekaLog's memory filter. Returns 0 if no allocations were made, or all allocations were released.

Remarks.

AllocMemSizeEx is the total size, in bytes, of all currently requested blocks of memory in use by an application. Use AllocMemSizeEx to find out how many bytes of memory an application has currently requested.

Tip. Unlike AllocMemSize, AllocMemSizeEx is not deprecated and always returns actual information.

Note. AllocMemSizeEx mimics the AllocMemSize function and indicates sum of all requested sizes - without additional overhead imposed by EurekaLog filter.

AllocMemSizeEx2

Represents the total size of allocated memory blocks, including overhead from EurekaLog's memory/leaks checks.

function AllocMemSizeEx2: Int64;

Return value.

Size in bytes of all allocated memory blocks, including overhead from EurekaLog's memory/leaks checks. Returns 0 if no allocations were made, or all allocations were released.

Remarks.

AllocMemSizeEx2 is the total size, in bytes, of all currently allocated blocks of memory in use by an application. Use AllocMemSizeEx2 to find out how many bytes of memory an application is currently using.

Tip. Unlike AllocMemSize, AllocMemSizeEx2 is not deprecated and always returns actual information.

Note. AllocMemSizeEx2 does NOT mimic the AllocMemSize function, it indicates sum of all requested sizes - including additional overhead imposed by EurekaLog filter.

AllocMemSizeMax

Represents the maximum size of allocated memory.

function AllocMemSizeMax: Int64;

Return value.

Size in bytes of maximum amount of all allocated memory blocks via EurekaLog's memory filter. Returns 0 if filter is not installed, or no allocations were made. This value is always equals or greater than AllocMemSizeEx (appendix A).

Remarks.

AllocMemSizeMax returns maximum of AllocMemSizeEx (appendix A). Use AllocMemSizeMax to find maximum memory usage of your application.

Tip. Unlike AllocMemSize, AllocMemSizeMax is not deprecated and always returns actual information.

CheckHeap

Checks heap for consistency.

procedure CheckHeap;

Remarks.

This function will scan heap (dynamically allocated memory) and check each memory block for errors. The errors include overflow and underflow errors (i.e. overwriting header/footer of memory block).

This function will call MemLeaksError event handler for each found error. This usually results in showing bug report about the problem and terminating application.

Tip. The function will scan only memory blocks allocated via EurekaLog's memory filter (appendix A, IsMemLeaksInstalled) with enabled registering memory leaks (appendix A, IsMemLeaksEnabled).

Note. This function will do nothing if memory leaks checks are not enabled or if leOverflow value is in MemLeaksErrorsToIgnore global variable.

Warning. This function will block all memory operations during scanning. Also, the scan takes a lot of time to complete. Do not call this routine in production. This function is designed to be called for local debugging purposes only. I.e. call this routine to locate known memory corruption issue.

DisableMemLeaksRegistering

Disables memory leaks checks.

procedure DisableMemLeaksRegistering;

Remarks.

This function temporally disables regestering memory leaks. This is a global state, which can be checked with IsMemLeaksEnabled function (appendix A, IsMemLeaksEnabled). You can enable regestering memory leaks back with EnableMemLeaksRegistering function (appendix A, EnableMemLeaksRegistering).

When registering memory leaks is enabled, EurekaLog will collect call stack information of each allocated memory block. Additional information (such as name, grouping, etc.) will also be stored.
When registering memory leaks is disabled, EurekaLog will not collect call stack and additional information. Overhead will be significantly reduced.

See also description of EMemLeaks unit (appendix C, EMemLeaks).

Important. This function will not disable generating report about already registered memory leak. To disable memory leak report - use ActivateMemoryLeakCheck function.

Note. You can use EurekaRegisterExpectedMemoryLeak function (appendix A, EurekaRegisterExpectedMemoryLeak) to register an expected memory leak or to disable leak reporting for already allocated memory block.

Caution!

DisableMemLeaksRegistering/EnableMemLeaksRegistering can not be called recursively. If you make two calls to DisableMemLeaksRegistering followed to one call to EnableMemLeaksRegistering - then registering of memory leaks will be enabled.

DumpAllocationsToFile

Logs all allocated memory to file.

procedure DumpAllocationsToFile(
  const AFileName: String;
  const ACount: Boolean = True;
  const AGroup: Boolean = True;
  const AGroupHeuristic: Boolean = True;
  const ASort: Boolean = True;
  const AFilter: TDumpFilterFunc = nil;
  const ACompare: TDumpCompareFunc = nil;
  const ACompareForCount: TDumpCompareFunc = nil
);

Parameters.

AFileName [in] — A fully qualified valid file name. File's folder must exists and be writable. File will be (re)created.
ACount [in, optional] — True - group duplicate memory blocks, False - report each memory block individually.
AGroup [in, optional] — True - group child blocks with parent, False - report all memory blocks.
AGroupHeuristic [in, optional] — True - group child blocks with parent objects by using call stack heuristic, False - group only explicitly parented blocks. This argument is ignored when AGroup is False.
ASort [in, optional] — True - sort memory blocks, default sort is: blocks with most count (i.e. same type and call stack) will be first, then blocks of bigger size, same size is sorted by type: first - objects, then dyn-arrays/strings, then RAW data; False - do not sort memory blocks, list blocks in order of allocation (older - first, newer - last).
AFilter [in, optional] — A custom filter for filtering out memory blocks.
ACompare [in, optional] — A custom comparator for sorting.
ACompareForCount [in, optional] — A custom comparator for counting. Positive and negative results are considered to be the same (e.g. "not equal"). (This argument could be the same as ACompare)

Remarks.

This function will log all allocated memory blocks to the specified file. Each memory block will be logged with call stack, properties (i.e. name, type, size, count) and short memory dump. Additionally a total memory statistics will be written.

This is a diagnostic function which can be used to find reasons for high memory usage, collect memory usage statitics, find hidden memory leaks, etc.

Counting

DumpAllocationsToFile will count memory blocks. Memory blocks are considered to be the same if these blocks have the same size, same type, same name and same call stack (up to 6 lines). Same memory block will be grouped together - only first block will be logged (with its call stack, dump and properties). Other blocks will not be logged. Instead, a count will be added to a header of the first logged memory blocks.

You may override a default comparison method by specifying your own ACompareForCount.

Typically, you are interested in memory blocks with higher counts. For example, when memory block is allocated 400 times - it may be an indication that such memory blocks are not released when needed.

Parenting

DumpAllocationsToFile may group child leaks with parent leak. Any memory block can be declared as child memory block to another memory block - you can do this via MemLeaksSetParentBlock function (appendix A, MemLeaksSetParentBlock) or MemLeaksOwn function (appendix A, MemLeaksOwn). Additionally, any memory allocated withing constructor of any object will be declared as child memory to this object - this is determinated by a heuristic check using call stacks.

Grouping by parent allows you to view a lot of memory blocks as a single object. This feature is used to simplify report: it filters out non-important entries, showing only root parent for all sub-children. The idea behind this: if parent is leaked - then all children are leaked as well. However, you are not interested in children leak, because there is no bug. The bug is leaked parent. Thus, we hide leaked children, show leaked parent, now you can easily identificate root cause for bug. You solve bug - no more parent leak, thus no more children leak. Of course, if parent is not leaking, but some child are leaking - a child will be included in report.

Filtering

If you get many unrelated memory blocks included in your report, then you can supply a custom filter function (AFilter) to remove any particular memory block from report. Since run-time address change on each application's launch, you can not use exact address to filter out memory blocks. You have to rely on block's size, type, call stack, name, or, perhaps, an allocation order.

Sorting

Not all memory blocks are equally interesting. For examples, RAW data are often allocated from objects. Thus, objects are usually more interesting than RAW data.

Tip. You can use parenting (see above) to eliminate such cases.

You can use sorting to spot interest blocks and place them first. Default sorting prefers repeated blocks (with higher count), then it prefers large blocks (by grouped total size, not size of single blocks), then comes block's type (object, array, string or RAW), named/unnamed.

You can also supply a custom comparator function (ACompare) to define your own preferred sort order.

Naming

Usually it is difficult to identificate memory blocks inside memory report. While there is a lot of information (call stack, type, size, dump) - this is not enough for many cases. For example, if memory is allocated in cycle (like "while" cycle to read a document and create entries for each document's block). Such memory blocks will look the same in report, it is not possible to distinguish between them.

You can use MemLeaksName (appendix A) or MemLeaksOwn (appendix A) functions to mark any memory block with arbitrary name tag. Name tag will be displayed in header for memory block in the report.

Tip. EurekaLog is capable of extracting class name from objects and "Name" property from components. Use custom names for other types of memory blocks.

Sizing

Headers for memory blocks indicate two sizes: single and total. Single is a size of allocation for each memory block inside the entry. Total is size occupied by entire entry. For duplicate (repeated) blocks: total size = single size * count. For parent-child grouping: parent total size = single parent size + each(total child size).

Tip. The function will log only memory blocks allocated via EurekaLog's memory filter (appendix A, IsMemLeaksInstalled) with enabled registering memory leaks (appendix A, IsMemLeaksEnabled).

Warning. This function will block all memory operations during logging. Also, the logging takes a lot of time to complete. Do not call this routine in production. This function is designed to be called for local debugging purposes only. I.e. call this routine to locate known memory leak issue.

Warning. While your application may work after calling this function, it is best to terminate the process immediatelly after calling this function.

For technical reasons heap memory may not be in valid state after calling this function. Thus, you may encounter memory-related crashes.

EnableMemLeaksRegistering

Enables memory leaks checks.

procedure EnableMemLeaksRegistering;

Remarks.

Enables back registering of memory leaks which was previously disabled with DisableMemLeaksRegistering (appendix A).

Caution!

EurekaAllocMem

AllocMem allocates a memory block and initializes each byte to zero.

function EurekaAllocMem(
  Size: TIntForRealloc
): Pointer;

Parameters.

Size [in] — A size of memory block to allocate (in bytes).

Return value.

A pointer to allocated memory block of Size bytes. Memory block is zero-initialized.

Remarks.

EurekaAllocMem allocates a block of the given Size on the heap, and returns the address of this memory. Each byte in the allocated buffer is set to zero. To dispose of the buffer, use EurekaFreeMem (appendix A). If there is not enough memory available to allocate the block, an leOutOfMemory error is raised.

Note. If the memory does not need to be zero-initialized, you can use EurekaGetMem (appendix A).

Note. Do not call EurekaAllocMem manually. This function will be called automatically when you call AllocMem function when EurekaLog's memory filter is installed.

Important. EurekaAllocMem usually never returns nil nor raise exceptions. Memory allocation errors are considered to be fatal. EurekaLog will call MemLeaksError event handler to hanle memory allocation error and terminate the application. See also: MemLeaksErrorsToIgnore global variable. You can use an explicit call to EurekaTryGetMem (appendix A) function to allocate memory with ignoring errors.

EurekaFreeMem

Frees a memory block previously allocated with EurekaGetMem (appendix A), EurekaTryGetMem (appendix A) or EurekaAllocMem (appendix A).

function EurekaFreeMem(
  P: Pointer
): Integer;

Parameters.

P [in] — A pointer to memory block returned by EurekaGetMem (appendix A), EurekaTryGetMem (appendix A) or EurekaAllocMem (appendix A).

Return value.

Return value is always 0.

Remarks.

Use this procedure to dispose of a memory block obtained with EurekaGetMem (appendix A), EurekaTryGetMem (appendix A) or EurekaAllocMem (appendix A).

Note. Do not call EurekaFreeMem manually. This function will be called automatically when you call FreeMem function when EurekaLog's memory filter is installed.

EurekaGetMem

Allocates a memory block via EurekaLog memory filter.

function EurekaGetMem(
  Size: PtrInt
): Pointer;

Parameters.

Size [in] — A size of memory block to allocate (in bytes).

Return value.

A pointer to allocated memory block of Size bytes. Memory block is not zero-initialized.

Remarks.

EurekaGetMem allocates a block of the given Size on the heap, and returns the address of this memory. The bytes of the allocated buffer are not set to zero. To dispose of the buffer, use EurekaFreeMem (appendix A). If there is not enough memory available to allocate the block, an leOutOfMemory error is raised.

Note. If the memory block must be initialized with zero, you can use EurekaAllocMem (appendix A).

Note. Do not call EurekaGetMem manually. This function will be called automatically when you call GetMem function when EurekaLog's memory filter is installed.

Important. EurekaGetMem usually never returns nil nor raise exceptions. Memory allocation errors are considered to be fatal. EurekaLog will call MemLeaksError event handler to hanle memory allocation error and terminate the application. See also: MemLeaksErrorsToIgnore global variable. You can use an explicit call to EurekaTryGetMem (appendix A) function to allocate memory with ignoring errors.

EurekaReallocMem

Resizes a memory block.

function EurekaReallocMem(
  P: Pointer;
  Size: PtrInt
): Pointer;

Parameters.

P [in] — A pointer to memory block returned by EurekaGetMem (appendix A), EurekaTryGetMem (appendix A) or EurekaAllocMem (appendix A).
Size [in] — New size of P in bytes. Size can be larger or smaller than original size of P. If Size is larger than old size, then the memory block will be expanded (with non initialized memory). If Size is smaller than old size, then the memory block will be truncated.

Return value.

A pointer to allocated memory block of Size bytes. This value may or may not be equal to P. Old content of P is preserved. If Size is larger than old size of P, then newly added memory is not zero-initialized.

Remarks.

EurekaReallocMem reallocates a memory block. EurekaGetMem allocates a block of the given Size on the heap. If you have to change the size of this memory block, call EurekaReallocMem, passing the existing memory block pointer in P and the revised block size in Size. If EurekaReallocMem can't expand the memory block pointed to by P, it frees the referenced memory and copies the values to the newly allocated memory that is returned. The content of the newly allocated memory is not set to zero.

Note. Do not call EurekaReallocMem manually. This function will be called automatically when you call ReallocMem function when EurekaLog's memory filter is installed.

Important. EurekaReallocMem usually never returns nil nor raise exceptions. Memory allocation errors are considered to be fatal. EurekaLog will call MemLeaksError event handler to hanle memory allocation error and terminate the application. See also: MemLeaksErrorsToIgnore global variable. You can use an explicit call to EurekaTryGetMem (appendix A) function to allocate memory with ignoring errors.

EurekaRegisterExpectedMemoryLeak

function EurekaRegisterExpectedMemoryLeak(
  P: Pointer
): Boolean;

Parameters.

P [in] — A pointer to memory block of expected leak.

Return value.

Indicate if leak was registered successfully. A False value usually indicate that this block was already registered.

Remarks.

This function registers a particular memory block to be excluded from memory leaks report. This feature can be used to skip reporting for "leaks by design" or for bugs in 3rd party code over which you have no control.

This function is used to exclude already allocated blocks. Thus, this function is usually used to register leaks from 3rd party code. To register expected leaks in your own code - you can use either this function or DisableMemLeaksRegistering function (appendix A, DisableMemLeaksRegistering).

Tip. While it is usually not needed, but you can call EurekaUnregisterExpectedMemoryLeak (appendix A) function to unregister memory block from excluded leaks.

Important. You must pass a pointer to the beginning of the memory block. Please note that dynamic arrays and strings do not point to the beginning of allocation. Use EurekaRegisterExpectedMemoryLeakDynArray (appendix A) and EurekaRegisterExpectedMemoryLeakStr (appendix A) for dynamic arrays and strings instead of this function.

EurekaRegisterExpectedMemoryLeakDynArray

function EurekaRegisterExpectedMemoryLeakDynArray(
  P: Pointer
): Boolean;

Parameters.

P [in] — A dynamic array casted to pointer.

Return value.

Indicate if leak was registered successfully. A False value usually indicate that this block was already registered.

Remarks.

This function is the same as EurekaRegisterExpectedMemoryLeak function (appendix A, EurekaRegisterExpectedMemoryLeak), but it accepts only pointers to dynamic arrays.

Tip. While it is usually not needed, but you can call EurekaUnregisterExpectedMemoryLeakDynArray (appendix A) function to unregister memory block from excluded leaks.

EurekaRegisterExpectedMemoryLeakStr

function EurekaRegisterExpectedMemoryLeakStr(
  P: Pointer
): Boolean;

Parameters.

P [in] — A dynamic array casted to pointer.

Return value.

Indicate if leak was registered successfully. A False value usually indicate that this block was already registered.

Remarks.

This function is the same as EurekaRegisterExpectedMemoryLeak function (appendix A, EurekaRegisterExpectedMemoryLeak), but it accepts only pointers to strings (ANSI or Unicode, but not WideStrings).

Tip. While it is usually not needed, but you can call EurekaUnregisterExpectedMemoryLeakStr (appendix A) function to unregister memory block from excluded leaks.

EurekaTryGetMem

Allocates a memory block via EurekaLog memory filter (w/o error checking).

function EurekaTryGetMem(
  Size: PtrUInt
): Pointer;

Parameters.

Size [in] — A size of memory block to allocate (in bytes).

Return value.

A pointer to allocated memory block of Size bytes (not initialized to zero) or nil if memory error occurs.

Remarks.

EurekaTryGetMem allocates a block of the given Size on the heap, and returns the address of this memory. The bytes of the allocated buffer are not set to zero. To dispose of the buffer, use EurekaFreeMem (appendix A). If there is not enough memory available to allocate the block, nil is returned.

Note. Unlike EurekaGetMem (appendix A), EurekaTryGetMem function can be called manually.

EurekaUnregisterExpectedMemoryLeak

Removes memory block from excluded leaks.

function EurekaUnregisterExpectedMemoryLeak(
  P: Pointer
): Boolean;

Parameters.

P [in] — A pointer to memory block which was previosly passed to EurekaRegisterExpectedMemoryLeak function (appendix A, EurekaRegisterExpectedMemoryLeak).

Return value.

True - expected leak was unregistered successfully. False - leak was not unregistered (e.g. leak was already unregistered earlier, no such leak was registered, or EurekaRegisterExpectedMemoryLeak function (appendix A, EurekaRegisterExpectedMemoryLeak) returned False).

Remarks.

This function removes a successfully registered expected memory leak from list of exclusions.

EurekaUnregisterExpectedMemoryLeakDynArray

Removes memory block from excluded leaks (variant for dynamic arrays).

function EurekaUnregisterExpectedMemoryLeakDynArray(
  P: Pointer
): Boolean;

Parameters.

P [in] — A pointer to memory block which was previosly passed to EurekaRegisterExpectedMemoryLeakDynArray function (appendix A, EurekaRegisterExpectedMemoryLeakDynArray).

Return value.

True - expected leak was unregistered successfully. False - leak was not unregistered (e.g. leak was already unregistered earlier, no such leak was registered, or EurekaRegisterExpectedMemoryLeakDynArray function (appendix A, EurekaRegisterExpectedMemoryLeakDynArray) returned False).

Remarks.

This function removes a successfully registered expected memory leak from list of exclusions.

EurekaUnregisterExpectedMemoryLeakStr

Removes memory block from excluded leaks (variant for strings).

function EurekaUnregisterExpectedMemoryLeakStr(
  P: Pointer
): Boolean;

Parameters.

P [in] — A pointer to memory block which was previosly passed to EurekaRegisterExpectedMemoryLeakStr function (appendix A, EurekaRegisterExpectedMemoryLeakStr).

Return value.

True - expected leak was unregistered successfully. False - leak was not unregistered (e.g. leak was already unregistered earlier, no such leak was registered, or EurekaRegisterExpectedMemoryLeakStr function (appendix A, EurekaRegisterExpectedMemoryLeakStr) returned False).

Remarks.

This function removes a successfully registered expected memory leak from list of exclusions.

IsMemLeaksEnabled

Indicate if memory leaks checks are enabled.

function IsMemLeaksEnabled: Boolean;

Return value.

True - memory leaks checks are enabled, False otherwise.

Remarks.

This function indicate if memory leaks checks are enabled.

When enabled, EurekaLog will collect call stack information of each allocated memory block. Additional information (such as name, grouping, etc.) will also be stored.
When disabled, EurekaLog will not collect call stack and additional information. Overhead will be significantly reduced.

See also description of EMemLeaks unit (appendix C, EMemLeaks).

This is a global state, which can be changed via EnableMemLeaksRegistering (appendix A)/DisableMemLeaksRegistering (appendix A) or SetMemLeaksRegistering functions. You may temporally disable memory leaks checks when executing code with large amount of memory allocations which are guaranteed not to leak.

Note. This function will always return False if EurekaLog is not installed. See IsMemLeaksInstalled function (appendix A, IsMemLeaksInstalled).

Tip. This function also returns False when inside EurekaLog's own code.

IsMemLeaksInstalled

Indicate if EurekaLog's memory filter is installed.

function IsMemLeaksInstalled: Boolean;

Return value.

True if filter is installed, False otherwise.

Remarks.

This value indicate if EurekaLog has installed memory filter to add additional functionality (memory problems checks).

When this value is True - EurekaLog's filter is used, overhead is added. When this value is False - native memory manager is used, no overhead. See also description of EMemLeaks unit (appendix C, EMemLeaks).

Note. This value is initialized on startup and never changes.

MemLeaksGetName

Returns memory block's name.

function MemLeaksGetName(
  const ABlock: Pointer
): String;

Parameters.

ABlock [in] — A pointer to memory block.

Return value.

Name of the memory block previously set by the MemLeaksName (appendix A) function or an empty string if the name was not set.

Remarks.

This function returns a custom name to any memory block allocated with EurekaGetMem with enabled registering leaks. A custom name will be visible in leak reports - which should allow you to identify memory block.

Tip. Name have limited length. Names are stored internally with TCustomName field. Owners of Enterprise version of EurekaLog (with full sources) can alter size of the name and recompile EurekaLog.

Important. You must pass a pointer to the beginning of the memory block. Please note that dynamic arrays and strings do not point to the beginning of allocation.

MemLeaksName

Names a memory block.

procedure MemLeaksName(
  const ABlock: Pointer;
  const AName: String
);

Parameters.

ABlock [in] — A pointer to memory block.
AName [in] — A custom name for the ABlock block.

Remarks.

This function assigns a custom name to any memory block allocated with EurekaGetMem with enabled registering leaks. A custom name will be visible in leak reports - which should allow you to identify memory block.

Important. You must pass a pointer to the beginning of the memory block. Please note that dynamic arrays and strings do not point to the beginning of allocation. Use MemLeaksNameDynArray (appendix A) and MemLeaksNameStr (appendix A) for dynamic arrays and strings instead of this function.

MemLeaksNameDynArray

Names a memory block (variant for dynamic arrays).

procedure MemLeaksNameDynArray(
  const ABlock: Pointer;
  const AName: String
);

Parameters.

ABlock [in] — A dynamic array casted to pointer.
AName [in] — A custom name for the ABlock block.

Remarks.

This function is the same as MemLeaksName function (appendix A, MemLeaksName), but it accepts only pointers to dynamic arrays.

MemLeaksNameStr

Names a memory block (variant for strings).

procedure MemLeaksNameStr(
  const ABlock: Pointer;
  const AName: String
);

Parameters.

ABlock [in] — A string casted to pointer.
AName [in] — A custom name for the ABlock block.

Remarks.

This function is the same as MemLeaksName function (appendix A, MemLeaksName), but it accepts only pointers to strings.

MemLeaksOwn

Sets ownership for memory block.

procedure MemLeaksOwn(
  const AParentBlock, AChildBlock: Pointer;
  const AName: String = ''
);

Parameters.

AParentBlock [in] — A pointer to parent block.
AChildBlock [in] — A pointer to child block.
AName [in, optional] — A custom name for the AChildBlock block. Empty string (default) means "do not change name".

Remarks.

This function is a combination of MemLeaksSetParentBlock (appendix A) and MemLeaksName (appendix A) functions. MemLeaksOwn will name AChildBlock with AName (as MemLeaksName (appendix A) do) and sets AParentBlock as a parent to AChildBlock (as MemLeaksSetParentBlock (appendix A) do).

The difference is that MemLeaksOwn will not overwrite a parent link in AChildBlock if that link was already set. Whereas MemLeaksSetParentBlock (appendix A) will always set parent link. This difference allows you to use MemLeaksOwn to set ownership for reference-counted data types passed to you as arguments. For example, if string is passed to constructor of your object, and you save this string into field of your object - you may use MemLeaksOwnStr (appendix A) to claim ownership of this string.

Important. You must pass a pointer to the beginning of the memory block. Please note that dynamic arrays and strings do not point to the beginning of allocation. Use MemLeaksOwnDynArrayChild (appendix A), MemLeaksOwnDynArrayParent (appendix A), MemLeaksOwnDynArrayBoth (appendix A) and MemLeaksOwnStr (appendix A) for dynamic arrays and strings instead of this function.

MemLeaksOwnDynArrayBoth

Sets ownership for memory block (variant for dynamic arrays).

procedure MemLeaksOwnDynArrayBoth(
  const AParentBlock, AChildBlock: Pointer;
  const AName: String = ''
);

Parameters.

AParentBlock [in] — A dynamic array casted to pointer.
AChildBlock [in] — A dynamic array casted to pointer.
AName [in, optional] — A custom name for the AChildBlock block. Empty string (default) means "do not change name".

Remarks.

This function is the same as MemLeaksOwn function (appendix A, MemLeaksOwn), but it accepts only pointers to dynamic arrays.

MemLeaksOwnDynArrayChild

Sets ownership for memory block (variant for dynamic arrays).

procedure MemLeaksOwnDynArrayChild(
  const AParentBlock, AChildBlock: Pointer;
  const AName: String = ''
);

Parameters.

AParentBlock [in] — A pointer to parent block.
AChildBlock [in] — A dynamic array casted to pointer.
AName [in, optional] — A custom name for the AChildBlock block. Empty string (default) means "do not change name".

Remarks.

This function is the same as MemLeaksOwn function (appendix A, MemLeaksOwn), but it accepts only pointers to dynamic arrays.

MemLeaksOwnDynArrayParent

Sets ownership for memory block (variant for dynamic arrays).

procedure MemLeaksOwnDynArrayParent(
  const AParentBlock, AChildBlock: Pointer;
  const AName: String = ''
);

Parameters.

AParentBlock [in] — A dynamic array casted to pointer.
AChildBlock [in] — A pointer to parent block.
AName [in, optional] — A custom name for the AChildBlock block. Empty string (default) means "do not change name".

Remarks.

This function is the same as MemLeaksOwn function (appendix A, MemLeaksOwn), but it accepts only pointers to dynamic arrays.

MemLeaksOwnStr

Sets ownership for memory block (variant for strings).

procedure MemLeaksOwnStr(
  const AParentBlock, AChildBlock: Pointer;
  const AName: String = ''
);

Parameters.

AParentBlock [in] — A pointer to parent block.
AChildBlock [in] — A string casted to pointer.
AName [in, optional] — A custom name for the AChildBlock block. Empty string (default) means "do not change name".

Remarks.

This function is the same as MemLeaksOwn function (appendix A, MemLeaksOwn), but it accepts only pointers to strings.

MemLeaksSetParentBlock

procedure MemLeaksSetParentBlock(
  const AParentBlock, AChildBlock: Pointer
);

MemLeaksSetParentBlockDynArrayBoth

Sets parent-child relation between two memory blocks for grouping (variant for dynamic arrays).

procedure MemLeaksSetParentBlockDynArrayBoth(
  const AParentBlock, AChildBlock: Pointer
);

Parameters.

AParentBlock [in] — A dynamic array casted to pointer.
AChildBlock [in] — A dynamic array casted to pointer.

Remarks.

This function is the same as MemLeaksSetParentBlock function (appendix A, MemLeaksSetParentBlock), but it accepts only pointers to strings.

MemLeaksSetParentBlockDynArrayChild

Sets parent-child relation between two memory blocks for grouping (variant for dynamic arrays).

procedure MemLeaksSetParentBlockDynArrayChild(
  const AParentBlock, AChildBlock: Pointer
);

Parameters.

AParentBlock [in] — A pointer to parent block.
AChildBlock [in] — A dynamic array casted to pointer.

Remarks.

This function is the same as MemLeaksSetParentBlock function (appendix A, MemLeaksSetParentBlock), but it accepts only pointers to strings.

MemLeaksSetParentBlockDynArrayParent

Sets parent-child relation between two memory blocks for grouping (variant for dynamic arrays).

procedure MemLeaksSetParentBlockDynArrayParent(
  const AParentBlock, AChildBlock: Pointer
);

Parameters.

AParentBlock [in] — A dynamic array casted to pointer.
AChildBlock [in] — A pointer to child block.

Remarks.

This function is the same as MemLeaksSetParentBlock function (appendix A, MemLeaksSetParentBlock), but it accepts only pointers to strings.

MemLeaksSetParentBlockStr

Sets parent-child relation between two memory blocks for grouping (variant for strings).

procedure MemLeaksSetParentBlockStr(
  const AParentBlock, AChildBlock: Pointer
);

Parameters.

AParentBlock [in] — A pointer to parent block.
AChildBlock [in] — A string casted to pointer.

Remarks.

This function is the same as MemLeaksSetParentBlock function (appendix A, MemLeaksSetParentBlock), but it accepts only pointers to strings.

EModules

DATE

Returns the compilation date of the current project.

function __DATE__: String;

Return value.

The compilation date of the current project as 'yyyy-mm-dd' string value. For example: '2021-02-07'. Date is returned in GMT/UTC.

Remarks.

This function is a simple combination of GetCompilationDate (appendix A) and FormatDateTime functions.

Warning. Please note that this function acts differently compared to DATE macros in C++. The DATE macros returns compilation date of a source file, which is not the same as compilation date of the project.

TIME

Returns the compilation time of the current project.

function __TIME__: String;

Return value.

The compilation time of the current project as 'hh:mm:ss' string value. For example: '11:09:10'. Time is returned in GMT/UTC.

Remarks.

This function is a simple combination of GetCompilationDate (appendix A) and FormatDateTime functions.

Warning. Please note that this function acts differently compared to TIME macros in C++. The TIME macros returns compilation time of a source file, which is not the same as compilation time of the project.

CurrentEurekaLogOptions

Returns current/global EurekaLog's options.

function CurrentEurekaLogOptions: TEurekaModuleOptions;

Return value.

Current/global EurekaLog's options.

Remarks.

This function returns global options for EurekaLog in current executable module. Options are present if EurekaLog was installed.

Important. If EurekaLog is not active - any attempt to call this function will result in error message "Cannot use ''CurrentEurekaLogOptions'' function in module "XYZ" without activate EurekaLog" and immediate process termination.

This behaviour is "as designed". It's done to avoid cases when you ship your application with EurekaLog's code but without EurekaLog active.

Default options are set based on EurekaLog's projects settings - as set by you in IDE expert or standalone Settings Editor Tool. Options can be changed at run-time at any time.

Note. Some options are read-only. That's because these options can not be changed after activation.

CurrentEurekaLogOptions represents global EurekaLog's options. These options can also be captured locally. In this case changes to global options will have no effect for captured options.

For example, when exception is raised - it creates a copy of options. Thus, if you change options globally - this will have no effect on already active exceptions.

If you want to change options for such exceptions - you should use local copy of options (i.e. .Options property for dialogs, AOptions argument in event handlers, etc.).

See TEurekaModuleOptions (appendix D) for detailed description of available EurekaLog's options.

Note. It's highly recommended to use enviroment variables when possible instead of customizing options at run-time. That's because some exceptions can occur before you get chance to setup options.

GetApplicationDescription

Gets application description.

function GetApplicationDescription: String;

Return value.

Description of .exe file or empty string if it's not available.

Sample output: 'bds.exe - (Embarcadero RAD Studio for Windows)'

Remarks.

This function extracts description of .exe file from version information. If such information is present - function returns "File description" field with .exe file name. Otherwise empty string is returned.

This function is simple combination GetModuleDescription(PrimaryInstance (appendix A))

GetApplicationName

Gets application name.

function GetApplicationName: String;

Return value.

Name of .exe file or empty string if it's not available.

Sample output: 'Embarcadero RAD Studio for Windows'

Remarks.

This function extracts description of .exe file from version information. If such information is present - function returns "File description" field. Otherwise empty string is returned.

This function is simple combination GetModuleDescriptionAndVersion(PrimaryInstance (appendix A))

GetCompilationDate

Returns the compilation date of the specified executable module.

function GetCompilationDate(
  const AModule: HINST;
  const ALocalTime: Boolean;
  out ADate: TDateTime
): Boolean;

Parameters.

AModule [in] — A handle of any loaded module in the current process. Typical value is HInstance.
ALocalTime [in] — Pass True if you want to get compilation date in your current time zone; pass False if you want to get compilation date in GMT/UTC.
ADate [out] — The compilation date of the specified module.

Return value.

True if function was able to obtain the compilation date. False otherwise. Function should always succeed if called for EurekaLog-enabled module. Function could fail if invalid handle is passed, if module is not EurekaLog-enabled module, and module does not have valid date in its headers.

Remarks.

This function reads post-processing date (almost the same as compilation date) from EurekaLog's embedded data for the module. If module does not have EurekaLog embedded - then the function tries to read date from module's PE headers.

Note. If module does not have EurekaLog injected - then it may not always be possible to retrieve date in the correct time zone.

GetCurrentModuleCompilationDate

Gets compilation time of current module.

function GetCurrentModuleCompilationDate: TDateTime;

Return value.

Compilation date-time of current module in local time or 0 if it's not available.

Remarks.

This function is simple combination of GetCompilationDate (appendix A)(PrimaryInstance (appendix A)).

Please see GetCompilationDate (appendix A) for limitations of this function.

GetExceptionModuleName

Gets description of exception's module.

function GetExceptionModuleName(
  const AAddr: Pointer
): String;

Parameters.

AAddr [in] — Exception address. Usually it's ExceptAddr value or equivalent.

This address is used to determinate handle of module which contains code with the specified address.

Return value.

Description of exception module file or empty string if it's not available.

Sample output: 'bds.exe - (Embarcadero RAD Studio for Windows)'

Remarks.

This function extracts description of module file from version information. If such information is present - function returns "File description" field with module file name. Otherwise empty string is returned.

If exception was raised in .exe file - the return value will be equal to GetApplicationDescription (appendix A).

This function is simple combination GetModuleDescription(FindHInstance(AAddr))

GetExceptionModuleVersion

Gets exception's module version.

function GetExceptionModuleVersion(
  const AAddr: Pointer
): String; overload;
function GetExceptionModuleVersion(
  const AModuleName: String
): String; overload;

Parameters.

AAddr [in] — Exception address. Usually it's ExceptAddr value or equivalent.

This address is used to determinate handle of module which contains code with the specified address.

AModuleName [in] — Full file name to get version number.

Return value.

File version of exception's module.

Example value: '1.0.0.0'.

Remarks.

This function extracts version number of module file from version information. If such information is present - function returns "File version" field. Otherwise empty string is returned.

EResLeaks

HookWin32API

Adds a function to resource monitoring.

function HookWin32API(
  const AModuleName, AAPIName, AAPICategory, AAPIType: String;
  AParamCount: Integer;
  ACreate: Boolean;
  ACheckType: TCheckType = ctEqual;
  ACheckValue: PtrUInt = 0;
  AResultParam: Integer = -1
): Pointer;

Parameters.

AModuleName

DLL file name to hook. Case insensitive

AAPIName

DLL's function name to hook. Case sensitive

AAPICategory

Category for API.

AAPIType

Sub-type of API. Typically equals APICategory

AParamCount

Number of functions arguments

ACreate

True - function creates resource, False - function destroys resource

ACheckType

Specifies valid/invalid conditions for function call. See TCheckType description for more details

ACheckValue

Value for failure call. See TCheckType description for more details

AResultParam

Index of function's argument which returns resource (for Create-like functions) or accepts resource (for Destroy-like functions). Use -1 for functions and >= 0 for procedures. Use -2 for resources without handles at all (i.e. handle is never exposed, so you only need to watch for pairing calls)

Remarks.

Notes:

ACheckValue is ignored (and must be 0) for ctNone, ctHResult, ctNTStatus.
AResultParam can't be a return value, if check type is ctHResult or ctNTStatus
Dispose-like function (ACreate = False) can't return handle - handle should be only passed as argument or be an internal handle (AResultParam = -2 or AResultParam >= 0)

EResourceStrings

ResStringCleanupCache

Cleanups internal cache of loaded resource strings.

procedure ResStringCleanupCache;

Remarks.

Call this function to cleanup the internal cache of loaded resource strings. It is useful for applications dynamically changing resource DLL's.

EScreenShot

FindScreenshotRect

Determinates screen area occupied by the specified object.

function FindScreenshotRect(
  const AScreenshotMode: TSendScreenshot
): TRect;

Parameters.

AScreenshotMode [in] — Specifies a screen area to locate.

Return value.

Absolute screen (desktop) coordinates of the AScreenshotMode. Or empty rectangle on failure.

Remarks.

This is a auxiliary routine which helps determinate what part of the screen (desktop) should be included in the screenshot.

The results of this function can be used to call Screenshot (appendix A) or ScreenshotInit (appendix A) routines.

Screenshot

Takes screenshot.

procedure Screenshot(
  const ARect: TRect;
  const AFocusWnd: HWND;
  const ACursorPos: TPoint;
  const ACursor: HCURSOR;
  const AFileName: String;
  const A8Bit: Boolean = True
); overload;
procedure Screenshot(
  const ARect: TRect;
  const AFocusWnd: HWND;
  const ACursorPos: TPoint;
  const ACursor: HCURSOR;
  const AStream: Classes.TStream;
  const A8Bit: Boolean = True
); overload;

Parameters.

ARect [in] — Screen area to take screenshot. Typically, this is a return value from the FindScreenshotRect (appendix A) function.
AFocusWnd [in, optional] — A window which borders should be highlighted. It does not have to be a top level window. This is typically a child control (such as a button), which indicates focused control. Pass 0 to disable this feature.
ACursorPos [in] — Absolute screen coordinates of mouse cursor. This is used to include image of mouse cursor in the screenshot.
ACursor [in] — Mouse cursor image. This is used to include image of mouse cursor in the screenshot.
AFileName [in] — Full absolute file name to save screenshot to.
A8Bit [in, optional] — True (default) - use 256-color image (to save space), False - use 32-bit color image.
AStream [in] — Data stream to save screenshot to.

Remarks.

This routine takes screenshot with specified parameters and saves it to file or data stream.

Note. Effectively, this routines is a simple combination of ScreenshotInit (appendix A) + ScreenshotSave (appendix A) + ScreenshotFree (appendix A).

ScreenshotFree

Release screenshot.

procedure ScreenshotFree(
  const AScreenshot: TScreeenshotHandle
);

Parameters.

AScreenshot [in] — Initialized screenshot. This is a return value from the ScreenshotInit (appendix A) function.

Remarks.

This routine releases screenshot created by the ScreenshotInit (appendix A) routine.

After a call to this function: AScreenshot is no longer valid and must not be used.

ScreenshotInit

Creates screenshot.

function ScreenshotInit(
  const ARect: TRect;
  const AFocusWnd: HWND;
  const ACursorPos: TPoint;
  const ACursor: HCURSOR
): TScreeenshotHandle;

Parameters.

ARect [in] — Screen area to take screenshot. Typically, this is a return value from the FindScreenshotRect (appendix A) function.
AFocusWnd [in, optional] — A window which borders should be highlighted. It does not have to be a top level window. This is typically a child control (such as a button), which indicates focused control. Pass 0 to disable this feature.
ACursorPos [in] — Absolute screen coordinates of mouse cursor. This is used to include image of mouse cursor in the screenshot.
ACursor [in] — Mouse cursor image. This is used to include image of mouse cursor in the screenshot.

Return value.

Descriptor of the created screenshot. This can be passed to the ScreenshotSave (appendix A) function. It must be released by a call to the ScreenshotFree (appendix A) function.

Remarks.

This function initializes screenshot with the specified parameters.

The screenshot descriptor must be released by a call to the ScreenshotFree (appendix A) function.

Note. This is a low-level function. If you need to simply take a screenshot - use Screenshot (appendix A) function.

ScreenshotSave

Saves screenshot to file or stream.

procedure ScreenshotSave(
  const AScreenshot: TScreeenshotHandle;
  const AFileName: String;
  const A8Bit: Boolean = True
); overload;
procedure ScreenshotSave(
  const AScreenshot: TScreeenshotHandle;
  const AStream: Classes.TStream;
  const A8Bit: Boolean = True
); overload;

Parameters.

AScreenshot [in] — Initialized screenshot. This is a return value from the ScreenshotInit (appendix A) function.
AFileName [in] — Full absolute file name to save screenshot to.
A8Bit [in, optional] — True (default) - use 256-color image (to save space), False - use 32-bit color image.
AStream [in] — Data stream to save screenshot to.

Remarks.

This routine saves screenshot which was prepared by a call to the ScreenshotInit (appendix A) routine.

Screenshot can be saved to file or data stream.

ESend

EnumSenders

Returns list of registered send method class names.

procedure EnumSenders(
  const ASenders: TStrings
);

Parameters.

ASenders [out] — List of class names.

Remarks.

Functions returns list of registered send method class names. Send method class registration is performed by RegisterSender (appendix A) and RegisterSenderFirst (appendix A) functions.

FindSender

Searches send method class by name.

function FindSender(
  const ASenderClassName: String
): TELUniversalSenderClass;

Parameters.

ASenderClassName [in] — Name of send method class. For example: 'TELTrackerMantisSender'.

Return value.

Registered send method class or nil if no class was found.

Remarks.

Functions looks for registered send method class with the specified name and return first found class. Send method class registration is performed by RegisterSender (appendix A) and RegisterSenderFirst (appendix A) functions.

RegisterSender

Registers send method class.

procedure RegisterSender(
  const ASenderClass: TELUniversalSenderClass
);

Parameters.

AClass [in] — Send method class to register.

Remarks.

Function registers the specified send method class into global list of available send method classes. Each send method class must be registered before using. Once registered, send method class can be used (selected) via SenderClasses property of TEurekaModuleOptions (appendix D) (which is usually altered using AddSenderClass and RemoveSenderClass methods).

Note. This function adds send method class to the end of the list.

Note. Once registered, send method can not be unregistered.

Note. There is no limitation to register different send method classes with the same class name. Double-registering the same class will have no effect.

RegisterSenderFirst

Registers send method class.

procedure RegisterSenderFirst(
  const ASenderClass: TELUniversalSenderClass
);

Parameters.

AClass [in] — Send method class to register.

Remarks.

Note. This function adds send method class to the beginning of the list.

Note. Once registered, send method class can not be unregistered.

Note. There is no limitation to register different send method classes with the same class name. Double-registering the same class will have no effect.

ESignature

SignatureGetInfo

Returns information about digital signature and its certificate of an executable file.

function SignatureGetInfo(
  const AFileName: String;
  const AWnd: HWND = 0
): TSignatureInfo;

Parameters.

AFileName [in] — Full absolute path to executable file (.exe, .dll, .bpl). File must exists and be readable.

Return value.

Information about digital signature of AFileName.

Remarks.

This function reads the specified file and returns information about its digital signature and certificate that was used to create the signature.

ESysInfo

ExpandEnvVars

Expands environment-variable strings.

function ExpandEnvVars(
  const ASource: String;
  AGetEnvVariable: TGetEnvVariableFunc = nil
): String; overload;
function ExpandEnvVars(
  const ASource: String;
  AGetEnvVariable: TGetEnvVariableMethod
): String; overload;

Parameters.

ASource [in] — A buffer that contains one or more environment-variable strings in the form: %variableName%. For each such reference, the %variableName% portion is replaced with the current value of that environment variable.

Case is ignored when looking up the environment-variable name. If the name is not found, the %variableName% portion will be unchanged.

AGetEnvVariable [in, optional] — An optional environment variable converter.

There are overloads for procedural and method converter.

This function is used to get value of variables. You can supply your own converter to support more variables or change value of existsing ones.

If you don't specify this argument - the default converter will be used (GetEnvVariable (appendix A)).

Return value.

ASource buffer with expanded environment variables.

Remarks.

Expands environment-variable strings and replaces them with the values defined for the current user. You can override variables by supplying the second argument (AGetEnvVariable)

Tip. This function is similar to ExpandEnvironmentStrings.

Note. This routine is often replaced in EurekaLog classes to supply extra variables. For example, exception informational class adds support for %_ExceptMsg% variable.

GetActiveFormClass

Gets window class of active window.

function GetActiveFormClass(
  const AWnd: HWND = 0
): String;

Return value.

If the function succeeds and there is active window, the return value is class of active window.

Sample output: 'TAppBuilder'.

If the function succeeds but there is no active window, the return value is empty string.

If the function fails, the return value is error message.

Tip. Return value never contains line breaks.

Remarks.

This function is combination of GetClassName (GetForegroundWindow)

GetActiveFormText

Gets caption of active window.

function GetActiveFormText(
  const AWnd: HWND = 0
): String;

Return value.

If the function succeeds and there is active window, the return value is caption of active window.

Sample output: 'XMLDocToXML - Embarcadero RAD Studio 2010 - ESysInfo'

If the function succeeds but there is no active window, the return value is empty string.

If the function fails, the return value is error message.

Remarks.

This function is combination of WM_GETTEXT message from GetForegroundWindow

Note. This function uses a timeout of 100 ms. If active window is hung and not responding - function will fail after timeout. Therefore it's safe to call this function, no deadlock is possible.

Tip. Return value nevers contain line breaks.

GetApplicationRect

Gets bounding rectangle for GUI application.

function GetApplicationRect(
  const APID: DWord
): TRect;

Parameters.

APID [in] — Process ID of running application.

Return value.

Bounding rectangle which includes all visible windows of the specified application.

If there is no visible windows belonging to the application - an empty region will be returned (0, 0, 0, 0).

Remarks.

Function enumerates all windows of the specified application and find the smallest possible rectangle area which will include all such windows. The resulting area is returned.

This function is used when taking screenshot of desktop with "Capture my application's windows only" option enabled - to determinate region of desktop to take screenshot from.

GetCompanyName

Gets company name.

function GetCompanyName: String;

Return value.

Company name or empty string.

Example value: 'Litware Ltd.'

Remarks.

This function checks the following registry keys for company information and returns the first suitable value:

'\SOFTWARE\MICROSOFT\WINDOWS NT\CURRENTVERSION'
'\SOFTWARE\MICROSOFT\WINDOWS\CURRENTVERSION'
'\SOFTWARE\MICROSOFT\MS SETUP (ACME)\USER INFO'

GetComputerName

Gets computer name user name.

function GetComputerName: String;

Return value.

Current computer name or empty string.

Example value: 'WORKSTATION1'

Remarks.

Retrieves the NetBIOS name of the local computer. This name is established at system startup, when the system reads it from the registry. The behavior of this function can be affected if the local computer is a node in a cluster. If the caller is running under a client session, this function returns the server name.

Note. This is a wrapper for GetComputerName function.

GetControlClass

Gets class of active control.

function GetControlClass(
  const AWnd: HWND = 0
): String;

Return value.

Class of active control.

Sample output: 'TEdit'

Remarks.

This function is combination of GetClassName (GetFocus)

GetControlText

Gets text of active control.

function GetControlText(
  const AWnd: HWND = 0
): String;

Return value.

Text of active (focused) single line text control. Empty string if there is no focused single line control.

Sample output: 'Some text'

Remarks.

This function is combination of WM_GETTEXT message from GetFocus

Note. This function uses a timeout of 100 ms. If active window is hung and not responding - function will return empty string after timeout. Therefore it's safe to call this function, no deadlock is possible.

Note. This function will not return clear text from password controls. Passwords will be masked by password characters (typically - *).

GetCurrentUserPrivileges

Gets description of user privileges.

function GetCurrentUserPrivileges: String;

Return value.

Status of enabled and disabled system privileges of the current security token. Result string will be multi-line values - one priviledge and its status per line.

Example return value (multi-line):

SeShutdownPrivilege - ON

SeChangeNotifyPrivilege - ON

SeUndockPrivilege - OFF

SeIncreaseWorkingSetPrivilege - OFF

SeTimeZonePrivilege - OFF

Remarks.

Function opens current process and ask for security token, then enumerates privileges listed in this token and collect status of all included privileges.

GetDiskInfo

Gets total and free disk space size.

function GetDiskInfo(
  out AFreeDisk, ATotalDisk: UInt64
): Boolean;

Parameters.

AFreeDisk [out] — Free disk space in bytes.
ATotalDisk [out] — Total disk space in bytes.

Return value.

If the function succeeds, the return value is True.

If the function fails, the return value is False. To get extended error information, call GetLastError.

Remarks.

Function returns disk space size information for disk, which contains current executable module (returned by CurrentInstance (appendix A)).

GetDisplayDPI

Gets screen DPI.

function GetDisplayDPI: Integer;

Return value.

DPI of desktop.

Example values: 96, 120, etc.

Remarks.

Basically, this is GetDeviceCaps(GetDC(0), LOGPIXELSY).

GetDisplayMode

Gets screen mode.

function GetDisplayMode: String;

Return value.

Screen resolution and color depth.

Example value: '1680 x 1050, 32 bit'

Remarks.

Function returns settings of primary monitor.

Note. Desktop pixel size may be larger in multi-monitor configurations. This function counts only primary monitor, all other monitors are ignored.

GetEnvVariable

Expands single environment variable.

function GetEnvVariable(
  const AName: String
): String;

Parameters.

AName [in] — Name of variable without %.

Return value.

Variable value or empty string if variable wasn't defined.

Remarks.

This is default implementation for variable name convertor for ExpandEnvVars (appendix A) function.

This default implementation supports all standard system and user environment variables and also adds the following additional EurekaLog pseudo-variables:

CSIDL_XYZ
FOLDERID_XYZ
_ThisModulePath
_ThisModuleName
_MainModulePath
_MainModuleName
_LineBreak
CD
Date
DateFmt
Time
TimeFmt
Random

Note. This routine is often replaced in EurekaLog classes to supply extra variables. For example, exception informational class adds support for %_ExceptMsg% variable.

GetEurekaLogLabel

Gets full EurekaLog version.

function GetEurekaLogLabel: String;

Return value.

Actual EurekaLog version information.

Example values:

'EurekaLog 7.0.0.177 Trial'

'EurekaLog 7.0.0.177 Professional'

'EurekaLog 7.0.0.177 Enterprise'

'EurekaLog 7.0.0.177 Registered' (for not installed EurekaLog)

'EurekaLog 7.0.0.177 RC 2 Enterprise (BETA)'

Remarks.

This function returns information about EurekaLog. Thus, its behaviour is different depending on EurekaLog status.

If EurekaLog is installed - function reads information about EurekaLog's version from the registry.

If EurekaLog is not installed - function returns build-in information.

Note. Result of this function equals GetEurekaLogVersion (appendix A) + GetEurekaLogLicense (appendix A) + GetEurekaLogStatus (appendix A).

Note. If you want version information about EurekaLog in current module - there is no need to call any function. Such information is always available in EEurekaLogVersion (appendix C) and EEurekaLogLicense (appendix C) constants.

GetEurekaLogLicense

Gets EurekaLog license.

function GetEurekaLogLicense: String;

Return value.

Actual EurekaLog license information.

Example values:

'Trial'

'Professional'

'Enterprise'

'Registered' (for not installed EurekaLog)

Remarks.

This function returns information about EurekaLog. Thus, its behaviour is different depending on installed EurekaLog.

If EurekaLog is installed - function reads information about the installed EurekaLog from the registry.

If EurekaLog is not installed - function returns build-in information.

Note. If you want license information about EurekaLog in current module - there is no need to call any function. Such information is always available in EEurekaLogLicense (appendix C) constant.

GetEurekaLogLicenseType

Gets EurekaLog license type.

function GetEurekaLogLicenseType: String;

Return value.

Actual EurekaLog license type information.

Example values:

'Single Developer'

'MVP'

'Company'

'Corporate'

Remarks.

This function returns information about EurekaLog. Thus, its behaviour is different depending on installed EurekaLog.

If EurekaLog is installed - function reads information about the installed EurekaLog from the registry.

If EurekaLog is not installed - function returns build-in information.

GetEurekaLogPath

Obsolete function, do not use.

function GetEurekaLogPath: String;
deprecated'Use GetFolderEurekaLogAppData';

Remarks.

Warning. This function is provided for backward compatibility only. It may be removed in the next version of EurekaLog.

Use GetFolderEurekaLog function instead.

GetEurekaLogStatus

Gets EurekaLog stable/beta information.

function GetEurekaLogStatus: String;

Return value.

Status of current EurekaLog sources.

Example values:

'(BETA)'

Remarks.

Function returns build-in information. No registry is read.

GetEurekaLogVersion

Gets EurekaLog version.

function GetEurekaLogVersion: String;

Return value.

String representation of current EurekaLog's version.

Example value: '7.0.0.177'.

For beta versions, RC versions and other non-stable releases a suffix is added. Example: '7.0.0.177 RC 2'

Remarks.

This function is the same as EEurekaLogVersion (appendix C) constant.

represents EurekaLog's version number in the standard 4-number format 'A.B.C.D' plus optional suffix for non-stable releases.

GetFileIcon

Gets executable file's icon.

function GetFileIcon(
  const ADPI: Integer;
  const AFileName: String;
  ALarge: Boolean;
  ASz: PSize;
  const AIconName: UnicodeString = '';
  const ALoadFromRCData: Boolean = False
): HICON;

Parameters.

ADPI [in, optional] — DPI settings (96, 120, etc.). Pass 0 to use defaults.
AFileName [in] — Full executable file name (.exe, .dll, .bpl).
ALarge [in] — True - extract large icon, False - extract small icon.

Icon sizes are determinated from system settings and DPI. Usually it's values like 40x40 or 32x32 for large size and 20x20 or 16x16 for small size.

ASz [out, optional] — Actual icon size in pixels. Caller may use this value for rendering resulting icon.

This value is undefined if function fails.

Return value.

If the function succeeds, the return value is default icon's handle of the specified file.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks.

Creates handle to large or small icon extracted from the specified executable file, DLL, or package.

You must destroy all icons extracted by GetFileIcon by calling the DestroyIcon function.

GetFileSize

Gets file size.

function GetFileSize(
  const AFileName: String
): UInt64;

Parameters.

AFileName [in] — Full file name.

Return value.

If the function succeeds, the return value is size of the specified file in bytes.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks.

Retrieves the size of the specified file, in bytes.

GetUserEMail

Gets user's e-mail.

function GetUserEMail: String;

Return value.

E-mail or empty string.

Example value: 'example@example.com'

Remarks.

The e-mail value is stored in the registry under EurekaLog info key. It can be set by the SetUserEMail (appendix A, SetUserEmail) function. Usually this value is set by dialogs when user enters his e-mail for sending.

IsWin10

Detect Windows 10 (minimum).

function IsWin10: Boolean;

Return value.

True if current computer is running under Windows 10 or better, False otherwise.

Remarks.

This function will return True for both consumer (Windows 10) and server operating system.

This function will return True for any later operating systems.

Tip. This function can be used to determinate minimum required level of operating system.

IsWin11

Detect Windows 11 (minimum).

function IsWin11: Boolean;

Return value.

True if current computer is running under Windows 11 or better, False otherwise.

Remarks.

This function will return True for both consumer (Windows 11) and server operating system.

This function will return True for any later operating systems.

Tip. This function can be used to determinate minimum required level of operating system.

IsWin64

Detect OS bitness.

function IsWin64: Boolean;

Return value.

True if current computer is running under 64-bit Windows, False otherwise.

Remarks.

This function will return True for Windows XP 64-bit, Windows Vista 64-bit, Windows 7 64-bit, their server equivalents or any later 64-bit systems.

Tip. The result of this function doesn't depend on bitness of calling application.

IsWin7

Detect Windows 7 (minimum).

function IsWin7: Boolean;

Return value.

True if current computer is running under Windows 7 or better, False otherwise.

Remarks.

This function will return True for both consumer (Windows 7) and server (Windows Server 2008 R2) operating system.

This function will return True for any later operating systems.

Tip. This function can be used to determinate minimum required level of operating system.

IsWin8

Detect Windows 8 (minimum).

function IsWin8: Boolean;

Return value.

True if current computer is running under Windows 8 or better, False otherwise.

Remarks.

This function will return True for both consumer (Windows 8) and server (Windows Server 2012) operating system.

This function will return True for any later operating systems.

Tip. This function can be used to determinate minimum required level of operating system.

IsWin81

Detect Windows 8.1 (minimum).

function IsWin81: Boolean;

Return value.

True if current computer is running under Windows 8.1 or better, False otherwise.

Remarks.

This function will return True for both consumer (Windows 8.1) and server (Windows Server 2012 R2) operating system.

This function will return True for any later operating systems.

Tip. This function can be used to determinate minimum required level of operating system.

IsWinVista

Detect Windows Vista (minimum).

function IsWinVista: Boolean;

Return value.

True if current computer is running under Windows Vista or better, False otherwise.

Remarks.

This function will return True for both consumer (Windows Vista) and server (Windows Server 2008) operating system.

This function will return True for any later operating systems (Windows 7, etc.).

Tip. This function can be used to determinate minimum required level of operating system.

IsWinXP

Detect Windows XP (minimum).

function IsWinXP: Boolean;

Return value.

True if current computer is running under Windows XP or better, False otherwise.

Remarks.

This function will return True for both consumer (Windows XP) and server (Windows Server 2003) operating system.

This function will return True for any later operating systems (Windows Vista, Windows 7, etc.).

If function has returned False - the computer is running under Windows 2000.

Tip. This function can be used to determinate minimum required level of operating system.

IsWorkstation

Gets server/workstation status of current computer.

function IsWorkstation: Boolean;

Return value.

True if current computer is workstation, False otherwise (it's server).

Remarks.

Function determinate server/workstation status based on operating system version. For consumer operating systems (for example - Window XP, Windows 7) it will return True. For server operating systems (for example, Windows Server 2003, Windows Server 2008) it will return False.

This function can be used to distinguish between, say, Windows 7 and Windows 2008 R2, etc.

SetUserEmail

Sets user's e-mail.

procedure SetUserEmail(
  const AUserEmail: String
);

Parameters.

AUserEmail [in] — A user e-mail to be saved in registry.

Remarks.

The e-mail value is stored in the registry under EurekaLog info key. It can be retrieved later by the GetUserEMail (appendix A) function. Usually this value is set by dialogs when user enters his e-mail for sending.

EThreadsManager

AcquireThreadData

Returns thread information (any thread).

function AcquireThreadData(
  const AThreadID: Cardinal;
  const AForce: Boolean = False
): TEurekaThreadData;

Parameters.

AThreadID [in] — TID (Thread ID) of a thread to get information.
AForce [in, optional] — True: return dummy object for empty result, false (default): return nil for empty result.

Return value.

Information about the AThreadID thread. You have to destroy the returned object. This value could be nil for rare cases (such as calling this function before/after EThreadsManager's initialization/finalization), or if AThreadID does not identify a valid running thread. The return value is always non-nil if AForce argument is True.

Remarks.

Use this function to get information about any running thread.

You have to release the returned object. A new return value object is created for each function's call.

There is no need to use locking - because informational object (appendix D, TEurekaThreadData) for the thread will be individual for each function's call. Any change for dynamic properties (such as Name, LastException, LastHTMLPage) will be ignored. Use ThreadData (appendix A) function to modify thread's dynamic properties.

This function can return information about any running thread.

Note. This function returns information only about running threads. Return value will be empty if AThreadID identifies already terminated thread.

ThreadData

Returns thread information (current thread only).

function ThreadData: TEurekaThreadData;

Return value.

Information about current thread. Do not destroy the returned object. This value could be nil for rare cases (such as calling this function before/after EThreadsManager's initialization/finalization).

Remarks.

Use this function to get information about current thread.

There is no need to release the returned object.

There is no need to use locking - because informational object (appendix D, TEurekaThreadData) for current thread will exist until thread is terminated. Most thread properties are read-only and don't require synchronization. Dynamic properties (such as Name, LastException, LastHTMLPage) should be modified by current thread only.

This function can return information only about current thread. Use AcquireThreadData (appendix A) or ThreadDataEnum (appendix A) functions to get information about arbitrary thread.

ThreadDataEnum

Enumerates running threads.

function ThreadDataEnum(
  const AForceAllActive: Boolean = False
): TEurekaThreadDataList;

Parameters.

AForceAllActive [in, optional] — False (default) - return a copy of internal thread list. This list will contain all known threads. Note that known threads may not represent all threads in your application (for example, if you did not intall low-level hooks or disable EurekaLog in system threads). True - build and return a list of all running threads in application. Only active (still running) threads are returned.

Return value.

A list of threads. You have to delete this object after use. A new object is created for each function's call.

Remarks.

This function creates new list of threads and fills it with information about all known threads. The returned list should be deleted after use.

There is no need to use locking - because informational object (appendix D, TEurekaThreadDataList) for the thread list will be individual for each function's call. Any change for dynamic properties (such as Name, LastException, LastHTMLPage) will be ignored. Use ThreadData (appendix A) function to modify thread's dynamic properties.

EWCT

WCTDone

Finalize EWCT unit.

procedure WCTDone;

Remarks.

This function clears all dynamically linked routines. Call this function after using EWCT unit. This is an optional action.

WCTInit

Initialize EWCT unit.

procedure WCTInit;

Remarks.

This function imports all dynamically linked routines. Call this function before using EWCT unit.

EWER

InitWER

Initializes EWER unit.

procedure InitWER;

Remarks.

This function imports dynamically linked WER functions (such as ReportFault, WerReportSubmit, etc.).

Call this function before using EWER unit.

ExceptionLog7

LastBugID

Returns BugID of last exception in current thread.

function LastBugID: TBugID;

Return value.

BugID of last thread exception or 0 if there was no exception raised.

EZip

TZipCompressionToString

Converts ZIP compression method value to string representation.

function TZipCompressionToString(
  Compression: TZipCompression
): string;

Parameters.

Compression

Compression method to get its textual representation.

Return value.

String representation of Compression argument.

Remarks.

Example return values are:

'Unknown'
'Stored'
'Shrunk'
'Reduced1'
'Reduced2'
'Imploded'
'Tokenized'
Etc.