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

IWMReaderAdvanced2

COM
📘 Microsoft Learn (日本語) · English
IIDae14a945-b90c-4d0d-9127-80d665f7d73e継承元IWMReaderAdvanced自前メソッド開始 vtbl23

公式ドキュメント

IWMReaderAdvanced2 インターフェイスは、リーダーオブジェクトに追加の高度なメソッドを提供します。

メソッド 15

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

vtbl 23 HRESULT SetPlayMode(WMT_PLAY_MODE Mode)

SetPlayMode メソッドは、再生モードを指定します。

ModeWMT_PLAY_MODEinWMT_PLAY_MODE 列挙型のメンバーを 1 つ格納する変数。

戻り値

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

解説(Remarks)

既定の再生モードは WMT_PLAY_MODE_AUTOSELECT で、リーダーがモードを選択できるようにします。アプリケーションが、要求した URL と互換性のない再生モードを選択した場合、URL を開くときにエラーが返されます。Open 要求に対する非同期応答が完了すると、モードは WMT_PLAY_MODE_AUTOSELECT から適切に選択された再生モードに変更されます。コンテンツを開いた後は再生モードを変更できず、変更しようとするとエラーが返されます。

vtbl 24 HRESULT GetPlayMode(WMT_PLAY_MODE* pMode)

GetPlayMode メソッドは、現在の再生モードを取得します。

pModeWMT_PLAY_MODE*outWMT_PLAY_MODE 列挙型のメンバーを受け取る変数へのポインター。

戻り値

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

解説(Remarks)

ファイルを開く前は、このメソッドはリーダーがファイルを開くときに使用する再生モードを返します。既定の設定は自動選択(リーダーがモードを選択)です。ファイルを開いた後は、このメソッドはファイルの再生に実際に使用されたモードを返します。非同期の Open 要求の場合、実際のモードは WMT_OPENED 状態メッセージを受信した後に取得できます。

詳細については、IWMReaderAdvanced2::SetPlayMode の解説セクションを参照してください。

vtbl 25 HRESULT GetBufferProgress(DWORD* pdwPercent, ULONGLONG* pcnsBuffering)

GetBufferProgress メソッドは、バッファリングされたデータの割合と、完了までの残り時間を取得します。

pdwPercentDWORD*outバッファリングされたデータの割合を格納する DWORD へのポインター。
pcnsBufferingULONGLONG*outすべてのバッファリングが完了するまでの残り時間を 100 ナノ秒単位で指定する変数へのポインター。

戻り値

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

解説(Remarks)

意味のある結果を得るには、このメソッドは WMT_BUFFERING_START イベントと WMT_BUFFERING_STOP イベントの間に呼び出す必要があります。WMT_BUFFERING_START イベントより前に呼び出された場合、両方のパラメーターは 0 を返します。WMT_BUFFERING_STOP の後、次の WMT_BUFFERING_START イベントより前に呼び出された場合、このメソッドは割合として 100 を、バッファリング時間(秒)として 0 を返します。WMT_BUFFERING_START イベントは、割合と残り秒数を 0 にリセットします。

vtbl 26 HRESULT GetDownloadProgress(DWORD* pdwPercent, ULONGLONG* pqwBytesDownloaded, ULONGLONG* pcnsDownload)

GetDownloadProgress メソッドは、ダウンロードされたデータの割合と量、および完了までの残り時間を取得します。

pdwPercentDWORD*outダウンロードされたデータの割合を格納する DWORD へのポインター。
pqwBytesDownloadedULONGLONG*outダウンロードされたデータのバイト数を格納する QWORD へのポインター。
pcnsDownloadULONGLONG*outデータのダウンロードに要する残り時間を 100 ナノ秒単位で指定する変数へのポインター。

戻り値

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

解説(Remarks)

このメソッドは、Web サーバーからコンテンツをダウンロードしている間の進行状況を監視するために呼び出すことができます。

コンテンツを Web サーバーからダウンロードできるのは、再生モードが WMT_PLAY_MODE_AUDTOSELECT の場合(この場合、リーダーは自動的に再生モードを DOWNLOAD に調整します)、または再生モードが明示的に WMT_PLAY_MODE_DOWNLOAD に設定されている場合です。

これら 2 つの再生モードのいずれも現在のモードでない状態でこのメソッドを呼び出すと、すべてのパラメーターは 0 を返します。

最初の WMT_BUFFERING_START イベントより前は、すべてのパラメーターは 0 を返します。WMT_BUFFERING_START と WMT_END_OF_STREAMING の間は、ダウンロード完了の割合とダウンロードされたバイト数の値は常に増加します。残りダウンロード秒数の値は、変化するダウンロード速度に応じて増減することがあります。WMT_END_OF_STREAMING が送信された後は、割合は 100 を返し、ダウンロードされたバイト数はダウンロードのサイズのままとなり、残り秒数は 0 になります。

vtbl 27 HRESULT GetSaveAsProgress(DWORD* pdwPercent)

GetSaveAsProgress メソッドは、保存されたデータの割合を取得します。

pdwPercentDWORD*out保存されたデータの割合を格納する DWORD へのポインター。

戻り値

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

解説(Remarks)

このメソッドは、IWMReaderAdvanced2::SaveFileAs が呼び出された後にのみ呼び出す必要があります。

ファイルの保存には時間がかかることがあります。この呼び出しは、WMT_SAVEAS_START イベントと WMT_SAVEAS_STOP イベントの間で行う必要があります。WMT_SAVEAS_START より前に呼び出された場合、またはエラーが発生した場合、このメソッドは 0 を返します。WMT_SAVEAS_STOP イベントが成功した後は 100 を返します。

vtbl 28 HRESULT SaveFileAs(LPWSTR pwszFilename)

SaveFileAs メソッドは、現在のファイルを保存します。

pwszFilenameLPWSTRinファイル名を格納するワイド文字の null 終端文字列へのポインター。

戻り値

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

戻り値 説明
S_OK
 メソッドが成功しました。
ERROR_OPERATION_ABORTED
 操作が完了する前にファイルが閉じられました。この場合、WMT_SAVEAS_STOP イベントも生成されます。
ASF_E_INVALID_STATE
 このメソッドの呼び出しが Open の呼び出しより前に行われました。
NS_E_BUSY
 以前の SaveFileAs 操作がまだ完了していません。ファイルの保存は順次行われます。
NS_E_INVALID_REQUEST
 再生モードが WMT_PLAY_MODE_DOWNLOAD ではありません。
STG_E_MEDIUMFULL
 ディスクの空き容量が不足しています。下の解説にある注を参照してください。

解説(Remarks)

このメソッドは、Web サーバーからダウンロードしたコンテンツをローカルのハードディスクに保存するために使用できます。ファイルは、リーダーが Web サーバーからダウンロードしているときに保存できます。

このメソッドを使用してサーバー側のプレイリストを保存できます。その場合、プレイリストに使用する名前を指定すると、プレイリスト内の各ファイルが自動的に保存されます。

この操作は非同期です。WMT_SAVEAS_STOP は、すべてのデータが保存されたことを示します。リーダーを閉じると、完了していない保存操作は終了します。

このメソッドは完了までに時間がかかることがあり、GetSaveAsProgress を呼び出して進行状況を確認できます。

メモ 保存するファイルが 1 MB を超える場合、ディスク容量不足エラー (STG_E_MEDIUMFULL) が発生する可能性があります。これは、Microsoft Internet Explorer の最大キャッシュサイズが 1 MB であるためで、この場合のエラーはディスクの空き容量を指しているわけではありません。このため、この方法で保存できるファイルのサイズは実質的に 1 MB 未満に制限されます。
vtbl 29 HRESULT GetProtocolName(LPWSTR pwszProtocol, DWORD* pcchProtocol)

GetProtocolName メソッドは、使用されているプロトコルの名前を取得します。

pwszProtocolLPWSTRoutプロトコル名を格納する文字列を受け取るバッファーへのポインター。名前の長さを取得するには NULL を渡します。
pcchProtocolDWORD*inout入力時は、pwszProtocol の長さ(文字数)を格納する変数へのポインター。出力時は、終端の null 文字を含む名前の長さがこの変数に格納されます。

戻り値

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

戻り値 説明
S_OK
 メソッドが成功しました。
ASF_E_BUFFERTOOSMALL
 バッファーが小さすぎます。
ASF_E_INVALIDSTATE
 プロトコルが確定していないか、ファイルが開かれていません。
E_INVALIDARG
 pcchProtocol パラメーターが NULL です。

解説(Remarks)

GetProtocolName は 2 回呼び出す必要があります。1 回目の呼び出しでは、pwszProtocol に NULL を渡します。戻ると、pcchProtocol が指す値に、プロトコル名を格納するために必要なワイド文字数(終端の null を含む)が設定されます。その後、文字列に必要な量のメモリを割り当て、2 回目の呼び出しでそのポインターを pwszProtocol として渡すことができます。

プロトコル名は、mmsu、http、file などの URL スキームです。ただし、リーダーオブジェクトは最適なプロトコルを見つけるためにプロトコルロールオーバーを使用する場合があるため、プロトコル名は IWMReader::Open で指定した URL スキームと異なることがあります。また、返される文字列は、ローカルファイルのコンテンツの場合は "File"、キャッシュに保存されたコンテンツの場合は "Cache" となることがあります。

プロトコル名を確定できない場合、このメソッドは空の文字列を返すことがあります。

vtbl 30 HRESULT StartAtMarker(WORD wMarkerIndex, ULONGLONG cnsDuration, FLOAT fRate, void* pvContext)

StartAtMarker メソッドは、指定したマーカーからリーダーを開始します。

wMarkerIndexWORDinマーカーインデックスを格納する WORD。
cnsDurationULONGLONGin継続時間を 100 ナノ秒単位で指定します。
fRateFLOATinレートを示す浮動小数点数。通常速度の再生は 1.0 で、大きい数値ほど再生が速くなります。0 未満の数値は逆方向のレート(巻き戻し)を示します。有効な範囲は 1.0～10.0 および -1.0～-10.0 です。
pvContextvoid*inアプリケーションで使用する汎用ポインター。

戻り値

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

戻り値 説明
S_OK
 メソッドが成功しました。
E_OUTOFMEMORY
 使用可能なメモリが不足しています。
NS_E_INVALID_REQUEST
 fRate の値が有効な範囲内にありません。
E_UNEXPECTED
 原因不明の理由でメソッドが失敗しました。

解説(Remarks)

このメソッドは IWMReader::Start と非常によく似ています。違いは、このメソッドがマーカーインデックスを使用するのに対し、IWMReader::Start は開始時刻を使用する点です。

vtbl 31 HRESULT GetOutputSetting(DWORD dwOutputNum, LPWSTR pszName, WMT_ATTR_DATATYPE* pType, BYTE* pValue, WORD* pcbLength)

GetOutputSetting メソッドは、特定の出力の設定を名前で取得します。

dwOutputNumDWORDin出力番号を格納する DWORD。
pszNameLPWSTRin設定名を格納するワイド文字の null 終端文字列へのポインター。設定名を表すグローバル定数の一覧については、Output Settings を参照してください。
pTypeWMT_ATTR_DATATYPE*out値の型を指定する WMT_ATTR_DATATYPE 列挙型のメンバーへのポインター。
pValueBYTE*out値を格納するバイトバッファーへのポインター。必要なバッファーの長さを取得するには NULL を渡します。
pcbLengthWORD*inout入力時は、pValue の長さを格納する変数へのポインター。出力時は、pValue のバイト数がこの変数に格納されます。

戻り値

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

解説(Remarks)

GetOutputSetting は 2 回呼び出す必要があります。1 回目の呼び出しでは、pValue に NULL を渡します。戻ると、pcbLength が指す値に、設定値を格納するために必要なバッファーサイズが設定されます。その後、バッファーに必要な量のメモリを割り当て、2 回目の呼び出しでそのポインターを pValue として渡すことができます。

vtbl 32 HRESULT SetOutputSetting(DWORD dwOutputNum, LPWSTR pszName, WMT_ATTR_DATATYPE Type, BYTE* pValue, WORD cbLength)

SetOutputSetting メソッドは、特定の出力に対して名前付きの設定を指定します。

dwOutputNumDWORDin出力番号を格納する DWORD。
pszNameLPWSTRin名前を格納するワイド文字の null 終端文字列へのポインター。設定名を表すグローバル定数の一覧については、Output Settings を参照してください。
TypeWMT_ATTR_DATATYPEin値の型を指定する WMT_ATTR_DATATYPE 列挙型のメンバー。
pValueBYTE*in値を格納するバイト配列へのポインター。
cbLengthWORDinpValue のサイズ。

戻り値

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

vtbl 33 HRESULT Preroll(ULONGLONG cnsStart, ULONGLONG cnsDuration, FLOAT fRate)

Preroll メソッドは、リーダーのプリロール(データのバッファリング)を開始するために使用します。

cnsStartULONGLONGin開始時刻を 100 ナノ秒単位で指定します。
cnsDurationULONGLONGin継続時間を 100 ナノ秒単位で指定します。
fRateFLOATinデータレートを指定します。

戻り値

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

解説(Remarks)

このメソッドは、アプリケーションが Start を呼び出す前に呼び出して、あらかじめデータのバッファリングを開始できます。ここでのパラメーターは、Start を呼び出すときに渡す値と同じ値に設定する必要があります。パラメーターが異なる場合、Start は再バッファリングを行います。

Start を呼び出す前に、リーダーのプリロール(データのバッファリング)が完了するのに十分な時間を確保することが重要です。ローカルファイルをプリロールする場合、通常は 6 秒で十分です。インターネット経由でファイルをプリロールする場合は、Start を呼び出す前にさらに時間を確保してください。十分な時間を確保しないと、Start を呼び出したときに Start にかかる時間が長くなります。

vtbl 34 HRESULT SetLogClientID(BOOL fLogClientID)

SetLogClientID メソッドは、リーダーがクライアントの一意の ID を記録するか、匿名のセッション ID を記録するかを指定します。

fLogClientIDBOOLin

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

値 説明
TRUE クライアントの一意の ID を送信します。
FALSE 匿名のセッション ID を送信します。

戻り値

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

解説(Remarks)

リーダーオブジェクトがネットワーク経由でコンテンツをストリーミングするとき、配信元のサーバーにログデータを送信します。このログ情報には、セッションを識別する GUID が含まれます。既定では、リーダーは匿名のセッション ID を生成します。fLogClientID の値が TRUE の場合、リーダーは現在のユーザーを一意に識別する ID を送信します。この一意の ID は、レジストリの HKEY_CURRENT_USER の下に格納されます。キーが存在しない場合、リーダーは動的に作成します。

匿名のセッション ID は常に次の形式になります。


3300AD50-2C39-46c0-AE0A-XXXXXXXXXXXX

末尾の 6 バイトはランダムに生成されます。

vtbl 35 HRESULT GetLogClientID(BOOL* pfLogClientID)

GetLogClientID メソッドは、リーダーがクライアントの一意の ID を記録するか、匿名のセッション ID を記録するかを照会します。

pfLogClientIDBOOL*outクライアントのログ ID をサーバーに送信する必要がある場合に True に設定されるブール値へのポインター。

戻り値

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

戻り値 説明
S_OK
 メソッドが成功しました。
E_INVALIDARG
 NULL または無効な引数が渡されました。

解説(Remarks)

SetLogClientID の解説を参照してください。

vtbl 36 HRESULT StopBuffering()

StopBuffering メソッドは、リーダーが WMT_BUFFERING_STOP メッセージをできるだけ早く送信するように要求します。

戻り値

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

解説(Remarks)

リーダーは、現在データをバッファリングしている場合にのみ、バッファリング停止の要求に応答します。これは、WMT_BUFFERING_START メッセージを送信済みで、対応する WMT_BUFFERING_STOP をまだ送信していない状態を意味します。ただし、リーダーがどれだけ早く要求に応答するかは保証されません。この機能は、再生モードが WMT_PLAY_MODE_DOWNLOAD に設定されている場合に特に便利です。

vtbl 37 HRESULT OpenStream(IStream* pStream, IWMReaderCallback* pCallback, void* pvContext)

OpenStream メソッドは、読み取りのために Windows Media ストリームを開きます。

pStreamIStream*inIStream インターフェイスへのポインター(下の解説セクションを参照)。
pCallbackIWMReaderCallback*inIWMReaderCallback インターフェイスへのポインター。
pvContextvoid*inアプリケーションで使用する汎用ポインター。これは IWMReaderCallback::OnStatus の呼び出し時にアプリケーションに渡されます。

戻り値

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

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

解説(Remarks)

このメソッドは、URL の代わりに IStream インターフェイスポインターを受け取る点を除いて、IWMReader::Open と同一です。IStream は、データを提供するための標準的な COM インターフェイスです。これにより、アプリケーションは単にファイルやネットワークからデータを取得するのではなく、独自のデータを提供できます。たとえば、サポートされているメディアファイル(Windows Media Audio、Windows Media Video、MP3 など)の内容を表す IStream インターフェイスポインターがあり、パフォーマンス上の理由で一時ファイルを書き込みたくない場合、これは SDK を使用してコンテンツを解析および展開できる 1 つの方法です。

このメソッドは、アプリケーションの IWMReaderCallback::OnStatus 関数に WMT_OPENED 状態通知を送信します。(OnStatus は IWMReaderCallback が IWMStatusCallback から継承しています。)

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IWMReaderAdvanced2 "{AE14A945-B90C-4D0D-9127-80D665F7D73E}"
#usecom global IWMReaderAdvanced2 IID_IWMReaderAdvanced2 "{}"
#comfunc global IWMReaderAdvanced2_SetPlayMode          23 int
#comfunc global IWMReaderAdvanced2_GetPlayMode          24 var
#comfunc global IWMReaderAdvanced2_GetBufferProgress    25 var,var
#comfunc global IWMReaderAdvanced2_GetDownloadProgress  26 var,var,var
#comfunc global IWMReaderAdvanced2_GetSaveAsProgress    27 var
#comfunc global IWMReaderAdvanced2_SaveFileAs           28 wstr
#comfunc global IWMReaderAdvanced2_GetProtocolName      29 var,var
#comfunc global IWMReaderAdvanced2_StartAtMarker        30 int,int64,float,sptr
#comfunc global IWMReaderAdvanced2_GetOutputSetting     31 int,wstr,var,var,var
#comfunc global IWMReaderAdvanced2_SetOutputSetting     32 int,wstr,int,var,int
#comfunc global IWMReaderAdvanced2_Preroll              33 int64,int64,float
#comfunc global IWMReaderAdvanced2_SetLogClientID       34 int
#comfunc global IWMReaderAdvanced2_GetLogClientID       35 var
#comfunc global IWMReaderAdvanced2_StopBuffering        36
#comfunc global IWMReaderAdvanced2_OpenStream           37 sptr,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。