The Memory Validator stub service libraries

 

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

 

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

 

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

 

 

Loading the Memory Validator DLL into your service

 

To load the Memory Validator stub dll svlMemoryValidatorStub(_x64).dll into your service, call svlMVStub_LoadMemoryValidator(), not LoadLibrary().

 

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

 

 

Shutting down the Memory Validator DLL from your service.

 

To shutdown Memory Validator's monitoring of the service , call svlMVStub_ShutdownMemoryValidator().

 

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

 

To unload the Memory Validator stub dll, call svlMVStub_UnloadMemoryValidator(), 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 Memory 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 Memory 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 svlMVStub_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);
   }

 

 

Starting Memory Validator DLL in your service

 

To start Memory Validator detecting memory leaks in your service call svlMVStub_StartMemoryValidator.

 

 

Starting Memory Validator DLL in IIS

 

To start Memory Validator profiling IIS call svlMVStub_StartMemoryValidatorForIIS().

 

 

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

 

 

Deleting the logfile

 

To delete the log file call svlMVStub_deleteLogFile().

 

 

Writing text to the logfile

 

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

 

 

Dumping the PATH environment to the logfile

 

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