LPHANDLER_FUNCTION回呼函式 (winsvc.h)

搭配 RegisterServiceCtrlHandler 函式使用的應用程式定義回呼函式。 服務程式可以使用它作為特定服務的控制處理程式函式。

LPHANDLER_FUNCTION類型會定義此函式的指標。 Handler 是應用程式定義名稱的佔位元。

此函式已被與 RegisterServiceCtrlHandlerEx 函式搭配使用的 HandlerEx 控制項處理程式函式取代。 服務可以使用任一控件處理程式，但新的控件處理程式支援使用者定義的內容數據和額外的擴充控件程序代碼。

語法

LPHANDLER_FUNCTION LphandlerFunction;

void LphandlerFunction(
  DWORD dwControl
)
{...}

參數

dwControl

傳回值

無

備註

啟動服務時，其 ServiceMain 函式應該會立即呼叫 RegisterServiceCtrlHandler 函式，以指定 Handler 函式來處理控制要求。

每當從服務控制管理員收到控制要求時，服務進程主線程中的控制發送器會叫用指定服務的控件處理程式函式。 處理控件要求之後，如果服務狀態變更以向服務控制管理員報告其新狀態，控件處理程式就必須呼叫 SetServiceStatus 函式。

控制處理程式函式的目的是要立即接收通知並傳回。 回呼函式應該儲存其參數，並建立其他線程來執行其他工作。 (您的應用程式必須確定這類線程在停止 service.) 之前已結束，特別是控制處理程式應該避免可能會封鎖的作業，例如進行鎖定，因為這可能會導致死結或導致系統停止回應。

當服務控制管理員將控制程式代碼傳送至服務時，它會等候處理程式函式傳回，再將其他控制程式碼傳送至其他服務。 控件處理程式應該儘快傳回;如果未在 30 秒內傳回，SCM 會傳回錯誤。 如果服務在執行控制處理程式時必須執行冗長的處理，它應該建立次要線程來執行冗長的處理，然後從控件處理程式傳回。 這可防止服務將控制發送器系結，並封鎖其他服務接收控制碼。

SERVICE_CONTROL_SHUTDOWN控制程式代碼應該只由必須在關機期間絕對清除的服務處理，因為服務關機 (大約 20 秒) 時間有限。 此時間到期之後，不論服務關機是否完成，系統關機都會繼續進行。 請注意，如果系統處於關機狀態， (未重新啟動或關閉電源) ，服務會繼續執行。 如果您的服務註冊接受 SERVICE_CONTROL_SHUTDOWN，它必須處理控制程式代碼並及時停止。 否則，服務可以增加關閉系統所需的時間，因為系統必須等候服務關機的完整時間，系統才能繼續系統關機。

如果服務需要更多時間來清除，它應該傳送 STOP_PENDING 狀態消息，以及等候提示，因此服務控制者知道在回報服務關機完成的系統之前要等候多久。 不過，若要防止服務停止關機，服務控制站等候的時間長度有限制。 如果服務正在透過服務嵌入式管理單元關閉，則限製為125秒。 如果操作系統重新啟動，則會在下列登錄機碼的 WaitToKillServiceTimeout 值中指定時間限制：

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

服務也可以使用 SetConsoleCtrlHandler 函式來接收關機通知。 當執行中的應用程式關閉時，就會收到此通知，這會在服務關閉之前發生。

範例

如需範例，請參閱 撰寫控件處理程式函式。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	winsvc.h (包含 Windows.h)

另請參閱

HandlerEx

RegisterServiceCtrlHandler

服務控制處理函式

服務函式

ServiceMain

SetServiceStatus