共用方式為


RegisterServiceCtrlHandlerExA 函式 (winsvc.h)

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

語法

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

另請參閱

CreateService

HandlerEx

服務控制處理函式

服務函式

ServiceMain

SetServiceStatus