SetServiceStatus 函式 (winsvc.h)

發行項
03/13/2024

匯報呼叫服務的服務控制管理員狀態資訊。

語法

BOOL SetServiceStatus(
  [in] SERVICE_STATUS_HANDLE hServiceStatus,
  [in] LPSERVICE_STATUS      lpServiceStatus
);

參數

[in] hServiceStatus

目前服務之狀態信息結構的句柄。 RegisterServiceCtrlHandlerEx 函式會傳回此句柄。

[in] lpServiceStatus

SERVICE_STATUS 結構的指標，包含呼叫服務的最新狀態資訊。

傳回值

如果函式成功，則傳回非零的值。

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

服務控制管理員可以設定下列錯誤碼。服務控制管理員所呼叫的登錄函式可以設定其他錯誤碼。

傳回碼	Description
ERROR_INVALID_DATA	指定的服務狀態結構無效。
ERROR_INVALID_HANDLE	指定的句柄無效。

備註

ServiceMain 函式會先呼叫 RegisterServiceCtrlHandlerEx 函式，以取得服務的SERVICE_STATUS_HANDLE。然後，它會立即呼叫 SetServiceStatus 函式，以通知服務控制管理員其狀態為SERVICE_START_PENDING。在初始化期間，服務可以提供更新的狀態，以指出其正在進行中，但需要更多時間。常見的 Bug 是讓服務讓主線程執行初始化，而個別線程會繼續呼叫 SetServiceStatus ，以防止服務控制管理員將它標示為無回應。不過，如果主線程停止回應，則服務最終會以無限循環啟動，因為背景工作線程會繼續報告主線程正在進行中。

處理控件要求之後，如果服務狀態變更為向服務控制管理員報告其新狀態，服務處理程式函式必須呼叫 SetServiceStatus 。只有在服務正在變更狀態時，才需要這麼做，例如處理停止或關機控件時。服務也可以隨時從服務的任何線程使用此函式，以通知服務控制管理員狀態變更，例如服務何時必須因為可復原的錯誤而停止。

服務只有在呼叫 RegisterServiceCtrlHandlerEx 以取得服務狀態句柄之後，才能呼叫此函式。

如果服務呼叫 SetServiceStatus 且 dwCurrentState 成員設定為 SERVICE_STOPPED 且 dwWin32ExitCode 成員設定為非零值，下列專案會寫入 System 事件記錄檔中：

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = <ServiceName> terminated with the following error:
                 <ExitCode>.

以下是呼叫此函式時的最佳做法：

初始化 SERVICE_STATUS 結構中的所有欄位，確保有有效的檢查點和等候提示值，以取得擱置狀態。使用合理的等候提示。
當狀態SERVICE_START_PENDING或服務可能會當機時，請勿註冊以接受控件。初始化完成後，請接受SERVICE_CONTROL_STOP程序代碼。
只有在服務正在進行與擱置啟動、停止、暫停或繼續作業相關的工作進行時，才使用檢查點和等候提示值呼叫此函式。否則，SCM 無法偵測您的服務是否無回應。
如果 ServiceMain 失敗，請輸入具有適當結束代碼的已停止狀態。
如果狀態SERVICE_STOPPED，請執行所有必要的清除，並只呼叫 SetServiceStatus 一次。此函式會對 SCM 進行 LRPC 呼叫。第一次呼叫處於SERVICE_STOPPED狀態的函式會關閉 RPC 內容句柄，而且任何後續的呼叫都可能導致進程當機。
請勿在呼叫具有 SERVICE_STOPPED 的 SetServiceStatus 之後嘗試執行任何其他工作，因為服務進程可以隨時終止。

範例

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

規格需求

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