IWMHeaderInfo

IWMHeaderInfo インターフェイスは、ASF ファイルのヘッダーセクション内の情報を設定および取得します。

IWMHeaderInfo インターフェイスは 4 つの異なるオブジェクトから利用できますが、すべてのケースですべての機能が利用できるわけではありません。次の表に、各オブジェクトにおける実装の違いをまとめます。

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

GetAttributeCount メソッドは、ASF ファイルのヘッダーセクションに定義されている属性の数を返します。このメソッドは IWMHeaderInfo3::GetAttributeCountEx および IWMHeaderInfo3::GetAttributeIndices に置き換えられており、今後は使用しないでください。

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

MP3 ファイル内の属性は、特定のストリームに固有のものにすることはできません。MP3 ファイルの場合、ストリーム番号は常にゼロに設定してください。

GetAttributeByIndex メソッドは、ASF ファイルのヘッダーセクションに格納されている記述的な属性を返します。このメソッドは IWMHeaderInfo3::GetAttributeByIndexEx に置き換えられており、使用しないでください。

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

取得したい属性ごとに、GetAttributeByIndex を 2 回呼び出す必要があります。最初の呼び出しでは、pwszName と pValue に NULL を渡します。戻り時には、pcchNameLen が指す値に、終端の null 文字を含む属性名を保持するために必要なワイド文字数が設定され、pcbLength が指す値に、属性値を保持するために必要なバイト数が設定されます。その後、適切なサイズのバッファーを作成して pwszName と pValue を受け取り、2 回目の呼び出しでそれらへのポインターを渡します。

MP3 ファイル内の属性は、ストリーム固有のものにすることはできません。このメソッドを MP3 ファイルで使用する場合は、ストリーム番号にゼロを使用する必要があります。

定義済みのすべての属性の一覧については、Attributes を参照してください。

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

GetAttributeByName メソッドは、ASF ファイルのヘッダーセクションに格納されている記述的な属性を返します。

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

通常、アプリケーションは取得する属性ごとにこのメソッドを 2 回呼び出す必要があります。最初の呼び出しでは、pValue パラメーターを NULL に設定します。pcbLength パラメーターは、属性値を保持するために必要なバッファーサイズを受け取ります。次に、十分なサイズのバイト配列を割り当て、その配列のアドレスを pType パラメーターに渡してメソッドを再度呼び出します。メソッドはバッファーに属性の値を格納します。バッファーは、pType で返された値が示すデータ型に変換してください。

ファイルに指定された属性が含まれていない場合、メソッドは ASF_E_NOTFOUND を返すことがあります。また、メソッドが成功しても、pcbLength に値ゼロを返す場合があります。

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

MP3 ファイル内の属性は、特定のストリームに固有のものにすることはできません。MP3 ファイルの場合、ストリーム番号は常にゼロに設定してください。

定義済みのすべての属性の一覧については、Attributes を参照してください。

例

次のサンプルコードは、"Title" 属性を取得する方法を示します。

HRESULT hr;
IWMHeaderInfo *pInfo;
WORD wStreamNum = 0;
WMT_ATTR_DATATYPE Type;
WORD cbLength;
//
// First, retrieve the length of the string, and allocate memory.
//
hr = pInfo->GetAttributeByName( &wStreamNum, L"Title", 
                                &Type, NULL, &cbLength );
if( FAILED( hr ) )
{
    return( hr );
}
WCHAR *pwszTitle = (WCHAR *) new BYTE[ cbLength ];
if( !pwszTitle )
{
    return( E_OUTOFMEMORY );
}
//
// Now, retrieve the string itself.
//
hr = pInfo->GetAttributeByName( &wStreamNum, L"Title", &Type, 
                                (BYTE *) pwszTitle, &cbLength );
if( FAILED( hr ) )
{
    return( hr );
}

SetAttribute メソッドは、ASF ファイルのヘッダーセクションに格納される記述的な属性を設定します。このメソッドは IWMHeaderInfo3::AddAttribute に置き換えられており、使用しないでください。

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

定義済みの属性の一覧については、Attributes セクションを参照してください。定義済みの属性の場合、Type パラメーターはその属性に定義されたデータ型と一致している必要があります。カスタム属性の場合、WMT_TYPE_GUID を除く任意の型を指定できますが、バッファーサイズ(cbLength で指定)は型と一致している必要があります。詳細については、WMT_ATTR_DATATYPE を参照してください。

IWMHeaderInfo インターフェイスは WMT_TYPE_GUID データ型をサポートしません。このデータ型を使用するには、IWMHeaderInfo3 インターフェイスのメソッドを使用する必要があります。

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

このメソッドは、64 キロバイトを超える値を持つ属性をサポートしません。大きな属性をファイルに含めるには、IWMHeaderInfo3 インターフェイスのメソッドを使用してください。

ライターオブジェクトは、IWMWriter::BeginWriting メソッドが呼び出される前にのみこのメソッドをサポートします。リーダーおよび同期リーダーのオブジェクトはこのメソッドをサポートしません。

ライターオブジェクトの IWMHeaderInfo インターフェイスを介してこのメソッドで DRM 属性を設定する前に、ライターが使用するプロファイルを設定する必要があります。

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

GetMarkerCount メソッドは、現在 ASF ファイルのヘッダーセクションにあるマーカーの数を返します。

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

GetMarker メソッドは、マーカーの名前と時刻を返します。

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

ライターはマーカーをサポートしておらず、このメソッドが呼び出されると E_NOTIMPL を返します。

AddMarker メソッドは、名前と特定の時刻から成るマーカーを ASF ファイルのヘッダーセクションに追加します。

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

ライターはマーカーをサポートしません。ライターから IWMheaderInfo にアクセスする場合、AddMarker の呼び出しは E_NOTIMPL を返します。

RemoveMarker メソッドは、ASF ファイルのヘッダーセクションからマーカーを削除します。

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

このメソッドはライターではサポートされません。

GetScriptCount メソッドは、現在 ASF ファイルのヘッダーセクションにあるスクリプトの数を返します。

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

GetScript メソッドは、スクリプトの型文字列とコマンド文字列、および表示時刻を返します。

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

取得したいスクリプトごとに、GetScript を 2 回呼び出す必要があります。最初の呼び出しでは、pwszType と pwszCommand に NULL を渡します。戻り時には、pcchTypeLen と pcchCommandLen が指す値にワイド文字数が設定されます。これらには終端の null 文字が含まれ、この文字数は pcchTypeLen にスクリプトの型を、pcchCommandLen にコマンドを保持するために必要です。その後、適切なサイズのバッファーを作成して pwszType と pwszCommand を受け取り、2 回目の呼び出しでそれらへのポインターを渡します。

AddScript メソッドは、型文字列とコマンド文字列、および特定の時刻から成るスクリプトを ASF ファイルのヘッダーセクションに追加します。

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

BeginWriting が呼び出される前は、ライターは AddScript のみをサポートします。リーダーは AddScript をサポートせず、常に E_NOTIMPL を返します。

ファイルがストリーミングを目的とする場合は、多数のスクリプトコマンドをファイルヘッダーに追加しないでください。一部のプロトコルはヘッダーのサイズに制限を課します。制限はプロトコルによって異なりますが、スクリプトコマンドの合計が数十キロバイトになる場合は、代わりにスクリプトストリームを作成してください。

DRM を使用してファイルを暗号化する場合、表示時刻が 0 のスクリプトコマンドを含めることはできません。

RemoveScript メソッドを使用すると、オブジェクトが ASF ファイルのヘッダーセクションからスクリプトを削除できます。

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

ライターは、BeginWriting メソッドが呼び出される前にのみこのメソッドをサポートします。このメソッドはリーダーではサポートされません。