共用方式為

NotifyServiceStatusChangeW 函式 （winsvc.h）

  • 發行項

可讓應用程式在建立或刪除指定的服務時，或在其狀態變更時接收通知。

語法

DWORD NotifyServiceStatusChangeW(
  [in] SC_HANDLE        hService,
  [in] DWORD            dwNotifyMask,
  [in] PSERVICE_NOTIFYW pNotifyBuffer
);

參數

[in] hService

服務或服務控制管理員的句柄。 OpenService 或 CreateService 函式會傳回服務的句柄，而且必須具有SERVICE_QUERY_STATUS訪問許可權。 服務控制管理員的句柄是由 OpenSCManager 函式傳回，而且必須具有SC_MANAGER_ENUMERATE_SERVICE訪問許可權。 如需詳細資訊，請參閱 服務安全性和存取權限。

每個服務只能有一個未處理的通知要求。

[in] dwNotifyMask

應該報告的狀態變更類型。 此參數可以是下列其中一或多個值。

價值 意義
SERVICE_NOTIFY_CREATED
0x00000080
 建立服務時報告。

hService 參數必須是 SCM 的句柄。
SERVICE_NOTIFY_CONTINUE_PENDING
0x00000010
 當服務即將繼續時報告。

hService 參數必須是服務的句柄。
SERVICE_NOTIFY_DELETE_PENDING
0x00000200
 當應用程式在呼叫 deleteService 函式時報告服務。 您的應用程式應該關閉服務的任何句柄，以便刪除它。

hService 參數必須是服務的句柄。
SERVICE_NOTIFY_DELETED
0x00000100
 當服務已刪除時報告。 如果應用程式具有服務的開啟句柄，則無法接收此通知。

hService 參數必須是 SCM 的句柄。
SERVICE_NOTIFY_PAUSE_PENDING
0x00000020
 當服務暫停時報告。

hService 參數必須是服務的句柄。
SERVICE_NOTIFY_PAUSED
0x00000040
 當服務暫停時報告。

hService 參數必須是服務的句柄。
SERVICE_NOTIFY_RUNNING
0x00000008
 報告服務執行時。

hService 參數必須是服務的句柄。
SERVICE_NOTIFY_START_PENDING
0x00000002
 報告服務啟動時。

hService 參數必須是服務的句柄。
SERVICE_NOTIFY_STOP_PENDING
0x00000004
 當服務停止時報告。

hService 參數必須是服務的句柄。
SERVICE_NOTIFY_STOPPED
0x00000001
 當服務停止時報告。

hService 參數必須是服務的句柄。

[in] pNotifyBuffer

包含通知資訊的 SERVICE_NOTIFY 結構的指標，例如回呼函式的指標。 在叫用回呼函式或呼叫線程取消通知要求之前，此結構必須保持有效。

除非第一次 呼叫的回呼函式已完成緩衝區或取消第一個通知要求，否則請勿使用相同緩衝區參數對 notifyServiceStatusChange 進行多次呼叫。 否則，不保證回呼函式將接收的緩衝區版本。

Windows Vista：回呼函式的地址必須位於載入模組的位址範圍內。 因此，回呼函式不能是運行時間產生的程式代碼（例如 JIT 編譯程式所產生的 Managed 程式代碼），或是在運行時間解壓縮的機器碼。 此限制已在 Windows Server 2008 和 Windows Vista SP1 中移除。

傳回值

如果函式成功，則傳回值會ERROR_SUCCESS。 如果服務已標示為要刪除，傳回值會ERROR_SERVICE_MARKED_FOR_DELETE且必須關閉服務的句柄。 如果服務通知落後於系統狀態太遠，函式會傳回ERROR_SERVICE_NOTIFY_CLIENT_LAGGING。 在此情況下，客戶端應該關閉 SCM 的句柄、開啟新的句柄，然後再次呼叫此函式。

如果函式失敗，傳回值是系統錯誤碼之一。

言論

NotifyServiceStatusChange 函式可用來接收服務應用程式的通知。 它無法用來接收有關驅動程式服務的通知。

當服務狀態變更時，系統會叫用指定的回呼函式作為佇列至呼叫線程的異步過程調用（APC）。 呼叫線程必須輸入可警示的等候（例如，藉由呼叫 SleepEx 函式）來接收通知。 如需詳細資訊，請參閱異步過程調用。

如果在呼叫 notifyServiceStatusChange 時，服務已處於任何要求狀態，則會立即將回呼函式排入佇列。 如果下次使用相同的服務和狀態呼叫函式時未變更服務狀態，則不會立即將回呼函式排入佇列：下次服務進入要求狀態時，回呼函式會排入佇列。

NotifyServiceStatusChange 函式會使用THREAD_SET_CONTEXT訪問許可權呼叫呼叫線程上的 OpenThread 函式。 如果呼叫線程沒有此訪問許可權，NotifyServiceStatusChange 失敗。 如果呼叫線程模擬另一個使用者，它可能沒有足夠的許可權可設定內容。

從執行等候的線程呼叫 NotifyServiceStatusChange 比建立其他線程更有效率。

叫用回呼函式之後，呼叫端必須呼叫 NotifyServiceStatusChange，才能接收其他通知。 請注意，Windows API 中的某些函式，包括 NotifyServiceStatusChange 和其他 SCM 函式，請使用遠端過程調用 （RPC）：這些函式可能會執行可警示的等候作業，因此無法從回呼函式內呼叫。 相反地，回呼函式應該儲存通知參數，並在回呼外部執行任何其他工作。

若要取消未處理的通知，請使用 closeServiceHandle 函式關閉服務句柄。 CloseServiceHandle 成功之後，就不會再將通知 APC 排入佇列。 如果呼叫線程結束而不關閉服務句柄，或等到產生APC為止，可能會發生記憶體流失。

重要 如果呼叫線程位於 DLL 中，而且在線程收到通知或呼叫之前卸除 DLL，CloseServiceHandle，則通知會導致無法預期的結果，並可能導致進程停止回應。
 

注意

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

要求

要求 價值
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 winsvc.h （包括 Windows.h）
連結庫 Advapi32.lib
DLL Advapi32.dll

另請參閱

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

Service Functions