共用方式為


WaitForSingleObject 函式 (synchapi.h)

等到指定的對象處於訊號狀態或逾時間隔經過為止。

若要進入可警示的等候狀態,請使用 WaitForSingleObjectEx 函式。 若要等候多個物件,請使用 WaitForMultipleObjects

語法

DWORD WaitForSingleObject(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds
);

參數

[in] hHandle

物件的句柄。 如需可指定句柄的物件類型清單,請參閱下列一節。

如果等候仍在擱置時關閉此句柄,則函式的行為未定義。

句柄必須具有 SYNCHRONIZE 存取權。 如需詳細資訊,請參閱 標準訪問許可權

[in] dwMilliseconds

逾時間隔,以毫秒為單位。 如果指定了非零值,函式會等到物件收到訊號或間隔經過為止。 如果 dwMilliseconds 為零,如果物件未發出訊號,則函式不會進入等候狀態;它一律會立即傳回。 如果 dwMillisecondsINFINITE,則函式只會在收到訊號時傳回。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 和 Windows Server 2008 R2: dwMilliseconds 值確實包含花費在低電源狀態的時間。 例如,當計算機處於睡眠狀態時,逾時會持續倒數。

Windows 8、Windows Server 2012、Windows 8.1、Windows Server 2012 R2、Windows 10 和 Windows Server 2016:dwMilliseconds 值不包含花費在低電量的時間國家。 例如,當計算機處於睡眠狀態時,逾時不會持續倒數。

傳回值

如果函式成功,傳回值會指出導致函式傳回的事件。 它可以是下列值之一。

傳回碼/值 Description
WAIT_ABANDONED
0x00000080L
指定的對像是一個 mutex 物件,該物件不是由擁有 mutex 對象的線程在擁有線程終止之前釋放。 Mutex 對象的擁有權會授與呼叫線程,且 mutex 狀態會設定為非簽署。

如果 mutex 正在保護持續性狀態資訊,您應該檢查其是否一致性。

WAIT_OBJECT_0
0x00000000L
指定的物件狀態會發出訊號。
WAIT_TIMEOUT
0x00000102L
經過逾時間隔,且物件的狀態為非ignaled。
WAIT_FAILED
(DWORD) 0xFFFFFFFF
函式失敗。 若要取得擴充的錯誤資訊,請呼叫 GetLastError

備註

WaitForSingleObject 函式會檢查指定物件的目前狀態。 如果物件的狀態為非ignalaled,則呼叫線程會進入等候狀態,直到物件收到訊號或逾時間隔經過為止。

函式會修改某些同步處理物件類型的狀態。 修改只會發生在發出訊號狀態導致函式傳回的物件。 例如,旗號物件的計數會減少一個。

WaitForSingleObject 函式可以等候下列物件:

  • 變更通知
  • 主控台輸入
  • 事件
  • 記憶體資源通知
  • Mutex
  • 流程
  • Semaphore
  • 執行緒
  • 可等候的定時器
呼叫直接或間接建立視窗的等候函式和程式代碼時,請小心。 如果線程建立任何視窗,則必須處理訊息。 訊息廣播會傳送至系統中的所有視窗。 使用沒有逾時間隔之等候函式的線程,可能會導致系統變成死結。 間接建立視窗的程式代碼範例包括 DDE 和 CoInitialize 函式。 因此,如果您有建立窗口的線程,請使用 MsgWaitForMultipleObjectsMsgWaitForMultipleObjectsEx,而不是 WaitForSingleObject

範例

如需範例,請參閱 使用 Mutex 物件

規格需求

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

另請參閱

同步處理函式

Wait 函式