IStorage::CopyTo メソッド (objidl.h)

  • [アーティクル]

CopyTo メソッドは、開いているストレージ オブジェクトの内容全体を別のストレージ オブジェクトにコピーします。

構文

HRESULT CopyTo(
  [in] DWORD     ciidExclude,
  [in] const IID *rgiidExclude,
  [in] SNB       snbExclude,
  [in] IStorage  *pstgDest
);

パラメーター

[in] ciidExclude

rgiidExclude によって指される配列内の要素の数。 rgiidExclude が NULL の場合、ciidExclude は無視されます。

[in] rgiidExclude

呼び出し元が認識し、コピーしたくないインターフェイス識別子 (ID) の配列。ストレージ オブジェクトはサポートしていませんが、呼び出し元は後で明示的にコピーする状態です。 配列には、ストリーム オブジェクトのみがコピーされることを示す IStorage と、ストレージ オブジェクトのみがコピーされることを示す IStream を含めることができます。 配列の長さが 0 の場合は、 IStorage オブジェクトによって公開される状態のみがコピーされることを示します。オブジェクト上の他のすべてのインターフェイスは無視されます。 NULL を渡すと、オブジェクト上のすべてのインターフェイスがコピーされることを示します。

[in] snbExclude

コピー先にコピーされないストレージ オブジェクトまたはストリーム オブジェクトのブロックを指定する文字列名ブロック ( SNB を参照)。 これらの要素は、変換先に作成されません。 IID_IStorageが rgiidExclude 配列内にある場合、このパラメーターは無視されます。 このパラメーターには NULL を指定できます。

[in] pstgDest

このストレージ オブジェクトのコピー先となる、開いているストレージ オブジェクトへのポインター。 宛先ストレージ オブジェクトは、ソース ストレージ オブジェクトとは異なる IStorage インターフェイスの実装にすることができます。 したがって、 IStorage::CopyTo では 、宛先ストレージ オブジェクトのパブリックに使用可能なメソッドのみを使用できます。 pstgDest がトランザクション モードで開いている場合は、IStorage::Revert メソッドを呼び出すことで元に戻すことができます。

戻り値

このメソッドは、これらの値のいずれかを返すことができます。

リターン コード 説明
S_OK ストレージ オブジェクトが正常にコピーされました。
E_PENDING 非同期ストレージのみ: コピーするデータの一部またはすべてを現在使用できません。
STG_E_ACCESSDENIED 宛先ストレージ オブジェクトは、ソース ストレージ オブジェクトの子です。
STG_E_INSUFFICIENTMEMORY メモリ不足のため、コピーが完了していません。
STG_E_INVALIDPOINTER ストレージ オブジェクトに指定されたポインターが無効でした。
STG_E_INVALIDPARAMETER パラメーターの 1 つが無効でした。
STG_E_TOOMANYOPENFILES 開いているファイルが多すぎるため、コピーは完了していません。
STG_E_REVERTED ストレージ オブジェクトは、トランザクション ツリーの上にある元に戻す操作によって無効になっています。
STG_E_MEDIUMFULL 記憶域メディアがいっぱいのため、コピーは完了していません。

注釈

このメソッドは、ソース ストレージ オブジェクトに含まれる要素と、コピー先に既に存在する要素をマージします。 コピー先ストレージ オブジェクトのレイアウトは、ソース ストレージ オブジェクトと異なる場合があります。

コピー プロセスは再帰的であり、ソース内に入れ子になった要素に対して IStorage::CopyTo と IStream::CopyTo を呼び出します。

同じ名前の既存のストリームの上にストリームをコピーすると、既存のストリームが最初に削除され、ソース ストリームに置き換えられます。 同じ名前の既存のストレージの上にストレージをコピーしても、既存のストレージは削除されません。 その結果、コピー操作の後、コピー先 の IStorage には、同じ名前の新しい要素に置き換えられなかった場合を除き、古い要素が含まれます。

ストレージ オブジェクトは、IRootStorage、IPropertyStorage、IPropertySetStorage などの IStorage 以外のインターフェイスを公開できます。 rgiidExclude パラメーターを使用すると、コピー操作からこれらの追加インターフェイスの一部またはすべてを除外できます。

既存のサブストレージまたはストリーム オブジェクトの新しい、またはより効率的なコピーを持つ呼び出し元は、これらのオブジェクトの現在のバージョンをコピー操作から除外できます。 snbExclude パラメーターと rgiidExclude パラメーターは、ストレージ オブジェクトの既存のストレージまたはストリームを除外する 2 つの方法を提供します。

呼び出し元へのメモ

IStorage::CopyTo メソッドを使用する最も一般的な方法は、ほとんどの完全保存および保存操作と同様に、ソースからコピー先にすべてをコピーすることです。

次のコード例は、ソース ストレージ オブジェクトからコピー先ストレージ オブジェクトにすべてをコピーする方法を示しています。

pstg->CopyTo(0, Null, Null, pstgDest)
メモ ドキュメント ファイルを圧縮するには、ルート ストレージ オブジェクトで CopyTo を呼び出し、新しいストレージ オブジェクトにコピーします。
 

要件

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

こちらもご覧ください

IStorage - 複合ファイルの実装

IStorage::MoveElementTo

IStorage::Revert