ホーム › Media.WindowsMediaFormat › IWMReader

IWMReader

COM

📘 Microsoft Learn (日本語) · English

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

公式ドキュメント

IWMReader インターフェイスは、WMReader オブジェクトのオープン、クローズ、開始、一時停止、再開、およびロック解除に使用します。

メソッド 11

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

vtbl 3 HRESULT Open(LPWSTR pwszURL, IWMReaderCallback* pCallback, void* pvContext)

Open メソッドは、読み取り用に ASF ファイルを開きます。

pwszURL	LPWSTR	in	開くファイルのパスと名前を格納したワイド文字の null 終端文字列へのポインター。このメソッドは、ローカルマシン上のフォルダーへのパス、ネットワーク共有へのパス、または URL (Uniform Resource Locator) を受け付けます。
pCallback	IWMReaderCallback*	in	IWMReaderCallback インターフェイスを実装するオブジェクトへのポインター。
pvContext	void*	in	アプリケーションが使用する汎用ポインター。これは OnStatus の呼び出しでアプリケーションに渡されます。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_POINTER	pCallback パラメーターが NULL です。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
E_UNEXPECTED	原因不明の理由でメソッドが失敗しました。

解説(Remarks)

このメソッドは非同期です。すぐに制御を返し、ファイルが開かれて使用可能な状態になると、アプリケーションの IWMStatusCallback::OnStatus メソッドに WMT_OPENED ステータス通知を送信します。

このメソッドはファイルが開かれる前に制御を返すため、戻り値が S_OK であっても、必ずしもファイルが正常に開かれたことを意味するわけではありません。呼び出しが成功したかどうかを確認するには、WMT_OPENED 通知を受信したときに OnStatus の hr パラメーターの値を調べる必要があります。

hr が NS_E_NO_STREAM の場合は、ヘッダーがまだ利用できないことを意味し、ヘッダーが利用可能になり次第 WMT_SOURCE_SWITCH イベントが送信されます。WMT_SOURCE_SWITCH の前に WMT_EOF が送信されることはありません。

ファイアウォールの内側からファイルを読み取るアプリケーションでは、アドレスを IP アドレスではなく DNS (Domain Name Server) 名で指定すると、ファイルを開く際のパフォーマンスが向上します。

vtbl 4 HRESULT Close()

Close メソッドは、リーダー上のすべての出力を削除し、ファイルリソースを解放します。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
NS_E_INVALID_REQUEST	ファイルは既に閉じられています

解説(Remarks)

このメソッドは、アプリケーションの IWMStatusCallback::OnStatus メソッドに WMT_CLOSE ステータス通知を送信します。

vtbl 5 HRESULT GetOutputCount(DWORD* pcOutputs)

GetOutputCount メソッドは、リーダーに読み込まれたファイルに対して配信される非圧縮メディアストリームの数を取得します。

pcOutputs

DWORD*

out

出力数へのポインター。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_POINTER	pcOutputs パラメーターが NULL です。
E_UNEXPECTED	原因不明の理由でメソッドが失敗しました。

解説(Remarks)

相互排他ストリームを含むファイルには、同じ出力に配信される複数のストリームが含まれます。ただし、再生中に一度に配信できるのはそれらのストリームのうち 1 つだけです。ファイルを読み取る際は、出力をループ処理し、IWMReader::GetOutputProps を呼び出してそれぞれのメディアプロパティを取得することで、出力を識別できます。

このメソッドは同期的であり、ステータスコールバックへのメッセージ送信は発生しません。

vtbl 6 HRESULT GetOutputProps(DWORD dwOutputNum, IWMOutputMediaProps** ppOutput)

GetOutputProps メソッドは、非圧縮出力ストリームの現在のプロパティを取得します。

dwOutputNum	DWORD	in	出力番号を格納した DWORD。
ppOutput	IWMOutputMediaProps**	out	IWMOutputMediaProps インターフェイスへのポインターへのポインター。このインターフェイスは、このメソッドの呼び出しが成功したときに作成される出力メディアプロパティオブジェクトに属します。出力メディアプロパティオブジェクトに加えた変更は、このインターフェイスを IWMReader::SetOutputProps の呼び出しに渡さない限り、リーダーの出力には影響しません。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_POINTER	ppOutput パラメーターが NULL であるか、dwOutputNum パラメーターが出力数を超えています。
E_UNEXPECTED	原因不明の理由でメソッドが失敗しました。

解説(Remarks)

Windows Media コーデックは、ストリームのメディアサンプルをさまざまな形式で配信できます。たとえば、Windows Media Video 9 コーデックは、サンプルをビットマップ画像として、あるいは用途に合わせてさまざまなプロパティを持つ YUV 画像として配信できます。ファイルを読み込むと、出力プロパティは、その出力に関連付けられたストリームの圧縮メディアタイプに対する既定値に設定されます。指定可能な出力形式を調べるには、IWMReader::GetOutputFormatCount を呼び出して指定可能な形式の総数を取得し、続いてそれぞれについて IWMReader::GetOutputFormat を呼び出します。

このメソッドは同期的であり、ステータスコールバックへのメッセージ送信は発生しません。

vtbl 7 HRESULT SetOutputProps(DWORD dwOutputNum, IWMOutputMediaProps* pOutput)

SetOutputProps メソッドは、非圧縮出力ストリームのメディアプロパティを指定します。

dwOutputNum	DWORD	in	出力番号を格納した DWORD。
pOutput	IWMOutputMediaProps*	in	IWMOutputMediaProps インターフェイスへのポインター。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_INVALIDARG	dwOutputNum パラメーターが出力ストリーム数を超えています。
E_UNEXPECTED	原因不明の理由でメソッドが失敗しました。

解説(Remarks)

GetOutputProps の呼び出しで取得したオブジェクトを操作しても、アプリケーションが SetOutputProps も呼び出さない限り、出力メディアストリームには影響しません。

DirectX VA 形式は GetOutputFormat から返される場合がありますが、SetOutputProps に渡すと、DirectX VA 形式はこの方法では指定できないため、このメソッドは失敗します。したがって、コードでは SetOutputProps に渡す前に形式を調べるか、このメソッドが失敗した場合に GetOutputFormat から列挙される次の形式を試して対処する必要があります。DirectX VA 形式を識別する方法を示すコードスニペットについては、Enabling DirectX Video Acceleration を参照してください。

このメソッドをリーダーの実行中に呼び出すと、IWMReaderCallbackAdvanced::OnOutputPropsChanged の呼び出しが生成されます。

vtbl 8 HRESULT GetOutputFormatCount(DWORD dwOutputNumber, DWORD* pcFormats)

GetOutputFormatCount メソッドは、リーダー上のこの出力メディアストリームがサポートする、指定可能なすべての形式タイプを判別するために使用します。

dwOutputNumber	DWORD	in	出力番号を格納した DWORD。
pcFormats	DWORD*	out	形式数へのポインター。

戻り値

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

解説(Remarks)

出力で配信できる形式の数は、デコードコーデックによって決まります。Windows Media コーデックは、ストリームのメディアサンプルをさまざまな形式で配信できます。たとえば、Windows Media Video 9 コーデックは、サンプルをビットマップ画像として、あるいは用途に合わせてさまざまなプロパティを持つ YUV 画像として配信できます。

すべての圧縮メディアタイプには、コーデックによって決まる既定の出力形式があります。既定の出力形式のプロパティは、IWMReader::GetOutputProps を呼び出して取得できます。

このメソッドは同期的であり、ステータスコールバックへのメッセージ送信は発生しません。

vtbl 9 HRESULT GetOutputFormat(DWORD dwOutputNumber, DWORD dwFormatNumber, IWMOutputMediaProps** ppProps)

GetOutputFormat メソッドは、指定した出力メディアストリームがサポートする形式を取得します。

dwOutputNumber	DWORD	in	出力番号を格納した DWORD。
dwFormatNumber	DWORD	in	形式番号を格納した DWORD。
ppProps	IWMOutputMediaProps**	out	IWMOutputMediaProps インターフェイスへのポインターへのポインター。このインターフェイスは、このメソッドの呼び出しが成功したときに作成される出力メディアプロパティオブジェクトに属します。このインターフェイスが公開するプロパティは、指定した出力がサポートできる形式を表します。その出力に現在設定されているプロパティは、IWMReader::GetOutputProps を呼び出して取得できます。

戻り値

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

解説(Remarks)

Windows Media コーデックは、ストリームのメディアサンプルをさまざまな形式で配信できます。たとえば、Windows Media Video 9 コーデックは、サンプルをさまざまな RGB 形式または YUV 形式で配信できます。このメソッドを IWMReader::GetOutputFormatCount と組み合わせて使用すると、利用可能な形式をループ処理し、必要な形式を見つけることができます。

このメソッドが返す形式を使用するには、IWMReader::SetOutputProps を呼び出す必要があります。

このメソッドは同期的であり、ステータスコールバックへのメッセージ送信は発生しません。

vtbl 10 HRESULT Start(ULONGLONG cnsStart, ULONGLONG cnsDuration, FLOAT fRate, void* pvContext)

Start メソッドは、リーダーオブジェクトに、指定した開始時間オフセットから読み取りを開始させます。データは読み取られると、アプリケーションの IWMReaderCallback::OnSample コールバックメソッドを通じてアプリケーションに渡されます。

cnsStart	ULONGLONG	in	読み取りを開始するファイル内の時間 (100 ナノ秒単位)。cnsStart に WM_START_CURRENTPOSITION を設定すると、現在の位置から再生が開始されます。
cnsDuration	ULONGLONG	in	読み取りの継続時間 (100 ナノ秒単位)。ファイルの末尾まで読み取る場合は 0 を指定します。
fRate	FLOAT	in	再生速度。通常の速度は 1.0 です。値を大きくすると再生が速くなり、0 未満の値は逆方向の速度 (巻き戻し) を示します。有効な範囲は 1.0 から 10.0、および -1.0 から -10.0 です。
pvContext	void*	in	アプリケーションが使用する汎用ポインター。このポインターは OnSample メソッドに渡されます。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
NS_E_INVALID_REQUEST	fRate の値が有効な範囲内にないか、ファイルがシーク可能ではないのに 0 以外の開始位置が指定されています。
E_UNEXPECTED	原因不明の理由でメソッドが失敗しました。

解説(Remarks)

このメソッドは、アプリケーションの IWMReaderCallback::OnStatus 関数に WMT_STARTED ステータス通知を送信します。

現在のファイル位置を変更せずに速度だけを変更するには、WM_START_CURRENTPOSITION 値を指定して Start メソッドを使用します。

一時停止中の Start の呼び出しは、いずれもファイル内のシークとして扱われ、ネットワークファイルではバッファリングのペナルティが発生します。これは WM_START_CURRENTPOSITION 値を指定した Start の呼び出しでも同様です。バッファリングのペナルティなしで現在の一時停止位置から再生を続行するには、Resume を呼び出します。

アプリケーションが (IWMReaderAdvanced::SetUserProvidedClock を呼び出して) クロックを提供している場合は、通常 cnsDuration パラメーターを 0 に設定する必要があります。アプリケーションが 0 以外の値を指定する場合は、IWMReaderAdvanced::DeliverTime メソッドを 1 回だけ呼び出す必要があり、DeliverTime に渡す値は停止時間または (QWORD)-1 のいずれかでなければなりません。その後、リーダーオブジェクトは指定した継続時間までサンプルを配信します。

このメソッドは IWMReaderAdvanced2::StartAtMarker メソッドとよく似ていますが、そのメソッドは開始時間の代わりにマーカーを使用します。

vtbl 11 HRESULT Stop()

Stop メソッドは、ファイルの読み取りを停止します。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
E_UNEXPECTED	原因不明の理由でメソッドが失敗しました。

解説(Remarks)

このメソッドは、アプリケーションの IWMReaderCallback::OnStatus 関数に WMT_STOPPED ステータス通知を送信します。

Stop を呼び出すと、現在の読み取り位置がなくなります。Stop を呼び出した後に開始時間を WM_START_CURRENTPOSITION に設定して Start を呼び出すと、エラーが返されます。

vtbl 12 HRESULT Pause()

Pause メソッドは、現在の読み取り操作を一時停止します。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_OUTOFMEMORY	使用可能なメモリが不足しています。
E_UNEXPECTED	原因不明の理由でメソッドが失敗しました。

vtbl 13 HRESULT Resume()

Resume メソッドは、Pause メソッドの呼び出し後、現在の位置からリーダーを開始します。

戻り値

メソッドが成功した場合は 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_IWMReader "{96406BD6-2B2B-11D3-B36B-00C04F6108FF}"
#usecom global IWMReader IID_IWMReader "{}"
#comfunc global IWMReader_Open                  3 wstr,sptr,sptr
#comfunc global IWMReader_Close                 4
#comfunc global IWMReader_GetOutputCount        5 var
#comfunc global IWMReader_GetOutputProps        6 int,sptr
#comfunc global IWMReader_SetOutputProps        7 int,sptr
#comfunc global IWMReader_GetOutputFormatCount  8 int,var
#comfunc global IWMReader_GetOutputFormat       9 int,int,sptr
#comfunc global IWMReader_Start                 10 int64,int64,float,sptr
#comfunc global IWMReader_Stop                  11
#comfunc global IWMReader_Pause                 12
#comfunc global IWMReader_Resume                13
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IWMReader "{96406BD6-2B2B-11D3-B36B-00C04F6108FF}"
#usecom global IWMReader IID_IWMReader "{}"
#comfunc global IWMReader_Open                  3 wstr,sptr,sptr
#comfunc global IWMReader_Close                 4
#comfunc global IWMReader_GetOutputCount        5 sptr
#comfunc global IWMReader_GetOutputProps        6 int,sptr
#comfunc global IWMReader_SetOutputProps        7 int,sptr
#comfunc global IWMReader_GetOutputFormatCount  8 int,sptr
#comfunc global IWMReader_GetOutputFormat       9 int,int,sptr
#comfunc global IWMReader_Start                 10 int64,int64,float,sptr
#comfunc global IWMReader_Stop                  11
#comfunc global IWMReader_Pause                 12
#comfunc global IWMReader_Resume                13
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。