IStorage::MoveElementTo
Copies or
moves a substorage or stream from this storage object to another storage
object.
HRESULT MoveElementTo(
|
const WCHAR * pwcsName, |
//Name
of the element to be moved |
|
IStorage * pstgDest, |
//Points
to destination storage object |
|
LPWSTR pwcsNewName, |
//Points
to new name of element in destination |
|
DWORD grfFlags |
//Specifies
a copy or a move |
|
); |
|
Parameters
pwcsName
[in] Points
to a wide character string that contains the name of the element in this
storage object to be moved or copied.
pstgDest
[in] IStorage
pointer to the destination storage object.
pwcsNewName
[in] Points
to a wide character string that contains the new name for the element in its
new storage object.
grfFlags
[in]
Specifies whether the operation should be a move (STGMOVE_MOVE) or a copy
(STGMOVE_COPY). See the STGMOVE enumeration.
Return Values
S_OK
The storage
object was successfully copied or moved.
E_PENDING
Asynchronous
Storage only: Part or all of the element s
data is currently unavailable. For more information see IFillLockBytes and Asynchronous
Storage.
STG_E_ACCESSDENIED
The
destination storage object is a child of the source storage object.
STG_E_FILENOTFOUND
The element
with the specified name does not exist.
STG_E_FILEALREADYEXISTS
The specified
file already exists.
STG_E_INSUFFICIENTMEMORY
The copy or
move was not completed due to a lack of memory.
STG_E_INVALIDFLAG
The value for
the grfFlags parameter is not valid.
STG_E_INVALIDNAME
Invalid value
for pwcsName.
STG_E_INVALIDPOINTER
The pointer
specified for the storage object was invalid.
STG_E_INVALIDPARAMETER
One of the
parameters was invalid.
STG_E_REVERTED
The storage
object has been invalidated by a revert operation above it in the transaction
tree.
STG_E_TOOMANYOPENFILES
The copy or
move was not completed because there are too many open files.
Remarks
The IStorage::MoveElementTo
method is typically the same as invoking the IStorage::CopyTo method on the indicated
element and then removing the source element. In this case, the MoveElementTo
method uses only the publicly available functions of the destination storage
object to carry out the move.
If the source
and destination storage objects have special knowledge about each other s implementation (they could, for example, be
different instances of the same implementation), this method can be
implemented more efficiently.
Before
calling this method, the element to be moved must be closed, and the
destination storage must be open.
See Also