RegisterServiceCtrlHandlerA 函式 (winsvc.h)

發行項
03/13/2024

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

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

語法

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
  [in] LPCSTR             lpServiceName,
  [in] LPHANDLER_FUNCTION lpHandlerProc
);

參數

[in] lpServiceName

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

如果服務類型SERVICE_WIN32_OWN_PROCESS，則函式不會驗證指定的名稱是否有效，因為進程中只有一個已註冊的服務。

[in] lpHandlerProc

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

傳回值

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

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

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

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

備註

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

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

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

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

範例

如需範例，請參閱撰寫 ServiceMain 函式。

注意

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

規格需求

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