Win32 API 日本語リファレンス
ホームSystem.Power › SetThreadExecutionState

SetThreadExecutionState

関数
スレッドの実行状態を設定しスリープ抑止などを制御する。
DLLKERNEL32.dll呼出規約winapi対応OSWindows XP 以降

シグネチャ

// KERNEL32.dll
#include <windows.h>

EXECUTION_STATE SetThreadExecutionState(
    EXECUTION_STATE esFlags
);

パラメーター

名前方向説明
esFlagsEXECUTION_STATEin

スレッドの実行要件。このパラメーターには、次の値を 1 つ以上指定できます。

意味
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 の値と組み合わせると、呼び出しは失敗し、指定された状態はいずれも設定されません。

戻り値の型: EXECUTION_STATE

公式ドキュメント

アプリケーションが使用中であることをシステムに通知できるようにし、これによりアプリケーションの実行中にシステムがスリープ状態に入ったりディスプレイがオフになったりするのを防ぎます。

戻り値

関数が成功した場合、戻り値は以前のスレッド実行状態です。

関数が失敗した場合、戻り値は NULL です。

解説(Remarks)

システムは、ローカルのキーボードやマウスの入力、サーバーのアクティビティ、ウィンドウ フォーカスの変更などのアクティビティを自動的に検出します。自動的に検出されないアクティビティには、ディスクや CPU のアクティビティ、ビデオ表示が含まれます。

ES_CONTINUOUS を指定せずに SetThreadExecutionState を呼び出すと、アイドル タイマーがリセットされるだけです。ディスプレイまたはシステムを動作状態に保つには、スレッドが定期的に SetThreadExecutionState を呼び出す必要があります。

電源管理されたコンピューター上で正しく動作させるには、FAX サーバー、留守番電話、バックアップ エージェント、ネットワーク管理アプリケーションなどのアプリケーションは、イベントを処理する際に ES_SYSTEM_REQUIREDES_CONTINUOUS の両方を使用する必要があります。ビデオ プレーヤーやプレゼンテーション アプリケーションなどのマルチメディア アプリケーションは、ユーザー入力なしで長時間ビデオを表示する場合に ES_DISPLAY_REQUIRED を使用する必要があります。ワード プロセッサ、表計算ソフト、ブラウザー、ゲームなどのアプリケーションは、 SetThreadExecutionState を呼び出す必要はありません。

ES_AWAYMODE_REQUIRED の値は、システムがスリープしているように見える間に、テレビ番組の録画や他のデバイスへのメディアのストリーミングなどのバックグラウンド タスクをシステムに実行させる必要があるメディア アプリケーションで、どうしても必要な場合にのみ使用してください。重要なバックグラウンド処理を必要としないアプリケーションや、ポータブル コンピューター上で実行されるアプリケーションは、アウェイ モードを有効にすべきではありません。アウェイ モードは、システムが真のスリープ状態に入って電力を節約するのを妨げるためです。

アウェイ モードを有効にするには、アプリケーションは ES_AWAYMODE_REQUIREDES_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);
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll
#include <windows.h>

EXECUTION_STATE SetThreadExecutionState(
    EXECUTION_STATE esFlags
);
[DllImport("KERNEL32.dll", ExactSpelling = true)]
static extern uint SetThreadExecutionState(
    uint esFlags   // EXECUTION_STATE
);
<DllImport("KERNEL32.dll", ExactSpelling:=True)>
Public Shared Function SetThreadExecutionState(
    esFlags As UInteger   ' EXECUTION_STATE
) As UInteger
End Function
' esFlags : EXECUTION_STATE
Declare PtrSafe Function SetThreadExecutionState Lib "kernel32" ( _
    ByVal esFlags As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

SetThreadExecutionState = ctypes.windll.kernel32.SetThreadExecutionState
SetThreadExecutionState.restype = wintypes.DWORD
SetThreadExecutionState.argtypes = [
    wintypes.DWORD,  # esFlags : EXECUTION_STATE
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
SetThreadExecutionState = Fiddle::Function.new(
  lib['SetThreadExecutionState'],
  [
    -Fiddle::TYPE_INT,  # esFlags : EXECUTION_STATE
  ],
  -Fiddle::TYPE_INT)
#[link(name = "kernel32")]
extern "system" {
    fn SetThreadExecutionState(
        esFlags: u32  // EXECUTION_STATE
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("KERNEL32.dll")]
public static extern uint SetThreadExecutionState(uint esFlags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_SetThreadExecutionState' -Namespace Win32 -PassThru
# $api::SetThreadExecutionState(esFlags)
#uselib "KERNEL32.dll"
#func global SetThreadExecutionState "SetThreadExecutionState" sptr
; SetThreadExecutionState esFlags   ; 戻り値は stat
; esFlags : EXECUTION_STATE -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "KERNEL32.dll"
#cfunc global SetThreadExecutionState "SetThreadExecutionState" int
; res = SetThreadExecutionState(esFlags)
; esFlags : EXECUTION_STATE -> "int"
; EXECUTION_STATE SetThreadExecutionState(EXECUTION_STATE esFlags)
#uselib "KERNEL32.dll"
#cfunc global SetThreadExecutionState "SetThreadExecutionState" int
; res = SetThreadExecutionState(esFlags)
; esFlags : EXECUTION_STATE -> "int"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	kernel32 = windows.NewLazySystemDLL("KERNEL32.dll")
	procSetThreadExecutionState = kernel32.NewProc("SetThreadExecutionState")
)

// esFlags (EXECUTION_STATE)
r1, _, err := procSetThreadExecutionState.Call(
	uintptr(esFlags),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // EXECUTION_STATE
function SetThreadExecutionState(
  esFlags: DWORD   // EXECUTION_STATE
): DWORD; stdcall;
  external 'KERNEL32.dll' name 'SetThreadExecutionState';
result := DllCall("KERNEL32\SetThreadExecutionState"
    , "UInt", esFlags   ; EXECUTION_STATE
    , "UInt")   ; return: EXECUTION_STATE
●SetThreadExecutionState(esFlags) = DLL("KERNEL32.dll", "dword SetThreadExecutionState(dword)")
# 呼び出し: SetThreadExecutionState(esFlags)
# esFlags : EXECUTION_STATE -> "dword"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "kernel32" fn SetThreadExecutionState(
    esFlags: u32 // EXECUTION_STATE
) callconv(std.os.windows.WINAPI) u32;
proc SetThreadExecutionState(
    esFlags: uint32  # EXECUTION_STATE
): uint32 {.importc: "SetThreadExecutionState", stdcall, dynlib: "KERNEL32.dll".}
pragma(lib, "kernel32");
extern(Windows)
uint SetThreadExecutionState(
    uint esFlags   // EXECUTION_STATE
);
ccall((:SetThreadExecutionState, "KERNEL32.dll"), stdcall, UInt32,
      (UInt32,),
      esFlags)
# esFlags : EXECUTION_STATE -> UInt32
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
uint32_t SetThreadExecutionState(
    uint32_t esFlags);
]]
local kernel32 = ffi.load("kernel32")
-- kernel32.SetThreadExecutionState(esFlags)
-- esFlags : EXECUTION_STATE
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('KERNEL32.dll');
const SetThreadExecutionState = lib.func('__stdcall', 'SetThreadExecutionState', 'uint32_t', ['uint32_t']);
// SetThreadExecutionState(esFlags)
// esFlags : EXECUTION_STATE -> 'uint32_t'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("KERNEL32.dll", {
  SetThreadExecutionState: { parameters: ["u32"], result: "u32" },
});
// lib.symbols.SetThreadExecutionState(esFlags)
// esFlags : EXECUTION_STATE -> "u32"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
uint32_t SetThreadExecutionState(
    uint32_t esFlags);
C, "KERNEL32.dll");
// $ffi->SetThreadExecutionState(esFlags);
// esFlags : EXECUTION_STATE
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Kernel32 extends StdCallLibrary {
    Kernel32 INSTANCE = Native.load("kernel32", Kernel32.class);
    int SetThreadExecutionState(
        int esFlags   // EXECUTION_STATE
    );
}
@[Link("kernel32")]
lib LibKERNEL32
  fun SetThreadExecutionState = SetThreadExecutionState(
    esFlags : UInt32   # EXECUTION_STATE
  ) : UInt32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef SetThreadExecutionStateNative = Uint32 Function(Uint32);
typedef SetThreadExecutionStateDart = int Function(int);
final SetThreadExecutionState = DynamicLibrary.open('KERNEL32.dll')
    .lookupFunction<SetThreadExecutionStateNative, SetThreadExecutionStateDart>('SetThreadExecutionState');
// esFlags : EXECUTION_STATE -> Uint32
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function SetThreadExecutionState(
  esFlags: DWORD   // EXECUTION_STATE
): DWORD; stdcall;
  external 'KERNEL32.dll' name 'SetThreadExecutionState';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "SetThreadExecutionState"
  c_SetThreadExecutionState :: Word32 -> IO Word32
-- esFlags : EXECUTION_STATE -> Word32
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let setthreadexecutionstate =
  foreign "SetThreadExecutionState"
    (uint32_t @-> returning uint32_t)
(* esFlags : EXECUTION_STATE -> uint32_t *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library kernel32 (t "KERNEL32.dll"))
(cffi:use-foreign-library kernel32)

(cffi:defcfun ("SetThreadExecutionState" set-thread-execution-state :convention :stdcall) :uint32
  (es-flags :uint32))   ; EXECUTION_STATE
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $SetThreadExecutionState = Win32::API::More->new('KERNEL32',
    'DWORD SetThreadExecutionState(DWORD esFlags)');
# my $ret = $SetThreadExecutionState->Call($esFlags);
# esFlags : EXECUTION_STATE -> DWORD
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

公式の関連項目
使用する型