CreateWaitableTimerExW 函式 (synchapi.h)

  • 發行項

建立或開啟可等候的計時器物件，並傳回物件的控制碼。

語法

HANDLE CreateWaitableTimerExW(
  [in, optional] LPSECURITY_ATTRIBUTES lpTimerAttributes,
  [in, optional] LPCWSTR               lpTimerName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

參數

[in, optional] lpTimerAttributes

SECURITY_ATTRIBUTES結構的指標。 如果此參數為 Null，則子進程無法繼承計時器控制碼。

如果 lpTimerAttributes 為 Null，計時器物件會取得預設的安全性描述元，而且無法繼承控制碼。 計時器預設安全性描述元中的 ACL 來自建立者的主要或模擬權杖。

[in, optional] lpTimerName

計時器物件的名稱。 名稱限制為 MAX_PATH 個字元。 名稱比較區分大小寫。

如果 lpTimerName 為 Null，則會在沒有名稱的情況下建立計時器物件。

如果 lpTimerName 符合現有事件、號志、mutex、作業或檔案對應物件的名稱，則函式會失敗，而且 GetLastError 會傳回 ERROR_INVALID_HANDLE。 這是因為這些物件共用相同的命名空間。

名稱可以有 「Global」 或 「Local」 前置詞，以在全域或會話命名空間中明確建立物件。 名稱的其餘部分可以包含反斜線字元 (\) 以外的任何字元。 如需詳細資訊，請參閱 核心物件命名空間。 使用終端機服務會話實作快速使用者切換。 核心物件名稱必須遵循終端機服務概述的指導方針，讓應用程式可以支援多個使用者。

物件可以在私用命名空間中建立。 如需詳細資訊，請參閱 物件命名空間。

[in] dwFlags

此參數可以是 0 或下列值。

值 意義
CREATE_WAITABLE_TIMER_MANUAL_RESET
0x00000001
 計時器必須手動重設。 否則，系統會在釋放單一等候執行緒之後自動重設計時器。
CREATE_WAITABLE_TIMER_HIGH_RESOLUTION
0x00000002
 建立高解析度計時器。 當短暫到期延遲到幾毫秒的順序無法接受時，請使用此值作為時間關鍵性的情況。 Windows 10版本 1803 和更新版本中支援此值。

[in] dwDesiredAccess

計時器物件的存取遮罩。 如需存取權限的清單，請參閱 同步處理物件安全性和存取權限。

傳回值

如果函式成功，則傳回值是計時器物件的控制碼。 如果具名計時器物件存在於函式呼叫之前，函式會傳回現有物件的控制碼，而 GetLastError 會 傳回ERROR_ALREADY_EXISTS。

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

備註

呼叫進程的任何執行緒都可以在呼叫其中一個 等候函式中指定計時器物件控制碼。

多個進程可以有相同計時器物件的控制碼，讓物件能夠用於進程間同步處理。

  • 如果CreateWaitableTimerEx的lpTimerAttributes參數啟用繼承，CreateProcess函式所建立的進程可以繼承計時器物件的控制碼。
  • 進程可以在對 DuplicateHandle 函式的呼叫中指定計時器物件控制碼。 產生的控制碼可由另一個進程使用。
  • 進程可以在 呼叫 OpenWaitableTimer 或 CreateWaitableTimerEx 函 式時指定計時器物件的名稱。

使用 CloseHandle 函式關閉控制碼。 當進程終止時，系統會自動關閉控制碼。 當最後一個控制碼關閉時，計時器物件就會終結。

若要將計時器與視窗產生關聯，請使用 SetTimer 函 式。

規格需求

   
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 synchapi.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

CloseHandle

同步處理函式

可等候的計時器物件