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)
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 |