Important: |
---|
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This method copies the entire contents of an open storage object to another storage object.
Syntax
HRESULT CopyTo( DWORD ciidExclude, IID const* rgiidExclude, SNB snbExclude, IStorage* pstgDest ); |
Parameters
- ciidExclude
-
[in] Number of elements in the array pointed to by the rgiidExcludeparameter. If rgiidExcludeis NULL, then ciidExcludeis ignored.
- rgiidExclude
-
[in] Array of interface identifiers that either the caller knows about and does not want to be copied or that the storage object does not support but whose state the caller will later explicitly copy.
The array can include the IStorageinterface, indicating that only stream objects are to be copied, and the IStreaminterface, indicates that only storage objects are to be copied.
An array length of zero indicating that only the state exposed by the IStorageobject 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.
- snbExclude
-
[in] String name block (see 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 rgiidExcludearray, this parameter is ignored.
This parameter may be NULL.
- pstgDest
-
[in] 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 IStorageinterface from the source storage object. Therefore, IStorage::CopyTocan only use publicly available methods of the destination storage object.
If pstgDestis open in transacted mode, it can be reverted by calling its IStorage::Revertmethod.
Return Value
The following table shows the return values for this method.
Value | 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. For more information see the IFillLockBytesinterface and Asynchronous Storage. |
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 invalid. |
STG_E_INVALIDPARAMETER |
One of the parameters was invalid. |
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::CopyToand the IStream::CopyTomethod 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 IStoragecontains 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 rgiidExcludeparameter provides a way to exclude 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 snbExcludeand rgiidExcludeparameters provide two different ways of excluding storage objects existing storages or streams.
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Note to Callers
The most common way to use this method is to copy everything possible from the source to the destination, as in most Full Save and SaveAs operations.
The following code example illustrates this call.
Copy Code | |
---|---|
pstg->CopyTo(0, NULL, NULL, pstgDest) |
Requirements
Header | objidl.h, objidl.idl |
Library | ole32.lib, uuid.lib |
Windows Embedded CE | Windows CE 2.0 and later |
Windows Mobile | Windows Mobile Version 5.0 and later |