RegisterServiceCtrlHandlerExA 函式 (winsvc.h)

發行項
03/04/2024

註冊函式來處理擴充服務控制要求。

語法

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

參數

[in] lpServiceName

呼叫線程所執行之服務的名稱。這是建立服務時，CreateService 函式中指定的服務控制程式所指定的服務名稱。

[in] lpHandlerProc

要註冊之處理程式函式的指標。如需詳細資訊，請參閱 HandlerEx。

[in, optional] lpContext

任何使用者定義的數據。這個參數會傳遞至處理程式函式，有助於在多個服務共用進程時識別服務。

傳回值

如果函式成功，傳回值為服務狀態句柄。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

服務控制管理員可以設定下列錯誤碼。

傳回碼	Description
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法將 ANSI 字串參數轉換成 Unicode。 Unicode 字串參數不會發生此錯誤。
ERROR_SERVICE_NOT_IN_EXE	當呼叫 StartServiceCtrlDispatcher 函式的進程時，服務專案指定不正確。

備註

新服務的 ServiceMain 函式應該立即呼叫 RegisterServiceCtrlHandlerEx 函式，以向控件發送器註冊控件處理程式函式。這可讓控件發送器在收到此服務的控制要求時叫用指定的函式。如需可能控制程式代碼的清單，請參閱 HandlerEx。呼叫進程的線程可以使用此函式所傳回的服務狀態句柄，在後續呼叫 SetServiceStatus 函式時識別服務。

RegisterServiceCtrlHandlerEx 函式必須在第一次 SetServiceStatus 呼叫之前呼叫，因為 RegisterServiceCtrlHandlerEx 會傳回服務狀態句柄，讓呼叫端無法使用，讓其他服務無法意外設定此服務狀態。此外，控件處理程式必須在服務透過 SetServiceStatus 函式指定它接受的控制時接收控制要求。

使用控件要求叫用控件處理程式函式時，服務必須呼叫 SetServiceStatus ，只有在服務狀態變更時，才會向服務控制管理員報告狀態，例如當服務正在處理停止或關機控件時。如果服務狀態尚未變更，服務不應該向服務控制管理員報告狀態。

服務狀態句柄不需要關閉。

注意

winsvc.h 標頭會將 RegisterServiceCtrlHandlerEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

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