ホーム › Media.WindowsMediaFormat › IWMHeaderInfo3

IWMHeaderInfo3

COM

IID15cc68e3-27cc-4ecd-b222-3f5d02d80bd5継承元IWMHeaderInfo2自前メソッド開始 vtbl17

公式ドキュメント

IWMHeaderInfo3 インターフェイスは、次の新しいメタデータ機能をサポートします。64 キロバイトを超える属性データ。同じ名前を持つ複数の属性。複数言語の属性。このインターフェイスを使用して作成される属性は名前が重複する可能性があるため、このインターフェイスのメソッドではインデックス値を使用して属性を識別します。IWMHeaderInfo3 インターフェイスは、メタデータエディターオブジェクト、ライターオブジェクト、リーダーオブジェクト、および同期リーダーオブジェクトによって実装されます。インスタンスへのポインターを取得するには、目的のオブジェクトの他の任意のインターフェイスの QueryInterface メソッドを呼び出します。

解説(Remarks)

ライターを使用したメタデータ編集については、To Edit Metadata with the Writer を参照してください。

メソッド 7

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

vtbl 17 HRESULT GetAttributeCountEx(WORD wStreamNum, WORD* pcAttributes)

GetAttributeCountEx メソッドは、指定したストリーム番号に関連付けられた属性の総数を取得します。

wStreamNum	WORD	in	属性数を取得する対象のストリーム番号を格納する WORD。特定のストリームではなくファイルに適用される属性の数を取得するには、ゼロを渡します。ストリーム固有とファイルレベルの両方を含む、ファイル内の全属性の総数を取得するには、0xFFFF を渡します。
pcAttributes	WORD*	out	指定したストリームに存在する属性の数を格納する WORD へのポインター。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_POINTER	pcAttributes が有効なポインターではありません。
NS_E_INVALIDREQUEST	wStreamNum が有効なストリーム番号ではありません。

解説(Remarks)

単一ストリームに対する属性の最大数は 65535 であり、これは WORD パラメーター pcAttributes の容量です。wStreamNum に 0xFFFF を渡すと、このメソッドはファイル全体の属性の総数を返します。この数は pcAttributes の容量を超える可能性があります。ファイル内の属性の数が 65535 を超える場合、このメソッドは予測できない結果を生成します。実際には、これほど多くの属性を持つファイルは通常存在しません。アプリケーションで非常に多数の属性を使用する場合は、単純に各ストリームおよびファイルレベルの属性ごとに GetAttributeCountEx を個別に呼び出してください。

vtbl 18 HRESULT GetAttributeIndices(WORD wStreamNum, LPWSTR pwszName, WORD* pwLangIndex, WORD* pwIndices, WORD* pwCount)

GetAttributeIndices メソッドは、指定したパラメーター内で有効な属性インデックスの一覧を取得します。

wStreamNum	WORD	in	属性インデックスを取得する対象のストリーム番号を格納する WORD。ゼロを渡すと、ファイルレベルの属性のインデックスを取得します。0xFFFF を渡すと、ストリームへの関連付けに関わらず、該当するすべての属性のインデックスを取得します。
pwszName	LPWSTR	in	インデックスを取得する対象の属性名を格納する、ワイド文字の null 終端文字列へのポインター。言語に基づいて属性のインデックスを取得するには、NULL を渡します。属性名は 1024 ワイド文字までに制限されます。
pwLangIndex	WORD*	in	属性インデックスを取得する対象の言語の言語インデックスを格納する WORD へのポインター。名前に基づいて属性のインデックスを取得するには、NULL を渡します。
pwIndices	WORD*	out	入力パラメーターで記述された条件を満たすインデックスを格納する WORD 配列へのポインター。配列のサイズを取得するには NULL を渡します。サイズは pwCount で返されます。
pwCount	WORD*	inout	出力時に、pwIndices 配列内の要素数を格納する WORD へのポインター。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
NS_E_SDK_BUFFERTOOSMALL	pwCount で指定されたサイズが小さすぎます。
NS_E_INVALID_REQUEST	wStreamNum が有効なストリーム番号ではない、pwLangIndex が有効な言語インデックスではない、または pwszName が有効な名前ではありません。
E_POINTER	ポインターが有効ではありません。

解説(Remarks)

取得するインデックスのセットごとに、GetAttributeIndices を 2 回呼び出す必要があります。1 回目の呼び出しでは、pwIndices に NULL を渡します。戻り時に、pwCount が指す変数にインデックス配列に必要な要素数が設定されます。次に、配列用のメモリを割り当て、pwIndices に配列へのポインターを渡して 2 回目の呼び出しを行います。

ストリーム番号に 0xFFFF を使用すると、返されるインデックス値はグローバルインデックスになります。グローバルインデックスを IWMHeaderInfo3 インターフェイスの他のメソッドの呼び出しに使用するのは、それらの呼び出しでもストリーム番号に 0xFFFF を使用する場合に限定してください。属性のグローバルインデックス値は、特定のストリーム番号(またはファイルレベル属性の場合はストリーム 0)を指定するときに使用する値とは異なります。

このメソッドで取得したインデックス値は、インデックスの降順で返されます。これは、常に降順で行うべき属性の削除を支援するためです。

vtbl 19 HRESULT GetAttributeByIndexEx(WORD wStreamNum, WORD wIndex, LPWSTR pwszName, WORD* pwNameLen, WMT_ATTR_DATATYPE* pType, WORD* pwLangIndex, BYTE* pValue, DWORD* pdwDataLength)

GetAttributeByIndexEx メソッドは、属性インデックスで指定した属性の値を取得します。

wStreamNum	WORD	in	属性が適用されるストリーム番号を格納する WORD。ファイルレベルの属性を取得するにはゼロに設定します。
wIndex	WORD	in	取得する属性のインデックスを格納する WORD。
pwszName	LPWSTR	out	属性名を格納する、ワイド文字の null 終端文字列へのポインター。文字列のサイズを取得するには NULL を渡します。サイズは pwNameLen で返されます。
pwNameLen	WORD*	inout	pwszName のサイズをワイド文字単位で格納する WORD へのポインター。このサイズには終端の null 文字が含まれます。属性名は 1024 ワイド文字までに制限されます。
pType	WMT_ATTR_DATATYPE*	out	属性に使用されるデータの型。サポートされるデータの型について詳しくは、WMT_ATTR_DATATYPE を参照してください。
pwLangIndex	WORD*	out	属性に関連付けられた言語の言語インデックスを格納する WORD へのポインター。これは、ファイルの言語リスト内におけるその言語のインデックスです。
pValue	BYTE*	out	属性値を格納するバイト配列へのポインター。属性値のサイズを取得するには NULL を渡します。サイズは pdwDataLength で返されます。
pdwDataLength	DWORD*	inout	pValue が指す属性値の長さをバイト単位で格納する DWORD へのポインター。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
NS_E_SDK_BUFFERTOOSMALL	名前または値に指定されたサイズが小さすぎます。
NS_E_INVALID_REQUEST	wStreamNum が有効なストリーム番号ではない、または wIndex に属性が存在しません。
E_POINTER	ポインターが有効ではありません。

解説(Remarks)

ストリーム番号に 0xFFFF を使用すると、グローバルインデックスを用いて属性を指定できます。グローバルインデックス値の範囲は、0 から、ストリーム番号を 0xFFFF に設定して IWMHeaderInfo3::GetAttributeCountEx を呼び出して取得した属性数より 1 少ない値までです。

Windows Media Format SDK のオブジェクトは、サポートされる一部のメタデータ属性に対して型チェックを行いますが、すべての属性に対して行うわけではありません。使用する属性は、このドキュメントの Attributes セクションで指定されたデータ型を使用して設定されていることを確認してください。同様に、他のアプリケーションによって設定された属性が正しいデータ型を使用していると想定することはできません。

vtbl 20 HRESULT ModifyAttribute(WORD wStreamNum, WORD wIndex, WMT_ATTR_DATATYPE Type, WORD wLangIndex, BYTE* pValue, DWORD dwLength)

ModifyAttribute メソッドは、既存の属性の設定を変更します。

wStreamNum	WORD	in	属性が適用されるストリーム番号を格納する WORD。ファイルレベルの属性の場合はゼロを渡します。
wIndex	WORD	in	変更する属性のインデックスを格納する WORD。
Type	WMT_ATTR_DATATYPE	in	新しい属性値に使用されるデータの型。サポートされるデータの型について詳しくは、WMT_ATTR_DATATYPE を参照してください。
wLangIndex	WORD	in	新しい属性に関連付ける言語の言語インデックスを格納する WORD。これは、ファイルの言語リスト内におけるその言語のインデックスです。
pValue	BYTE*	in	属性値を格納するバイト配列へのポインター。
dwLength	DWORD	in	属性値の長さをバイト単位で格納する DWORD。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_INVALIDARG	不正なパラメーターの組み合わせ、データ型、または属性名が使用されました。
E_NOTIMPL	このメソッドはリーダーオブジェクトでは実装されていません。
E_POINTER	ポインターが有効ではありません。
NS_E_ATTRIBUTE_READ_ONLY	属性を変更できません。
NS_E_INVALID_REQUEST	wStreamNum が有効なストリーム番号ではない、または wIndex に属性が存在しません。

解説(Remarks)

MP3 ファイルの属性を設定する場合、メタデータエディターは Unicode 仕様に従ってバイトオーダーマークを自動的に挿入します。バイトオーダーマークを手動で挿入した場合、このメソッドは失敗しませんが、値にマークが 2 つ含まれることになり、属性の読み取り時に問題が発生する可能性があります。

vtbl 21 HRESULT AddAttribute(WORD wStreamNum, LPWSTR pszName, WORD* pwIndex, WMT_ATTR_DATATYPE Type, WORD wLangIndex, BYTE* pValue, DWORD dwLength)

AddAttribute メソッドは、メタデータ属性を追加します。既存の属性の値を変更するには、IWMHeaderInfo3::ModifyAttribute メソッドを使用します。

wStreamNum	WORD	in	属性が適用されるストリームのストリーム番号を格納する WORD。この値をゼロに設定すると、ファイル全体に適用される属性を示します。
pszName	LPWSTR	in	属性名を格納する、ワイド文字の null 終端文字列へのポインター。属性名は 1024 ワイド文字までに制限されます。
pwIndex	WORD*	out	WORD へのポインター。メソッドが正常に完了すると、この値には新しい属性に割り当てられたインデックスが設定されます。
Type	WMT_ATTR_DATATYPE	in	新しい属性に使用されるデータの型。サポートされるデータの型について詳しくは、WMT_ATTR_DATATYPE を参照してください。
wLangIndex	WORD	in	新しい属性に関連付ける言語の言語インデックスを格納する WORD。これは、ファイルの言語リスト内におけるその言語のインデックスです。この値をゼロに設定すると、既定の言語が使用されることを示します。既定の言語は、アプリケーションを実行しているコンピューターの地域設定に従って作成および設定されます。
pValue	BYTE*	in	属性値を格納するバイト配列へのポインター。
dwLength	DWORD	in	属性値の長さをバイト単位で格納する DWORD。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_INVALIDARG	不正なパラメーターの組み合わせ、データ型、または属性名が使用されました。
E_NOTIMPL	このメソッドはリーダーオブジェクトでは実装されていません。
E_POINTER	ポインターが有効ではありません。
NS_E_SDK_BUFFERTOOSMALL	dwLength で指定されたサイズが小さすぎます。
NS_E_INVALID_REQUEST	wStreamNum が有効なストリーム番号ではありません。

解説(Remarks)

このメソッドは、pwszName に渡された文字列の末尾に null 文字がない場合、それを追加します。この場合、属性名を取得するために必要なバッファーは入力バッファーより 2 バイト大きくなります。

注意値の型表現を正しく使用するよう注意してください。たとえば、WM/MediaClassPrimaryID または WM/MediaClassSecondaryID 属性を設定する場合、値は文字列をバイト配列に変換したものではなく、GUID をバイト配列に変換したものとして表現する必要があります。

vtbl 22 HRESULT DeleteAttribute(WORD wStreamNum, WORD wIndex)

DeleteAttribute メソッドは、ファイルヘッダーから属性を削除します。

wStreamNum	WORD	in	属性が適用されるストリーム番号を格納する WORD。この値をゼロに設定すると、ファイルレベルの属性を示します。
wIndex	WORD	in	削除する属性のインデックスを格納する WORD。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。
E_NOTIMPL	このメソッドはリーダーオブジェクトでは実装されていません。
NS_E_INVALIDREQUEST	wStreamNum が有効なストリーム番号ではない、または wIndex に属性が存在しません。

解説(Remarks)

複数の属性を削除する場合は、インデックス値の降順で行う必要があります。便宜上、これは IWMHeaderInfo3::GetAttributeIndices によってインデックス値が取得される順序でもあります。

vtbl 23 HRESULT AddCodecInfo(LPWSTR pwszName, LPWSTR pwszDescription, WMT_CODEC_INFO_TYPE codecType, WORD cbCodecInfo, BYTE* pbCodecInfo)

AddCodecInfo メソッドは、コーデック情報をファイルに追加します。圧縮ストリームをあるファイルから別のファイルにコピーする場合、このメソッドを使用してエンコードコーデックに関する情報をファイルヘッダーに含めます。

pwszName	LPWSTR	in	名前を格納する、ワイド文字の null 終端文字列へのポインター。
pwszDescription	LPWSTR	in	説明を格納する、ワイド文字の null 終端文字列へのポインター。
codecType	WMT_CODEC_INFO_TYPE	in	コーデックの種類を指定する WMT_CODEC_INFO_TYPE 列挙体の値。
cbCodecInfo	WORD	in	コーデック情報のサイズ(バイト単位)。
pbCodecInfo	BYTE*	in	コーデック情報を格納するバイト配列へのポインター。

戻り値

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

Return code	Description
S_OK	メソッドは成功しました。

解説(Remarks)

このメソッドに渡すパラメーターは、IWMHeaderInfo2::GetCodecInfo の呼び出しによって元のファイルから取得する必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IWMHeaderInfo3 "{15CC68E3-27CC-4ECD-B222-3F5D02D80BD5}"
#usecom global IWMHeaderInfo3 IID_IWMHeaderInfo3 "{}"
#comfunc global IWMHeaderInfo3_GetAttributeCountEx    17 int,var
#comfunc global IWMHeaderInfo3_GetAttributeIndices    18 int,wstr,var,var,var
#comfunc global IWMHeaderInfo3_GetAttributeByIndexEx  19 int,int,var,var,var,var,var,var
#comfunc global IWMHeaderInfo3_ModifyAttribute        20 int,int,int,int,var,int
#comfunc global IWMHeaderInfo3_AddAttribute           21 int,wstr,var,int,int,var,int
#comfunc global IWMHeaderInfo3_DeleteAttribute        22 int,int
#comfunc global IWMHeaderInfo3_AddCodecInfo           23 wstr,wstr,int,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IWMHeaderInfo3 "{15CC68E3-27CC-4ECD-B222-3F5D02D80BD5}"
#usecom global IWMHeaderInfo3 IID_IWMHeaderInfo3 "{}"
#comfunc global IWMHeaderInfo3_GetAttributeCountEx    17 int,sptr
#comfunc global IWMHeaderInfo3_GetAttributeIndices    18 int,wstr,sptr,sptr,sptr
#comfunc global IWMHeaderInfo3_GetAttributeByIndexEx  19 int,int,sptr,sptr,sptr,sptr,sptr,sptr
#comfunc global IWMHeaderInfo3_ModifyAttribute        20 int,int,int,int,sptr,int
#comfunc global IWMHeaderInfo3_AddAttribute           21 int,wstr,sptr,int,int,sptr,int
#comfunc global IWMHeaderInfo3_DeleteAttribute        22 int,int
#comfunc global IWMHeaderInfo3_AddCodecInfo           23 wstr,wstr,int,int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。