IPersistStorage::InitNew メソッド (objidl.h)

  • [アーティクル]

新しいストレージ オブジェクトを初期化します。

構文

HRESULT InitNew(
  [in] IStorage *pStg
);

パラメーター

[in] pStg

初期化する新しいストレージ オブジェクトへの IStorage ポインター。 コンテナーは、そのストレージ オブジェクトに入れ子になったストレージ オブジェクトを作成します ( 「IStorage::CreateStorage」を参照)。 次に、コンテナーは WriteClassStg 関数を呼び出して、オブジェクト クラス識別子 (CLSID) を使用して新しいストレージ オブジェクトを初期化します。

戻り値

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

リターン コード 説明
S_OK
 メソッドは正常に完了しました。
CO_E_ALREADYINITIALIZED
 オブジェクトは、 IPersistStorage::Load メソッドまたは IPersistStorage::InitNew メソッドの以前の呼び出しによって既に初期化されています。
E_OUTOFMEMORY
 メモリ不足のため、ストレージ オブジェクトが初期化されませんでした。
E_FAIL
 ストレージ オブジェクトは、メモリ不足以外の何らかの理由で初期化されませんでした。

注釈

コンテナー アプリケーションは、たとえば InsertObject コマンドを使用して新しいオブジェクトを初期化する必要がある場合に、このメソッドを呼び出すことができます。

IPersistStorage インターフェイスをサポートするオブジェクトは、実行中に常に有効なストレージ オブジェクトにアクセスできる必要があります。 これには、オブジェクトが作成された直後、オブジェクトが永続的になるまでの時間が含まれます。 オブジェクトのコンテナーは、IPersistStorage::InitNew の呼び出しを通じて、この期間中にストレージへの有効な IStorage ポインターをオブジェクトに提供する必要があります。 コンテナーの状態によっては、この目的のために一時ファイルを作成する必要がある場合があります。

オブジェクトが IStorage インスタンスを保持する場合は、 AddRef を呼び出して参照カウントをインクリメントする必要があります。

IPersistStorage::InitNew の呼び出しの後、オブジェクトは読み込まれた状態または実行中の状態になります。 たとえば、オブジェクト クラスにインプロセス サーバーがある場合、オブジェクトは実行中の状態になります。 ただし、オブジェクトで既定のハンドラーが使用されている場合、コンテナーの InitNew の呼び出しでは、オブジェクトを実行しないハンドラーの実装のみが呼び出されます。 後でコンテナーが オブジェクトを実行する場合、ハンドラーは オブジェクトの InitNew メソッドを呼び出します。

呼び出し元へのメモ

IPersistStorage::InitNew を直接呼び出すのではなく、通常、次の処理を行う OleCreate ヘルパー関数を呼び出します。
  1. CoCreateInstance 関数を呼び出して、オブジェクト クラスのインスタンスを作成します。
  2. IPersistStorage インターフェイスの新しいインスタンスに対してクエリを実行します。
  3. InitNew メソッドを呼び出して、 オブジェクトを初期化します。
コンテナー アプリケーションは、オブジェクトに対する後の操作で使用するために、 オブジェクトへの IPersistStorage ポインターをキャッシュする必要があります。

実装者へのメモ

IPersistStorage::InitNew の実装では、次の手順を実行して、オブジェクトを既定の状態に初期化する必要があります。
  1. オブジェクトが自身をこのストレージに保存するために必要なストリームまたはストレージへのポインターを事前に開いてキャッシュします。
  2. AddRef を呼び出し、渡されたストレージ ポインターをキャッシュします。
  3. WriteFmtUserTypeStg 関数を呼び出して、オブジェクトのネイティブ クリップボード形式とユーザー型文字列をストレージ オブジェクトに書き込みます。
  4. オブジェクトのダーティ フラグを設定します。
最初の 2 つの手順は、オブジェクトがメモリ不足の状況で自身を保存できるようにするために特に重要です。 ストリーム インターフェイスとストレージ インターフェイスへのポインターを事前に開いて保持すると、メモリ不足のため、このストレージへの保存操作が失敗しないことが保証されます。

このメソッドの実装では、IPersistStorage::InitNew メソッドまたは IPersistStorage::Load メソッドの呼び出しが既に初期化された後に受け取った場合は、CO_E_ALREADYINITIALIZED エラー コードを返す必要があります。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー objidl.h

こちらもご覧ください

IPersistStorage