Please enable JavaScript to view this site.

Coverage Validator Help

The API consists of the following functions.

 

SVL_SERVICE_ERROR Enumeration

 

typedef enum _svlServiceError
{
   SVL_OK,                                                              // Normal behaviour
   SVL_ALREADY_LOADED,                                                  // Stub DLL already loaded into service
   SVL_LOAD_FAILED,                                                     // Failed to load stub DLL into service
   SVL_FAILED_TO_ENABLE_STUB_SYMBOLS,                                   // Loaded DLL, but failed to enable stub symbols because couldn't find function
   SVL_NOT_LOADED,                                                      // Couldn't unload DLL because DLL not loaded
   SVL_FAIL_UNLOAD,                                                     // Couldn't unload DLL because couldn't find function
   SVL_FAIL_TO_CLEANUP_INTERNAL_HEAP,                                   // Couldn't get the internal stub heap and thus couldn't clean it up
   SVL_FAIL_MODULE_HANDLE                                               // Couldn't get the stub DLL handle so couldn't continue
   SVL_FAIL_SETSERVICECALLBACK,                                         // Couldn't call the set service callback

   SVL_FAIL_COULD_NOT_FIND_ENTRY_POINT,                                 // Couldn't find the DLL entry point to start the validator

   SVL_FAIL_TO_START,                                                   // Failed to start the Validator

   SVL_FAIL_SETSERVICECALLBACKTHRESHOLD,                                // Couldn't call the set service callback threshold

   SVL_FAIL_PATHS_DO_NOT_MATCH,                                        // Path to service in env vars doesn't match the service being run

   SVL_FAIL_INCORRECT_PRODUCT_PREFIX,                                // Wrong validator

   SVL_FAIL_X86_VALIDATOR_FOUND_EXPECTED_X64_VALIDATOR,        // Found wrong bit depth validator

   SVL_FAIL_X64_VALIDATOR_FOUND_EXPECTED_X86_VALIDATOR,        // Found wrong bit depth validator

   SVL_FAIL_DID_YOU_MONITOR_A_SERVICE_FROM_VALIDATOR,                // Looks like Monitor A Service wasn't used

   SVL_FAIL_ENV_VAR_NOT_FOUND,                                        // Env Var not found

   SVL_FAIL_VALIDATOR_ENV_VAR_NOT_FOUND,                                // Env Var identifying validator not found

   SVL_FAIL_VALIDATOR_ID_NOT_SPECIFIED,                                // Validator process not specified

   SVL_FAIL_VALIDATOR_ID_NOT_A_PROCESS,                                // Validator process identified doesn't exist

   SVL_FAIL_VALIDATOR_NOT_FOUND,                                        // Validator process identified doesn't exist

} SVL_SERVICE_ERROR;

 

 

svlCVStub_LoadCoverageValidator

 

 extern "C" 

 SVL_SERVICE_ERROR svlCVStub_LoadCoverageValidator();
 

To load the Coverage Validator stub svlCoverageValidatorStub.dll into your service, use svlCVStub_LoadCoverageValidator(), not LoadLibrary().

 

This loads the DLL and sets up a few internal variables in the DLL to ensure that symbols are sent from the stub to the Coverage Validator user interface.

 

This is necessary because the Coverage Validator user interface can't open a process handle to a service and so is unable to get symbols from the process.

 

To solve this, symbols are sent from the stub to the user interface as needed.

 

If you just call LoadLibrary() on the DLL, symbols will not be sent to the Coverage Validator user interface and you won't get meaningful function names in your stack traces.

 

This function can be used when monitoring:

 

32 bit services or applications with Coverage Validator
 

64 bit services or applications with Coverage Validator x64

 

If you are monitoring 32 bit applications with Coverage Validator x64 you should use svlCVStub_LoadCoverageValidator6432().

 

Which function you should call is shown in the table below.

 


32 bit Coverage Validator

64 bit Coverage Validator

32 bit service

svlCVStub_LoadCoverageValidator()

svlCVStub_LoadCoverageValidator6432()

64 bit service

N/A

svlCVStub_LoadCoverageValidator()

 

 

svlCVStub_LoadCoverageValidator6432

 
 extern "C" 

 SVL_SERVICE_ERROR svlCVStub_LoadCoverageValidator6432();
 

To load the Coverage Validator stub svlCoverageValidatorStub6432.dll into your service, use svlCVStub_LoadCoverageValidator6432(), not LoadLibrary().

 

This loads the DLL and sets up a few internal variables in the DLL to ensure that symbols are sent from the stub to the Coverage Validator user interface.

 

This is necessary because the Coverage Validator user interface can't open a process handle to a service and so is unable to get symbols from the process.

 

To solve this, symbols are sent from the stub to the user interface as needed.

 

If you just call LoadLibrary() on the DLL, symbols will not be sent to the Coverage Validator user interface and you won't get meaningful function names in your stack traces.

 

This function should only be used when monitoring 32 bit services or applications with Coverage Validator x64.

 

 

svlCVStub_StartCoverageValidator

 
 extern "C" 

 SVL_SERVICE_ERROR svlCVStub_StartCoverageValidator();

 

To start Coverage Validator inspecting the service call svlCVStub_StartCoverageValidator().

 

 

svlCVStub_StartCoverageValidatorForIIS

 

 extern "C"

 SVL_SERVICE_ERROR svlCVStub_StartCoverageValidatorForIIS();
 

To start Coverage Validator inspecting IIS call svlCVStub_StartCoverageValidatorForIIS().

 

Example usage.

 

 

svlCVStub_ShutdownCoverageValidator

 

 extern "C" 

 SVL_SERVICE_ERROR svlCVStub_ShutdownCoverageValidator();

 

To stop Coverage Validator inspecing the service call svlCVStub_ShutdownCoverageValidator().

 

This sends the shutting down notification and removes any hooks for your process.

 

Calling this function is optional. You can stop your service without calling this function.

 

 

svlCVStub_UnloadCoverageValidator

 
 extern "C" 

 SVL_SERVICE_ERROR svlCVStub_UnloadCoverageValidator();
 

To unload Coverage Validator call svlCVStub_UnloadCoverageValidator(), do not call FreeLibrary().

 

Calling this function is optional. You can stop your service without calling this function.

 

 

svlCVStub_SetServiceCallback

 
 extern "C" 

 SVL_SERVICE_ERROR svlCVStub_SetServiceCallback(serviceCallback_FUNC callback,
                                                      void*                userParam);
 

svlCVStub_SetServiceCallback is used to setup a service callback that is used to inform the Windows service control manager that the service is alive.

 

userParam is a value you can supply which will then be passed to the callback every time the callback is called during instrumentation.

 

 

Why is a service callback needed?

 

When a service is starting, Windows requires the service to inform the Service Control Manager (SCM) that is starting at least every ten seconds.

 

Failure to do so results in Windows concluding that the service has failed to start, and the service is terminated.

 

Instrumenting your service may well take more than 10 seconds, depending on the complexity and size of your service.

 

The solution is for Coverage Validator to periodically call a user supplied callback from which you can regularly inform the SCM of the appropriate status.

 

 

We strongly recommend that you setup a service callback. Not setting a service callback can result in failure of your service to run because Windows kills it during startup and Coverage Validator's instrumentation phase.

 

 

Debugging functions

 

The following functions are provided to help you log information about the progress, success or failure of the NT Service API attaching Coverage Validator to your service.

 

We strongly recommend that you use these logging functions so that you can understand why Coverage Validator might fail to connect to a service.

 

To see example usage of these debugging functions please look in service.cpp in the examples\service directory in the Coverage Validator install directory.

 

 
svlCVStub_setLogFileName

 
 extern "C" 

 void svlCVStub_setLogFileName(const wchar_t* fileName);
 

 

Call svlCVStub_setLogFileName to set the name of the filename used for logging.

 

This function must be called before you can use any of the other debugging functions.

 

Setting this filename also sets the filename used by some of these API functions - you will find additional logging data from those functions that will help debug any issues with the service.

 

 

svlCVStub_deleteLogFile

 
 extern "C"

 void svlCVStub_deleteLogFile();
 

This function deletes the log file.

 

 

svlCVStub_writeToLogFileA

 
 extern "C" 

 void svlCVStub_writeToLogFileA(const char* text);
 

This function writes a standard ANSI character string to the log file.

 

The ANSI string will be converted to Unicode prior to writing to the log file.

 

 

svlCVStub_writeToLogFileW

 
 extern "C"

 void svlCVStub_writeToLogFileW(const wchar_t* text);
 

This function writes a Unicode character string to the log file.

 

 

svlCVStub_writeToLogFile

 
 extern "C"

 void svlCVStub_writeToLogFile(SVL_SERVICE_ERROR errCode);
 

This function writes a human readable description of the SVL_SERVICE_ERROR error code to the log file.

 

 

svlCVStub_writeToLogFileLastError

 
 extern "C"

 void svlCVStub_writeToLogFileLastError(DWORD errCode);
 

This function writes a human readable description of the Windows error code to the log file.

 

The errCode parameter is the error code returned from GetLastError().

 

 

svlCVStub_dumpPathToLogFile

 
 extern "C"

 void svlCVStub_dumpPathToLogFile();

 

This function writes the contents of the PATH environment variable to the log file.

 

This can be useful if you want to know what the search path is when trying to debug why a DLL wasn't found during an attempt to load the Validator DLL.