ホーム › Media.MediaFoundation › IMFHttpDownloadRequest

IMFHttpDownloadRequest

COM

IIDf779fddf-26e7-4270-8a8b-b983d1859de0継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

アプリケーションは、Microsoft Media Foundation が使用する HTTP および HTTPS プロトコルの既定の実装を上書きするために、このインターフェイスを実装します。(IMFHttpDownloadRequest)

メソッド 16

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

vtbl 3 HRESULT AddHeader(LPWSTR szHeader)

1 つの HTTP ヘッダーを HTTP 要求に追加するために Microsoft Media Foundation によって呼び出されます。Microsoft Media Foundation は、HTTP 要求に含めるべき各ヘッダーごとに、BeginSendRequest メソッドを呼び出す前に、このメソッドを 1 回ずつ呼び出します。

szHeader

LPWSTR

1 つの HTTP 要求ヘッダー(例:“Accept: /”)を格納します。この文字列には、キャリッジリターンやラインフィードの文字は含まれません。

戻り値

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

戻り値	説明
S_OK	要求とともに送信されるヘッダーの一覧にヘッダーを正常に追加しました。
E_OUTOFMEMORY	操作を完了するのに十分なメモリがありません。

vtbl 4 HRESULT BeginSendRequest(BYTE* pbPayload, DWORD cbPayload, IMFAsyncCallback* pCallback, IUnknown* punkState)

HTTP または HTTPS 要求を送信するために Microsoft Media Foundation によって呼び出されます。

pbPayload	BYTE*	inoptional	要求で送信するメッセージペイロードを格納するバッファーへのポインター。このパラメーターは POST 要求で使用されます。GET 要求はメッセージペイロードを持たないため、pbPayload は NULL になります。
cbPayload	DWORD	in	pbPayload バッファーのサイズ(バイト単位)。
pCallback	IMFAsyncCallback*	in	Microsoft Media Foundation が実装するコールバックオブジェクトの IMFAsyncCallback インターフェイスへのポインター。
punkState	IUnknown*	inoptional	Microsoft Media Foundation が定義する状態オブジェクトの IUnknown インターフェイスへのポインター。このパラメーターは NULL でもかまいません。

戻り値

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

戻り値	説明
S_OK	非同期操作を正常に開始しました。
E_OUTOFMEMORY	操作を完了するのに十分なメモリがありません。

解説(Remarks)

非同期書き込みがまだ保留中の間、Microsoft Media Foundation はバッファーを再割り当て、解放、または書き込みしないため、BeginWrite の実装では pbPayload が指すメモリのプライベートコピーを作成する必要はありません。

vtbl 5 HRESULT EndSendRequest(IMFAsyncResult* pResult)

BeginSendRequest によって開始された非同期操作を完了するために Microsoft Media Foundation によって呼び出されます。

pResult

IMFAsyncResult*

IMFAsyncResult インターフェイスへのポインター。Microsoft Media Foundation は、そのコールバックオブジェクトが IMFAsyncCallback::Invoke メソッドで受け取ったものと同じポインターを渡します。

戻り値

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

戻り値	説明
S_OK	要求はサーバーに正常に送信されました。

vtbl 6 HRESULT BeginReceiveResponse(IMFAsyncCallback* pCallback, IUnknown* punkState)

以前に送信した HTTP または HTTPS 要求に対してサーバーが返した応答を受信するために Microsoft Media Foundation によって呼び出されます。Media Foundation は、EndSendRequest メソッドを正常に呼び出した後にのみ、このメソッドを呼び出します。

pCallback	IMFAsyncCallback*	in	Microsoft Media Foundation が実装するコールバックオブジェクトの IMFAsyncCallback インターフェイスへのポインター。
punkState	IUnknown*	inoptional	Microsoft Media Foundation が定義する状態オブジェクトの IUnknown インターフェイスへのポインター。このパラメーターは NULL でもかまいません。

戻り値

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

戻り値	説明
S_OK	非同期操作を正常に開始しました。

vtbl 7 HRESULT EndReceiveResponse(IMFAsyncResult* pResult)

BeginReceiveResponse によって開始された非同期操作を完了するために Microsoft Media Foundation によって呼び出されます。

pResult

IMFAsyncResult*

戻り値

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

戻り値	説明
S_OK	HTTP 応答と関連するヘッダーを正常に受信しました。

解説(Remarks)

サーバーが要求を失敗させたものの特定の HTTP ステータスコードで応答した場合でも、EndReceiveResponse は S_OK を返すべきです。Media Foundation は、HTTP ステータスコードを取得するために GetHttpStatus メソッドを呼び出します。

vtbl 8 HRESULT BeginReadPayload(BYTE* pb, DWORD cb, IMFAsyncCallback* pCallback, IUnknown* punkState)

以前に送信した HTTP または HTTPS 要求に対する応答のメッセージ本文を受信するために Microsoft Media Foundation によって呼び出されます。

pb	BYTE*	out	データを受け取るバッファーへのポインター。
cb	DWORD	in	pb バッファーのサイズ(バイト単位)を指定します。
pCallback	IMFAsyncCallback*	in	Microsoft Media Foundation が実装するコールバックオブジェクトの IMFAsyncCallback インターフェイスへのポインター。
punkState	IUnknown*	inoptional	Microsoft Media Foundation が定義する状態オブジェクトの IUnknown インターフェイスへのポインター。このパラメーターは NULL でもかまいません。

戻り値

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

戻り値	説明
S_OK	非同期操作を正常に開始しました。

解説(Remarks)

Microsoft Media Foundation は、以前の BeginReadPayload の呼び出しがまだ完了していない間に BeginReadPayload を呼び出すことはありません。

vtbl 9 HRESULT EndReadPayload(IMFAsyncResult* pResult, ULONGLONG* pqwOffset, DWORD* pcbRead)

BeginReadPayload によって開始された非同期操作を完了するために Microsoft Media Foundation によって呼び出されます。

pResult	IMFAsyncResult*	in	IMFAsyncResult インターフェイスへのポインター。Microsoft Media Foundation は、そのコールバックオブジェクトが IMFAsyncCallback::Invoke メソッドで受け取ったものと同じポインターを渡します。
pqwOffset	ULONGLONG*	out	バッファーに書き込まれた最初のバイトの、現在の HTTP 要求のメッセージ本文全体を基準とするオフセット。たとえば、Media Foundation が特定の IMFHttpDownloadRequest に対して BeginReadPayload を初めて呼び出し、バッファーサイズに 100 を指定した場合、pqwOffset パラメーターには 0 が設定されます。次に、Media Foundation が同じ IMNFHttpDownloadRequest に対して 2 回目の BeginReadPayload を呼び出すと、pqwOffset パラメーターには 100 が設定されます。
pcbRead	DWORD*	out	Media Foundation が BeginReadPayload の呼び出し時に提供したバッファーに書き込まれたバイト数を指定します。この値は、要求が失敗した場合、またはメッセージ本文の末尾に達した場合を除き、常に BeginReadPayload で指定されたバッファーのサイズと等しくなければならないことに注意してください。

戻り値

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

戻り値	説明
S_OK	BeginReadPayload で提供されたバッファーにデータを正常に書き込みました。

vtbl 10 HRESULT QueryHeader(LPWSTR szHeaderName, DWORD dwIndex, LPWSTR* ppszHeaderValue)

以前に送信した HTTP または HTTPS 要求に対する応答から、指定した HTTP ヘッダーの値を取得するために Microsoft Media Foundation によって呼び出されます。

szHeaderName	LPWSTR	in	値を照会する HTTP ヘッダーの名前。
dwIndex	DWORD	in	応答に同じ名前のヘッダーが複数含まれる場合の、指定したヘッダーのインデックス番号。値 0 は、指定した名前を持つ最初のヘッダーの値が要求されていることを示し、1 は 2 番目のヘッダーが要求されていることを示す、といった具合です。
ppszHeaderValue	LPWSTR*	out	要求されたヘッダーの値(キャリッジリターンやラインフィードの文字は含まない)に設定されます。ppszHeaderValue のメモリは CoTaskMemAlloc で割り当てる必要があり、Media Foundation が CoTaskMemFree で解放します。

戻り値

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

戻り値	説明
S_OK	指定したインデックスの、指定したヘッダーの値を正常に返しました。
E_OUTOFMEMORY	操作を完了するのに十分なメモリがありません。
E_POINTER	ppszHeaderValue パラメーターが無効なポインターです。
MF_E_OUT_OF_RANGE	dwIndex パラメーターの値が範囲外です。

vtbl 11 HRESULT GetURL(LPWSTR* ppszURL)

要求の送信に使用される URL を返します。

ppszURL

LPWSTR*

out

サーバーへ要求を送信するために使用される URL。サーバーが HTTP プロトコルの“リダイレクト”を発行した場合、この URL は異なる場合があることに注意してください。pszURL のメモリは CoTaskMemAlloc で割り当てる必要があり、Media Foundation が CoTaskMemFree で解放します。

戻り値

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

戻り値	説明
S_OK	URL を正常に返しました。
E_OUTOFMEMORY	操作を完了するのに十分なメモリがありません。
E_POINTER	ppszURL パラメーターが無効なポインターです。

解説(Remarks)

既定では、GetURL は、Media Foundation が IMFHttpDownloadSession::SetServer および IMFHttpDownloadSession::CreateRequest メソッドで提供したパラメーターから合成された URL を返します。ただし、HTTP サーバーが(すなわち“302 See Other” HTTP 応答を通じて)IMFHttpDownloadRequest を別のサーバーへリダイレクトした場合、GetURL メソッドは HTTP サーバーが指定した URL を返します。

vtbl 12 HRESULT HasNullSourceOrigin(BOOL* pfNullSourceOrigin)

HTTP または HTTPS 要求が異なる“オリジン”の別のサーバーへリダイレクトされた場合を検出するために Microsoft Media Foundation によって呼び出されます。

pfNullSourceOrigin

BOOL*

out

現在の要求のソースオリジンが“null”である場合に TRUE に設定されます。ソースオリジンは、HTTP 要求があるサーバーから別のサーバーへリダイレクトされ、かつその 2 つのサーバーのオリジンが異なる場合に“null”になります。

戻り値

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

戻り値	説明
S_OK	操作を正常に完了しました。
E_POINTER	pfNullSOurceOrigin パラメーターが無効なポインターです。

解説(Remarks)

HasNullSourceOrigin が EndReceiveResponse の呼び出し前に呼び出された場合、pfNullSourceOrigin パラメーターは TRUE に設定されるべきです。HTTP におけるオリジンの概念の詳細については、RFC-6454 を参照してください。

vtbl 13 HRESULT GetTimeSeekResult(ULONGLONG* pqwStartTime, ULONGLONG* pqwStopTime, ULONGLONG* pqwDuration)

サーバーが応答で指定した TimeSeekRange.DLNA.ORG HTTP ヘッダーの値(存在する場合)を取得するために Microsoft Media Foundation によって呼び出されます。

pqwStartTime	ULONGLONG*	out	開始時間オフセット(100 ナノ秒単位)。
pqwStopTime	ULONGLONG*	out	終了時間オフセット(100 ナノ秒単位)。
pqwDuration	ULONGLONG*	out	応答に含まれるデータの時間長(100 ナノ秒単位)。サーバーが継続時間を指定しなかった(すなわち継続時間として“*”を指定した)場合は、このパラメーターを 0 に設定します。

戻り値

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

戻り値	説明
S_OK	TimeSeekRange.DLNA.ORG HTTP ヘッダーが応答に存在し、正常に解析できました。
S_FALSE	TimeSeekRange.DLNA.ORG HTTP ヘッダーが応答に存在しなかったか、構文エラーがありました。
E_POINTER	pfNullSOurceOrigin パラメーターが無効なポインターです。

解説(Remarks)

GetTimeSeekResult が EndReceiveResponse の呼び出し前に呼び出された場合、すべてのパラメーターの値は 0 に設定されるべきです。TimeSeekRange.DLNA.ORG ヘッダーの構文については、DLNA の Web サイトを参照してください。

vtbl 14 HRESULT GetHttpStatus(DWORD* pdwHttpStatus)

サーバーが応答で指定した HTTP ステータスコードを取得するために Microsoft Media Foundation によって呼び出されます。Media Foundation は、EndReceiveResponse の呼び出しが成功した後にこのメソッドを呼び出します。

pdwHttpStatus

DWORD*

out

応答の HTTP ステータスコード。たとえば、典型的な成功応答の場合、値は 200 になります。

戻り値

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

戻り値	説明
S_OK	HTTP ステータスコードを正常に返しました。
E_FAIL	HTTP 応答をまだ受信していません。
E_POINTER	pdwHttpStatus パラメーターが無効なポインターです。

vtbl 15 HRESULT GetAtEndOfPayload(BOOL* pfAtEndOfPayload)

応答のメッセージ本文からデータを読み取るために BeginReadPayload を呼び出すべきかどうかを確認するために Microsoft Media Foundation によって呼び出されます。

pfAtEndOfPayload

BOOL*

out

BeginReadPayload の呼び出しが 1 バイト以上のデータを Media Foundation に返せる場合は FALSE に設定します。返すデータがそれ以上ない場合は TRUE に設定します。

戻り値

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

戻り値	説明
S_OK	操作を正常に完了しました。
E_POINTER	pfAtEndOfPayload パラメーターが無効なポインターです。

解説(Remarks)

Microsoft Media Foundation は、EndReceiveResponse を正常に呼び出した後にのみ GetAtEndOfPayload を呼び出します。

vtbl 16 HRESULT GetTotalLength(ULONGLONG* pqwTotalLength)

ダウンロード中のリソースの総長(判明している場合)を取得するために Microsoft Media Foundation によって呼び出されます。

pqwTotalLength

ULONGLONG*

out

ダウンロード中のリソースの総長(バイト単位)(判明している場合)。判明していない場合は、MAX_ULONG(0xFFFFFFFFFFFFFFFF)に設定します。

戻り値

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

戻り値	説明
S_OK	操作を正常に完了しました。
E_POINTER	pqwTotalLength パラメーターが無効なポインターです。

解説(Remarks)

Microsoft Media Foundation は、EndReceiveResponse を正常に呼び出した後にのみ GetTotalLength を呼び出します。リソースの総長は、現在の応答でサーバーが返したデータ量よりも大きい場合があります。たとえば、要求に HTTP“Range”ヘッダーが含まれていた場合、応答で返されるデータはリソースの総長より少ない場合があります。現在の応答で返されるデータ量は、GetRangeEndOffset メソッドを使用して計算できます。

vtbl 17 HRESULT GetRangeEndOffset(ULONGLONG* pqwRangeEnd)

現在の応答における最後のバイトの、リソースの先頭から数えたオフセットを取得するために Microsoft Media Foundation によって呼び出されます。これは、要求が HTTP“Range”ヘッダーを使用してリソースの一部のみをダウンロードする場合に役立ちます。

pqwRangeEnd

ULONGLONG*

out

現在の応答における最後のバイトの、リソースの先頭から数えたオフセット(判明している場合)。たとえば、要求で HTTP ヘッダー“Range: bytes=1000-”を指定し、応答のメッセージ本文のサイズが 200 バイトである場合、pwqRangeEnd は 1199 になります。値が判明していない場合(たとえば、サーバーが応答のサイズを指定しなかった場合)、pwqRangeEnd は MAX_ULONG(0xFFFFFFFFFFFFFFFF)に設定されます。

戻り値

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

戻り値	説明
S_OK	操作を正常に完了しました。
E_POINTER	qwpRangeEnd パラメーターが無効なポインターです。

解説(Remarks)

Microsoft Media Foundation は、EndReceiveResponse を正常に呼び出した後にのみ GetRangeEndOffset を呼び出します。

vtbl 18 HRESULT Close()

IMFHttpDownloadRequest が内部リソースを解放できるようにするために Microsoft Media Foundation によって呼び出されます。現在の要求がまだ進行中の場合は、その要求もキャンセルされます。

戻り値

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

戻り値	説明
S_OK	要求オブジェクトを正常に閉じました。

解説(Remarks)

Microsoft Media Foundation は、Close を呼び出した後、IMFHttpDownloadRequest インターフェイスの他のメソッドを一切呼び出しません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMFHttpDownloadRequest "{F779FDDF-26E7-4270-8A8B-B983D1859DE0}"
#usecom global IMFHttpDownloadRequest IID_IMFHttpDownloadRequest "{}"
#comfunc global IMFHttpDownloadRequest_AddHeader             3 wstr
#comfunc global IMFHttpDownloadRequest_BeginSendRequest      4 var,int,sptr,sptr
#comfunc global IMFHttpDownloadRequest_EndSendRequest        5 sptr
#comfunc global IMFHttpDownloadRequest_BeginReceiveResponse  6 sptr,sptr
#comfunc global IMFHttpDownloadRequest_EndReceiveResponse    7 sptr
#comfunc global IMFHttpDownloadRequest_BeginReadPayload      8 var,int,sptr,sptr
#comfunc global IMFHttpDownloadRequest_EndReadPayload        9 sptr,var,var
#comfunc global IMFHttpDownloadRequest_QueryHeader           10 wstr,int,var
#comfunc global IMFHttpDownloadRequest_GetURL                11 var
#comfunc global IMFHttpDownloadRequest_HasNullSourceOrigin   12 var
#comfunc global IMFHttpDownloadRequest_GetTimeSeekResult     13 var,var,var
#comfunc global IMFHttpDownloadRequest_GetHttpStatus         14 var
#comfunc global IMFHttpDownloadRequest_GetAtEndOfPayload     15 var
#comfunc global IMFHttpDownloadRequest_GetTotalLength        16 var
#comfunc global IMFHttpDownloadRequest_GetRangeEndOffset     17 var
#comfunc global IMFHttpDownloadRequest_Close                 18
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IMFHttpDownloadRequest "{F779FDDF-26E7-4270-8A8B-B983D1859DE0}"
#usecom global IMFHttpDownloadRequest IID_IMFHttpDownloadRequest "{}"
#comfunc global IMFHttpDownloadRequest_AddHeader             3 wstr
#comfunc global IMFHttpDownloadRequest_BeginSendRequest      4 sptr,int,sptr,sptr
#comfunc global IMFHttpDownloadRequest_EndSendRequest        5 sptr
#comfunc global IMFHttpDownloadRequest_BeginReceiveResponse  6 sptr,sptr
#comfunc global IMFHttpDownloadRequest_EndReceiveResponse    7 sptr
#comfunc global IMFHttpDownloadRequest_BeginReadPayload      8 sptr,int,sptr,sptr
#comfunc global IMFHttpDownloadRequest_EndReadPayload        9 sptr,sptr,sptr
#comfunc global IMFHttpDownloadRequest_QueryHeader           10 wstr,int,sptr
#comfunc global IMFHttpDownloadRequest_GetURL                11 sptr
#comfunc global IMFHttpDownloadRequest_HasNullSourceOrigin   12 sptr
#comfunc global IMFHttpDownloadRequest_GetTimeSeekResult     13 sptr,sptr,sptr
#comfunc global IMFHttpDownloadRequest_GetHttpStatus         14 sptr
#comfunc global IMFHttpDownloadRequest_GetAtEndOfPayload     15 sptr
#comfunc global IMFHttpDownloadRequest_GetTotalLength        16 sptr
#comfunc global IMFHttpDownloadRequest_GetRangeEndOffset     17 sptr
#comfunc global IMFHttpDownloadRequest_Close                 18
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。