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 メソッドを呼び出すことで元に戻すことができます。

戻り値

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

注釈

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

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

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

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

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

呼び出し元へのメモ

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

pstg->CopyTo(0, Null, Null, pstgDest)

要件

こちらもご覧ください

IStorage - 複合ファイルの実装

IStorage::MoveElementTo

IStorage::Revert