IPin

このインターフェイスは、すべての入力ピンおよび出力ピンによって公開されます。フィルターグラフマネージャーは、このインターフェイスを使用してピンを接続し、フラッシュ操作を実行します。

Connect メソッドは、ピンを別のピンに接続します。

HRESULT 値を返します。指定できる値には次のものがあります。

pmt パラメーターには NULL を指定できます。また、メジャータイプ、サブタイプ、またはフォーマットに GUID_NULL の値を指定することで、部分的なメディアタイプを指定することもできます。

このメソッドは、接続が可能かどうかを検証します。ピンが接続を拒否した場合、このメソッドは失敗します。接続元のピンは、受信側ピンで IPin::ReceiveConnection を呼び出すことでメディアタイプを提案します。

ReceiveConnection メソッドは、別のピンからの接続を受け入れます。

HRESULT 値を返します。指定できる値には次のものがあります。

出力ピンが接続するとき、入力ピンに対してこのメソッドを呼び出します。入力ピンは、指定されたメディアタイプが受け入れ可能かどうかを検証する必要があります。また、所有元フィルター固有のその他の接続要件を確認する必要がある場合もあります。接続が適切であれば、入力ピンは S_OK を返し、さらに次の処理を行う必要があります。

• メディアタイプを保存し、IPin::ConnectionMediaType メソッドで同じタイプを返します。
• 出力ピンの IPin インターフェイス（pConnector）を保存し、IPin::ConnectedTo メソッドでこのポインターを返します。

CBasePin クラスは、メディアタイプと IPin ポインターの保存を含め、このメソッドの基本的なフレームワークを実装しています。

Disconnect メソッドは、現在のピン接続を切断します。

HRESULT 値を返します。指定できる値には次のものがあります。

このメソッドは、フィルターが一時停止中または実行中の場合は失敗します。ピンが IPinConnection インターフェイスをサポートしている場合は、フィルターが一時停止中または実行中にピンを切断するには IPinConnection::DynamicDisconnect を呼び出します。

このメソッドは、ピン接続のもう一方のピンは切断しません。

ConnectedTo メソッドは、接続されているピンがある場合、そのピンへのポインターを取得します。

HRESULT 値を返します。指定できる値には次のものがあります。

このメソッドが成功した場合、返される IPin インターフェイスには未解放の参照カウントが残っています。使用が終わったら必ず解放してください。

ConnectionMediaType メソッドは、現在のピン接続にメディアタイプがある場合、そのメディアタイプを取得します。

HRESULT 値を返します。指定できる値には次のものがあります。

ピンが接続されている場合、このメソッドは pmt で指定された AM_MEDIA_TYPE 構造体にメディアタイプをコピーします。呼び出し元は、メディアタイプのフォーマットブロックを解放する必要があります。Microsoft® Win32® の CoTaskMemFree 関数、または FreeMediaType ヘルパー関数を使用できます。

ピンが接続されていない場合、このメソッドは pmt で指定されたメディアタイプをクリアし、エラーコードを返します。

QueryPinInfo メソッドは、ピンに関する情報を取得します。

HRESULT 値を返します。指定できる値には次のものがあります。

メソッドが返るときに、PIN_INFO 構造体の pFilter メンバーが非 NULL の場合、そのインターフェイスには未解放の参照カウントが残っています。使用が終わったら必ずインターフェイスを解放してください。

QueryDirection メソッドは、ピンの方向（入力または出力）を取得します。

HRESULT 値を返します。指定できる値には次のものがあります。

QueryId メソッドは、ピンの識別子を取得します。

HRESULT 値を返します。指定できる値には次のものがあります。

このメソッドはグラフの永続化をサポートします。ピンの状態を保存するにはこのメソッドを使用し、状態を復元するには IBaseFilter::FindPin メソッドを使用します。ピンの識別子文字列はフィルターの実装によって定義されます。識別子はフィルター内で一意である必要があります。

QueryAccept メソッドは、ピンが指定されたメディアタイプを受け入れるかどうかを判定します。

次のいずれかの値を返します。

S_OK という戻り値は、次のサンプル、またはピンの再接続後のいずれかで、ピンがメディアタイプを受け入れることを示します。実装では、他のピンの接続やフィルターに設定可能な各種プロパティを含め、フィルターの現在の状態を考慮する必要があります。

S_FALSE を含むその他の戻り値は、ピンがメディアタイプを拒否することを意味します。したがって、S_OK を明示的にテストしてください。SUCCEEDED マクロは使用しないでください。

フィルターが実行中の場合、S_OK という戻り値はあいまいです。ピンは再接続せずに次のメディアサンプルでのフォーマット変更を受け入れる可能性もあれば、再接続が必要な可能性もあります。ピンが IPinConnection インターフェイスをサポートしている場合は、IPinConnection::DynamicQueryAccept メソッドを呼び出してください。このメソッドは、ピンが再接続せずに新しいタイプを受け入れられるかどうかを具体的にテストします。

EnumMediaTypes メソッドは、ピンが優先するメディアタイプを列挙します。

HRESULT 値を返します。指定できる値には次のものがあります。

IEnumMediaTypes インターフェイスは、標準的な COM 列挙子と同様に動作します。詳細については、Enumerating Objects in a Filter Graph を参照してください。このメソッドが成功した場合、IEnumMediaTypes インターフェイスには未解放の参照カウントが残っています。使用が終わったら必ず解放してください。

QueryInternalConnections メソッドは、このピンに（フィルター内部で）内部的に接続されているピンを取得します。

HRESULT 値を返します。指定できる値には次のものがあります。

このメソッドは、フィルターにおける入力ピンから出力ピンへの内部的なマッピングに関する情報を返します。言い換えると、入力ピンが出力ピンにどのようにデータを配信するかを表します。

ほとんどのフィルターでは、すべての入力ピンがすべての出力ピンに接続されます。たとえば、変換フィルターでは 1 つの入力が 1 つの出力に接続され、スプリッターフィルターでは 1 つの入力が複数の出力に接続されます。これらの場合、このメソッドは単に E_NOTIMPL を返す必要があります。

それ以外の場合、このメソッドは、照会したピンに内部的にマッピングされているピンごとに 1 つずつ、IPin ポインターの配列を返します。入力ピンでこのメソッドを呼び出すと、配列には出力ピンへのポインターが格納され、その逆も同様です。

呼び出し元が IPin ポインターの配列を割り当てます。必要な配列サイズを取得するには、apPin を NULL にしてメソッドを一度呼び出します。サイズは nPin パラメーターで返されます。次に配列を割り当て、apPin に配列のアドレスを、nPin に配列サイズを設定して、メソッドを再度呼び出します。するとメソッドは配列を IPin ポインターで埋めます。返される各ポインターには未解放の参照カウントが残っており、呼び出し元が解放する必要があります。

このメソッドには、現在では非推奨となっている別の用途があります。Filter Graph Manager は、少なくとも 1 つの入力ピンがこのメソッドを実装しているが nPin に 0 を返す場合、そのフィルターをレンダラーフィルターと見なします。ただし、新しいレンダラーフィルターを作成する場合は、このメソッドを使用してフィルターがレンダラーであることを示すのではなく、IAMFilterMiscFlags インターフェイスを実装する必要があります。

EndOfStream メソッドは、フィルターに新しい実行（run）コマンドが発行されるまで追加のデータが予期されないことをピンに通知します。

HRESULT 値を返します。指定できる値には次のものがあります。

このメソッドは入力ピンでのみ呼び出してください。出力ピンは E_UNEXPECTED を返します。

このメソッドは、ストリーム終端（end-of-stream）通知をピンに送信します。ピンはその通知を下流へ配信します。ストリーム終端通知は IMemInputPin::Receive の呼び出しとの間で順序付けする必要があります。ピンが配信のためにメディアサンプルをキューに入れる場合は、ストリーム終端通知も同様にキューに入れる必要があります。IPin::BeginFlush メソッドは、キューに入っているストリーム終端通知をフラッシュします。

BeginFlush メソッドは、フラッシュ操作を開始します。(IPin.BeginFlush)

HRESULT 値を返します。指定できる値には次のものがあります。

このメソッドは入力ピンでのみ呼び出してください。出力ピンは E_UNEXPECTED を返します。

フラッシュ操作では、フィルターは処理中のデータをすべて破棄します。フラッシュが完了するまで、新しいデータを拒否します。フラッシュは、上流のピンが IPin::EndFlush メソッドを呼び出したときに完了します。フラッシュにより、通常のデータフローを変化させるイベントが発生したときに、フィルターグラフの応答性が向上します。たとえば、シーク中にフラッシュが発生します。

BeginFlush が呼び出されると、フィルターは次の手順を実行します。

1. IPin::BeginFlush の呼び出しを下流へ渡します。
2. IMemInputPin::Receive など、すべてのデータストリーミングメソッドを失敗させる内部フラグを設定します。
3. Receive メソッドへのブロックされた呼び出しがあれば、そこから復帰させます。

BeginFlush が呼び出された後、ピンは IPin::EndFlush メソッドが呼び出されるまで、上流からのすべてのサンプルを S_FALSE の戻り値で拒否します。

EndFlush メソッドは、フラッシュ操作を終了します。(IPin.EndFlush)

HRESULT 値を返します。指定できる値には次のものがあります。

このメソッドは入力ピンでのみ呼び出してください。出力ピンは E_UNEXPECTED を返します。

このメソッドが呼び出されると、フィルターは次の処理を実行します。

1. キューに入っているすべてのサンプルが破棄されるのを待ちます。
2. 保留中のストリーム終端通知を含め、バッファリングされたデータをすべて解放します。
3. 保留中の EC_COMPLETE 通知をすべてクリアします。
4. 下流に対して EndFlush を呼び出します。

NewSegment メソッドは、この呼び出し以降に受信するメディアサンプルが、共通の開始時刻・停止時刻・レートを持つ 1 つのセグメントとしてグループ化されることをピンに通知します。

成功した場合は S_OK を返し、失敗した場合はエラーの原因を示す HRESULT 値を返します。

ソースフィルター（またはパーサーフィルター）は、新しいストリームの開始時、および各シーク操作の後に、このメソッドを呼び出します。前のデータのまとまりを配信した後、かつ新しいデータで IMemInputPin::Receive を呼び出す前に、下流フィルターの入力ピンに対してこのメソッドを呼び出します。下流フィルターは NewSegment の呼び出しをさらに下流へ伝搬させます。

フィルターはセグメント情報を使用してサンプルを処理できます。たとえば、一部のフォーマットでは、次のキーフレームがないとデルタフレームを再構築できません。そのため、停止時刻がデルタフレーム上にある場合、ソースフィルターは追加のフレームをいくつか送信する必要があります。デコーダーフィルターは、セグメント情報に基づいて最終フレームを決定します。セグメントレートは、オーディオデータなどの連続的なデータソースをレンダリングするために使用されます。たとえば、オーディオレンダラーは、サンプリングレートとセグメントレートを使用してオーディオデータを正しくレンダリングします。