Writing a Control Handler Function

  • Article

When a Handler function is called by the dispatcher thread, it handles the control code passed in the Opcode parameter and then calls the ReportSvcStatus function to update the service status. When a Handler function receives a control code, it should report the service status only if handling the control code causes the service status to change. If the service does not act on the control, it should not report status to the service control manager. For the source code for ReportSvcStatus, see Writing a ServiceMain Function.

In the following example, the SvcCtrlHandler function is an example of a Handler function. Note that the ghSvcStopEvent variable is a global variable that should be initialized and used as demonstrated in Writing a ServiceMain function.

//
// Purpose: 
//   Called by SCM whenever a control code is sent to the service
//   using the ControlService function.
//
// Parameters:
//   dwCtrl - control code
// 
// Return value:
//   None
//
VOID WINAPI SvcCtrlHandler( DWORD dwCtrl )
{
   // Handle the requested control code. 

   switch(dwCtrl) 
   {  
      case SERVICE_CONTROL_STOP: 
         ReportSvcStatus(SERVICE_STOP_PENDING, NO_ERROR, 0);

         // Signal the service to stop.

         SetEvent(ghSvcStopEvent);
         ReportSvcStatus(gSvcStatus.dwCurrentState, NO_ERROR, 0);
         
         return;
 
      case SERVICE_CONTROL_INTERROGATE: 
         break; 
 
      default: 
         break;
   } 
   
}

Service Control Handler Function

The Complete Service Sample