Microsoft DirectX 8.0

IAsyncReader インターフェイス

IAsyncReader インターフェイスは 非同期ファイル ソース フィルタの出力ピンによって実装される。このインターフェイスによって、メディア ストリーム内の異なる位置から複数の読み取りをオーバーラップさせることができる。このインターフェイスのメソッドはダウンストリーム フィルタの入力ピンによって呼び出される。アプリケーションでこのインターフェイスを使用することはない。

フィルタ開発者: フィルタがソースから MEDIATYPE_Stream メディア タイプのデータを読み取る場合は、このインターフェイスをピンで実装する。接続中に、IAsyncReader をサポートする出力ピンは、その出力ピンの QueryInterface メソッドが呼び出されて IAsyncReader インターフェイスが要求されたかどうを調べる必要がある。呼び出されていないと、接続中に使用するほかの転送を確立しない限り、出力ピンが接続に失敗する。

vtable 順のメソッド

IUnknown メソッド説明
QueryInterface サポートされているインターフェイスへのポインタを取得する。
AddRef 参照カウントをインクリメントする。
Release 参照カウントをデクリメントする。
IAsyncReader メソッド説明
RequestAllocator 実際に使用されるアロケータを取得する。
Request データ要求をキューに入れる。
WaitForNext 次のサンプルが完了するか、またはタイムアウトが発生するまでブロックする。
SyncReadAligned 位置合わせされた同期読み取りを実行する。
SyncRead 同期読み取りを実行する。
Length ストリームのトータルの長さ、および現在利用可能な長さを取得する。
BeginFlush すべての未処理の読み取りが返される。
EndFlush フラッシング操作を完了する。

IAsyncReader::BeginFlush

IAsyncReader インターフェイス

フラッシング操作を開始する。

構文

HRESULT BeginFlush(void);

戻り値

成功した場合は S_OK、それ以外の場合は S_FALSE を返す。

注意

すべての未処理の読み取りが返される。これに失敗コード (VFW_E_TIMEOUT) が付随する場合もある。この操作は、未処理の読み取りをキャンセルすることを示す。IAsyncReader::BeginFlush 呼び出しと IAsyncReader::EndFlush 呼び出しの間に、IAsyncReader::Request 呼び出しが失敗し、即座に IAsyncReader::WaitForNext 呼び出しが必ず完了する。

IAsyncReader::EndFlush

IAsyncReader インターフェイス

フラッシング操作を完了する。

構文

HRESULT EndFlush(void);

戻り値

成功した場合は S_OK、それ以外の場合は S_FALSE を返す。

注意

IAsyncReader::BeginFlush 呼び出しと IAsyncReader::EndFlush 呼び出しの間に、IAsyncReader::Request 呼び出しが失敗し、即座に IAsyncReader::WaitForNext 呼び出しが必ず完了する。このメソッドを呼び出して、ソースのスレッドが IAsyncReader::WaitForNext メソッド内で再び待機できるようする。

IAsyncReader::Length

IAsyncReader インターフェイス

ストリームのトータルの長さ、および現在利用可能な長さを取得する。

構文

HRESULT Length(

  LONGLONG *pTotal,
  LONGLONG *pAvailable
  );

パラメータ

pTotal
割り当て済みのトータルの長さへのポインタ。
pAvailable
利用可能な長さへのポインタ。

戻り値

成功した場合は S_OK、ファイルが開かれていない場合は E_UNEXPECTED を返す。

注意

読み取りがトータルの長さ以内であっても利用可能な長さを超える場合、通常その操作は成功するが、長時間ブロックする場合がある。

IAsyncReader::Request

IAsyncReader インターフェイス

データ要求をキューに入れる。

構文

HRESULT Request(

  IMediaSample *pSample,
  DWORD dwUser
  );

パラメータ

pSample
要求されているメディア サンプルへのポインタ。
dwUser
[in] ユーザー コンテキスト。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。 現在の Microsoft® DirectShow® の実装での戻り値は、次のとおりである。
VFW_E_BADALIGN無効なアラインメントが指定された。
VFW_E_MEDIA_TIME_NOT_SET 時間が設定されていない。
HRESULT_FROM_WIN32 ファイルの末尾を越えるデータが要求されている。
NOERRORエラーなし。
S_OK成功。

注意

メディア サンプルの開始タイムと終了タイムには、要求される絶対バイト位置が含まれる。ただし、開始位置は含まれるが、停止位置は含まれない。このメソッドは、合意されたアロケータからサンプルが取得されない場合、あるいは開始位置または停止位置が合意されたアラインメントに一致しない場合に失敗することがある。IAsyncReader::WaitForNext から戻るまでに、ソース ピンのアロケータから割り当てられたサンプルによって、IMediaSample::GetPointer が失敗する場合がある。

停止位置は位置合わせされなければならない。ただし、その停止位置が時間幅を超えている場合がある。その場合は、完了時に停止位置は位置合わせされていない実際のデータに訂正される。

dwUser パラメータは、IAsyncReader::WaitForNext メソッドから返されるサンプルを識別するために、呼び出し元が使用する。これは IAsyncReader 内では無意味だが、サンプル情報を個別に追跡する場合に使用できる。

IAsyncReader::RequestAllocator

IAsyncReader インターフェイス

実際に使用されるアロケータを取得する。

構文

HRESULT RequestAllocator(

  IMemAllocator *pPreferred,
  ALLOCATOR_PROPERTIES *pProps,
  IMemAllocator **ppActual
  );

パラメータ

pPreferred
[in] 優先するアロケータへのポインタ。
pProps
[in] 優先するアロケータのプロパティ (サイズ、カウント、およびアラインメント) へのポインタ。
ppActual
[out] 実際に使用されるアロケータへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
E_FAILアロケータの初期化が失敗した。
VFW_E_BADALIGN無効なアラインメントが指定された。
S_OK アロケータが返された。

注意

優先するアロケータおよび優先するアロケータのプロパティを渡す必要がある。このメソッドは実際に使用されるアロケータを返す。

選択されているアラインメントおよびプレフィックスを調べるには、返されたアロケータに対して IMemAllocator::GetProperties を呼び出す。このアロケータに対してコミットおよびデコミットを指示するのは、非同期リーダーではなく、コンシューマである。IAsyncReader::Request を呼び出す前に、このメソッドを呼び出す必要がある。

IAsyncReader::SyncRead

IAsyncReader インターフェイス

同期読み取りを実行する。

構文

HRESULT SyncRead(

  LONGLONG llPosition,
  LONG lLength,
  BYTE *pBuffer
  );

パラメータ

llPosition
[in] 絶対ファイル位置。
lLength
[in] 必要なバイト数。
pBuffer
[out] データが書き込まれている場所へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
VFW_E_BADALIGN無効なアラインメントが指定された。
HRESULT_FROM_WIN32 Microsoft® Win32® エラー。
S_FALSE サイズが変更された (おそらくファイルの末尾を越えたため)。
S_OK成功。

注意

SyncRead メソッドは実行状態だけでなく停止状態でも動作する。読み取りは必ずしも位置合わせされている必要はない。読み取りが実際のトータルの長さを超えていると、このメソッドは失敗する。

IAsyncReader::SyncReadAligned

IAsyncReader インターフェイス

データの同期読み取りを実行する。

構文

HRESULT SyncReadAligned(

  IMediaSample *pSample
  );

パラメータ

pSample
読み込むサンプルへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
VFW_E_BADALIGN無効なアラインメントが指定された。
HRESULT_FROM_WIN32 Win32 エラー。
S_FALSE サイズが変更された (おそらくファイルの末尾を越えたため)。
S_OK成功。

注意

渡されるサンプルは、合意されたアロケータから取得されていなければならない。開始位置と停止位置は、IAsyncReader::Request/IAsyncReader::WaitForNext ペアに合わせて位置合わせされなければならないが、ソース フィルタ上のスレッドの必要性はなくなる。

IAsyncReader::WaitForNext

IAsyncReader インターフェイス

IAsyncReader::Request を介して要求された次の読み取りが完了するまで、またはタイムアウトが発生するまでブロックする。

構文

HRESULT WaitForNext(

  DWORD dwTimeout,
  IMediaSample **ppSample,
  DWORD *pdwUser
  );

パラメータ

dwTimeout
[in] タイムアウト (ミリ秒単位)。ゼロまたは INFINITE も指定できる。
ppSample
[out] 完了したサンプルへのポインタのアドレス。
pdwUser
[out] ユーザー コンテキストへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
VFW_E_TIMEOUT タイムアウトに達した。
VFW_E_WRONG_STATE フィルタが不正な状態にあるため、操作を実行できなかった。
E_FAIL失敗。
S_OK成功。

注意

サンプルが順番どおりに返されない場合がある。なんらかの読み取りエラーがある場合、ソース フィルタによる通知が既に完了しており、HRESULT がエラーになる。ppSample が NULL ではなければ、要求は返された結果コードで完了している。

pdwUser パラメータは、返されたサンプルに対応する呼び出し元のコンテキスト DWORD を返す。