IStorage::CopyTo-Methode (objidl.h)

Die CopyTo-Methode kopiert den gesamten Inhalt eines geöffneten Speicherobjekts in ein anderes Speicherobjekt.

Syntax

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

Parameter

[in] ciidExclude

Die Anzahl der Elemente im Array, auf die rgiidExclude verweist. Wenn rgiidExcludeNULL ist, wird ciidExclude ignoriert.

[in] rgiidExclude

Ein Array von Schnittstellenbezeichnern (Interface Identifiers, IIDs), die entweder dem Aufrufer bekannt sind und nicht kopiert werden sollen, oder das das Speicherobjekt nicht unterstützt, dessen Zustand der Aufrufer später jedoch explizit kopieren wird. Das Array kann IStorage enthalten, was angibt, dass nur Streamobjekte kopiert werden sollen, und IStream, was angibt, dass nur Speicherobjekte kopiert werden sollen. Eine Arraylänge von 0 (null) gibt an, dass nur der vom IStorage-Objekt verfügbar gemachte Zustand kopiert werden soll. alle anderen Schnittstellen für das Objekt sind zu ignorieren. Das Übergeben von NULL gibt an, dass alle Schnittstellen im Objekt kopiert werden sollen.

[in] snbExclude

Ein Zeichenfolgennamenblock (siehe SNB), der einen Speicherblock oder Streamobjekte angibt, die nicht in das Ziel kopiert werden sollen. Diese Elemente werden nicht am Ziel erstellt. Wenn sich IID_IStorage im rgiidExclude-Array befindet, wird dieser Parameter ignoriert. Dieser Parameter kann NULL sein.

[in] pstgDest

Ein Zeiger auf das geöffnete Speicherobjekt, in das dieses Speicherobjekt kopiert werden soll. Das Zielspeicherobjekt kann eine andere Implementierung der IStorage-Schnittstelle als das Quellspeicherobjekt sein. Daher kann IStorage::CopyTo nur öffentlich verfügbare Methoden des Zielspeicherobjekts verwenden. Wenn pstgDest im Transaktionsmodus geöffnet ist, kann es durch Aufrufen der IStorage::Revert-Methode wiederhergestellt werden.

Rückgabewert

Diese Methode kann einen dieser Werte zurückgeben.

Rückgabecode	Beschreibung
S_OK	Das Speicherobjekt wurde erfolgreich kopiert.
E_PENDING	Nur asynchroner Speicher: Ein Teil oder alle zu kopierenden Daten sind derzeit nicht verfügbar.
STG_E_ACCESSDENIED	Das Zielspeicherobjekt ist ein untergeordnetes Element des Quellspeicherobjekts.
STG_E_INSUFFICIENTMEMORY	Der Kopiervorgang wurde aufgrund eines Mangels an Arbeitsspeicher nicht abgeschlossen.
STG_E_INVALIDPOINTER	Der für das Speicherobjekt angegebene Zeiger war ungültig.
STG_E_INVALIDPARAMETER	Einer der Parameter war ungültig.
STG_E_TOOMANYOPENFILES	Der Kopiervorgang wurde nicht abgeschlossen, da zu viele dateien geöffnet sind.
STG_E_REVERTED	Das Speicherobjekt wurde durch einen rückgängig machen Vorgang darüber in der Transaktionsstruktur ungültig gemacht.
STG_E_MEDIUMFULL	Der Kopiervorgang wurde nicht abgeschlossen, da das Speichermedium voll ist.

Hinweise

Diese Methode führt Elemente, die im Quellspeicherobjekt enthalten sind, mit den Elementen zusammen, die bereits im Ziel vorhanden sind. Das Layout des Zielspeicherobjekts kann sich vom Quellspeicherobjekt unterscheiden.

Der Kopiervorgang ist rekursiv und wird für die in der Quelle geschachtelten Elemente IStorage::CopyTo und IStream::CopyTo aufgerufen.

Beim Kopieren eines Datenstroms über einen vorhandenen Datenstrom mit demselben Namen wird der vorhandene Datenstrom zuerst entfernt und dann durch den Quelldatenstrom ersetzt. Beim Kopieren eines Speichers auf einem vorhandenen Speicher mit demselben Namen wird der vorhandene Speicher nicht entfernt. Daher enthält der IStorage-Zielspeicher nach dem Kopiervorgang ältere Elemente, es sei denn, sie wurden durch neuere Elemente mit denselben Namen ersetzt.

Ein Speicherobjekt kann andere Schnittstellen als IStorage verfügbar machen, einschließlich IRootStorage, IPropertyStorage oder IPropertySetStorage. Der Parameter rgiidExclude ermöglicht den Ausschluss einer oder aller dieser zusätzlichen Schnittstellen aus dem Kopiervorgang.

Ein Aufrufer mit einer neueren oder effizienteren Kopie eines vorhandenen Unterspeichers oder Streamobjekts möchte möglicherweise die aktuellen Versionen dieser Objekte vom Kopiervorgang ausschließen. Die Parameter snbExclude und rgiidExclude bieten zwei Möglichkeiten zum Ausschließen vorhandener Speicherobjekte oder Streams.

Hinweis für Anrufer

Die gängigste Methode zur Verwendung der IStorage::CopyTo-Methode besteht darin, alles von der Quelle in das Ziel zu kopieren, wie bei den meisten Vollständigen Speichern und Speichern als Vorgängen.

Der folgende Beispielcode zeigt, wie Alles aus dem Quellspeicherobjekt in das Zielspeicherobjekt kopiert wird.

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

Hinweis Um eine Dokumentdatei zu komprimieren, rufen Sie CopyTo für das Stammspeicherobjekt auf, und kopieren Sie in ein neues Speicherobjekt.

 

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [Desktop-Apps | UWP-Apps]
Zielplattform	Windows
Kopfzeile	objidl.h
Bibliothek	Uuid.lib
DLL	Ole32.dll

Weitere Informationen

IStorage – Implementierung von Zusammengesetzten Dateien

IStorage::MoveElementTo

IStorage::Revert