Microsoft DirectX 8.0

IMediaEvent オブジェクト

このオブジェクトは、フィルタ グラフおよびフィルタ グラフ内のフィルタからアプリケーションへのイベント通知をサポートする。

1 つのイベント コードと 2 つのパラメータで通知情報を表す。これを利用して、非同期動作の完了、非同期動作の最中に発生したエラー、または、ユーザーによるホット スポットのクリックなどのユーザー操作イベントを通知できる。

フィルタ グラフ内のフィルタおよびフィルタ グラフ自体がイベント通知を生成する。通知できるイベントには、再生の完了または非同期再生のエラーが含まれる。また、フィルタ グラフは、特定の基準クロック時間にイベントを生成するメソッドを備えている。

イベント通知はキューに入れられる。アプリケーションは IMediaEvent オブジェクトの GetEvent メソッドを呼び出して、次の通知をキューから取り出す。このメソッドは、返すイベントがキューに入るまで動作を停止する。GetEvent メソッドのタイムアウト パラメータを利用して、アプリケーションは、イベントを待機する時間をミリ秒単位で指定することができる。ゼロ (待機しない) および無限大 (常に待機) も指定できる。

さらに、アプリケーションはイベント ハンドルを取得できる。GetEventHandle は、Microsoft® Win32® CreateEvent 関数によって作成された手動リセット イベントのハンドルを返す。このイベントは、収集するイベント通知が存在する限り、通知済状態に置かれる。収集するイベント通知がなくなると、GetEvent メソッドはイベントを消去する。この機能により、アプリケーションは、MsgWaitForMultipleObjects などの API (アプリケーション プログラミング インターフェイス) を利用して、イベントとその他の対象を同時に待つことができる。このイベント ハンドルは、フィルタ グラフが解放されたときに閉じる。したがって、アプリケーションは、その時点以降にイベント ハンドルを使用しないように注意する必要がある。

フィルタ グラフは、フィルタによって生成され、アプリケーションに渡されない一部のイベントを処理する。EC_REPAINT イベント通知がその例である。このイベントのデフォルトの処理は、フィルタ グラフをポーズさせることによって、ビデオ レンダラの静止画像を再描画することである。アプリケーションは、イベント値をパラメータとして CancelDefaultHandling メソッドを呼び出すことにより、特定のイベントのデフォルト処理をオーバーライドすることができる。RestoreDefaultHandling メソッドは、指定されたイベント値のデフォルト処理を元に戻す。これらのメソッドは、デフォルト処理がないイベントには影響を与えない。

トランスポート状態への移行中にフィルタ上でエラーが発生した場合は、Run メソッドがエラー値を返す。この場合、フィルタ グラフ内の一部のフィルタは問題なくトランスポートしている可能性がある。フィルタ グラフは、エラーが発生したときにグラフを停止するかどうかの判断をアプリケーションに任せる。Run メソッドが終了した後、イベント通知は、その他のエラーを報告する。EC_ERRORABORT イベント通知と EC_USERABORT イベント通知は、グラフで (しかもエラーが報告されたフィルタで) 再生が停止した可能性があることを示す。その他のエラーおよびイベントは、グラフがまだトランスポート中であることを示す。ただし、どんな場合でも、アプリケーションが明示的にグラフを停止モードまたはポーズ モードに移行させるまで、グラフはトランスポート モードにとどまる点に注意すること。

フィルタ グラフ内のストリームがストリームの末尾を検出すると、ストリームは、EC_COMPLETE イベント通知を使ってそれを報告する。フィルタ グラフは、"シーク可能なレンダラ" 経由で EC_COMPLETE を報告できるかどうかをフィルタに問い合わせる。

シーク可能なレンダラは、フィルタ上で IMediaPosition オブジェクトをサポートし、入力ピンだけを持つレンダラ、または、その時点でレンダリングが終了したことを報告する入力ピンを持つレンダラである。フィルタ グラフはシーク可能なレンダラを検出する。シーク可能なレンダラは、そのフィルタ上のすべてのシーク可能なストリームがストリームの末尾に達すると EC_COMPLETE を報告する。

フィルタ グラフ マネージャは、各ストリームから EC_COMPLETE イベント通知を受け取るまで、EC_COMPLETE をアプリケーションに渡さない。たとえば、ファイル再生ビデオのバックグラウンドとしてライブ カメラのストリームが再生されている場合、アプリケーションは、ファイルのビデオ ストリームとオーディオ ストリームがストリームの末尾に達すると、ライブ ソースがまだ再生中であっても EC_COMPLETE の通知を受け取る。この場合も、フィルタ グラフは、アプリケーションが明示的に Pause メソッドまたは Stop メソッドを呼び出すまで、トランスポート状態にとどまる。

EC_COMPLETE をパラメータとして CancelDefaultHandling を呼び出すことにより、EC_COMPLETE メッセージの集合を無効にすることができる。この場合、フィルタによって生成されたすべての EC_COMPLETE イベントは直接アプリケーションに渡される。

システム定義のイベント通知の一覧については、GetEvent メソッドを参照すること。

メソッド

CancelDefaultHandling 指定されたイベントのフィルタ グラフによるデフォルト処理をキャンセルする。
GetEvent 次の通知イベントを取得する。
GetEventHandle 通知済になる手動リセット イベントのハンドルを取得する。
RestoreDefaultHandling このイベントのデフォルト処理を復元する。
WaitForCompletion フィルタ グラフの動作が完了するまで待機する。

CancelDefaultHandling メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

指定されたイベントのフィルタ グラフによるデフォルト処理をキャンセルし、イベントがアプリケーションに渡されるようにする。

構文

objMediaEvent.CancelDefaultHandling lEvCode

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
lEvCode
デフォルト処理をキャンセルするイベント コードを指定する Long 型の値。 次の値が有効である。

戻り値

このメソッドは、イベントにデフォルト処理がない場合にエラーを生成する。

注意

現在、フィルタ グラフ マネージャは、EC_COMPLETEEC_REPAINT のみにデフォルト処理を適用する。

GetEvent メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

次の通知済イベントを取得する。

構文

objMediaEvent.GetEvent lEventCode, lParam1, lParam2, msTimeout

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
IEventCode
次のイベント通知を返す。以下の値が有効である。
lParam1
イベントの第 1 パラメータを指定する Long 型の値。
lParam2
イベントの第 2 パラメータを指定する Long 型の値。
msTimeout
イベントがないと見なすまでのミリ秒単位の時間。直ちに終了するには、タイムアウト値を 0 にする。

注意

このメソッドは、キューの先頭から次のイベント通知を削除し、そのイベント通知を返す。イベントがない場合、このメソッドは msTimeout ミリ秒が経過するまで待機する。

GetEventHandle メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

渡すイベント通知がある限り通知済になる、手動リセット イベントのハンドルを返す。

構文

objMediaEvent.GetEventHandle hEvent

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
hEvent
イベント ハンドルが格納される Long 型の値。

注意

イベントを Win32 WaitForMultipleObjects 関数または MsgWaitForMultipleObjects 関数に渡し、1 つのスレッド上で、ほかのメッセージやイベントと同時に、イベント通知を待つことができる。

RestoreDefaultHandling メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

指定されたイベントのフィルタ グラフによる通常のデフォルト処理があれば、それを復元する。

構文

objMediaEvent.RestoreDefaultHandling lEvCode

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
lEvCode
復元するイベント。次の一覧は、システム定義イベント通知を示している。

注意

EC_REPAINT などのようにデフォルト処理が指定されているイベントは、通常、アプリケーションに渡されない。

WaitForCompletion メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

フィルタ グラフの動作が完了するまで待機する。

構文

objMediaEvent.WaitForCompletion msTimeout, EvCode

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
msTimeout
タイムアウトの時間幅をミリ秒単位で指定する Long 型の値。無期限で動作を停止させるには、–1 を渡す。直ちに終了させるには、ゼロを渡す。
EvCode
EC_COMPLETE などのイベント終了コードの値が格納された Long 型の値。ゼロは、動作が完了しなかったことを示す。

注意

このメソッドは、メソッドが EC_COMPLETE イベント通知、EC_ERRORABORT イベント通知、または EC_USERABORT イベント通知を受け取るか、タイムアウトの期限が切れるか、どちらかが最初に起きるまで GetEvent を繰り返し呼び出すことによって、動作停止状態にとどまる。

タイムアウトの値に達した場合、メソッドは、終了コード値 0 を返し、「アプリケーション定義エラーまたはオブジェクト定義エラー」を示す実行時エラー 287 を生成する。msTimeOut パラメータを –1 (無限大) 以外の値に設定すると、この実行時エラーが発生する可能性がある。On Error Resume Next ステートメントでこのエラーを処理し、EvCode の値をチェックすることができる。0 はタイムアウトが起きたことを示し、1 (EC_COMPLETE) 以上の値は、動作が完了していることを示す。次の例は、タイムアウトを 0 にしてこのメソッドを使用するのを示している。

Dim pME As IMediaEvent
Dim EventCode As Long
Set pME = pMC

    On Error Resume Next

pME.WaitForCompletion 0, EventCode	'WaitForCompletion から直ちに戻る
    
    Set pME = Nothing

If EventCode = 0 Then Exit Sub

無期限のタイムアウトを使用するには、次の例のように、戻りイベント コード 1 をチェックする。

Dim pME As IMediaEvent
Dim EventCode As Long
Set pME = pMC

pME.WaitForCompletion -1, EventCode	'EC_COMPLETE まで待機
    
If EventCode = 1 Then Exit Sub

メソッドが終了した時点で、フィルタ グラフはまだトランスポート状態になっている。このメソッドでは、アプリケーションが IMediaEvent への別の呼び出しを行っていないものと想定している。グラフがトランスポート状態になっていない場合、またはトランスポート状態へ移行中でない場合、このメソッドは失敗する。