API changes - February 2018

 

To make the API easier to use with services we made the following changes:

 

•Changed the API by adding many debugging functions to allow you to easily log information.

 

•We also extended the error enumeration to provide additional error status values.

 

•We also split the function of loading and starting Performance Validator into two functions - a load function and a start function.

 

•We split the functionality so that you could setup a service callback prior to calling the start function.

 

The service callback allows the service control manager to be informed that the service is still active during time consuming operations, such as starting the Performance Validator when the service is non-trivial in scope.

 

Failure to inform the service control manager results in the service being killed by the service control manager because it thinks the service has hung.

 

This change in the API is to ensure you get better results from using our software.

 

 

What do you need to do to move from the old API to the new API?

 

Change all SVL_ERROR declarations to SVL_SERVICE_ERROR.

 

Your previous startup code probably looked like this:

 

   SVL_ERROR errCode;
 
   errCode = svlPVStub_LoadPerformanceValidator();

 

 

Change it to this:

 

   SVL_SERVICE_ERROR errCode;
 
   errCode = svlPVStub_LoadPerformanceValidator();
 
   errCode = svlPVStub_SetServiceCallback(serviceCallback, NULL);
 
   errCode = svlPVStub_StartPerformanceValidator();

 

 

The serviceCallback would look something like this:

 

   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);
   }

 

In the code above we have omitted error handling. To see how to use the new logging function with error handling please examine the source code service.cpp in the example service project.

 

 

Important.

 

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);.