IMediaEvent

IMediaEvent インターフェイスには、イベント通知を取得するためのメソッドと、Filter Graph Manager によるイベントの既定の処理をオーバーライドするためのメソッドが含まれています。

GetEventHandle メソッドは、キューにイベント通知が存在する間はシグナル状態を維持する、手動リセット イベントのハンドルを取得します。

S_OK を返します。

Filter Graph Manager は、イベント キューの状態を反映する手動リセット イベントを保持しています。キューにイベント通知が含まれている場合、この手動リセット イベントはシグナル状態になります。キューが空の場合、IMediaEvent::GetEvent メソッドがイベントをリセットします。

アプリケーションは、このイベントを使用してキューの状態を判断できます。まず GetEventHandle を呼び出してイベントのハンドルを取得します。次に WaitForSingleObject などの関数を使用して、イベントがシグナル状態になるのを待ちます。イベントがシグナル状態になったら、IMediaEvent::GetEvent メソッドを呼び出してキューから次のイベント通知を取得します。Filter Graph Manager は、キューが空になるまでイベントをシグナル状態に保ち、空になった時点でイベントをリセットします。

このメソッドが返すイベント ハンドルは、フィルター グラフが内部的に使用しているため、閉じないでください。また、Filter Graph Manager を解放した後にこのハンドルを使用しないでください。Filter Graph Manager が破棄された後は、ハンドルが無効になるためです。(このエラーを回避するには、DuplicateHandle を呼び出してハンドルを複製し、元のハンドルの代わりに複製を使用することをお勧めします。使用が終わったら複製したハンドルを閉じてください。)

オートメーションとの互換性のため、このメソッドは OAEVENT 型へのポインターを受け取ります。C++ では、次のように HANDLE 型の変数を宣言し、それを OAEVENT ポインターにキャストします。

HANDLE hEvent;
GetEventHandle( (OAEVENT*) &hEvent );

アプリケーションがイベント キューを監視するもう一つの方法として、IMediaEventEx::SetNotifyWindow メソッドを呼び出す方法があります。

GetEvent メソッドは、イベント キューから次のイベント通知を取得します。

HRESULT 値を返します。取り得る値には、次の表に示すものが含まれます。

キューにイベントが存在しない場合、このメソッドはイベントが到着するまで最大 msTimeout ミリ秒待機します。GetEvent で待機している間はスレッドがメッセージを処理できなくなるため、タイムアウト間隔に INFINITE を使用することは避けてください。Windows メッセージを処理するスレッドと同じスレッドから GetEvent を呼び出す場合は、ユーザー入力に対する応答性を保つため、待機時間を小さな値のみに指定してください。

GetEvent を呼び出した後は、IMediaEvent::FreeEventParams メソッドを呼び出して、イベント パラメーターに割り当てられたリソースを解放してください。

通知コードとイベント パラメーター値の一覧については、Event Notification Codes を参照してください。

このメソッドはフィルター グラフのイベント キューからイベントを削除するため、複数のクライアントが同じグラフのイベントを監視する方法はありません。

WaitForCompletion メソッドは、フィルター グラフが利用可能なすべてのデータをレンダリングするのを待ちます。フィルター グラフが実行中でなければ、このメソッドは失敗します。

HRESULT 値を返します。取り得る値には次のものが含まれます。

このメソッドは、タイムアウトが経過するか、次のいずれかのイベントが発生するまでブロックします。

• EC_COMPLETE
• EC_ERRORABORT
• EC_USERABORT

戻り値が S_OK の場合、pEvCode パラメーターは待機を終了させたイベント コードを受け取ります。メソッドが戻った時点でも、フィルター グラフはまだ実行中です。アプリケーションは、必要に応じてグラフを一時停止または停止できます。

CancelDefaultHandling メソッドは、指定したイベントに対する Filter Graph Manager の既定の処理をキャンセルします。イベント通知はアプリケーションに渡されます。

HRESULT 値を返します。取り得る値には、次の表に示すものが含まれます。

イベントの既定の処理を復元するには、そのイベント コードを指定して IMediaEvent::RestoreDefaultHandling メソッドを呼び出します。

RestoreDefaultHandling メソッドは、指定したイベントに対する Filter Graph Manager の既定の処理を復元します。

HRESULT 値を返します。取り得る値には次のものが含まれます。

既定では、Filter Graph Manager は一部のイベント(EC_REPAINT など)を、アプリケーションに渡さずに処理します。IMediaEvent::CancelDefaultHandling メソッドを呼び出してイベントの既定の処理をオーバーライドした場合、同じイベント コードを指定して RestoreDefaultHandling を呼び出すことで既定の動作を復元できます。

FreeEventParams メソッドは、イベントのパラメーターに関連付けられたリソースを解放します。

S_OK を返します。

IMediaEvent::GetEvent メソッドを呼び出してイベント通知を取得した後は、FreeEventParams を呼び出す必要があります。このメソッドは、イベント パラメーターに割り当てられたリソースを解放します。GetEvent の呼び出しで使用したものと同じ変数を渡してください。

例

hr = pEvent->GetEvent(&evCode, &param1, &param2, 0);
// イベントを処理します(コードは省略)。 
hr = pEvent->FreeEventParams(evCode, param1, param2);