IWMReaderCallbackAdvanced
COM公式ドキュメント
IWMReaderCallback インターフェイスは、ファイルから読み取られるデータを処理するためにアプリケーションによって実装されます。
メソッド 6
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
OnStreamSample メソッドは、ソースファイルのストリームサンプルを、最初に展開せずに配信します。
| wStreamNum | WORD | in | ストリーム番号を格納する WORD。 | ||||||||||
| cnsSampleTime | ULONGLONG | in | サンプル時刻を 100 ナノ秒単位で格納する QWORD。 | ||||||||||
| cnsSampleDuration | ULONGLONG | in | サンプルの継続時間を 100 ナノ秒単位で格納する QWORD。 | ||||||||||
| dwFlags | DWORD | in | 指定できるフラグには、次の用途があります。
| ||||||||||
| pSample | INSSBuffer* | in | INSSBuffer インターフェイスに格納されたサンプルへのポインター。リーダーは、OnStreamSample メソッドが戻った後、このポインターに対して SAFE_RELEASE を呼び出します。バッファーの参照カウントを保持する必要がある場合は、このポインターに対して AddRef を呼び出すことができます。AddRef を呼び出していない限り、このポインターに対して Release を呼び出さないでください。 | ||||||||||
| pvContext | void* | in | アプリケーションが使用する汎用ポインター。 |
戻り値
このメソッドを使用するには、アプリケーションで実装する必要があります。実装に適した任意の HRESULT エラーコードを返すことができます。Windows Media Format SDK で使用するために用意されている HRESULT エラーコードの詳細については、エラーコードを参照してください。
解説(Remarks)
非同期リーダーを使用する場合、ストリーム番号に対して配信できるのは圧縮されたサンプルのみです。ストリーム番号を指定して非圧縮のサンプルを取得したい場合は、同期リーダーを使用してください。
圧縮されたサンプルを取得したい理由は数多くあります。最も一般的な用途は、ある ASF ファイルから別の ASF ファイルへストリームを転送することです。
圧縮されたサンプルを受け取った場合は、それらを圧縮したままにするか、アプリケーションで展開する必要があります。Windows Media Format SDK は、ファイルから取り出したサンプルを展開するメソッドを提供していません。
このメソッドはセキュリティで保護されたコンテンツを配信できません。保護されたコンテンツが使用されている場合、このメソッドは NS_E_PROTECTEDCONTENT を返します。
このメソッドによって配信されるサンプルは圧縮されていますが、それ以外の点では IWMReaderCallback::OnSample を通じて配信されるサンプルとまったく同じです。
特定のストリームのサンプルを取得するには、IWMReaderAdvanced::SetReceiveStreamSamples を呼び出します。
OnTime メソッドは、リーダーが基準としているクロック時刻をアプリケーションに通知します。このメソッドは、ユーザーが提供するクロックが指定されている場合に使用されます。
| cnsCurrentTime | ULONGLONG | in | 現在時刻を 100 ナノ秒単位で格納する QWORD。 |
| pvContext | void* | in | アプリケーションが使用する汎用ポインター。このポインターは、IWMReader::Start メソッドに渡されたコンテキストポインターです。 |
戻り値
このメソッドを使用するには、アプリケーションで実装する必要があります。実装に適した任意の HRESULT エラーコードを返すことができます。Windows Media Format SDK で使用するために用意されている HRESULT エラーコードの詳細については、エラーコードを参照してください。
解説(Remarks)
リーダーが現在の経過時間として登録した内容を示すコールバックを、アプリケーションが受け取る必要があるケースは 2 つあります。1 つ目のケースは、ASF ファイルにギャップがある場合(たとえば 10 秒間オーディオがない場合)です。この場合、OnSample は呼び出されませんが、OnTime メソッドは呼び出され続けます。2 つ目のケースは、アプリケーションがクロックを駆動している場合で、リーダーは、IWMReaderAdvanced::DeliverTime の呼び出しでアプリケーションが要求したポイントまでのすべてのデータを配信した後に OnTime を呼び出します。
OnStreamSelection メソッドは、帯域幅の制限によって行われたストリームの変更をアプリケーションに通知します。このメソッドを呼び出させるには、IWMReaderAdvanced::SetReceiveSelectionCallbacks を呼び出します。
| wStreamCount | WORD | in | pStreamNumbers 配列内のエントリ数を格納する WORD。 |
| pStreamNumbers | WORD* | in | ストリーム番号の配列へのポインター。 |
| pSelections | WMT_STREAM_SELECTION* | in | WMT_STREAM_SELECTION 列挙型のメンバーの配列へのポインター。この配列の各要素は、pStreamNumbers が指す配列の対応する要素に格納されているストリーム番号に対応します。 |
| pvContext | void* | in | アプリケーションが使用する汎用ポインター。このポインターは、IWMReader::Start メソッドに渡されたコンテキストポインターです。 |
戻り値
このメソッドを使用するには、アプリケーションで実装する必要があります。実装に適した任意の HRESULT エラーコードを返すことができます。Windows Media Format SDK で使用するために用意されている HRESULT エラーコードの詳細については、エラーコードを参照してください。
解説(Remarks)
ストリーム番号の範囲は 1 から 63 です。
アプリケーションは、帯域幅の制限によるストリームの変更が発生したときにもコールバックを受け取ることができます。
OnOutputPropsChanged メソッドは、指定された出力のメディアプロパティが変更されたことを示します。この変更は、IWMReader::SetOutputProps メソッドの呼び出しの結果として発生します。
| dwOutputNum | DWORD | in | 出力番号を格納する DWORD。 |
| pMediaType | WM_MEDIA_TYPE* | in | WM_MEDIA_TYPE 構造体へのポインター。 |
| pvContext | void* | in | アプリケーションが使用する汎用ポインター。このポインターは、IWMReader::Start メソッドに渡されたコンテキストポインターです。 |
戻り値
このメソッドを使用するには、アプリケーションで実装する必要があります。実装に適した任意の HRESULT エラーコードを返すことができます。Windows Media Format SDK で使用するために用意されている HRESULT エラーコードの詳細については、エラーコードを参照してください。
解説(Remarks)
このメソッドは、呼び出し元が SetOutputProps メソッド呼び出しから非同期の結果を受け取った場合に、リーダーによって呼び出されます。この出力に対して次に受信するサンプルは、これらのプロパティを持ちます。SetOutputProps を呼び出してから OnOutputPropsChanged が呼び出されるまでの間、メディアタイプの内容は未定義です。
AllocateForStream メソッドは、IWMReaderCallbackAdvanced::OnStreamSample に配信されるストリームサンプル用に、ユーザーが作成したバッファーを割り当てます。独自のバッファーの割り当ての詳細については、「ユーザー割り当てサンプルのサポート」を参照してください。
| wStreamNum | WORD | in | ストリーム番号を格納する WORD。 |
| cbBuffer | DWORD | in | バッファーのサイズ(バイト単位)。 |
| ppBuffer | INSSBuffer** | out | メソッドが成功した場合、INSSBuffer インターフェイスへのポインターへのポインターを返します。 |
| pvContext | void* | in | アプリケーションが使用する汎用ポインター。このポインターは、IWMReader::Start メソッドに渡されたコンテキストポインターです。 |
戻り値
このメソッドを使用するには、アプリケーションで実装する必要があります。実装に適した任意の HRESULT エラーコードを返すことができます。Windows Media Format SDK で使用するために用意されている HRESULT エラーコードの詳細については、エラーコードを参照してください。
解説(Remarks)
ストリーム番号の範囲は 1 から 63 です。
このメソッドの拡張版である AllocateForStreamEx が IWMReaderAllocatorEx インターフェイスに存在します。
バッファーを割り当てる際は、アプリケーションに適した任意のロジックを使用できます。通常、アプリケーションはファイル用のバッファープール、またはストリームや出力ごとのバッファープールを初期化します。アプリケーションがサンプルの使用を終えると、バッファーは再利用のためにプールに戻されます。
ストリームの最大サンプルを保持するのに必要なサイズは、IWMReaderAdvanced::GetMaxStreamSampleSize を呼び出すことで判断できます。これが、その出力に使用するプール内のサンプルに設定すべきサイズです。
このメソッドの実装内でサンプルを割り当てる際は、INSSBuffer::SetLength を呼び出して、リーダーが cbBuffer パラメーターで渡した長さにバッファーの長さを設定する必要があります。バッファーに現在の長さを設定しないと、リーダーでエラーが発生する場合があります。
AllocateForOutput メソッドは、IWMReaderCallback::OnSample に配信されるサンプル用に、ユーザーが作成したバッファーを割り当てます。独自のバッファーの割り当ての詳細については、「ユーザー割り当てサンプルのサポート」を参照してください。
| dwOutputNum | DWORD | in | 出力番号を格納する DWORD。 |
| cbBuffer | DWORD | in | バッファーのサイズ(バイト単位)。 |
| ppBuffer | INSSBuffer** | out | メソッドが成功した場合、INSSBuffer インターフェイスへのポインターへのポインターを返します。 |
| pvContext | void* | in | アプリケーションが使用する汎用ポインター。このポインターは、IWMReader::Start メソッドに渡されたコンテキストポインターです。 |
戻り値
このメソッドを使用するには、アプリケーションで実装する必要があります。実装に適した任意の HRESULT エラーコードを返すことができます。Windows Media Format SDK で使用するために用意されている HRESULT エラーコードの詳細については、エラーコードを参照してください。
解説(Remarks)
このメソッドの拡張版である AllocateForOutputEx が IWMReaderAllocatorEx インターフェイスに存在します。
バッファーを割り当てる際は、アプリケーションに適した任意のロジックを使用できます。通常、アプリケーションはファイル用のバッファープール、またはストリームや出力ごとのバッファープールを初期化します。アプリケーションがサンプルの使用を終えると、バッファーは再利用のためにプールに戻されます。
出力の最大サンプルを保持するのに必要なサイズは、IWMReaderAdvanced::GetMaxOutputSampleSize を呼び出すことで判断できます。これが、その出力に使用するプール内のサンプルに設定すべきサイズです。
このメソッドの実装内でサンプルを割り当てる際は、INSSBuffer::SetLength を呼び出して、リーダーが cbBuffer パラメーターで渡した長さにバッファーの長さを設定する必要があります。バッファーに現在の長さを設定しないと、リーダーでエラーが発生する場合があります。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IWMReaderCallbackAdvanced "{96406BEB-2B2B-11D3-B36B-00C04F6108FF}" #usecom global IWMReaderCallbackAdvanced IID_IWMReaderCallbackAdvanced "{}" #comfunc global IWMReaderCallbackAdvanced_OnStreamSample 3 int,int64,int64,int,sptr,sptr #comfunc global IWMReaderCallbackAdvanced_OnTime 4 int64,sptr #comfunc global IWMReaderCallbackAdvanced_OnStreamSelection 5 int,var,var,sptr #comfunc global IWMReaderCallbackAdvanced_OnOutputPropsChanged 6 int,var,sptr #comfunc global IWMReaderCallbackAdvanced_AllocateForStream 7 int,int,sptr,sptr #comfunc global IWMReaderCallbackAdvanced_AllocateForOutput 8 int,int,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IWMReaderCallbackAdvanced "{96406BEB-2B2B-11D3-B36B-00C04F6108FF}" #usecom global IWMReaderCallbackAdvanced IID_IWMReaderCallbackAdvanced "{}" #comfunc global IWMReaderCallbackAdvanced_OnStreamSample 3 int,int64,int64,int,sptr,sptr #comfunc global IWMReaderCallbackAdvanced_OnTime 4 int64,sptr #comfunc global IWMReaderCallbackAdvanced_OnStreamSelection 5 int,sptr,sptr,sptr #comfunc global IWMReaderCallbackAdvanced_OnOutputPropsChanged 6 int,sptr,sptr #comfunc global IWMReaderCallbackAdvanced_AllocateForStream 7 int,int,sptr,sptr #comfunc global IWMReaderCallbackAdvanced_AllocateForOutput 8 int,int,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。