ホーム › System.Com › CoWaitForMultipleHandles

CoWaitForMultipleHandles

関数

メッセージを処理しつつ複数のハンドルのシグナルを待機する。

DLLOLE32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

HRESULT CoWaitForMultipleHandles(
    DWORD dwFlags,
    DWORD dwTimeout,
    DWORD cHandles,
    HANDLE* pHandles,
    DWORD* lpdwindex
);

パラメーター

名前	型	方向	説明
dwFlags	DWORD	in	待機オプション。指定可能な値は COWAIT_FLAGS 列挙体から取得します。
dwTimeout	DWORD	in	タイムアウト時間(ミリ秒単位)。
cHandles	DWORD	in	pHandles 配列の要素数。
pHandles	HANDLE*	in	ハンドルの配列。
lpdwindex	DWORD*	out	返されるステータスが S_OK の場合に、関数が戻る原因となったイベントを示す値を受け取る変数へのポインター。この値は通常、シグナル状態になったハンドルに対応する pHandles 内のインデックスです。 pHandles にミューテックスオブジェクトのハンドルが 1 つ以上含まれている場合、WAIT_ABANDONED_0 から (WAIT_ABANDONED_0 + nCount - 1) までの値は、放棄されたミューテックスに対応する pHandles 内のインデックスを示します。 dwFlags に COWAIT_ALERTABLE フラグが設定されている場合、WAIT_IO_COMPLETION の値は、スレッドにキューイングされた 1 つ以上のユーザーモード非同期プロシージャ呼び出し(APC)によって待機が終了したことを示します。詳細については WaitForMultipleObjectsEx を参照してください。

戻り値の型: HRESULT

公式ドキュメント

指定したハンドルがシグナル状態になるか、指定したタイムアウト時間が経過するまで待機します。

戻り値

この関数は次の値を返すことがあります。

注意 dwFlags に COWAIT_ALERTABLE フラグが設定されている場合、または pHandles にミューテックスオブジェクトのハンドルが 1 つ以上含まれている場合、CoWaitForMultipleHandles の戻り値は非決定的になることがあります。推奨される回避策は、CoWaitForMultipleHandles を呼び出す前に SetLastError(ERROR_SUCCESS) を呼び出すことです。

戻り値	説明
S_OK	必要なハンドルがシグナル状態になりました。
E_INVALIDARG	pHandles が NULL であったか、lpdwindex が NULL であったか、または dwFlags が COWAIT_FLAGS 列挙体の値ではありませんでした。
RPC_E_NO_SYNC	pHandles の値が 0 でした。
RPC_S_CALLPENDING	必要なハンドルがシグナル状態になる前にタイムアウト時間が経過しました。

解説(Remarks)

dwFlags パラメーターに設定されたフラグに応じて、CoWaitForMultipleHandles は次のいずれかのイベントが発生するまで呼び出し元スレッドをブロックします。

ハンドルの 1 つ、またはすべてがシグナル状態になる。ミューテックスオブジェクトの場合、ミューテックスが放棄されることでもこの条件は満たされます。
QueueUserAPC 関数の呼び出しによって、呼び出し元スレッドに非同期プロシージャ呼び出し(APC)がキューイングされる。
タイムアウト時間が経過する。

呼び出し元がシングルスレッドアパートメントに存在する場合、CoWaitForMultipleHandles は COM のモーダルループに入り、スレッドのメッセージループはスレッドのメッセージフィルターを使用してメッセージのディスパッチを継続します。スレッドにメッセージフィルターが登録されていない場合は、既定の COM メッセージ処理が使用されます。

呼び出し元スレッドがマルチスレッドアパートメント(MTA)に存在する場合、CoWaitForMultipleHandles は WaitForMultipleObjectsEx 関数を呼び出します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

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

HRESULT CoWaitForMultipleHandles(
    DWORD dwFlags,
    DWORD dwTimeout,
    DWORD cHandles,
    HANDLE* pHandles,
    DWORD* lpdwindex
);

[DllImport("OLE32.dll", ExactSpelling = true)]
static extern int CoWaitForMultipleHandles(
    uint dwFlags,   // DWORD
    uint dwTimeout,   // DWORD
    uint cHandles,   // DWORD
    IntPtr pHandles,   // HANDLE*
    out uint lpdwindex   // DWORD* out
);

<DllImport("OLE32.dll", ExactSpelling:=True)>
Public Shared Function CoWaitForMultipleHandles(
    dwFlags As UInteger,   ' DWORD
    dwTimeout As UInteger,   ' DWORD
    cHandles As UInteger,   ' DWORD
    pHandles As IntPtr,   ' HANDLE*
    <Out> ByRef lpdwindex As UInteger   ' DWORD* out
) As Integer
End Function

' dwFlags : DWORD
' dwTimeout : DWORD
' cHandles : DWORD
' pHandles : HANDLE*
' lpdwindex : DWORD* out
Declare PtrSafe Function CoWaitForMultipleHandles Lib "ole32" ( _
    ByVal dwFlags As Long, _
    ByVal dwTimeout As Long, _
    ByVal cHandles As Long, _
    ByVal pHandles As LongPtr, _
    ByRef lpdwindex As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CoWaitForMultipleHandles = ctypes.windll.ole32.CoWaitForMultipleHandles
CoWaitForMultipleHandles.restype = ctypes.c_int
CoWaitForMultipleHandles.argtypes = [
    wintypes.DWORD,  # dwFlags : DWORD
    wintypes.DWORD,  # dwTimeout : DWORD
    wintypes.DWORD,  # cHandles : DWORD
    ctypes.c_void_p,  # pHandles : HANDLE*
    ctypes.POINTER(wintypes.DWORD),  # lpdwindex : DWORD* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLE32.dll')
CoWaitForMultipleHandles = Fiddle::Function.new(
  lib['CoWaitForMultipleHandles'],
  [
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    -Fiddle::TYPE_INT,  # dwTimeout : DWORD
    -Fiddle::TYPE_INT,  # cHandles : DWORD
    Fiddle::TYPE_VOIDP,  # pHandles : HANDLE*
    Fiddle::TYPE_VOIDP,  # lpdwindex : DWORD* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ole32")]
extern "system" {
    fn CoWaitForMultipleHandles(
        dwFlags: u32,  // DWORD
        dwTimeout: u32,  // DWORD
        cHandles: u32,  // DWORD
        pHandles: *mut *mut core::ffi::c_void,  // HANDLE*
        lpdwindex: *mut u32  // DWORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("OLE32.dll")]
public static extern int CoWaitForMultipleHandles(uint dwFlags, uint dwTimeout, uint cHandles, IntPtr pHandles, out uint lpdwindex);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLE32_CoWaitForMultipleHandles' -Namespace Win32 -PassThru
# $api::CoWaitForMultipleHandles(dwFlags, dwTimeout, cHandles, pHandles, lpdwindex)

#uselib "OLE32.dll"
#func global CoWaitForMultipleHandles "CoWaitForMultipleHandles" sptr, sptr, sptr, sptr, sptr
; CoWaitForMultipleHandles dwFlags, dwTimeout, cHandles, pHandles, varptr(lpdwindex)   ; 戻り値は stat
; dwFlags : DWORD -> "sptr"
; dwTimeout : DWORD -> "sptr"
; cHandles : DWORD -> "sptr"
; pHandles : HANDLE* -> "sptr"
; lpdwindex : DWORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "OLE32.dll"
#cfunc global CoWaitForMultipleHandles "CoWaitForMultipleHandles" int, int, int, sptr, var
; res = CoWaitForMultipleHandles(dwFlags, dwTimeout, cHandles, pHandles, lpdwindex)
; dwFlags : DWORD -> "int"
; dwTimeout : DWORD -> "int"
; cHandles : DWORD -> "int"
; pHandles : HANDLE* -> "sptr"
; lpdwindex : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "OLE32.dll"
#cfunc global CoWaitForMultipleHandles "CoWaitForMultipleHandles" int, int, int, sptr, sptr
; res = CoWaitForMultipleHandles(dwFlags, dwTimeout, cHandles, pHandles, varptr(lpdwindex))
; dwFlags : DWORD -> "int"
; dwTimeout : DWORD -> "int"
; cHandles : DWORD -> "int"
; pHandles : HANDLE* -> "sptr"
; lpdwindex : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。