IWMReaderAdvanced
COM公式ドキュメント
リーダーオブジェクトから QueryInterface を呼び出すことで、このセクションで説明する高度な機能が公開されます。
メソッド 20
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
SetUserProvidedClock メソッドは、アプリケーションが提供するクロックを使用するかどうかを指定します。
| fUserClock | BOOL | in | アプリケーション提供のクロックを使用する場合は True となるブール値です。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| リーダーがこの要求を処理できるように正しく構成されていません。 | |
| メソッドはメモリを割り当てることができませんでした。 | |
| 内部イベントを設定できません。 |
解説(Remarks)
この SDK 上に構築されたアプリケーションでは、クロックを実時間ではなくアプリケーションによって駆動する必要がある場合があります。たとえば、アプリケーションがファイルを再生に要する時間よりも速い速度で読み取る場合がこれに該当します。ユーザー提供のクロックは、ソースファイルがローカルファイルである場合にのみサポートされます。
このメソッドは、現在のソースがユーザー提供のクロックをサポートしていない場合に失敗することがあります。クロックを駆動するには、アプリケーションが DeliverTime を呼び出し、その後 IWMReaderCallbackAdvanced::OnTime が指定した時刻に達するのを待つ必要があります。
GetUserProvidedClock メソッドは、ユーザー提供のクロックが指定されているかどうかを確認します。
| pfUserClock | BOOL* | out | ユーザー提供のクロックが指定されている場合に True に設定されるブール値へのポインターです。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| pfUserClock パラメーターが NULL です。 |
DeliverTime メソッドは、リーダーにクロック時刻を提供します。このメソッドは、アプリケーションがクロックを提供している場合にのみ使用してください。
| cnsTime | ULONGLONG | in | 時刻(100 ナノ秒単位)です。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| メソッドは原因不明の理由で失敗しました。 |
解説(Remarks)
このメソッドを初めて呼び出す前に、IWMReaderAdvanced::SetUserProvidedClock メソッドを値 TRUE で呼び出し、アプリケーションがクロックを提供することを指定してください。指定しない場合、DeliverTime メソッドは E_UNEXPECTED を返します。
DeliverTime が呼び出されると、リーダーは指定された時刻に達するまでできる限り高速にデータを読み取ります。リーダーがその時刻に達すると、IWMReaderCallbackAdvanced::OnTime を呼び出し、その後サンプルをコールバックに送信します。
一般に、cnsTime の値はメソッドが呼び出されるたびに増加する必要があります(つまり、クロックは前進する必要があります)。ただし、より小さい値を渡すことが可能な場合もあります。DeliverTime メソッドは非同期であり、リーダーオブジェクトは別のスレッドでデータを読み取ります。アプリケーションがより小さい時刻値を指定できるのは、リーダーオブジェクトがファイル内のその位置にまだ達していない場合に限られます。たとえば、アプリケーションが値 100 秒で DeliverTime を呼び出し、直後に値 50 秒で再度呼び出した場合、リーダーオブジェクトはファイル内の 50 秒の位置にまだ達していないため、この呼び出しはおそらく成功します。ただし、アプリケーションはリーダーのスレッドを制御していないため、この場合に呼び出しが成功する保証はありません。
SetManualStreamSelection メソッドは、ストリーム選択を手動で制御するかどうかを指定します。
| fSelection | BOOL | in | 手動選択を指定する場合は True となるブール値です。 |
戻り値
このメソッドは常に S_OK を返します。
解説(Remarks)
このメソッドを呼び出して手動ストリーム選択を有効にすると、ファイル内のすべてのストリームが選択されます。特定のストリームを選択するには、目的のストリーム番号の配列を IWMReaderAdvanced::SetStreamsSelected メソッドに渡します。
手動ストリーム選択が有効な場合、GetStreamSelected と SetStreamsSelected を使用して選択されたストリームを管理できます。
ストリーム番号は 1 から 63 の範囲です。
GetManualStreamSelection メソッドは、手動ストリーム選択が指定されているかどうかを確認します。
| pfSelection | BOOL* | out | 手動選択が指定されている場合に True となるブール値へのポインターです。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| pfSelection パラメーターが NULL です。 | |
| リーダーオブジェクトはまだファイルを開いていません。 |
SetStreamsSelected メソッドは、手動ストリーム選択が有効な場合に選択されるストリームを指定します。
| cStreamCount | WORD | in | pwStreamNumbers 配列内のストリーム番号の数を格納する WORD です。 |
| pwStreamNumbers | WORD* | in | ストリーム番号を格納する配列へのポインターです。ストリーム番号は 1 から 63 の範囲です。 |
| pSelections | WMT_STREAM_SELECTION* | in | pwStreamNumbers と同じ長さの配列へのポインターで、各エントリには WMT_STREAM_SELECTION 列挙型のメンバーが 1 つ格納されます。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| メソッドは原因不明の理由で失敗しました。 |
解説(Remarks)
このメソッドを使用すると、複数のストリームの選択状態を同時に変更できます。これにより、必要とされる正確なタイミングで複数のストリームをオンまたはオフにできます。このため、このメソッドと GetStreamSelected メソッドのパラメーターは同一ではありません。
ストリームを手動で選択する場合、ファイル内の相互排他的なストリームの各セットから一度に 1 つのストリームのみを選択してください。SDK は相互排他的な複数のストリームを選択することを妨げませんが、すべての相互排他的なストリームのサンプルは同じ出力番号を使用して IWMReaderCallback::OnSample に配信されます。このため、各ストリームのサンプルを区別することが困難になります。
ストリーム番号ごとにサンプルを配信するには、非圧縮のストリームサンプルを受け取る必要があります。特定のストリームのストリームサンプルは、IWMReaderAdvanced::SetReceiveStreamSamples を呼び出すことで受け取れます。また、IWMReaderCallbackAdvanced::OnStreamSample を実装する必要もあります。
GetStreamSelected メソッドは、特定のストリームが現在選択されているかどうかを確認します。このメソッドは、手動ストリーム選択が指定されている場合にのみ使用できます。
| wStreamNum | WORD | in | ストリーム番号を格納する WORD です。ストリーム番号は 1 から 63 の範囲です。 |
| pSelection | WMT_STREAM_SELECTION* | out | WMT_STREAM_SELECTION 列挙型のメンバー 1 つへのポインターです。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| pSelection パラメーターが NULL であるか、ストリーム番号が無効です。 | |
| メソッドは原因不明の理由で失敗しました。 | |
| リーダーオブジェクトはまだファイルを開いていません。 |
SetReceiveSelectionCallbacks メソッドは、ストリーム選択の通知を IWMReaderCallbackAdvanced::OnStreamSelection に送信する必要があるかどうかを指定します。
| fGetCallbacks | BOOL | in | ストリーム選択でコールバックを生成する必要がある場合は True となるブール値です。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| コールバックインターフェースが指定されていません。 |
GetReceiveSelectionCallbacks メソッドは、ストリーム選択の通知を受け取るオプションが有効になっているかどうかを確認します。
| pfGetCallbacks | BOOL* | out | ストリーム選択の通知が IWMReaderCallbackAdvanced::OnStreamSelection に送信される場合に True に設定されるブール値へのポインターです。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| pfGetCallbacks パラメーターが NULL です。 |
SetReceiveStreamSamples メソッドは、ストリームサンプルを IWMReaderCallbackAdvanced::OnStreamSample コールバックに配信するかどうかを指定します。
| wStreamNum | WORD | in | ストリーム番号を格納する WORD です。ストリーム番号は 1 から 63 の範囲です。 |
| fReceiveStreamSamples | BOOL | in | ストリームサンプルを配信する場合は True となるブール値です。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| メソッドは原因不明の理由で失敗しました。 | |
| コールバックインターフェースが指定されていません。 | |
| DRM で保護されたファイルの読み取りが試行されました。 |
解説(Remarks)
ストリームサンプルは、ソースファイルから直接受け取るサンプルであり、展開(解凍)されていません。圧縮されたサンプルを受け取る場合は、圧縮したまま保持するか、アプリケーションで展開する必要があります。Windows Media Format SDK は、ファイルから取り出したサンプルを展開するメソッドを提供していません。
アプリケーションは、リーダーに最初に展開させるのではなく、Windows Media ストリームから直接サンプルを受け取るように自身を登録できます。これを行うには、IWMReaderCallback を実装するオブジェクト(アプリケーションが提供)が IWMReaderCallbackAdvanced をサポートしている必要があります。ASF ファイル内にどのストリームがあり、そのストリーム番号が何であるかを判別するには、リーダーオブジェクトを使用して QueryInterface を呼び出して IWMProfile インターフェースにアクセスし、プロファイル内のストリームを調べます。
GetReceiveStreamSamples メソッドは、ストリームサンプルが IWMReaderCallbackAdvanced::OnStreamSample の呼び出しに配信されるかどうかを確認します。
| wStreamNum | WORD | in | ストリーム番号を格納する WORD です。ストリーム番号は 1 から 63 の範囲です。 |
| pfReceiveStreamSamples | BOOL* | out | ストリームサンプルが OnStreamSample に配信される場合に True に設定されるブール値へのポインターです。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| pfReceiveStreamSamples パラメーターが NULL であるか、ストリーム番号が無効です。 | |
| メソッドは原因不明の理由で失敗しました。 |
解説(Remarks)
ストリームサンプルは、ソースファイルから直接受け取るサンプルであり、展開(解凍)されていません。圧縮されたサンプルを受け取る場合は、圧縮したまま保持するか、アプリケーションで展開する必要があります。Windows Media Format SDK は、ファイルから取り出したサンプルを展開するメソッドを提供していません。
SetAllocateForOutput メソッドは、リーダーが出力サンプル用のバッファーを自身で割り当てるか、アプリケーションからバッファーを取得するかを指定します。
| dwOutputNum | DWORD | in | 出力番号を格納する DWORD です。 |
| fAllocate | BOOL | in | リーダーがアプリケーションからバッファーを取得する場合は True となるブール値です。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。
解説(Remarks)
独自のバッファーをファイル読み取り用に割り当てることで、リーダーオブジェクトがサンプルごとに新しいバッファーを割り当てるために必要となるオーバーヘッドを削減できます。リーダーオブジェクトは IWMReaderCallbackAdvanced::AllocateForOutput メソッドを呼び出します。
アプリケーションのコールバックが IWMReaderAllocatorEx インターフェースを実装している場合、AllocateForOutput の代わりに AllocateForOutputEx メソッドが呼び出されます。
GetAllocateForOutput メソッドは、IWMReaderCallback::OnSample コールバックによって配信されるサンプルの割り当てに IWMReaderCallbackAdvanced インターフェースを使用するようにリーダーが構成されているかどうかを確認します。
| dwOutputNum | DWORD | in | 出力メディアストリームを識別する番号を格納する DWORD です。 |
| pfAllocate | BOOL* | out | リーダーがサンプルの割り当てに IWMReaderCallbackAdvanced を使用する場合に True に設定されるブール値へのポインターです。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。
SetAllocateForStream メソッドは、ストリームサンプル用のバッファーの割り当てにリーダーが IWMReaderCallbackAdvanced::AllocateForStream を使用するかどうかを指定します。
| wStreamNum | WORD | in | ストリーム番号を格納する WORD です。ストリーム番号は 1 から 63 の範囲です。 |
| fAllocate | BOOL | in | リーダーがストリームの割り当てに IWMReaderCallbackAdvanced を使用する場合は True となるブール値です。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。
解説(Remarks)
アプリケーションのコールバックが IWMReaderAllocatorEx インターフェースを実装している場合、AllocateForStream の代わりに AllocateForStreamEx メソッドが呼び出されます。
GetAllocateForStream メソッドは、IWMReaderCallbackAdvanced::OnStreamSample コールバックによって配信されるストリームサンプルの割り当てに IWMReaderCallbackAdvanced を使用するようにリーダーが構成されているかどうかを確認します。
| dwSreamNum | WORD | in | ストリーム番号を格納する WORD です。 |
| pfAllocate | BOOL* | out | リーダーがサンプルの割り当てに IWMReaderCallbackAdvanced を使用する場合に True に設定されるブール値へのポインターです。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。
解説(Remarks)
ストリーム番号は 1 から 63 の範囲です。
GetStatistics メソッドは、現在のリーダー統計情報を取得します。
| pStatistics | WM_READER_STATISTICS* | inout | WM_READER_STATISTICS 構造体へのポインターです。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| pStatistics が NULL であるか、pStatistics の cbSize メンバーが WM_READER_STATISTICS のサイズに設定されていません。 | |
| メソッドは内部オブジェクトのためのメモリを割り当てることができません。 | |
| リーダーオブジェクトはまだファイルを開いていません。 |
解説(Remarks)
WM_READER_STATISTICS 構造体はアプリケーションが提供する必要があります。構造体をメソッドに渡す前に cbSize データメンバーを設定する必要があります。残りのメンバーはこのメソッドによって設定されます。
どのメソッドでも同様ですが、呼び出しが多すぎるとパフォーマンスに影響する可能性があります。実際のパフォーマンスへの影響はマシンに依存します。サンプルごとに GetStatistics メソッドを使用することは推奨されません。Microsoft Windows Media Encoder は 1 秒に 1 回データを取得しており、これにより渡されるデータ量が管理可能な範囲に収まります。
GetStatistics メソッドは、IWMReaderCallback::OnSample のようなコールバックメソッドでの使用は推奨されません。一般に、そのような呼び出しはデッドロックにつながる可能性があります。
サンプルを受け取る前に接続帯域幅を判別するには、IWMReaderNetworkConfig::GetConnectionBandwidth メソッドの使用が推奨されます。GetStatistics メソッドはオーバーヘッドが大きくなります。
SetClientInfo メソッドは、ログ記録に使用されるクライアント側の情報を設定します。
| pClientInfo | WM_READER_CLIENTINFO* | in | 呼び出し元によって割り当てられた WM_READER_CLIENTINFO 構造体へのポインターで、クライアントに関する情報を格納します。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 無効な引数です。cbSize メンバーを設定する必要があり、文字列値は 1024 文字を超えてはなりません。 |
解説(Remarks)
このメソッドを呼び出す前に WM_READER_CLIENTINFO 構造体を初期化してください。cbSize メンバーには必ず構造体のサイズを設定し、未使用のフィールドはすべてゼロに設定してください。
WM_READER_CLIENTINFO info;
ZeroMemory(&info, sizeof(WM_READER_CLIENTINFO));
info.cbSize = sizeof(WM_READER_CLIENTINFO);
// その他のフィールドを設定します(表示省略)。
hr = pReaderAdvanced->SetClientInfo( &info );
GetMaxOutputSampleSize メソッドは、指定されたメディアストリームの出力サンプルに割り当てられるバッファーの最大サイズを取得します。
| dwOutput | DWORD | in | 出力メディアストリームを指定する DWORD です。 |
| pcbMax | DWORD* | out | 割り当てられるバッファーの最大サイズへのポインターです。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
|
サンプルのためのファイルが開かれていません。 |
| dwOutput が誤った出力を指定しているか、pcbMax が NULL ポインターです。 |
GetMaxStreamSampleSize メソッドは、指定されたメディアストリームのストリームサンプルに割り当てられるバッファーの最大サイズを取得します。
| wStream | WORD | in | ストリーム番号です。 |
| pcbMax | DWORD* | out | 割り当てられるバッファーの最大サイズへのポインターです。 |
戻り値
このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。
| リターンコード | 説明 |
|---|---|
| メソッドは成功しました。 | |
|
ストリームサンプルのためのファイルが開かれていません。 |
| wStream が誤ったストリームを指定しているか、pcbMax が NULL ポインターです。 |
NotifyLateDelivery メソッドは、リーダーに対して、アプリケーションへのデータ配信が遅すぎることを通知するために使用されます。
| cnsLateness | ULONGLONG | in | データがどれだけ遅れているかを 100 ナノ秒単位で示す QWORD です。 |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IWMReaderAdvanced "{96406BEA-2B2B-11D3-B36B-00C04F6108FF}" #usecom global IWMReaderAdvanced IID_IWMReaderAdvanced "{}" #comfunc global IWMReaderAdvanced_SetUserProvidedClock 3 int #comfunc global IWMReaderAdvanced_GetUserProvidedClock 4 var #comfunc global IWMReaderAdvanced_DeliverTime 5 int64 #comfunc global IWMReaderAdvanced_SetManualStreamSelection 6 int #comfunc global IWMReaderAdvanced_GetManualStreamSelection 7 var #comfunc global IWMReaderAdvanced_SetStreamsSelected 8 int,var,var #comfunc global IWMReaderAdvanced_GetStreamSelected 9 int,var #comfunc global IWMReaderAdvanced_SetReceiveSelectionCallbacks 10 int #comfunc global IWMReaderAdvanced_GetReceiveSelectionCallbacks 11 var #comfunc global IWMReaderAdvanced_SetReceiveStreamSamples 12 int,int #comfunc global IWMReaderAdvanced_GetReceiveStreamSamples 13 int,var #comfunc global IWMReaderAdvanced_SetAllocateForOutput 14 int,int #comfunc global IWMReaderAdvanced_GetAllocateForOutput 15 int,var #comfunc global IWMReaderAdvanced_SetAllocateForStream 16 int,int #comfunc global IWMReaderAdvanced_GetAllocateForStream 17 int,var #comfunc global IWMReaderAdvanced_GetStatistics 18 var #comfunc global IWMReaderAdvanced_SetClientInfo 19 var #comfunc global IWMReaderAdvanced_GetMaxOutputSampleSize 20 int,var #comfunc global IWMReaderAdvanced_GetMaxStreamSampleSize 21 int,var #comfunc global IWMReaderAdvanced_NotifyLateDelivery 22 int64 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IWMReaderAdvanced "{96406BEA-2B2B-11D3-B36B-00C04F6108FF}" #usecom global IWMReaderAdvanced IID_IWMReaderAdvanced "{}" #comfunc global IWMReaderAdvanced_SetUserProvidedClock 3 int #comfunc global IWMReaderAdvanced_GetUserProvidedClock 4 sptr #comfunc global IWMReaderAdvanced_DeliverTime 5 int64 #comfunc global IWMReaderAdvanced_SetManualStreamSelection 6 int #comfunc global IWMReaderAdvanced_GetManualStreamSelection 7 sptr #comfunc global IWMReaderAdvanced_SetStreamsSelected 8 int,sptr,sptr #comfunc global IWMReaderAdvanced_GetStreamSelected 9 int,sptr #comfunc global IWMReaderAdvanced_SetReceiveSelectionCallbacks 10 int #comfunc global IWMReaderAdvanced_GetReceiveSelectionCallbacks 11 sptr #comfunc global IWMReaderAdvanced_SetReceiveStreamSamples 12 int,int #comfunc global IWMReaderAdvanced_GetReceiveStreamSamples 13 int,sptr #comfunc global IWMReaderAdvanced_SetAllocateForOutput 14 int,int #comfunc global IWMReaderAdvanced_GetAllocateForOutput 15 int,sptr #comfunc global IWMReaderAdvanced_SetAllocateForStream 16 int,int #comfunc global IWMReaderAdvanced_GetAllocateForStream 17 int,sptr #comfunc global IWMReaderAdvanced_GetStatistics 18 sptr #comfunc global IWMReaderAdvanced_SetClientInfo 19 sptr #comfunc global IWMReaderAdvanced_GetMaxOutputSampleSize 20 int,sptr #comfunc global IWMReaderAdvanced_GetMaxStreamSampleSize 21 int,sptr #comfunc global IWMReaderAdvanced_NotifyLateDelivery 22 int64 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。