共用方式為


SetServiceStatus 函式 (winsvc.h)

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

語法

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 以取得服務狀態句柄之後,才能呼叫此函式。

如果服務呼叫 SetServiceStatusdwCurrentState 成員設定為 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

另請參閱

HandlerEx

RegisterServiceCtrlHandlerEx

SERVICE_STATUS

服務函式

ServiceMain

SetServiceBits