IStorage::CopyTo method (objidl.h)

The CopyTo method copies the entire contents of an open storage object to another storage object.

Syntax

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

Parameters

[in] ciidExclude

The number of elements in the array pointed to by rgiidExclude. If rgiidExclude is NULL, then ciidExclude is ignored.

[in] rgiidExclude

An array of interface identifiers (IIDs) that either the caller knows about and does not want copied or that the storage object does not support, but whose state the caller will later explicitly copy. The array can include IStorage, indicating that only stream objects are to be copied, and IStream, indicating that only storage objects are to be copied. An array length of zero indicates that only the state exposed by the IStorage object is to be copied; all other interfaces on the object are to be ignored. Passing NULL indicates that all interfaces on the object are to be copied.

[in] snbExclude

A string name block (refer to SNB) that specifies a block of storage or stream objects that are not to be copied to the destination. These elements are not created at the destination. If IID_IStorage is in the rgiidExclude array, this parameter is ignored. This parameter may be NULL.

[in] pstgDest

A pointer to the open storage object into which this storage object is to be copied. The destination storage object can be a different implementation of the IStorage interface from the source storage object. Thus, IStorage::CopyTo can use only publicly available methods of the destination storage object. If pstgDest is open in transacted mode, it can be reverted by calling its IStorage::Revert method.

Return value

This method can return one of these values.

Return code Description
S_OK The storage object was successfully copied.
E_PENDING Asynchronous Storage only: Part or all of the data to be copied is currently unavailable.
STG_E_ACCESSDENIED The destination storage object is a child of the source storage object.
STG_E_INSUFFICIENTMEMORY The copy was not completed due to a lack of memory.
STG_E_INVALIDPOINTER The pointer specified for the storage object was not valid.
STG_E_INVALIDPARAMETER One of the parameters was not valid.
STG_E_TOOMANYOPENFILES The copy was not completed because there are too many open files.
STG_E_REVERTED The storage object has been invalidated by a revert operation above it in the transaction tree.
STG_E_MEDIUMFULL The copy was not completed because the storage medium is full.

Remarks

This method merges elements contained in the source storage object with those already present in the destination. The layout of the destination storage object may differ from the source storage object.

The copy process is recursive, invoking IStorage::CopyTo and IStream::CopyTo on the elements nested inside the source.

When copying a stream on top of an existing stream with the same name, the existing stream is first removed and then replaced with the source stream. When copying a storage on top of an existing storage with the same name, the existing storage is not removed. As a result, after the copy operation, the destination IStorage contains older elements, unless they were replaced by newer ones with the same names.

A storage object may expose interfaces other than IStorage, including IRootStorage, IPropertyStorage, or IPropertySetStorage. The rgiidExclude parameter permits the exclusion of any or all of these additional interfaces from the copy operation.

A caller with a newer or more efficient copy of an existing substorage or stream object may want to exclude the current versions of these objects from the copy operation. The snbExclude and rgiidExclude parameters provide two ways of excluding a storage objects existing storages or streams.

Note to Callers

The most common way to use the IStorage::CopyTo method is to copy everything from the source to the destination, as in most full-save and save-as operations.

The following example code shows how to copy everything from the source storage object to the destination storage object.

pstg->CopyTo(0, Null, Null, pstgDest)
Note  To compact a document file, call CopyTo on the root storage object and copy to a new storage object.
 

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps | UWP apps]
Minimum supported server Windows 2000 Server [desktop apps | UWP apps]
Target Platform Windows
Header objidl.h
Library Uuid.lib
DLL Ole32.dll

See also

IStorage - Compound File Implementation

IStorage::MoveElementTo

IStorage::Revert