The Coverage Validator stub service libraries

 

The NT Service API is very simple, consisting of functions to load and unload the Coverage Validator DLL.

 

We have also provided some debugging functions to help you debug the implementation of the NT Service API because getting data into and out of services is not always straightforward.

 

The stub service libraries used for this are shown in the following table:

 

 

 

All the functions exported from these libraries are exported as extern "C" so that C and C++ users can use them.

 

Library name suffixes

 

The MD suffix indicates the library was built with the /MD compiler switch.

The MT suffix indicates the library was built with the /MT compiler switch.

 

Directory Name: 2010 or 2012?

 

Visual Studio 6 to Visual Studio 2010

If you are using Visual Studio 2010 or earlier, use libraries from a directory with 2010 in the directory name.

 

Visual Studio 2010 to Visual Studio 2022

If you are using Visual Studio 2012 or later, use libraries from a directory with 2012 in the directory name.

 

 

Header files

 

The header files can be found in the svlCVStubService directory in the Coverage Validator install directory.

 

The headers file provide an error enumeration and the NT Service API functions.

 

 svlCVStubService.h

 svlServiceError.h

 

 

Linker Problems

 

Some linkers cannot link the stub service library file.  If you have this problem see What do I do if I cannot use svlCVStubService.lib?

 

 

Loading the Coverage Validator DLL into your service

 

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

 

If you are monitoring a 32 bit service with the 64 bit Coverage Validator user interface you should use svlCVStub_LoadCoverageValidator6432().

 

 

Shutting down the Coverage Validator DLL from your service.

 

To shutdown Coverage Validator's monitoring of 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.

 

 

Unloading the Coverage Validator DLL from your service.

 

To unload the Coverage Validator stub dll, call svlCVStub_UnloadCoverageValidator(), not FreeLibrary().

 

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

 

 

Setting a service notification callback

 

Once you have successfully loaded the Coverage Validator DLL you can setup a service callback so that the service control manager can be kept updated during the process of starting the validator.

 

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.

 

You can set the service callback with svlCVStub_SetServiceCallback(callback, userParam).

 

Usage

 

Here is an example callback which ignores the userParam.

 

   void serviceCallback(void   *userParam)
   {
       static DWORD dwCheckPoint = 1;
   
       ssStatus.dwServiceType = SERVICE_WIN32_OWN_PROCESS;
       ssStatus.dwServiceSpecificExitCode = 0;
 
       ssStatus.dwControlsAccepted = 0;
      
       ssStatus.dwCurrentState = dwCurrentState;
       ssStatus.dwWin32ExitCode = dwWin32ExitCode;
       ssStatus.dwWaitHint = dwWaitHint;
      
       ssStatus.dwCheckPoint = dwCheckPoint++;
      
       // Report the status of the service to the service control manager.
 
       return SetServiceStatus( sshStatusHandle, &ssStatus);
   }

 

Once your service is running (rather than starting) your service callback should set the appropriate running status SERVICE_RUNNING rather than SERVICE_START_PENDING.

 

   if (!ReportStatusToSCMgr(SERVICE_RUNNING,       // service state
                            NO_ERROR,              // exit code
                            0))                    // wait hint
   {
      dwErr = GetLastError();
      if (bLogging)
         svlCVStub_writeToLogFileW(L"ReportStatusToSCMgr:5\r\n");
      goto cleanup;
   }

 

An alternative solution is to prevent the service callback from being called once the service status has been set to running.

 

   svlCVStub_SetServiceCallback(NULL, NULL);.

 

 

Starting Coverage Validator DLL in your service

 

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

 

 

Starting Coverage Validator DLL in IIS

 

To start Coverage Validator inspecting IIS call svlCVStub_StartCoverageValidatorForIIS().

 

 

Setting a filename for all logging data to be written to

 

To set the filename for all debugging/logging information to be written to call svlCVStub_setLogFileName().

 

 

Deleting the logfile

 

To delete the log file call svlCVStub_deleteLogFile().

 

 

Writing text to the logfile

 

To write a standard ANSI character string to the log file call svlCVStub_writeToLogFileA(text). The ANSI string will be converted to Unicode prior to writing to the log file.
 

To write a Unicode character string to the log file call svlCVStub_writeToLogFileW(text).

 

 

Writing error code descriptions to the logfile

 

To write a human readable description of the SVL_SERVICE_ERROR error code to the log file call svlCVStub_writeToLogFile(errCode).

 

 

Writing LastError code descriptions to the logfile

 

To write a human readable description of the Windows error code to the log file call svlCVStub_writeToLogFileLastError(errCode).

 

 

Dumping the PATH environment to the logfile

 

To write the contents of the PATH environment variable to the log file call svlCVStub_dumpPathToLogFile().

 

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.