共用方式為

NotifyServiceStatusChangeA 函式 (winsvc.h)

  • 發行項

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

語法

DWORD NotifyServiceStatusChangeA(
  [in] SC_HANDLE        hService,
  [in] DWORD            dwNotifyMask,
  [in] PSERVICE_NOTIFYA 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 函式會呼叫呼叫線程上的 OpenThread 函式，並具有THREAD_SET_CONTEXT訪問許可權。 如果呼叫線程沒有此訪問許可權， NotifyServiceStatusChange 就會失敗。 如果呼叫線程模擬另一位使用者，它可能沒有足夠的許可權可設定內容。

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

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

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

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

注意

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

規格需求

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

另請參閱

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

服務函式