Win32 API 日本語リファレンス
ホームMedia.WindowsMediaFormat › IWMReaderAdvanced

IWMReaderAdvanced

COM
IID96406bea-2b2b-11d3-b36b-00c04f6108ff継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

リーダーオブジェクトから QueryInterface を呼び出すことで、このセクションで説明する高度な機能が公開されます。

メソッド 20

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT SetUserProvidedClock(BOOL fUserClock)

SetUserProvidedClock メソッドは、アプリケーションが提供するクロックを使用するかどうかを指定します。

fUserClockBOOLinアプリケーション提供のクロックを使用する場合は True となるブール値です。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
NS_E_INVALID_REQUEST
リーダーがこの要求を処理できるように正しく構成されていません。
E_OUTOFMEMORY
メソッドはメモリを割り当てることができませんでした。
E_FAIL
内部イベントを設定できません。

解説(Remarks)

この SDK 上に構築されたアプリケーションでは、クロックを実時間ではなくアプリケーションによって駆動する必要がある場合があります。たとえば、アプリケーションがファイルを再生に要する時間よりも速い速度で読み取る場合がこれに該当します。ユーザー提供のクロックは、ソースファイルがローカルファイルである場合にのみサポートされます。

このメソッドは、現在のソースがユーザー提供のクロックをサポートしていない場合に失敗することがあります。クロックを駆動するには、アプリケーションが DeliverTime を呼び出し、その後 IWMReaderCallbackAdvanced::OnTime が指定した時刻に達するのを待つ必要があります。

vtbl 4 HRESULT GetUserProvidedClock(BOOL* pfUserClock)

GetUserProvidedClock メソッドは、ユーザー提供のクロックが指定されているかどうかを確認します。

pfUserClockBOOL*outユーザー提供のクロックが指定されている場合に True に設定されるブール値へのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_POINTER
pfUserClock パラメーターが NULL です。
vtbl 5 HRESULT DeliverTime(ULONGLONG cnsTime)

DeliverTime メソッドは、リーダーにクロック時刻を提供します。このメソッドは、アプリケーションがクロックを提供している場合にのみ使用してください。

cnsTimeULONGLONGin時刻(100 ナノ秒単位)です。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_UNEXPECTED
メソッドは原因不明の理由で失敗しました。

解説(Remarks)

このメソッドを初めて呼び出す前に、IWMReaderAdvanced::SetUserProvidedClock メソッドを値 TRUE で呼び出し、アプリケーションがクロックを提供することを指定してください。指定しない場合、DeliverTime メソッドは E_UNEXPECTED を返します。

DeliverTime が呼び出されると、リーダーは指定された時刻に達するまでできる限り高速にデータを読み取ります。リーダーがその時刻に達すると、IWMReaderCallbackAdvanced::OnTime を呼び出し、その後サンプルをコールバックに送信します。

一般に、cnsTime の値はメソッドが呼び出されるたびに増加する必要があります(つまり、クロックは前進する必要があります)。ただし、より小さい値を渡すことが可能な場合もあります。DeliverTime メソッドは非同期であり、リーダーオブジェクトは別のスレッドでデータを読み取ります。アプリケーションがより小さい時刻値を指定できるのは、リーダーオブジェクトがファイル内のその位置にまだ達していない場合に限られます。たとえば、アプリケーションが値 100 秒で DeliverTime を呼び出し、直後に値 50 秒で再度呼び出した場合、リーダーオブジェクトはファイル内の 50 秒の位置にまだ達していないため、この呼び出しはおそらく成功します。ただし、アプリケーションはリーダーのスレッドを制御していないため、この場合に呼び出しが成功する保証はありません。

vtbl 6 HRESULT SetManualStreamSelection(BOOL fSelection)

SetManualStreamSelection メソッドは、ストリーム選択を手動で制御するかどうかを指定します。

fSelectionBOOLin手動選択を指定する場合は True となるブール値です。

戻り値

このメソッドは常に S_OK を返します。

解説(Remarks)

このメソッドを呼び出して手動ストリーム選択を有効にすると、ファイル内のすべてのストリームが選択されます。特定のストリームを選択するには、目的のストリーム番号の配列を IWMReaderAdvanced::SetStreamsSelected メソッドに渡します。

手動ストリーム選択が有効な場合、GetStreamSelectedSetStreamsSelected を使用して選択されたストリームを管理できます。

ストリーム番号は 1 から 63 の範囲です。

vtbl 7 HRESULT GetManualStreamSelection(BOOL* pfSelection)

GetManualStreamSelection メソッドは、手動ストリーム選択が指定されているかどうかを確認します。

pfSelectionBOOL*out手動選択が指定されている場合に True となるブール値へのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_POINTER
pfSelection パラメーターが NULL です。
NS_E_INVALID_REQUEST
リーダーオブジェクトはまだファイルを開いていません。
vtbl 8 HRESULT SetStreamsSelected(WORD cStreamCount, WORD* pwStreamNumbers, WMT_STREAM_SELECTION* pSelections)

SetStreamsSelected メソッドは、手動ストリーム選択が有効な場合に選択されるストリームを指定します。

cStreamCountWORDinpwStreamNumbers 配列内のストリーム番号の数を格納する WORD です。
pwStreamNumbersWORD*inストリーム番号を格納する配列へのポインターです。ストリーム番号は 1 から 63 の範囲です。
pSelectionsWMT_STREAM_SELECTION*inpwStreamNumbers と同じ長さの配列へのポインターで、各エントリには WMT_STREAM_SELECTION 列挙型のメンバーが 1 つ格納されます。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_UNEXPECTED
メソッドは原因不明の理由で失敗しました。

解説(Remarks)

このメソッドを使用すると、複数のストリームの選択状態を同時に変更できます。これにより、必要とされる正確なタイミングで複数のストリームをオンまたはオフにできます。このため、このメソッドと GetStreamSelected メソッドのパラメーターは同一ではありません。

ストリームを手動で選択する場合、ファイル内の相互排他的なストリームの各セットから一度に 1 つのストリームのみを選択してください。SDK は相互排他的な複数のストリームを選択することを妨げませんが、すべての相互排他的なストリームのサンプルは同じ出力番号を使用して IWMReaderCallback::OnSample に配信されます。このため、各ストリームのサンプルを区別することが困難になります。

ストリーム番号ごとにサンプルを配信するには、非圧縮のストリームサンプルを受け取る必要があります。特定のストリームのストリームサンプルは、IWMReaderAdvanced::SetReceiveStreamSamples を呼び出すことで受け取れます。また、IWMReaderCallbackAdvanced::OnStreamSample を実装する必要もあります。

vtbl 9 HRESULT GetStreamSelected(WORD wStreamNum, WMT_STREAM_SELECTION* pSelection)

GetStreamSelected メソッドは、特定のストリームが現在選択されているかどうかを確認します。このメソッドは、手動ストリーム選択が指定されている場合にのみ使用できます。

wStreamNumWORDinストリーム番号を格納する WORD です。ストリーム番号は 1 から 63 の範囲です。
pSelectionWMT_STREAM_SELECTION*outWMT_STREAM_SELECTION 列挙型のメンバー 1 つへのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_INVALIDARG
pSelection パラメーターが NULL であるか、ストリーム番号が無効です。
E_UNEXPECTED
メソッドは原因不明の理由で失敗しました。
NS_E_INVALID_REQUEST
リーダーオブジェクトはまだファイルを開いていません。
vtbl 10 HRESULT SetReceiveSelectionCallbacks(BOOL fGetCallbacks)

SetReceiveSelectionCallbacks メソッドは、ストリーム選択の通知を IWMReaderCallbackAdvanced::OnStreamSelection に送信する必要があるかどうかを指定します。

fGetCallbacksBOOLinストリーム選択でコールバックを生成する必要がある場合は True となるブール値です。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_NOINTERFACE
コールバックインターフェースが指定されていません。
vtbl 11 HRESULT GetReceiveSelectionCallbacks(BOOL* pfGetCallbacks)

GetReceiveSelectionCallbacks メソッドは、ストリーム選択の通知を受け取るオプションが有効になっているかどうかを確認します。

pfGetCallbacksBOOL*outストリーム選択の通知が IWMReaderCallbackAdvanced::OnStreamSelection に送信される場合に True に設定されるブール値へのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_POINTER
pfGetCallbacks パラメーターが NULL です。
vtbl 12 HRESULT SetReceiveStreamSamples(WORD wStreamNum, BOOL fReceiveStreamSamples)

SetReceiveStreamSamples メソッドは、ストリームサンプルを IWMReaderCallbackAdvanced::OnStreamSample コールバックに配信するかどうかを指定します。

wStreamNumWORDinストリーム番号を格納する WORD です。ストリーム番号は 1 から 63 の範囲です。
fReceiveStreamSamplesBOOLinストリームサンプルを配信する場合は True となるブール値です。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_UNEXPECTED
メソッドは原因不明の理由で失敗しました。
E_NOINTERFACE
コールバックインターフェースが指定されていません。
NS_E_PROTECTED_CONTENT
DRM で保護されたファイルの読み取りが試行されました。

解説(Remarks)

ストリームサンプルは、ソースファイルから直接受け取るサンプルであり、展開(解凍)されていません。圧縮されたサンプルを受け取る場合は、圧縮したまま保持するか、アプリケーションで展開する必要があります。Windows Media Format SDK は、ファイルから取り出したサンプルを展開するメソッドを提供していません。

アプリケーションは、リーダーに最初に展開させるのではなく、Windows Media ストリームから直接サンプルを受け取るように自身を登録できます。これを行うには、IWMReaderCallback を実装するオブジェクト(アプリケーションが提供)が IWMReaderCallbackAdvanced をサポートしている必要があります。ASF ファイル内にどのストリームがあり、そのストリーム番号が何であるかを判別するには、リーダーオブジェクトを使用して QueryInterface を呼び出して IWMProfile インターフェースにアクセスし、プロファイル内のストリームを調べます。

vtbl 13 HRESULT GetReceiveStreamSamples(WORD wStreamNum, BOOL* pfReceiveStreamSamples)

GetReceiveStreamSamples メソッドは、ストリームサンプルが IWMReaderCallbackAdvanced::OnStreamSample の呼び出しに配信されるかどうかを確認します。

wStreamNumWORDinストリーム番号を格納する WORD です。ストリーム番号は 1 から 63 の範囲です。
pfReceiveStreamSamplesBOOL*outストリームサンプルが OnStreamSample に配信される場合に True に設定されるブール値へのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_INVALIDARG
pfReceiveStreamSamples パラメーターが NULL であるか、ストリーム番号が無効です。
E_UNEXPECTED
メソッドは原因不明の理由で失敗しました。

解説(Remarks)

ストリームサンプルは、ソースファイルから直接受け取るサンプルであり、展開(解凍)されていません。圧縮されたサンプルを受け取る場合は、圧縮したまま保持するか、アプリケーションで展開する必要があります。Windows Media Format SDK は、ファイルから取り出したサンプルを展開するメソッドを提供していません。

vtbl 14 HRESULT SetAllocateForOutput(DWORD dwOutputNum, BOOL fAllocate)

SetAllocateForOutput メソッドは、リーダーが出力サンプル用のバッファーを自身で割り当てるか、アプリケーションからバッファーを取得するかを指定します。

dwOutputNumDWORDin出力番号を格納する DWORD です。
fAllocateBOOLinリーダーがアプリケーションからバッファーを取得する場合は True となるブール値です。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

解説(Remarks)

独自のバッファーをファイル読み取り用に割り当てることで、リーダーオブジェクトがサンプルごとに新しいバッファーを割り当てるために必要となるオーバーヘッドを削減できます。リーダーオブジェクトは IWMReaderCallbackAdvanced::AllocateForOutput メソッドを呼び出します。

アプリケーションのコールバックが IWMReaderAllocatorEx インターフェースを実装している場合、AllocateForOutput の代わりに AllocateForOutputEx メソッドが呼び出されます。

vtbl 15 HRESULT GetAllocateForOutput(DWORD dwOutputNum, BOOL* pfAllocate)

GetAllocateForOutput メソッドは、IWMReaderCallback::OnSample コールバックによって配信されるサンプルの割り当てに IWMReaderCallbackAdvanced インターフェースを使用するようにリーダーが構成されているかどうかを確認します。

dwOutputNumDWORDin出力メディアストリームを識別する番号を格納する DWORD です。
pfAllocateBOOL*outリーダーがサンプルの割り当てに IWMReaderCallbackAdvanced を使用する場合に True に設定されるブール値へのポインターです。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

vtbl 16 HRESULT SetAllocateForStream(WORD wStreamNum, BOOL fAllocate)

SetAllocateForStream メソッドは、ストリームサンプル用のバッファーの割り当てにリーダーが IWMReaderCallbackAdvanced::AllocateForStream を使用するかどうかを指定します。

wStreamNumWORDinストリーム番号を格納する WORD です。ストリーム番号は 1 から 63 の範囲です。
fAllocateBOOLinリーダーがストリームの割り当てに IWMReaderCallbackAdvanced を使用する場合は True となるブール値です。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

解説(Remarks)

アプリケーションのコールバックが IWMReaderAllocatorEx インターフェースを実装している場合、AllocateForStream の代わりに AllocateForStreamEx メソッドが呼び出されます。

vtbl 17 HRESULT GetAllocateForStream(WORD dwSreamNum, BOOL* pfAllocate)

GetAllocateForStream メソッドは、IWMReaderCallbackAdvanced::OnStreamSample コールバックによって配信されるストリームサンプルの割り当てに IWMReaderCallbackAdvanced を使用するようにリーダーが構成されているかどうかを確認します。

dwSreamNumWORDinストリーム番号を格納する WORD です。
pfAllocateBOOL*outリーダーがサンプルの割り当てに IWMReaderCallbackAdvanced を使用する場合に True に設定されるブール値へのポインターです。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

解説(Remarks)

ストリーム番号は 1 から 63 の範囲です。

vtbl 18 HRESULT GetStatistics(WM_READER_STATISTICS* pStatistics)

GetStatistics メソッドは、現在のリーダー統計情報を取得します。

pStatisticsWM_READER_STATISTICS*inoutWM_READER_STATISTICS 構造体へのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_INVALIDARG
pStatisticsNULL であるか、pStatisticscbSize メンバーが WM_READER_STATISTICS のサイズに設定されていません。
E_OUTOFMEMORY
メソッドは内部オブジェクトのためのメモリを割り当てることができません。
NS_E_INVALID_REQUEST
リーダーオブジェクトはまだファイルを開いていません。

解説(Remarks)

WM_READER_STATISTICS 構造体はアプリケーションが提供する必要があります。構造体をメソッドに渡す前に cbSize データメンバーを設定する必要があります。残りのメンバーはこのメソッドによって設定されます。

どのメソッドでも同様ですが、呼び出しが多すぎるとパフォーマンスに影響する可能性があります。実際のパフォーマンスへの影響はマシンに依存します。サンプルごとに GetStatistics メソッドを使用することは推奨されません。Microsoft Windows Media Encoder は 1 秒に 1 回データを取得しており、これにより渡されるデータ量が管理可能な範囲に収まります。

GetStatistics メソッドは、IWMReaderCallback::OnSample のようなコールバックメソッドでの使用は推奨されません。一般に、そのような呼び出しはデッドロックにつながる可能性があります。

サンプルを受け取る前に接続帯域幅を判別するには、IWMReaderNetworkConfig::GetConnectionBandwidth メソッドの使用が推奨されます。GetStatistics メソッドはオーバーヘッドが大きくなります。

vtbl 19 HRESULT SetClientInfo(WM_READER_CLIENTINFO* pClientInfo)

SetClientInfo メソッドは、ログ記録に使用されるクライアント側の情報を設定します。

pClientInfoWM_READER_CLIENTINFO*in呼び出し元によって割り当てられた WM_READER_CLIENTINFO 構造体へのポインターで、クライアントに関する情報を格納します。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
E_INVALIDARG
無効な引数です。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 );
vtbl 20 HRESULT GetMaxOutputSampleSize(DWORD dwOutput, DWORD* pcbMax)

GetMaxOutputSampleSize メソッドは、指定されたメディアストリームの出力サンプルに割り当てられるバッファーの最大サイズを取得します。

dwOutputDWORDin出力メディアストリームを指定する DWORD です。
pcbMaxDWORD*out割り当てられるバッファーの最大サイズへのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
ASF_E_INVALIDSTATE
サンプルのためのファイルが開かれていません。
E_INVALIDARG
dwOutput が誤った出力を指定しているか、pcbMaxNULL ポインターです。
vtbl 21 HRESULT GetMaxStreamSampleSize(WORD wStream, DWORD* pcbMax)

GetMaxStreamSampleSize メソッドは、指定されたメディアストリームのストリームサンプルに割り当てられるバッファーの最大サイズを取得します。

wStreamWORDinストリーム番号です。
pcbMaxDWORD*out割り当てられるバッファーの最大サイズへのポインターです。

戻り値

このメソッドは HRESULT を返します。取り得る値には次の表に示すものが含まれますが、これらに限定されません。

リターンコード 説明
S_OK
メソッドは成功しました。
ASF_E_INVALIDSTATE
ストリームサンプルのためのファイルが開かれていません。
E_INVALIDARG
wStream が誤ったストリームを指定しているか、pcbMaxNULL ポインターです。
vtbl 22 HRESULT NotifyLateDelivery(ULONGLONG cnsLateness)

NotifyLateDelivery メソッドは、リーダーに対して、アプリケーションへのデータ配信が遅すぎることを通知するために使用されます。

cnsLatenessULONGLONGinデータがどれだけ遅れているかを 100 ナノ秒単位で示す QWORD です。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
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 方式にも切替可。