Método IStorage::CopyTo (objidl.h)

O método CopyTo copia todo o conteúdo de um objeto de armazenamento aberto para outro objeto de armazenamento.

Sintaxe

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

Parâmetros

[in] ciidExclude

O número de elementos na matriz apontada por rgiidExclude. Se rgiidExclude for NULL, ciidExclude será ignorado.

[in] rgiidExclude

Uma matriz de IIDs (identificadores de interface) que o chamador conhece e não quer copiado ou que o objeto de armazenamento não dá suporte, mas cujo estado o chamador copiará explicitamente mais tarde. A matriz pode incluir IStorage, indicando que somente objetos de fluxo devem ser copiados e IStream, indicando que apenas objetos de armazenamento devem ser copiados. Um comprimento de matriz de zero indica que somente o estado exposto pelo objeto IStorage deve ser copiado; todas as outras interfaces no objeto devem ser ignoradas. Passar NULL indica que todas as interfaces no objeto devem ser copiadas.

[in] snbExclude

Um bloco de nome de cadeia de caracteres (consulte SNB) que especifica um bloco de objetos de armazenamento ou fluxo que não devem ser copiados para o destino. Esses elementos não são criados no destino. Se IID_IStorage estiver na matriz rgiidExclude , esse parâmetro será ignorado. Esse parâmetro pode ser NULL.

[in] pstgDest

Um ponteiro para o objeto de armazenamento aberto no qual esse objeto de armazenamento deve ser copiado. O objeto de armazenamento de destino pode ser uma implementação diferente da interface IStorage do objeto de armazenamento de origem. Assim, IStorage::CopyTo só pode usar métodos disponíveis publicamente do objeto de armazenamento de destino. Se pstgDest estiver aberto no modo transacionado, ele poderá ser revertido chamando seu método IStorage::Revert .

Retornar valor

Esse método pode retornar um desses valores.

Código de retorno	Descrição
S_OK	O objeto de armazenamento foi copiado com êxito.
E_PENDING	Somente armazenamento assíncrono: parte ou todos os dados a serem copiados não estão disponíveis no momento.
STG_E_ACCESSDENIED	O objeto de armazenamento de destino é um filho do objeto de armazenamento de origem.
STG_E_INSUFFICIENTMEMORY	A cópia não foi concluída devido à falta de memória.
STG_E_INVALIDPOINTER	O ponteiro especificado para o objeto de armazenamento não era válido.
STG_E_INVALIDPARAMETER	Um dos parâmetros não era válido.
STG_E_TOOMANYOPENFILES	A cópia não foi concluída porque há muitos arquivos abertos.
STG_E_REVERTED	O objeto de armazenamento foi invalidado por uma operação de reverter acima dele na árvore de transações.
STG_E_MEDIUMFULL	A cópia não foi concluída porque o meio de armazenamento está cheio.

Comentários

Esse método mescla elementos contidos no objeto de armazenamento de origem com aqueles que já estão presentes no destino. O layout do objeto de armazenamento de destino pode ser diferente do objeto de armazenamento de origem.

O processo de cópia é recursivo, invocando IStorage::CopyTo e IStream::CopyTo nos elementos aninhados dentro da origem.

Ao copiar um fluxo na parte superior de um fluxo existente com o mesmo nome, o fluxo existente é removido primeiro e substituído pelo fluxo de origem. Ao copiar um armazenamento sobre um armazenamento existente com o mesmo nome, o armazenamento existente não é removido. Como resultado, após a operação de cópia, o IStorage de destino contém elementos mais antigos, a menos que eles tenham sido substituídos por mais recentes pelos mesmos nomes.

Um objeto de armazenamento pode expor interfaces diferentes de IStorage, incluindo IRootStorage, IPropertyStorage ou IPropertySetStorage. O parâmetro rgiidExclude permite a exclusão de qualquer ou todas essas interfaces adicionais da operação de cópia.

Um chamador com uma cópia mais recente ou mais eficiente de um objeto de subconstoragem ou fluxo existente pode querer excluir as versões atuais desses objetos da operação de cópia. Os parâmetros snbExclude e rgiidExclude fornecem duas maneiras de excluir os armazenamentos ou fluxos existentes de objetos de armazenamento.

Observação aos Chamadores

A maneira mais comum de usar o método IStorage::CopyTo é copiar tudo da origem para o destino, como na maioria das operações de salvamento e salvamento completo.

O código de exemplo a seguir mostra como copiar tudo do objeto de armazenamento de origem para o objeto de armazenamento de destino.

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

Nota Para compactar um arquivo de documento, chame CopyTo no objeto de armazenamento raiz e copie para um novo objeto de armazenamento.

 

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	objidl.h
Biblioteca	Uuid.lib
DLL	Ole32.dll

Confira também

IStorage – Implementação de arquivo composto

IStorage::MoveElementTo

IStorage::Revert