IOleCache

COM

IID0000011e-0000-0000-c000-000000000046継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

オブジェクトの内部にキャッシュされるプレゼンテーションデータを制御する手段を提供します。キャッシュされたプレゼンテーションデータは、サーバーアプリケーションが実行されていない場合や利用できない場合でも、オブジェクトのコンテナーから利用できます。

メソッド 5

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

vtbl 3 HRESULT Cache(FORMATETC* pformatetc, DWORD advf, DWORD* pdwConnection)

埋め込みオブジェクトの内部にキャッシュするフォーマットおよびその他のデータを指定します。

pformatetc	FORMATETC*	in	キャッシュするフォーマットおよびその他のデータを指定する FORMATETC 構造体へのポインター。ビューキャッシュを指定するには、pformatetc にクリップボードフォーマットとして 0 を渡します。
advf	DWORD	in	キャッシュを制御するフラグのグループ。指定可能な値は ADVF 列挙体に由来します。このコンテキストでキャッシュに対して使用する場合、これらの値には特定の意味があり、その詳細は「解説」で説明します。より詳しい説明については ADVF 列挙体を参照してください。
pdwConnection	DWORD*	out	この接続の識別子を受け取る変数へのポインター。この識別子は、後でキャッシュを無効にするために(IOleCache::Uncache に渡すことで)使用できます。この値が 0 の場合、接続は確立されませんでした。OLE が提供する実装では、接続識別子として 0 以外の数値を使用します。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

戻り値	説明
E_INVALIDARG	指定された pformatetc または advf 引数が無効です。
E_UNEXPECTED	予期しないエラーが発生しました。
E_OUTOFMEMORY	この操作に利用できるメモリが不足しています。
CACHE_S_FORMATETC_NOTSUPPORTED	キャッシュは作成されましたが、オブジェクトアプリケーションが指定されたフォーマットをサポートしていません。フォーマットがサポートされていない場合でもキャッシュの作成は成功し、呼び出し元がキャッシュを埋めることができます。ただし、呼び出し元がキャッシュを保持する必要がない場合は、IOleCache::Uncache を呼び出してください。
CACHE_S_SAMECACHE	IOleCache::Uncache に渡された FORMATETC に対するキャッシュが既に存在します。この場合、新しいアドバイズフラグがキャッシュに割り当てられ、以前に割り当てられた接続識別子が返されます。
DV_E_LINDEX	pformatetc->lindex の値が無効です。現在サポートされているのは -1 のみです。
DV_E_TYMED	pformatetc->tymed に対して無効な値です。
DV_E_DVASPECT	pformatetc->dwAspect に対して無効な値です。
DV_E_CLIPFORMAT	pformatetc->cfFormat に対して無効な値です。
CO_E_NOTINITIALIZED	キャッシュのストレージが初期化されていません。
DV_E_DVTARGETDEVICE	pformatetc-->ptd に対して無効な値です。
OLE_E_STATIC	キャッシュは静的オブジェクト用であり、既にキャッシュノードを持っています。

解説(Remarks)

IOleCache::Cache は、データキャッシュまたはビュー(プレゼンテーション)キャッシュのいずれかを指定できます。データキャッシュを指定するには、pformatetc に有効なデータフォーマットを渡す必要があります。ビューキャッシュの場合、キャッシュするフォーマットはキャッシュオブジェクト自身が決定するため、呼び出し元は次のように pformatetc にデータフォーマットとして 0 を渡します。

pFormatetc->cfFormat == 0

カスタムオブジェクトハンドラーは、特定のフォーマットでデータを保存しないことを選択できます。その代わりに、要求されたときにオンデマンドで合成することができます。

advf の値は ADVF 列挙体のメンバーを指定します。このコンテキストでこれらの値のいずれか(または複数の値を OR で組み合わせたもの)を使用する場合、それぞれ次の意味を持ちます。

ADVF の値	説明
ADVF_NODATA	実行中のオブジェクトに加えられた変更によってキャッシュを更新しません。代わりに、コンテナーが IOleCache::SetData、IDataObject::SetData、または IOleCache2::UpdateCache を明示的に呼び出すことでキャッシュを更新します。このフラグは通常、オブジェクトのアイコン表示をキャッシュする際に使用されます。
ADVF_ONLYONCE	キャッシュを一度だけ更新します。更新が完了すると、オブジェクトとキャッシュ間のアドバイズ接続は切断されます。アドバイズ接続のソースオブジェクトが Release メソッドを呼び出します。
ADVF_PRIMEFIRST	キャッシュを更新する前に、データまたはビューの変更を待機しません。ADVF_ONLYONCE と OR で組み合わせると、このパラメーターは非同期の IDataObject::GetData 呼び出しを提供します。
ADVFCACHE_NOHANDLER	ADVFCACHE_FORCEBUILTIN と同義です。
ADVFCACHE_FORCEBUILTIN	オブジェクトを描画する DLL オブジェクトアプリケーションやオブジェクトハンドラーが、キャッシュ内に確実にプレゼンテーションが存在するようにプレゼンテーションデータをキャッシュするために使用します。これにより、オブジェクトやハンドラーのコードが利用できない場合でもデータを取得できるようになります。
ADVFCACHE_ONSAVE	キャッシュを含むオブジェクトが保存されたときにのみ、キャッシュされた表現を更新します。また、OLE オブジェクトが実行状態から読み込み状態に戻ったときにもキャッシュが更新されます(その後の保存操作では再びオブジェクトを実行する必要があるためです)。

vtbl 4 HRESULT Uncache(DWORD dwConnection)

以前に IOleCache::Cache を使用して作成されたキャッシュ接続を削除します。

dwConnection

DWORD

削除するキャッシュ接続。この 0 以外の値は、キャッシュが最初に確立されたときに IOleCache::Cache によって返された値です。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

戻り値	説明
OLE_E_NOCONNECTION	dwConnection に対応するキャッシュ接続が存在しません。

解説(Remarks)

IOleCache::Uncache メソッドは、以前の IOleCache::Cache の呼び出しで作成されたキャッシュ接続を削除します。以前の IOleCache::Cache の呼び出しで返された dwConnection パラメーターを使用します。

vtbl 5 HRESULT EnumCache(IEnumSTATDATA** ppenumSTATDATA)

現在のキャッシュ接続を列挙するために使用できる列挙子を作成します。

ppenumSTATDATA

IEnumSTATDATA**

out

新しい列挙子オブジェクトへのインターフェイスポインターを受け取る IEnumSTATDATA ポインター変数へのポインター。このパラメーターが NULL の場合、現時点でキャッシュ接続は存在しません。

戻り値

このメソッドは、列挙子オブジェクトが正常にインスタンス化された場合、またはキャッシュ接続が存在しない場合に S_OK を返します。

注意どちらの結果が発生したかを判断するには ppenumSTATDATA パラメーターを確認してください。ppenumSTATDATA パラメーターが NULL の場合、現時点でキャッシュ接続は存在しません。

解説(Remarks)

このメソッドによって返される列挙子オブジェクトは IEnumSTATDATA インターフェイスを実装します。IEnumSTATDATA は、現在のキャッシュ接続に関する情報を含む STATDATA 構造体の配列に格納されたデータを列挙します。

vtbl 6 HRESULT InitCache(IDataObject* pDataObject)

指定されたデータオブジェクトが提供するデータを使用して、必要に応じてキャッシュを埋めます。

pDataObject

IDataObject*

キャッシュの初期化元となるデータオブジェクト上の IDataObject インターフェイスへのポインター。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

戻り値	説明
E_INVALIDARG	IDataObject インターフェイスへのポインターが無効です。
E_OUTOFMEMORY	この操作に利用できるメモリが不足しています。
OLE_E_NOTRUNNING	キャッシュが実行されていません。
CACHE_E_NOCACHE_UPDATED	いずれのキャッシュも更新されませんでした。
CACHE_S_SOMECACHES_NOTUPDATED	既存のキャッシュの一部のみが更新されました。

解説(Remarks)

InitCache は通常、ドラッグアンドドロップ操作やクリップボードの貼り付け操作からオブジェクトを作成する際に使用されます。クリップボード上またはドラッグアンドドロップ操作で提供されたデータオブジェクトが提供するすべてのデータフォーマットのプレゼンテーションデータを使用して、必要に応じてキャッシュを埋めます。OleCreateFromData や OleCreateLinkFromData などのヘルパー関数は、必要に応じてこのメソッドを呼び出します。コンテナーが複合ドキュメントオブジェクトの作成にこれらのヘルパー関数を使用しない場合は、IOleCache::Cache を使用してキャッシュエントリを設定し、それを InitCache で埋めることができます。

vtbl 7 HRESULT SetData(FORMATETC* pformatetc, STGMEDIUM* pmedium, BOOL fRelease)

指定されたフォーマットで、指定された媒体上のデータを使用してキャッシュを初期化します。

pformatetc	FORMATETC*	in	キャッシュに配置するプレゼンテーションデータのフォーマットを指定する FORMATETC 構造体へのポインター。
pmedium	STGMEDIUM*	in	プレゼンテーションデータを含むストレージ媒体を指定する STGMEDIUM 構造体へのポインター。
fRelease	BOOL	in	メソッド完了後のストレージ媒体の所有権を示します。fRelease が TRUE の場合、キャッシュが所有権を取得し、使用が終わったときに媒体を解放します。fRelease が FALSE の場合、呼び出し元が所有権を保持し、媒体を解放する責任を負います。この場合、キャッシュは呼び出しの間のみストレージ媒体を使用できます。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値は次のとおりです。

戻り値	説明
DV_E_LINDEX	pformatetc->lindex に対して無効な値です。現在サポートされているのは -1 のみです。
DV_E_FORMATETC	FORMATETC 構造体が無効です。
DV_E_TYMED	pformatetc->tymed に対して無効な値です。
DV_E_DVASPECT	pformatetc->dwAspect に対して無効な値です。
OLE_E_BLANK	未初期化のオブジェクトがあります。
DV_E_TARGETDEVICE	オブジェクトが静的であるにもかかわらず、pformatetc->ptd が NULL ではありません。
STG_E_MEDIUMFULL	ストレージ媒体が満杯です。

解説(Remarks)

IOleCache::SetData は通常、クリップボードまたはドラッグアンドドロップ操作からオブジェクトが作成され、Embed Source データを使用してオブジェクトを作成する際に呼び出されます。

IOleCache::SetData と IOleCache::InitCache は非常に似ています。主な違いは 2 つあります。1 つ目の違いは、IOleCache::InitCache がデータオブジェクトによって提供されるプレゼンテーションフォーマットでキャッシュを初期化するのに対し、IOleCache::SetData は単一のフォーマットで初期化する点です。2 つ目は、IOleCache::SetData メソッドが ADVF_NODATA フラグを無視するのに対し、IOleCache::InitCache はこのフラグに従う点です。

コンテナーは、このメソッドを使用して、オブジェクトのアイコン表示など、オブジェクトの単一の表示を維持できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IOleCache "{0000011E-0000-0000-C000-000000000046}"
#usecom global IOleCache IID_IOleCache "{}"
#comfunc global IOleCache_Cache      3 var,int,var
#comfunc global IOleCache_Uncache    4 int
#comfunc global IOleCache_EnumCache  5 sptr
#comfunc global IOleCache_InitCache  6 sptr
#comfunc global IOleCache_SetData    7 var,var,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IOleCache "{0000011E-0000-0000-C000-000000000046}"
#usecom global IOleCache IID_IOleCache "{}"
#comfunc global IOleCache_Cache      3 sptr,int,sptr
#comfunc global IOleCache_Uncache    4 int
#comfunc global IOleCache_EnumCache  5 sptr
#comfunc global IOleCache_InitCache  6 sptr
#comfunc global IOleCache_SetData    7 sptr,sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。