SetThreadExecutionState 函式 (winbase.h)

發行項
08/27/2023

讓代理程式更新系統正在使用中，進而防止系統在應用程式執行時進入睡眠狀態或關閉顯示器。

語法

EXECUTION_STATE SetThreadExecutionState(
  [in] EXECUTION_STATE esFlags
);

參數

[in] esFlags

執行緒的執行需求。此參數可以是下列一或多個值。

值	意義
ES_AWAYMODE_REQUIRED 0x00000040	啟用離開模式。這個值必須使用 ES_CONTINUOUS來指定。離開模式只能由媒體錄製和媒體散發應用程式使用，這些應用程式必須在電腦似乎處於睡眠狀態時，在桌上型電腦上執行重要的背景處理。請參閱＜備註＞。
ES_CONTINUOUS 0x80000000	通知系統，要設定的狀態應該維持有效狀態，直到下一次使用 ES_CONTINUOUS 的呼叫，並清除另一個狀態旗標為止。
ES_DISPLAY_REQUIRED 0x00000002	藉由重設顯示閒置計時器，強制顯示開啟。
ES_SYSTEM_REQUIRED 0x00000001	藉由重設系統閒置計時器，強制系統處於工作狀態。
ES_USER_PRESENT 0x00000004	不支援此值。如果 ES_USER_PRESENT 與其他 esFlags 值結合，則呼叫將會失敗，而且不會設定任何指定的狀態。

傳回值

如果函式成功，則傳回值是先前的執行緒執行狀態。

如果函式失敗，則傳回值為 Null。

備註

系統會自動偵測本機鍵盤或滑鼠輸入、伺服器活動和變更視窗焦點等活動。未自動偵測到的活動包括磁片或 CPU 活動和視訊顯示。

呼叫 SetThreadExecutionState 而不 ES_CONTINUOUS 只會重設閒置計時器;若要讓顯示或系統處於工作狀態，執行緒必須定期呼叫 SetThreadExecutionState 。

若要在電源管理電腦上正常執行，傳真伺服器、回應電腦、備份代理程式和網路管理應用程式等應用程式必須在處理事件時同時使用 ES_SYSTEM_REQUIRED 和 ES_CONTINUOUS 。多媒體應用程式，例如視訊播放程式和簡報應用程式，必須在顯示視訊長時間沒有使用者輸入的情況下，使用 ES_DISPLAY_REQUIRED 。字處理器、試算表、瀏覽器和遊戲等應用程式不需要呼叫 SetThreadExecutionState。

只有在需要系統執行背景工作的媒體應用程式絕對需要時，才應該使用 ES_AWAYMODE_REQUIRED 值，例如錄製電視內容或串流媒體到其他裝置，而系統似乎處於睡眠狀態。不需要重要背景處理或在可攜式電腦上執行的應用程式不應該啟用離開模式，因為它可防止系統藉由進入真正的睡眠來節省電源。

若要啟用離開模式，應用程式會同時使用ES_AWAYMODE_REQUIRED和ES_CONTINUOUS;若要停用離開模式，應用程式會使用ES_CONTINUOUS呼叫SetThreadExecutionState，並清除ES_AWAYMODE_REQUIRED。啟用離開模式時，會將電腦進入睡眠模式的任何作業，都會改為進入離開模式。當系統繼續執行不需要使用者輸入的工作時，電腦似乎處於睡眠狀態。離開模式不會影響睡眠閒置計時器;若要防止系統在計時器過期時進入睡眠狀態，應用程式也必須設定 ES_SYSTEM_REQUIRED 值。

SetThreadExecutionState函式無法用來防止使用者將電腦放入睡眠狀態。當使用者關閉膝上型電腦上的蓋子或按下電源按鈕時，應用程式應該遵守預期特定行為。

此函式不會停止螢幕保護裝置程式執行。

範例

// Television recording is beginning. Enable away mode and prevent
// the sleep idle time-out.
//
SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_AWAYMODE_REQUIRED);

//
// Wait until recording is complete...
//

//
// Clear EXECUTION_STATE flags to disable away mode and allow the system to idle to sleep normally.
//
SetThreadExecutionState(ES_CONTINUOUS);

規格需求


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