DeleteTimerQueueTimer 函式 (threadpoollegacyapiset.h)

  • 發行項

從定時器佇列中移除定時器，並選擇性地等候目前正在執行的定時器回呼函式完成，再刪除定時器。

語法

BOOL DeleteTimerQueueTimer(
  [in, optional] HANDLE TimerQueue,
  [in]           HANDLE Timer,
  [in, optional] HANDLE CompletionEvent
);

參數

[in, optional] TimerQueue

定時器佇列的句柄。 CreateTimerQueue 函式會傳回此句柄。

如果使用預設定時器佇列建立定時器，此參數應該是 NULL。

[in] Timer

定時器佇列定時器的句柄。 CreateTimerQueueTimer 函式會傳回這個句柄。

[in, optional] CompletionEvent

當系統取消定時器且所有回呼函式都已完成時，要發出訊號的事件物件句柄。 此參數可以是 Null。

如果此參數 INVALID_HANDLE_VALUE，函式會等候任何執行中的定時器回呼函式完成，然後再傳回。

如果此參數為 NULL，函式會標記定時器進行刪除，並立即傳回。 如果定時器已經過期，定時器回呼函式就會執行到完成。 不過，定時器回呼函式完成時不會傳送通知。 大部分的呼叫端不應該使用此選項，而且應該等候執行定時器回呼函式完成，以便執行任何所需的清除。

傳回值

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

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。 如果錯誤碼 ERROR_IO_PENDING，就不需要再次呼叫此函式。 針對任何其他錯誤，您應該重試呼叫。

備註

當線程使用模擬時，無法呼叫此函式。 產生的行為未定義。

只要回呼函式未在定時器線程中執行，您就可以從另一個定時器的定時器回呼內呼叫此函式時，將 CompletionEvent 設定為 INVALID_HANDLE_VALUE 。 不過，如果兩個回呼函式嘗試在彼此的定時器上封鎖 DeleteTimerQueueTimer 呼叫，就會發生死結。 此外，您無法在與回呼相關聯的定時器上進行封鎖刪除呼叫。

在持續性線程上進行封鎖 DeleteTimerQueueTimer 呼叫時，請小心。 如果已刪除的定時器是使用 WT_EXECUTEINPERSISTENTTHREAD 建立的，可能會發生死結。

如果有未處理的回呼函式且 CompletionEvent 為 NULL，函式將會失敗，並將錯誤碼設定為 ERROR_IO_PENDING。 這表示有未處理的回呼函式。 這些回呼將會執行，或是在執行中。 當回呼函式完成執行時，就會清除定時器。

若要取消定時器佇列中的所有定時器，請呼叫 DeleteTimerQueueEx 函式。

若要編譯使用此函式的應用程式，請將 _WIN32_WINNT 定義為0x0500或更新版本。 如需詳細資訊，請參閱 使用 Windows 標頭。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 threadpoollegacyapiset.h
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

CreateTimerQueue

CreateTimerQueueTimer

DeleteTimerQueueEx

同步處理函式

定時器佇列