Метод IStorage::CopyTo (objidl.h)

Статья
08/25/2023

Метод CopyTo копирует все содержимое открытого объекта хранилища в другой объект хранилища.

Синтаксис

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

Параметры

[in] ciidExclude

Количество элементов в массиве, на который указывает rgiidExclude. Если параметр rgiidExclude имеет значение NULL, ciidExclude игнорируется.

[in] rgiidExclude

Массив идентификаторов интерфейсов (IID), о которых вызывающий объект знает и не хочет копировать, или который объект хранилища не поддерживает, но состояние которого вызывающий объект позже будет явно копировать. Массив может включать IStorage, указывающий, что копируются только потоковые объекты, и IStream, указывающий, что копируются только объекты хранилища. Нулевая длина массива указывает, что копируется только состояние, предоставляемое объектом 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	Один из параметров был недопустим.
STG_E_TOOMANYOPENFILES	Копирование не было завершено, так как открыто слишком много файлов.
STG_E_REVERTED	Объект хранилища был признан недействительным в результате операции отменить изменения над ним в дереве транзакций.
STG_E_MEDIUMFULL	Копирование не было завершено, так как носитель хранилища заполнен.

Этот метод объединяет элементы, содержащиеся в объекте исходного хранилища, с элементами, которые уже присутствуют в назначении. Макет целевого объекта хранилища может отличаться от исходного объекта хранилища.

Процесс копирования является рекурсивным, вызывая IStorage::CopyTo и IStream::CopyTo для элементов, вложенных в источник.

При копировании потока поверх существующего потока с тем же именем существующий поток сначала удаляется, а затем заменяется исходным потоком. При копировании хранилища поверх существующего хранилища с тем же именем существующее хранилище не удаляется. В результате после операции копирования конечный IStorage содержит старые элементы, если только они не были заменены новыми элементами с теми же именами.

Объект хранилища может предоставлять интерфейсы, отличные от IStorage, включая IRootStorage, IPropertyStorage или IPropertySetStorage. Параметр rgiidExclude позволяет исключить любой или все из этих дополнительных интерфейсов из операции копирования.

Вызывающий объект с более новой или более эффективной копией существующего подчиненного или потокового объекта может захотеть исключить текущие версии этих объектов из операции копирования. Параметры snbExclude и rgiidExclude предоставляют два способа исключения объектов хранилища, существующих хранилищ или потоков.

Примечание к вызывающим абонентам

Наиболее распространенным способом использования метода IStorage::CopyTo является копирование всех данных из источника в место назначения, как и в большинстве операций полного сохранения и сохранения как.

В следующем примере кода показано, как скопировать все данные из исходного объекта хранилища в целевой.

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

Примечание Чтобы сжать файл документа, вызовите CopyTo в корневом объекте хранилища и скопируйте его в новый объект хранилища.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	objidl.h
Библиотека	Uuid.lib
DLL	Ole32.dll

См. также раздел

IStorage — реализация составного файла

IStorage::MoveElementTo

IStorage::Revert