ホーム › System.Com › IPersistStreamInit

IPersistStreamInit

COM

📘 Microsoft Learn (日本語) · English

IID7fd52380-4e07-101b-ae2d-08002b2ec713継承元IPersist自前メソッド開始 vtbl4

公式ドキュメント

初期化メソッドを追加した IPersistStream の代替インターフェイスです。

メソッド 5

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

vtbl 4 HRESULT IsDirty()

オブジェクトが、最後にストリームへ保存されて以降に変更されたかどうかを判定します。(IPersistStreamInit.IsDirty)

戻り値

このメソッドは、オブジェクトが変更されている場合に S_OK を返します。それ以外の場合は S_FALSE を返します。

解説(Remarks)

オブジェクトを閉じる前に保存すべきかどうかを判定するために、このメソッドを使用します。オブジェクトのダーティフラグは、IPersistStreamInit::Save メソッド内で条件付きでクリアされます。

呼び出し側への注意

エラーの戻りコードは、オブジェクトが変更されたことを示すものとして扱ってください。このメソッドが明示的に S_FALSE を返さない限り、オブジェクトは保存する必要があるものと想定してください。

OLE が提供するモニカーインターフェイスにおける IPersistStreamInit::IsDirty メソッドの OLE 提供実装は、内部状態が変化しないため常に S_FALSE を返す点に注意してください。

vtbl 5 HRESULT Load(IStream* pStm)

以前に保存されたストリームからオブジェクトを初期化します。(IPersistStreamInit.Load)

pStm

IStream*

オブジェクトの読み込み元となるストリームを指す IStream ポインターです。

戻り値

このメソッドは、次の値を返すことがあります。

戻りコード	説明
S_OK	メソッドは正常に完了しました。
E_OUTOFMEMORY	メモリ不足のため、オブジェクトを読み込めませんでした。
E_FAIL	メモリ不足以外の何らかの理由により、オブジェクトを読み込めませんでした。

解説(Remarks)

オブジェクトが既に IPersistStreamInit::InitNew によって初期化されている場合、このメソッドは E_UNEXPECTED を返す必要があります。

このメソッドは、関連付けられたストリームからオブジェクトを読み込みます。シークポインターは、直近の IPersistStreamInit::Save メソッドの時点と同じ状態に設定されます。このメソッドはストリームに対してシークおよび読み取りを行えますが、書き込みはできません。

vtbl 6 HRESULT Save(IStream* pStm, BOOL fClearDirty)

指定したストリームにオブジェクトを保存します。(IPersistStreamInit.Save)

pStm	IStream*	in	オブジェクトの保存先となるストリームを指す IStream ポインターです。
fClearDirty	BOOL	in	保存の完了後にダーティフラグをクリアするかどうかを示します。TRUE の場合、フラグをクリアします。FALSE の場合、フラグは変更されずそのまま保持されます。

戻り値

このメソッドは、次の値を返すことがあります。

戻りコード	説明
S_OK	メソッドは正常に完了しました。
STG_E_CANTSAVE	オブジェクトは自身をストリームへ保存できませんでした。このエラーは、たとえばオブジェクトがストリームへシリアル化できない別のオブジェクトを含んでいる場合や、ISequentialStream::Write の呼び出しが STG_E_CANTSAVE を返した場合などに発生する可能性があります。
STG_E_MEDIUMFULL	ストレージデバイスに空き領域がないため、オブジェクトを保存できませんでした。

解説(Remarks)

IPersistStreamInit::Save は、指定したストリームにオブジェクトを保存し、オブジェクトがダーティフラグをリセットすべきかどうかを示します。

シークポインターは、オブジェクトがデータの書き込みを開始すべきストリーム内の位置に設定されます。オブジェクトは、ISequentialStream::Write メソッドを呼び出してデータを書き込みます。

終了時には、シークポインターはオブジェクトデータの直後に位置している必要があります。エラーが返された場合、シークポインターの位置は未定義です。

実装者への注意

IPersistStreamInit::Save メソッドは CLSID をストリームに書き込みません。CLSID の書き込みは呼び出し側の責任です。

IPersistStreamInit::Save メソッドは、ストリームに対して読み取り、書き込み、およびシークを行えますが、開始時点のシークポインターより前の位置へシークしてはなりません。

vtbl 7 HRESULT GetSizeMax(ULONGLONG* pCbSize)

オブジェクトの保存に必要なストリームのサイズを取得します。(IPersistStreamInit.GetSizeMax)

pCbSize

ULONGLONG*

out

このオブジェクトの保存に必要なストリームのサイズ(バイト単位)です。

戻り値

このメソッドは、サイズが正常に取得されたことを示すために S_OK を返します。

解説(Remarks)

このメソッドは、オブジェクトの保存に必要なサイズを返します。IPersistStreamInit::Save メソッドを呼び出す前に、このメソッドを呼び出してサイズを確認し、必要なバッファーを設定できます。

実装者への注意

呼び出し側が拡張不可能なストリームを指定して IPersistStreamInit::Save メソッドを呼び出す可能性があるため、GetSizeMax の実装では必要なサイズを余裕を持って見積もった値を返す必要があります。

vtbl 8 HRESULT InitNew()

オブジェクトを既定の状態に初期化します。このメソッドは、IPersistStreamInit::Load の代わりに呼び出されます。

戻り値

このメソッドは、標準の戻り値である E_OUTOFMEMORY および E_UNEXPECTED に加えて、次の値を返すことがあります。

戻りコード	説明
S_OK	メソッドは正常に完了しました。
E_NOTIMPL	オブジェクトは既定の初期化を必要としません。このエラーコードが許容されるのは、オブジェクトが単に直交性のため、あるいは将来このメソッドが必要になることを見越して IPersistStreamInit を実装する場合があるためです。

解説(Remarks)

オブジェクトが既に IPersistStreamInit::Load によって初期化されている場合、このメソッドは E_UNEXPECTED を返す必要があります。

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