IStorage::Commit-Methode (objidl.h)
Die Commit-Methode stellt sicher, dass alle Änderungen, die an einem im Transaktionsmodus geöffneten Speicherobjekt vorgenommen werden, im übergeordneten Speicher widergespiegelt werden. Bei Nicht-Stammspeicherobjekten im direkten Modus hat diese Methode keine Auswirkung. Bei einem Stammspeicher spiegelt er die Änderungen im tatsächlichen Gerät wider. z. B. eine Datei auf dem Datenträger. Rufen Sie für ein im direkten Modus geöffnetes Stammspeicherobjekt immer die IStorage::Commit-Methode vor Release auf. IStorage::Commit löscht alle Speicherpuffer auf den Datenträger für einen Stammspeicher im direkten Modus und gibt bei einem Fehler einen Fehlercode zurück. Obwohl Release auch Speicherpuffer auf den Datenträger leert, kann es bei einem Fehler keine Fehlercodes zurückgeben. Daher führt das Aufrufen von Release , ohne zuerst Commit aufzurufen , zu unbestimmten Ergebnissen.
Syntax
HRESULT Commit(
[in] DWORD grfCommitFlags
);
Parameter
[in] grfCommitFlags
Steuert, wie die Änderungen auf das Speicherobjekt festgelegt werden. Eine Definition dieser Werte finden Sie in der STGC-Enumeration .
Rückgabewert
Diese Methode kann einen dieser Werte zurückgeben.
| Rückgabecode | Beschreibung |
|---|---|
| S_OK | Änderungen am Speicherobjekt wurden erfolgreich auf die übergeordnete Ebene festgelegt. Wenn STGC_CONSOLIDATE angegeben wurde, wurde der Speicher erfolgreich konsolidiert oder der Speicher war bereits zu kompakt, um sich weiter zu konsolidieren. |
| STG_S_MULTIPLEOPENS | Der Commitvorgang war erfolgreich, aber der Speicher konnte nicht konsolidiert werden, da er mehrmals mit dem STGM_NOSNAPSHOT-Flag geöffnet wurde. |
| STG_S_CANNOTCONSOLIDATE | Der Commitvorgang war erfolgreich, aber der Speicher konnte aufgrund eines falschen Speichermodus nicht konsolidiert werden. Bei zusammengesetzten Dateien wurde der Speicher möglicherweise mit dem STGM_NOSCRATCH-Flag geöffnet, oder der Speicher ist nicht die äußerste Transaktionsebene. |
| STG_S_CONSOLIDATIONFAILED | Der Commitvorgang war erfolgreich, aber der Speicher konnte aufgrund eines internen Fehlers (z. B. eines Fehlers bei der Speicherzuordnung) nicht konsolidiert werden. |
| E_PENDING | Nur asynchroner Speicher: Ein Teil oder alle daten, die committet werden sollen, sind derzeit nicht verfügbar. |
| STG_E_INVALIDFLAG | Der Wert für den grfCommitFlags-Parameter ist ungültig. |
| STG_E_INVALIDPARAMETER | Einer der Parameter war ungültig. |
| STG_E_NOTCURRENT | Eine andere offene instance des Speicherobjekts hat Änderungen zugesagt. Daher kann der aktuelle Commitvorgang frühere Änderungen überschreiben. |
| STG_E_MEDIUMFULL | Auf dem Gerät ist kein Commit mehr verfügbar. |
| STG_E_TOOMANYOPENFILES | Der Commitvorgang konnte nicht abgeschlossen werden, 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. |
Hinweise
IStorage::Commit nimmt permanente Änderungen an einem Speicherobjekt vor, das sich im Transaktionsmodus befindet, in dem Änderungen in einem Puffer akkumuliert werden und erst dann im Speicherobjekt widergespiegelt werden, wenn diese Methode aufgerufen wird. Die Alternative besteht darin, ein Objekt im direkten Modus zu öffnen, in dem Änderungen sofort im Speicherobjekt widerspiegelt werden. Ein im direkten Modus geöffnetes Objekt erfordert keinen Aufruf von IStorage::Commit , um dauerhafte Änderungen am Speicherobjekt vorzunehmen. Das Aufrufen der IStorage::Commit-Methode für einen Nicht-Stammspeicher, der im direkten Modus geöffnet wird, hat keine Auswirkungen. Beim Öffnen eines Stammspeicherobjekts im direkten Modus wird sichergestellt, dass Änderungen in den Speicherpuffern auf das zugrunde liegende Speichergerät geschrieben werden.
Der Commitvorgang veröffentlicht die aktuellen Änderungen in diesem Speicherobjekt und seinen untergeordneten Elementen auf der nächsten Ebene in der Speicherhierarchie. Um aktuelle Änderungen vor dem Commit rückgängig zu machen, rufen Sie IStorage::Revert auf, um ein Rollback zur zuletzt zugesagten Version durchzuführen.
Das Aufrufen von IStorage::Commit hat keine Auswirkungen auf derzeit geöffnete geschachtelte Elemente dieses Speicherobjekts. Sie bleiben gültig und können verwendet werden. Die IStorage::Commit-Methode committ Änderungen jedoch nicht automatisch an diese geschachtelten Elemente. Der Commitvorgang veröffentlicht nur bekannte Änderungen auf der nächsthöheren Ebene in der Speicherhierarchie. Daher müssen Transaktionen auf geschachtelte Ebenen für dieses Speicherobjekt festgelegt werden, bevor sie auf höhere Ebenen gebunden werden können.
In Commitvorgängen müssen Sie Schritte ausführen, um sicherzustellen, dass die Daten während des Commitvorgangs geschützt sind:
- Beim Commit von Änderungen an Stammspeicherobjekten muss der Aufrufer den Rückgabewert überprüfen, um festzustellen, ob der Vorgang erfolgreich abgeschlossen wurde, und falls nicht, ob der alte Commitinhalt des IStorage noch intakt ist und wiederhergestellt werden kann.
- Wenn dieses Speicherobjekt mit ausgeschlossenen Elementen geöffnet wurde, ist der Aufrufer dafür verantwortlich, sie vor dem Aufrufen des Commits neu zu schreiben. Der Schreibmodus ist für die Speicheröffnung erforderlich, damit der Commit erfolgreich ist.
- Es sei denn, mehrere gleichzeitige Writer für dasselbe Speicherobjekt zu verbieten, sollte eine Anwendung, die diese Methode aufruft, mindestens STGC_ONLYIFCURRENT im grfCommitFlags-Parameter angeben, um zu verhindern, dass die von einem Writer vorgenommenen Änderungen versehentlich die von einem anderen vorgenommenen Änderungen überschreiben.
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 |