Please enable JavaScript to view this site.

Bug Validator Help

Navigation: » No topics above this level «

Native API

Scroll Prev Top Next More


The Bug Validator API


There are some features of Bug Validator that are useful to call directly from your program, including tracking of memory in custom heap managers.


Bug Validator has an API that makes this possible; just include svlBVAPI.c and svlBVAPI.h to your codebase. There is no library to link to, dlls to copy.



Source files


The source files can be found in the API directory in the Bug Validator install directory.





Just add these files to your project and build.
If you are using precompiled headers you will need to disable them for svlBVAPI.c.



Working with services?


If you are working with services you to attach Bug Validator to a service and to start Bug Validator, you should use the NT Service API, not the functions in this API.


All the other functions in this API can be used with applications and with services.



Unicode or ANSI?


All the API functions are provided in Unicode and ANSI variants where strings are used. We've also provided a character width neutral #define in the same fashion that the Windows.h header files do.


For example the function for naming a heap is provided as bvSetHeapNameA(), bvSetHeapNameW() with the character width neutral bvSetHeapName() mapping to bvSetHeapNameW() for unicode and bvSetHeapNameA() for ANSI.


In this document we're going to use TCHAR like the Window.h header files do.



Loading the Profiler


For most use cases won't need to load the profiler, as the profiler will have been loaded when your launched your program from Bug Validator, or when you injected into your program using Inject or Wait For Application.


However if you're running your program from outside of Bug Validator and want to load the profiler from inside your program you can use bvLoadProfiler() to do that. You'll then need to call bvStartProfiler() to start it.


Function Definition:


extern "C" 

void bvLoadProfiler();



If you are using services, you should use the NT Service API to attach Bug Validator to your service, not the functions in this API.



Starting the Profiler


To start the profiler from your API code you need to call the function "startProfiler" from your code before you call any API functions. Ideally you should call this function as early in your program as possible.


Function Definition:


extern "C" 

void bvStartProfiler();


If you prefer to start the profiler from the user interface or command line you can omit the startProfiler() call. You can leave it present if you wish to start Bug Validator from your program.


All the API functions are declared as extern "C", so C as well as  C++ users can use them.



If you are using services, you should use the NT Service API to start Bug Validator, not the functions in this API.





Sets the name of a thread.


extern "C" 
void bvSetThreadNameA(DWORD                threadID

                      const char        *name);





Sets the name of a thread.


extern "C" 
void bvSetThreadNameW(DWORD                threadID

                      const wchar_t        *name);





Enables or disables data collection - i.e. whether data is sent to Bug Validator from your target application.


extern "C" 
void bvSetCollect(int enable); // TRUE to enable, FALSE to disable





Returns whether data collection is on.


extern "C" 
int bvGetCollect();                 // Returns TRUE or FALSE



Calling API functions using GetProcAddress


If you don't want to use the svlBVAPI.c/h files you can use GetProcAddress to find the interface functions in the Bug Validator DLL.


The interface functions have different names and do not use C++ name mangling, but have identical parameters to the API functions.


To determine the function name take any native API name, replace the leading bv with api. For example bvSetThreadNameW() becomes apiSetThreadNameW();



Example usage


HMODULE getValidatorModule()
   HMODULE   hModule;
   hModule = GetModuleHandle("svlBugValidatorStub6432.dll");                // 32 bit DLL with 64 bit Bug Validator GUI
   if (hModule == NULL)
      hModule = GetModuleHandle("svlBugValidatorStub_x64.dll");        // 64 bit DLL with 64 bit Bug Validator GUI
   if (hModule == NULL)
      hModule = GetModuleHandle("svlBugValidatorStub.dll");                // 32 bit DLL with 32 bit Bug Validator GUI
   return hModule;

// get module, will only succeed if Bug Validator launched this app or is injected into this app
hMod = getValidatorModule();
if (hMod != NULL)
    // MV is present, lookup the function and call it to set a watermark for this location in the code
    bvSetThreadNameW_FUNC   pFunc;
    // "apiSetThreadNameW" is equivalent to linking against "bvSetThreadNameW"
    pFunc = (bvSetThreadNameW_FUNC)GetProcAddress(hMod, "apiSetThreadNameW");
    if (pFunc != NULL)



API functions and their GetProcAddress names


For any API functions not listed, try looking up the name in svlBugValidatorStub.dll using depends.exe




Other exported functions


You may see some other functions exported from svlBugValidatorStub.dll(_x64).dll.


warningnote These other functions are for Bug Validator's use. Using them may damage memory locations and/or crash your code. Best not to use them!