The Performance Validator stub service libraries

 

The NT Service API is very simple, consisting of functions to load, start and unload the Performance 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 svlPVStubService directory in the Performance Validator install directory.

 

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

 

 svlPVStubService.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 svlPVStubService.lib?

 

 

Loading the Performance Validator DLL into your service

 

To load the Performance Validator stub dll svlPerformanceValidatorStub(_x64).dll into your service, call svlPVStub_LoadPerformanceValidator(), not LoadLibrary().

 

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

 

 

Shutting down the Performance Validator DLL from your service.

 

To shutdown Performance Validator's monitoring of the service , call svlPVStub_ShutdownPerformanceValidator().

 

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 Performance Validator DLL from your service.

 

To unload the Performance Validator stub dll, call svlPVStub_UnloadPerformanceValidator(), 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 Performance 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 Performance 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 svlPVStub_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)
         svlPVStub_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.

 

   svlPVStub_SetServiceCallback(NULL, NULL);.

 

 

Starting Performance Validator DLL in your service

 

To start Performance Validator profiling your service call svlPVStub_StartPerformanceValidator.

 

 

Starting Performance Validator DLL in IIS

 

To start Performance Validator profiling IIS call svlPVStub_StartPerformanceValidatorForIIS().

 

 

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 svlPVStub_setLogFileName().

 

 

Deleting the logfile

 

To delete the log file call svlPVStub_deleteLogFile().

 

 

Writing text to the logfile

 

To write a standard ANSI character string to the log file call svlPVStub_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 svlPVStub_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 svlPVStub_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 svlPVStub_writeToLogFileLastError(errCode).

 

 

Dumping the PATH environment to the logfile

 

To write the contents of the PATH environment variable to the log file call svlPVStub_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.