STGM-Konstanten

Die STGM-Konstanten sind Flags, die Bedingungen zum Erstellen und Löschen des Objekt- und Zugriffsmodus für das Objekt angeben. Die STGM-Konstanten sind in den Schnittstellen IStorage, IStream und IPropertySetStorage sowie in den Funktionen StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorage und StgOpenStorageEx enthalten.

Diese Elemente werden häufig mithilfe eines OR-Operatorskombiniert. Sie werden in Gruppen interpretiert, wie in der folgenden Tabelle aufgeführt. Es ist nicht gültig, mehr als ein Element aus einer einzelnen Gruppe zu verwenden.

Verwenden Sie beim Erstellen eines Objekts ein Flag aus der Erstellungsgruppe, z. B. mit StgCreateStorageEx oder IStorage::CreateStream.

Weitere Informationen zur Transaktion finden Sie im Abschnitt Hinweise.

STGM_READ

0x00000000L

Gibt an, dass das Objekt schreibgeschützt ist, was bedeutet, dass keine Änderungen vorgenommen werden können. Wenn beispielsweise ein Streamobjekt mit STGM_READ geöffnet wird, kann die ISequentialStream::Read-Methode aufgerufen werden, die ISequentialStream::Write-Methode jedoch nicht. Wenn ein Speicherobjekt mit STGM_READ geöffnet wird, können die Methoden IStorage::OpenStream und IStorage::OpenStorage aufgerufen werden, die Methoden IStorage::CreateStream und IStorage::CreateStorage hingegen nicht.

STGM_WRITE

0x00000001L

Ermöglicht ihnen das Speichern von Änderungen am Objekt, lässt jedoch keinen Zugriff auf seine Daten zu. Die bereitgestellten Implementierungen der Schnittstellen IPropertyStorage und IPropertySetStorage unterstützen diesen Schreibmodus nicht.

STGM_READWRITE

0x00000002L

Ermöglicht den Zugriff und die Änderung von Objektdaten. Wenn beispielsweise ein Streamobjekt in diesem Modus erstellt oder geöffnet wird, ist es möglich, sowohl IStream::Read als auch IStream::Write aufzurufen. Beachten Sie, dass es sich bei dieser Konstante nicht um eine einfache binäre OR-Operation der STGM_WRITE - und STGM_READ-Elemente handelt.

STGM_SHARE_DENY_NONE

0x00000040L

Gibt an, dass nachfolgenden Öffnungen des Objekts der Lese- oder Schreibzugriff nicht verweigert wird. Wenn kein Flag aus der Freigabegruppe angegeben wird, wird dieses Flag angenommen.

STGM_SHARE_DENY_READ

0x00000030L

Verhindert, dass andere das Objekt anschließend im STGM_READ-Modus öffnen. Es wird in der Regel für ein Stammspeicherobjekt verwendet.

STGM_SHARE_DENY_WRITE

0x00000020L

Verhindert, dass andere das Objekt anschließend für STGM_WRITE oder STGM_READWRITE Zugriff öffnen. Im Transaktionsmodus kann die Freigabe von STGM_SHARE_DENY_WRITE oder STGM_SHARE_EXCLUSIVE die Leistung erheblich verbessern, da sie keine Momentaufnahmen erfordern. Weitere Informationen zur Transaktion finden Sie im Abschnitt Hinweise.

STGM_SHARE_EXCLUSIVE

0x00000010L

Verhindert, dass andere das Objekt anschließend in einem beliebigen Modus öffnen. Beachten Sie, dass es sich bei diesem Wert nicht um eine einfache bitweise OR-Operation der STGM_SHARE_DENY_READ - und STGM_SHARE_DENY_WRITE-Werte handelt. Im Transaktionsmodus kann die Freigabe von STGM_SHARE_DENY_WRITE oder STGM_SHARE_EXCLUSIVE die Leistung erheblich verbessern, da sie keine Momentaufnahmen erfordern. Weitere Informationen zur Transaktion finden Sie im Abschnitt Hinweise.

STGM_PRIORITY

0x00040000L

Öffnet das Speicherobjekt mit exklusivem Zugriff auf die zuletzt committete Version. Daher können andere Benutzer keine Änderungen am Objekt committen, während es im Prioritätsmodus geöffnet ist. Sie profitieren von Leistungsvorteilen für Kopiervorgänge, verhindern jedoch, dass andere Änderungen committen. Begrenzen Sie die Zeit, in der Objekte im Prioritätsmodus geöffnet sind. Sie müssen STGM_DIRECT und STGM_READ im Prioritätsmodus angeben, und Sie können STGM_DELETEONRELEASE nicht angeben. STGM_DELETEONRELEASE ist nur beim Erstellen eines Stammobjekts gültig, z. B. mit StgCreateStorageEx. Es ist ungültig, wenn ein vorhandenes Stammobjekt geöffnet wird, z. B. mit StgOpenStorageEx. Es ist auch ungültig, wenn ein Unterelement erstellt oder geöffnet wird, z. B. mit IStorage::OpenStorage.

STGM_CREATE

0x00001000L

Gibt an, dass ein vorhandenes Speicherobjekt oder Datenstrom entfernt werden soll, bevor es durch das neue Objekt ersetzt wird. Ein neues Objekt wird erstellt, wenn dieses Flag nur angegeben wird, wenn das vorhandene Objekt erfolgreich entfernt wurde.

Dieses Flag wird verwendet, wenn versucht wird, Folgendes zu erstellen:

• Ein Speicherobjekt auf einem Datenträger, aber eine Datei mit diesem Namen ist vorhanden.
• Ein Objekt in einem Speicherobjekt, aber ein Objekt mit dem angegebenen Namen ist vorhanden.
• Ein Bytearrayobjekt, aber eines mit dem angegebenen Namen ist vorhanden.

Dieses Flag kann nicht mit geöffneten Vorgängen wie StgOpenStorageEx oder IStorage::OpenStream verwendet werden.

STGM_CONVERT

0x00020000L

Erstellt das neue Objekt unter Beibehaltung vorhandener Daten in einem Stream mit dem Namen "Contents". Bei einem Speicherobjekt oder einem Bytearray werden die alten Daten in einen Stream formatiert, unabhängig davon, ob das vorhandene Datei- oder Bytearray derzeit ein mehrschichtiges Speicherobjekt enthält. Dieses Flag kann nur beim Erstellen eines Stammspeicherobjekts verwendet werden. Es kann nicht innerhalb eines Speicherobjekts verwendet werden. beispielsweise in IStorage::CreateStream. Es ist auch nicht gültig, dieses Flag und das STGM_DELETEONRELEASE-Flag gleichzeitig zu verwenden.

STGM_FAILIFTHERE

0x00000000L

Führt dazu, dass der Erstellungsvorgang fehlschlägt, wenn ein vorhandenes Objekt mit dem angegebenen Namen vorhanden ist. In diesem Fall wird STG_E_FILEALREADYEXISTS zurückgegeben. Dies ist der Standarderstellungsmodus. Das heißt, wenn kein anderes Create-Flag angegeben ist, wird STGM_FAILIFTHERE impliziert.

STGM_DIRECT

0x00000000L

Gibt an, dass im direkten Modus jede Änderung an einem Speicher- oder Streamelement geschrieben wird, während sie auftritt. Dies ist der Standardwert, wenn weder STGM_DIRECT noch STGM_TRANSACTED angegeben ist.

STGM_TRANSACTED

0x00010000L

Gibt an, dass Änderungen im Transaktionsmodus nur gepuffert und geschrieben werden, wenn ein expliziter Commitvorgang aufgerufen wird. Um die Änderungen zu ignorieren, rufen Sie die Revert-Methode in der IStream-, IStorage- oder IPropertyStorage-Schnittstelle auf. Die COM-Verbunddateiimplementierung von IStorage unterstützt keine Transaktionsdatenströme. Dies bedeutet, dass Datenströme nur im direkten Modus geöffnet werden können, und Sie können keine Änderungen daran rückgängig machen, jedoch werden transaktionsierte Speicher unterstützt. Die Dateisystemimplementierungen für zusammengesetzte Dateien, eigenständige und NTFS-Dateisystemimplementierungen von IPropertySetStorage unterstützen ebenfalls keine transaktionsbasierten einfachen Eigenschaftensätze, da diese Eigenschaftssätze in Streams gespeichert werden. Es werden jedoch Transaktionen von nicht einfachen Eigenschaftensätzen unterstützt, die durch Angeben des PROPSETFLAG_NONSIMPLE-Flags im grfFlags-Parameter von IPropertySetStorage::Create erstellt werden können.

STGM_NOSCRATCH

0x00100000L

Gibt an, dass im Transaktionsmodus normalerweise eine temporäre Scratchdatei verwendet wird, um Änderungen zu speichern, bis die Commit-Methode aufgerufen wird. Wenn Sie STGM_NOSCRATCH angeben, kann der nicht verwendete Teil der ursprünglichen Datei als Arbeitsbereich verwendet werden, anstatt eine neue Datei für diesen Zweck zu erstellen. Dies wirkt sich nicht auf die Daten in der ursprünglichen Datei aus, und in bestimmten Fällen kann die Leistung verbessert werden. Es ist nicht gültig, dieses Flag anzugeben, ohne auch STGM_TRANSACTED anzugeben, und dieses Flag kann nur in einem geöffneten Stamm verwendet werden. Weitere Informationen zum NoScratch-Modus finden Sie im Abschnitt Hinweise.

STGM_NOSNAPSHOT

0x00200000L

Dieses Flag wird beim Öffnen eines Speicherobjekts mit STGM_TRANSACTED und ohne STGM_SHARE_EXCLUSIVE oder STGM_SHARE_DENY_WRITE verwendet. In diesem Fall verhindert die Angabe STGM_NOSNAPSHOT, dass die vom System bereitgestellte Implementierung eine Momentaufnahme Kopie der Datei erstellt. Stattdessen werden Änderungen an der Datei an das Ende der Datei geschrieben. Nicht genutzter Speicherplatz wird nicht zurückgewonnen, es sei denn, die Konsolidierung wird während des Commits durchgeführt, und es gibt nur einen aktuellen Writer für die Datei. Wenn die Datei im Modus ohne Momentaufnahme geöffnet wird, kann kein weiterer Vorgang zum Öffnen ausgeführt werden, ohne STGM_NOSNAPSHOT anzugeben. Dieses Flag kann nur in einem geöffneten Root-Vorgang verwendet werden. Weitere Informationen zum NoSnapshot-Modus finden Sie im Abschnitt Hinweise.

STGM_SIMPLE

0x08000000L

Ermöglicht eine schnellere Implementierung einer zusammengesetzten Datei in einem begrenzten, aber häufig verwendeten Fall. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

STGM_DIRECT_SWMR

0x00400000L

Unterstützt den direkten Modus für Einzelschreibvorgänge mit mehreren Lesevorgängen. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

STGM_DELETEONRELEASE

0x040000000L

Gibt an, dass die zugrunde liegende Datei automatisch zerstört werden soll, wenn das Stammspeicherobjekt freigegeben wird. Dieses Feature ist am nützlichsten zum Erstellen temporärer Dateien. Dieses Flag kann nur beim Erstellen eines Stammobjekts verwendet werden, z. B. mit StgCreateStorageEx. Sie ist ungültig, wenn Sie ein Stammobjekt öffnen, z. B. mit StgOpenStorageEx, oder beim Erstellen oder Öffnen eines Unterelements, z. B. mit IStorage::CreateStream. Es ist auch nicht gültig, dieses Flag und das STGM_CONVERT-Flag gleichzeitig zu verwenden.

Bemerkungen

Sie können diese Flags kombinieren, aber sie können nur ein Flag aus jeder Gruppe verwandter Flags auswählen. In der Regel muss für alle Funktionen und Methoden, die diese Konstanten verwenden, ein Flag aus jeder Zugriffs- und Freigabegruppe angegeben werden. Flags aus anderen Gruppen sind optional.

Transaktionsmodus

Wenn das flag STGM_DIRECTangegeben wird, kann nur eine der folgenden Kombinationen von Flags aus den Zugriffs- und Freigabegruppen angegeben werden.

    STGM_READ      | STGM_SHARE_DENY_WRITE

    STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_READ      | STGM_PRIORITY

Beachten Sie, dass der direkte Modus durch das Fehlen von STGM_TRANSACTED impliziert wird. Das heißt, wenn weder STGM_DIRECT noch STGM_TRANSACTED angegeben wird, wird STGM_DIRECT angenommen.

Wenn das STGM_TRANSACTED-Flag angegeben wird, werden Objekte im Transaktionsmodus erstellt oder geöffnet. In diesem Modus bleiben Änderungen an einem Objekt erst dann bestehen, wenn sie committet werden. Beispielsweise werden Änderungen an einem transaktionsierten Speicherobjekt erst beibehalten, wenn die IStorage::Commit-Methode aufgerufen wird. Änderungen an einem solchen Speicherobjekt gehen verloren, wenn das Speicherobjekt freigegeben wird (endgültiges Release), bevor die Commit-Methode aufgerufen wird, oder wenn die IStorage::Revert-Methode aufgerufen wird.

Wenn ein Objekt im Transaktionsmodus erstellt oder geöffnet wird, muss die Implementierung sowohl die ursprünglichen Daten als auch Die Aktualisierungen dieser Daten beibehalten, damit Updates bei Bedarf wiederhergestellt werden können. Dies erfolgt in der Regel durch Schreiben von Änderungen in einen Scratchbereich, bis sie committet wurden, oder durch Erstellen einer Kopie der zuletzt als Momentaufnahme bezeichneten Daten.

Wenn ein Stammspeicherobjekt im Transaktionsmodus geöffnet wird, können der Speicherort und das Verhalten der Scratchdaten und der Momentaufnahme Kopien gesteuert werden, um die Leistung mit den flags STGM_NOSCRATCH und STGM_NOSNAPSHOT zu optimieren. (Ein Stammspeicherobjekt wird beispielsweise von der StgOpenStorageEx-Funktion abgerufen. Ein Speicherobjekt, das von der IStorage::OpenStorage-Methode abgerufen wird, ist ein Unterspeicherobjekt.) In der Regel werden die Scratchdaten und Momentaufnahmen in temporären Dateien gespeichert, die vom Speicher getrennt sind.

Die Wirkung dieser Flags hängt von der Anzahl der Leser und/oder Autoren ab, die auf den Stammspeicher zugreifen.

Im Fall "Single Writer" wird ein Speicherobjekt im Transaktionsmodus für den Schreibzugriff geöffnet, und es kann keinen anderen Zugriff auf die Datei geben. Das heißt, die Datei wird mit STGM_TRANSACTED, Zugriff auf STGM_WRITE oder STGM_READWRITE und Freigabe von STGM_SHARE_EXCLUSIVE geöffnet. In diesem Fall werden Änderungen am Speicherobjekt in den Scratchbereich geschrieben. Wenn diese Änderungen committet werden, werden sie in den ursprünglichen Speicher kopiert. Wenn also tatsächlich keine Änderungen am Speicherobjekt vorgenommen werden, erfolgt keine unnötige Datenübertragung.

Im Fall "Multiple Writer" wird ein transaktionsbasiertes Speicherobjekt für den Schreibzugriff geöffnet, aber so freigegeben, dass andere Autoren zugelassen werden. Das heißt, das Speicherobjekt wird mit STGM_TRANSACTED, Zugriff auf STGM_WRITE oder STGM_READWRITE und Freigabe von STGM_SHARE_DENY_READ geöffnet. Wenn stattdessen die Freigabe von STGM_SHARE_DENY_NONE angegeben wird, lautet der Fall "multiple writer, multiple-reader". In diesen Fällen wird während des geöffneten Vorgangs eine Momentaufnahme der ursprünglichen Daten vorgenommen. Selbst wenn keine Änderungen am Speicher vorgenommen werden und/oder er nicht von einem anderen Writer gleichzeitig geöffnet wird, ist die Datenübertragung während des Öffnens immer noch notwendig. Dadurch kann die beste Open-Time-Leistung erzielt werden, indem das Speicherobjekt im STGM_SHARE_DENY_WRITE - oder STGM_SHARE_EXCLUSIVE-Modus geöffnet wird. Weitere Informationen zum Commit von Änderungen, wenn mehrere Autoren vorhanden sind, finden Sie unter IStorage::Commit.

Im Fall "Single Writer, Multiple Reader" wird ein transaktionsbasiertes Speicherobjekt für den Schreibzugriff geöffnet, aber für Leser freigegeben. Das heißt, das Speicherobjekt wird vom Writer mit STGM_TRANSACTED, Zugriff auf STGM_READWRITE oder STGM_WRITE und Freigabe von STGM_SHARE_DENY_WRITE geöffnet. Der Speicher wird von Lesern mit STGM_TRANSACTED, Zugriff auf STGM_READ und Freigabe von STGM_SHARE_DENY_NONE geöffnet. In diesem Fall verwendet der Writer den Scratchbereich, um nicht signierte Änderungen zu speichern. Wie in den oben genannten Fällen entsteht beim Erstellen einer Momentaufnahme Kopie der Daten eine Zeitstrafe für den Leser.

In der Regel ist der Scratchbereich eine temporäre Datei, die von den ursprünglichen Daten getrennt ist. Wenn Änderungen an der ursprünglichen Datei festgelegt werden, müssen die Daten aus der temporären Datei übertragen werden. Um diese Datenübertragung zu vermeiden, kann das flag STGM_NOSCRATCHangegeben werden. Wenn dieses Flag angegeben wird, werden Teile der Speicherobjektdatei für den Scratchbereich anstelle einer separaten temporären Datei verwendet. Daher können Commitänderungen schnell ausgeführt werden, da nur wenig Datenübertragung erforderlich ist. Der Nachteil ist, dass die Speicherdatei größer werden kann, als sie andernfalls sein würde, da sie vergrößert werden muss, um sowohl für die ursprünglichen Daten als auch für den Scratchbereich groß genug zu sein. Um die Daten zu konsolidieren und diesen unnötigen Bereich zu entfernen, öffnen Sie den Stammspeicher im Transaktionsmodus erneut, ohne das Flag STGM_NOSCRATCH festzulegen. Rufen Sie dann IStorage::Commit auf, wobei das STGC_CONSOLIDATE-Flag festgelegt ist.

Der Momentaufnahme Bereich, wie der Scratchbereich, ist in der Regel auch eine temporäre Datei, und auch dies kann mit einem STGM-Flag betroffen sein. Durch Angeben des STGM_NOSNAPSHOT-Flags wird keine separate temporäre Momentaufnahme-Datei erstellt. Stattdessen werden die ursprünglichen Daten nie geändert, auch wenn es einen oder mehrere Writer pro Objekt gibt. Wenn Änderungen festgelegt werden, werden sie der Datei hinzugefügt, aber die ursprünglichen Daten bleiben intakt. Dieser Modus erhöht die Effizienz, da die Laufzeit reduziert wird, da die Notwendigkeit, während des geöffneten Vorgangs eine Momentaufnahme zu erstellen, beseitigt wird. Die Verwendung dieses Modus kann jedoch zu einer sehr großen Speicherdatei führen, da Daten in der Datei nie überschrieben werden können. Dies ist keine Beschränkung für die Größe der Dateien, die im NoSnapshot-Modus geöffnet wurden.

Direct Single Writer, Multiple-Reader Modus

Wie beschrieben ist es möglich, über einen einzelnen Writer und mehrere Reader eines Speicherobjekts zu verfügen, wenn dieses Objekt im Transaktionsmodus geöffnet wird. Es ist auch möglich, die Einzelschreib-, Multireader-Groß- und Kleinschreibung im direkten Modus zu erreichen, indem Sie das flag STGM_DIRECT_SWMR angeben.

Im STGM_DIRECT_SWMR Modus ist es für einen Aufrufer möglich, ein Objekt für den Lese-/Schreibzugriff zu öffnen, während andere Aufrufer gleichzeitig die Datei für schreibgeschützten Zugriff geöffnet haben. Es ist nicht gültig, dieses Flag in Kombination mit dem STGM_TRANSACTED-Flag zu verwenden. In diesem Modus öffnet der Writer das Objekt mit den folgenden Flags:

| STGM_DIRECT_SWMR | STGM_READWRITE STGM_SHARE_DENYWRITE

und jeder Leser öffnet das Objekt mit den folgenden Flags:

| STGM_DIRECT_SWMR | STGM_READ STGM_SHARE_DENY_NONE

In diesem Modus muss der Writer exklusiven Zugriff auf das Objekt erhalten, um das Speicherobjekt zu ändern. Dies ist möglich, wenn alle Leser sie geschlossen haben. Der Writer verwendet die IDirectWriterLock-Schnittstelle , um diesen exklusiven Zugriff zu erhalten.

Einfacher Modus

Der einfache Modus (STGM_SIMPLE) ist nützlich für Anwendungen, die vollständige Speichervorgänge ausführen. Es ist effizient, hat jedoch die folgenden Einschränkungen:

• Für Unterspeicher ist keine Unterstützung vorhanden.
• Das Speicherobjekt und die daraus abgerufenen Streamobjekte können nicht gemarst werden.
• Jeder Stream hat eine Mindestgröße. Wenn weniger als die Mindestbytes in einen Stream geschrieben werden, wenn der Stream veröffentlicht wird, wird der Stream auf die Mindestgröße erweitert. Die Mindestgröße für eine bestimmte IStream-Implementierung beträgt beispielsweise 4 KB. Ein Stream wird erstellt, und 1 KB wird in ihn geschrieben. Beim endgültigen Release dieses IStream wird die Streamgröße automatisch auf 4 KB erweitert. Anschließend wird beim Öffnen des Datenstroms und aufrufen der IStream::Stat-Methode eine Größe von 4 KB angezeigt.
• Nicht alle Methoden von IStorage oder IStream werden von der Implementierung unterstützt. Weitere Informationen finden Sie unter IStorage – Implementierung zusammengesetzter Dateien und IStream – Implementierung zusammengesetzter Dateien.

Marshalling ist der Prozess des Packens, Entpackens und Sendens von Schnittstellenmethodenparametern über Thread- oder Prozessgrenzen innerhalb eines Remoteprozeduraufrufs (RPC). Weitere Informationen finden Sie unter Marshallingdetails und Interface Marshaling.

Wenn ein Speicherobjekt durch einen Create-Vorgang im einfachen Modus abgerufen wird:

• Streamelemente können erstellt, aber nicht geöffnet werden.
• Wenn ein Streamelement durch Aufrufen von IStorage::CreateStream erstellt wird, ist es nicht möglich, einen weiteren Stream zu erstellen, bis dieses Streamobjekt freigegeben wird.
• Nachdem alle Streams geschrieben wurden, rufen Sie IStorage::Commit auf, um die Änderungen zu löschen.

Wenn ein Speicherobjekt durch einen Open-Vorgang im einfachen Modus abgerufen wird:

• Es ist möglich, jeweils nur ein Streamelement zu öffnen.
• Es ist nicht möglich, die Größe eines Streams durch Aufrufen der IStream::SetSize-Methode oder durch Suchen oder Schreiben über das Ende des Datenstroms hinaus zu ändern. Da jedoch alle Streams eine Mindestgröße haben, ist es möglich, den Stream bis zu dieser Größe zu verwenden, auch wenn ursprünglich weniger Daten in ihn geschrieben wurden. Verwenden Sie die IStream::Stat-Methode , um die Größe eines Datenstroms zu bestimmen.

Beachten Sie, dass es nicht möglich ist, dieses Speicherelement im einfachen Modus zu öffnen, wenn ein Speicherelement von einem Speicherobjekt geändert wird, das sich nicht im einfachen Modus befindet.

Anforderungen

Siehe auch

ISequentialStream::Read

IStorage

StgCreateDocfile

StgCreateDocfileOnILockBytes

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx

StgOpenStorageOnILockBytes