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

ITocEntry

COM
📘 Microsoft Learn (日本語) · English
IIDf22f5e06-585c-4def-8523-6555cfbc0cb3継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ITocEntry インターフェイスは、目次内の個々のエントリを表します。エントリの記述情報を設定および取得するためのメソッドを提供します。

メソッド 8

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

vtbl 3 HRESULT SetTitle(LPWSTR pwszTitle)

SetTitle メソッドは、エントリのタイトルを設定します。

pwszTitleLPWSTRinタイトルを格納した、NULL 終端のワイド文字列へのポインター。

戻り値

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

戻り値 説明
S_OK
 メソッドは成功しました。
vtbl 4 HRESULT GetTitle(WORD* pwTitleSize, LPWSTR pwszTitle)

GetTitle メソッドは、以前の SetTitle の呼び出しで設定されたエントリのタイトルを取得します。

pwTitleSizeWORD*inoutpwszTitle が NULL の場合、これはタイトルを受け取るために必要なバッファーのサイズ(ワイド文字単位)を受け取る出力パラメーターです。pwszTitle が NULL でない場合、これは pwszTitle が指す呼び出し元が割り当てたバッファーのサイズ(ワイド文字単位)を指定する入力パラメーターです。
pwszTitleLPWSTRoutoptionalNULL、または呼び出し元が割り当てたバッファーへのポインター。正常に完了すると、このバッファーにタイトルが格納されます。タイトルは NULL 終端されます。

戻り値

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

戻り値 説明
S_OK
 メソッドは成功しました。
MF_E_BUFFERTOOSMALL
 pwszTitle が NULL でなく、かつタイトルが NULL 終端子を含めて pwTitleSize で指定されたサイズより大きい場合、メソッドはこのエラーコードを返します。この場合、pwTitleSize は出力パラメーターとして機能し、必要なバッファーのサイズを受け取ります。
vtbl 5 HRESULT SetDescriptor(TOC_ENTRY_DESCRIPTOR* pDescriptor)

SetDescriptor メソッドは、記述子(descriptor)をエントリに関連付けます。

pDescriptorTOC_ENTRY_DESCRIPTOR*inout記述子を格納した TOC_ENTRY_DESCRIPTOR 構造体へのポインター。

戻り値

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

戻り値 説明
S_OK
 メソッドは成功しました。
vtbl 6 HRESULT GetDescriptor(TOC_ENTRY_DESCRIPTOR* pDescriptor)

GetDescriptor メソッドは、以前の SetDescriptor の呼び出しで設定されたエントリの記述子(descriptor)を取得します。

pDescriptorTOC_ENTRY_DESCRIPTOR*inout記述子を受け取る TOC_ENTRY_DESCRIPTOR 構造体へのポインター。

戻り値

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

戻り値 説明
S_OK
 メソッドは成功しました。
vtbl 7 HRESULT SetSubEntries(DWORD dwNumSubEntries, WORD* pwSubEntryIndices)

SetSubEntries は、一連のエントリをこのエントリのサブエントリとして識別します。

dwNumSubEntriesDWORDinpwSubEntryIndices が指す配列内のインデックスの数。
pwSubEntryIndicesWORD*inoutWORD の配列へのポインター。配列内の各 WORD は、このエントリのサブエントリと見なされるエントリのインデックスを指定します。

戻り値

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

戻り値 説明
S_OK
 メソッドは成功しました。
vtbl 8 HRESULT GetSubEntries(DWORD* pdwNumSubEntries, WORD* pwSubEntryIndices)

GetSubEntries メソッドは、以前の SetSubEntries の呼び出しで設定されたサブエントリインデックスの配列を取得します。

pdwNumSubEntriesDWORD*inoutpwSubEntryIndices が NULL の場合、これはこのエントリに関連付けられたサブエントリの数を受け取る出力パラメーターです。pwSubEntryIndices が NULL でない場合、これは pwSubEntryIndices が指す呼び出し元が割り当てた配列内の DWORD の数を指定する入力パラメーターです。
pwSubEntryIndicesWORD*inoutNULL、またはサブエントリインデックスを受け取る、呼び出し元が割り当てた DWORD の配列へのポインター。

戻り値

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

戻り値 説明
S_OK
 メソッドは成功しました。
MF_E_BUFFERTOOSMALL
 pwSubEntryIndices が NULL でなく、かつサブエントリの数が pdwNumSubEntries で指定された数より大きい場合、メソッドはこのエラーコードを返します。この場合、pdwNumSubEntries は出力パラメーターとして機能し、利用可能なサブエントリインデックスの数を受け取ります。
vtbl 9 HRESULT SetDescriptionData(DWORD dwDescriptionDataSize, BYTE* pbtDescriptionData, GUID* pguidType)

SetDescriptionData メソッドは、呼び出し元が指定したデータブロックをエントリに関連付けます。

dwDescriptionDataSizeDWORDinデータブロックのサイズ(バイト単位)。
pbtDescriptionDataBYTE*inoutデータブロックの先頭バイトへのポインター。
pguidTypeGUID*inoutブロック内のデータの種類を識別する GUID へのポインター。このパラメーターは NULL にすることができます。「解説」を参照してください。

戻り値

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

戻り値 説明
S_OK
 メソッドは成功しました。

解説(Remarks)

このメソッドを使用すると、任意の情報をエントリに関連付けることができます。記述データブロックに格納する情報の性質は、完全にあなた次第です。TOC Parser は記述データブロックを検査したり解釈したりしません。

特定のエントリには、同時に 1 つの記述データブロックしか関連付けることができません。ただし、異なる種類の記述データブロックを設計し、各種類のブロックをグローバル一意識別子(GUID)で識別したい場合があります。そのようにすれば、ある種類の記述データを一部のエントリに関連付け、別の種類の記述データを他のエントリに関連付けることができます。異なる種類の記述データブロックを区別する必要がない場合は、pguidType を NULL に設定できます。

vtbl 10 HRESULT GetDescriptionData(DWORD* pdwDescriptionDataSize, BYTE* pbtDescriptionData, GUID* pGuidType)

GetDescriptionData メソッドは、以前の SetDescriptionData の呼び出しでエントリに関連付けられた記述データブロックを取得します。

pdwDescriptionDataSizeDWORD*inoutpbtDescriptionData が NULL の場合、これは記述データブロックのサイズ(バイト単位)を受け取る出力パラメーターです。pbtDescriptionData が NULL でない場合、これは pbtDescriptionData が指す呼び出し元が割り当てたバッファーのサイズ(バイト単位)を指定する入力パラメーターです。
pbtDescriptionDataBYTE*inoutNULL、または呼び出し元が割り当てたバッファーへのポインター。正常に完了すると、このバッファーに記述データブロックが格納されます。
pGuidTypeGUID*inout記述データブロック内のデータの種類を識別するグローバル一意識別子(GUID)を受け取る変数へのポインター。「解説」を参照してください。

戻り値

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

戻り値 説明
S_OK
 メソッドは成功しました。
MF_E_BUFFERTOOSMALL
 pbtDescriptionData が NULL でなく、かつコンテキストブロックが pdwDescriptionDataSize で指定されたサイズより大きい場合、メソッドはこのエラーコードを返します。この場合、pdwDescriptionDataSize は出力パラメーターとして機能し、必要なバッファーのサイズ(バイト単位)を受け取ります。

解説(Remarks)

特定のエントリには、同時に 1 つの記述データブロックしか関連付けることができません。ただし、異なる種類の記述データブロックを設計し、各種類のブロックをグローバル一意識別子(GUID)で識別したい場合があります。そのようにすれば、SetDescriptionData を呼び出す際に、データブロックを特定の種類としてマークできます。GetDescriptionData を呼び出す際には、pGuidType で返される値を調べることで、取得したデータブロックの種類を判別できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ITocEntry "{F22F5E06-585C-4DEF-8523-6555CFBC0CB3}"
#usecom global ITocEntry IID_ITocEntry "{}"
#comfunc global ITocEntry_SetTitle            3 wstr
#comfunc global ITocEntry_GetTitle            4 var,var
#comfunc global ITocEntry_SetDescriptor       5 var
#comfunc global ITocEntry_GetDescriptor       6 var
#comfunc global ITocEntry_SetSubEntries       7 int,var
#comfunc global ITocEntry_GetSubEntries       8 var,var
#comfunc global ITocEntry_SetDescriptionData  9 int,var,var
#comfunc global ITocEntry_GetDescriptionData  10 var,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。