Output the Sequence of Function Calls Using a Custom DLL

Applies to AQTime 8.81, last modified on January 18, 2022

The Function Trace profiler traces the hierarchy of function calls in your application. It can display function call stacks in AQTime’s Report panel or it can output profiling results into a text file or to the CodeSite tool.

If you need special processing for results, you can create a dynamic link library. AQTime loads this DLL upon the profiler start and unloads after the profiling is over. The Function Trace profiler sends information about each function call to the library, which, in its turn, performs further result processing.

This dynamic link library must export the following functions:

C++

void __stdcall Tracer_OnStartProfiling(BOOL Enabled);

void __stdcall Tracer_OnStopProfiling();

void __stdcall Tracer_OnEnabledChanged(BOOL Enabled);

void __stdcall Tracer_OnThreadCreate(LPCWSTR Thread);

void __stdcall Tracer_OnRoutineEnter(LPCWSTR RoutineName,
                                     LPCWSTR ClassName,
                                     LPCWSTR ModuleName,
                                     LPCWSTR UnitName,
                                     LPCWSTR Thread,
                                     PAQPROF_PARAMETER_DATA Param);

void __stdcall Tracer_OnRoutineExit (LPCWSTR RoutineName,
                                     LPCWSTR ClassName,
                                     LPCWSTR ModuleName,
                                     LPCWSTR UnitName,
                                     LPCWSTR Thread,
                                     PAQPROF_PARAMETER_DATA Param);

void __stdcall Tracer_OnExceptionThrown (LPCWSTR RoutineName,
                                     LPCWSTR ClassName,
                                     LPCWSTR ModuleName,
                                     LPCWSTR UnitName,
                                     LPCWSTR Thread);
typedef void* CVOID_PTR;
typedef struct AQPROF_PARAMETER_DATA
  {
    BSTR Type;
    BSTR Value;
    CVOID_PTR pNextParameter;
  } AQPROF_PARAMETER_DATA, *PAQPROF_PARAMETER_DATA;

The Tracer_OnStartProfiling function is called upon starting the Function Trace profiler. The Enabled parameter indicates whether profiling is turned on. Remember that you can switch the profiling state with the Enable/Disable Profiling toolbar and menu item or with the EnableProfiling function (see Controlling Profiling From Application Code). If this occurs, the Tracer_OnEnabledChanged function is called with Enabled to specify the new profiling state. When the profiling is over, the OnStopProfiling function is called.

The Tracer_OnThreadCreate function is called when a new thread is created, the Thread parameter contains the thread ID or the thread name (see Assigning Names to Threads).

The Tracer_OnRoutineEnter function is called when the profiled application enters a function. The Tracer_OnRoutineExit function is called when the application exits a function. Both functions have the same parameters that allow AQTime to identify the profiled routine:

Parameter Description
RoutineName The name of the profiled routine.
ClassName The name of the class where the profiled routine is declared.
ModuleName The name of the module where the profiled routine is declared.
UnitName The name of the linkage unit that holds the routine.
Thread The ID or name of the thread that called the profiled routine.
Param A pointer to the AQPROF_PARAMETER_DATA structure that holds a linked list of parameters passed to the current routine call. For information about how parameters are interpreted, see the Tracing Function Call Parameters and Result Values topic. The structure’s fields Type and Value contain the parameter’s data type and value, the pNextParameter field is a pointer to the next parameter passed to this routine. In case the parameter’s value cannot be displayed, the corresponding fields will hold an empty string.

The Tracer_OnExceptionThrown function is called upon exception. The values of the RoutineName, ClassName, ModuleName, UnitName and Thread parameters specify the routine, class, module, unit and thread where the exception occurred.

For more information on how to create dynamic link libraries, see your development tool’s documentation.

See Also

Function Calls Tracing
Best Practices and How to Tutorials
Function Trace Profiler - Overview

Highlight search results