The Bug Validator stub service libraries

 

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

 

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

 

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

 

 

Loading the Bug Validator DLL into your service

 

To load the Bug Validator stub dll svlBugValidatorStub.dll into your service, call svlBVStub_LoadBugValidator(), do not call LoadLibrary().

 

 

Shutting down the Bug Validator DLL from your service.

 

To shutdown Bug Validator's monitoring of the service , call svlBVStub_ShutdownBugValidator().

 

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

 

To unload the Bug Validator stub dll, call svlBVStub_UnloadBugValidator(), 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 Bug 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 Bug 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 svlBVStub_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)
         svlBVStub_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.

 

   svlBVStub_SetServiceCallback(NULL, NULL);.

 

 

Starting Bug Validator DLL in your service

 

To start Bug Validator inspecting your service call svlBVStub_StartBugValidator().

 

 

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

 

 

Deleting the logfile

 

To delete the log file call svlBVStub_deleteLogFile().

 

 

Writing text to the logfile

 

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

 

 

Dumping the PATH environment to the logfile

 

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