IPropertyStorage-Compound-Dateiimplementierung
Die COM-Implementierung der Architektur des strukturierten Speichers wird als Verbunddateien bezeichnet. Speicherobjekte, die in zusammengesetzten Dateien implementiert sind, umfassen eine Implementierung von IPropertyStorage, der Schnittstelle, die einen einzelnen persistenten Eigenschaftensatz verwaltet, und IPropertySetStorage, der Schnittstelle, die Gruppen persistenter Eigenschaftssätze verwaltet. Weitere Informationen zur IPropertyStorage-Schnittstelle finden Sie unter Überlegungen zu IPropertyStorage und Eigenschaftenspeicher.
Um einen Zeiger auf die Verbunddateiimplementierung von IPropertyStorage zu erhalten, rufen Sie StgCreateStorageEx auf, um ein neues Verbunddateiobjekt zu erstellen, oder StgOpenStorageEx , um ein zuvor erstelltes Verbunddateiobjekt zu öffnen. Im Fall von StgCreateStorageEx sollte der stgfmt-Parameter auf STGFMT_STORAGE festgelegt werden. Im Fall von StgOpenStorageEx sollte der stgfmt-Parameter auf STGFMT_STORAGE oder STGFMT_ANY festgelegt werden. In beiden Fällen sollte der riid-Parameter auf IID_IPropertySetStorage festgelegt werden. Beide Funktionen stellen einen Zeiger auf die IPropertySetStorage-Schnittstelle des Objekts bereit. Indem Sie entweder die Create - oder Open-Methode dieser Schnittstelle aufrufen, erhalten Sie einen Zeiger auf die IPropertyStorage-Schnittstelle , die Sie zum Aufrufen einer ihrer Methoden verwenden können.
Eine alternative Möglichkeit zum Abrufen eines Zeigers auf die Verbunddateiimplementierung von IPropertySetStorage besteht darin, die älteren Funktionen StgCreateDocfile und StgOpenStorage aufzurufen oder einen riid-Parameter von IID_IStorage für die StgCreateStorageEx - oder StgOpenStorageEx-Funktion anzugeben. In beiden Fällen wird ein Zeiger auf die IStorage-Schnittstelle des Objekts zurückgegeben. Rufen Sie bei persistenten Eigenschaftensätzen QueryInterface für die IPropertySetStorage-Schnittstelle auf, und geben Sie den vom Header definierten Namen für den Schnittstellenbezeichner (Interface Identifier, IID) IID_IPropertySetStorage an.
Einsatzgebiet
Verwenden Sie IPropertyStorage , um Eigenschaften innerhalb eines einzelnen Eigenschaftensatzes zu verwalten. Seine Methoden unterstützen das Lesen, Schreiben und Löschen von Eigenschaften und optionalen Zeichenfolgennamen, die Eigenschaftenbezeichnern zugeordnet werden können. Andere Methoden unterstützen standardmäßige Commit- und rückgängig machen Speichervorgänge. Es gibt auch eine Methode, mit der Sie Zeiten festlegen können, die dem Eigenschaftenspeicher zugeordnet sind, und eine andere, die die Zuweisung einer CLSID zulässt, die verwendet werden kann, um anderen Code, z. B. Benutzeroberflächencode, dem Eigenschaftensatz zuzuordnen. Der Aufruf der Enum-Methode liefert einen Zeiger auf die Verbunddateiimplementierung von IEnumSTATPROPSTG, mit der Sie die Eigenschaften im Satz auflisten können.
Hinweis
Wenn Sie einen Zeiger auf IPropertyStorage abrufen, indem Sie StgCreateDocfile, StgCreateStorageEx, StgOpenStorage oder StgOpenStorageEx für einen Simple-Mode-Eigenschaftensatzspeicher aufrufen, halten die IPropertyStorage-Methoden die Regeln von Datenströmen im einfachen Modus ein. Der Eigenschaftssatzspeicher ist ein einfacher Modus, wenn er für eine Datei abgerufen wurde, die mit dem flag STGM_SIMPLE erstellt oder geöffnet wurde. In diesem Fall ist es nicht immer möglich, den zugrunde liegenden Stream zu vergrößern, und es ist nicht möglich, vorhandene Eigenschaften durch größere Eigenschaften zu ersetzen. Weitere Informationen finden Sie unter IPropertySetStorage-Verbunddateiimplementierung.
IPropertyStorage und Zwischenspeicherung
Die Verbunddateiimplementierung von IPropertyStorage speichert offene Eigenschaftssätze im Arbeitsspeicher zwischen, um die Leistung zu verbessern. Daher werden Änderungen an einem Eigenschaftensatz erst in die Verbunddatei geschrieben, wenn die Commit - oder Release-Methoden (letzter Verweis) aufgerufen werden.
Simple Mode-Eigenschaftssätze
Ein Eigenschaftsspeicherobjekt befindet sich im einfachen Modus, wenn es aus einem Einfachen Modus-Eigenschaftensatzspeicherobjekt erstellt wird. Beispielsweise würde sich ein Eigenschaftensatzspeicherobjekt im einfachen Modus befinden, wenn es von der StgOpenStorageEx-Funktion abgerufen würde, wobei das flag STGM_SIMPLE im grfMode-Parameter festgelegt ist. Beachten Sie, dass "einfacher Modus" nicht mit "einfachen Eigenschaftssätzen" zusammenhängt. Ein Eigenschaftssatz ist einfach, wenn er durch Aufrufen von IPropertySetStorage::Create mit dem im grfFlags-Parameter festgelegten PROPSETFLAG_NONSIMPLE-Flag erstellt wird. Weitere Informationen zu einfachen und nicht einfachen Eigenschaftensätzen finden Sie unter Speicher- und Streamobjekte für einen Eigenschaftensatz.
Wenn ein Einfaches Modus-Eigenschaftsspeicherobjekt erstellt wird, gibt es keine Einschränkungen bei der Verwendung. Wenn ein vorhandenes Eigenschaftenspeicherobjekt im einfachen Modus geöffnet wird, kann das zugrunde liegende Streamobjekt, das den Eigenschaftensatz speichert, nicht vergrößert werden. Daher ist es nicht immer möglich, ein solches Eigenschaftsspeicherobjekt zu ändern, wenn die Änderung einen größeren Stream erfordert.
Eigenschaftensatzformate
Die Verbunddateiimplementierung von IPropertyStorage unterstützt sowohl die Serialisierungsformate der Version 0 als auch die Eigenschaftssatzformate der Version 1. Das Format der Version 1 wird auf Computern unter Windows 2000 unterstützt. Weitere Informationen finden Sie unter Serialisierung von Eigenschaftensatz. Eigenschaftssätze werden im Format version 0 erstellt und verbleiben in diesem Format, es sei denn, neue Features werden angefordert. In diesem Fall wird das Format auf Version 1 aktualisiert.
Wenn beispielsweise ein Eigenschaftensatz mit dem flag PROPSETFLAG_DEFAULT erstellt wird, ist sein Format Version 0. Solange Eigenschaftentypen, die dem Format der Version 0 entsprechen, in diesen Eigenschaftensatz geschrieben und daraus gelesen werden, bleibt der Eigenschaftensatz im Format Version 0 erhalten. Wenn ein Eigenschaftentyp der Version 1 in den Eigenschaftensatz geschrieben wird, wird der Eigenschaftensatz automatisch auf Version 1 aktualisiert. Anschließend kann dieser Eigenschaftssatz nicht mehr von Implementierungen gelesen werden, die nur Version 0 erkennen.
IPropertyStorage und Variant-Typen
Die Verbunddateiimplementierung von IPropertyStorage unterstützt die Variantentypen VT_UNKNOWN oder VT_DISPATCH im vt-Member der PROPVARIANT-Struktur nicht.
In der folgenden Tabelle sind Variantentypen aufgeführt, die in einem SafeArray unterstützt werden. Das heißt, diese Werte können mit VT_ARRAY im vt-Member der PROPVARIANT-Struktur kombiniert werden.
Variantentypen, die in SafeArray von der Implementierung von IPropertyStorage unterstützt werden
VT_I1
VT_UI1
VT_I2
VT_UI2
VT_I4
VT_UI4
VT_INT
VT_UINT
VT_R4
VT_R8
VT_CY
VT_DATE
VT_BSTR
VT_BOOL
VT_DECIMAL
VT_ERROR
VT_VARIANT
Wenn VT_VARIANT mit VT_ARRAY kombiniert wird, enthält safeArray selbst PROPVARIANT-Strukturen . Die Typen dieser Elemente müssen jedoch aus der vorherigen Liste entnommen werden, können nicht VT_VARIANT werden und dürfen nicht die Indikatoren VT_VECTOR, VT_ARRAY oder VT_BYREF enthalten.
IPropertyStorage-Methoden
Die Verbunddateiimplementierung von IPropertyStorage unterstützt die folgenden Methoden:
-
Liest die im rgpspec-Array angegebenen Eigenschaften und stellt die Werte aller gültigen Eigenschaften im rgvar-Array von PROPVARIANTs bereit. In der COM-Verbunddateiimplementierung führen doppelte Eigenschaftenbezeichner, die auf Datenstrom- oder Speichertypen verweisen, zu mehreren Aufrufen von IStorage::OpenStream oder IStorage::OpenStorage , und der Erfolg oder Fehler von ReadMultiple hängt von der Fähigkeit der zugrunde liegenden Speicherimplementierung ab, Öffnungsvorgänge gemeinsam zu nutzen. Da in einer zusammengesetzten Datei STGM_SHARE_EXCLUSIVE erzwungen wird, schlagen mehrere Geöffnete Versuche fehl. Das mehrmalsige Öffnen desselben Speicherobjekts aus demselben übergeordneten Speicher wird nicht unterstützt. Das flag STGM_SHARE_EXCLUSIVE muss angegeben werden.
Um einen threadsicheren Vorgang sicherzustellen, wenn dieselbe Stream- oder Speicherwerteigenschaft mehrmals über denselben IPropertyStorage-Zeiger in der COM-Verbunddateiimplementierung angefordert wird, ist der Öffnenvorgang erfolgreich oder schlägt fehl, je nachdem, ob die Eigenschaft bereits geöffnet ist und ob das zugrunde liegende Dateisystem mehrere Öffnungen eines Datenstroms oder Speichers verarbeitet. Daher führt der ReadMultiple-Vorgang für eine Stream- oder Speicherwerteigenschaft immer zu einem Aufruf von IStorage::OpenStream oder IStorage::OpenStorage, die den Zugriff (STGM_READWRITE usw.) und Freigabeflags (STGM_SHARE_EXCLUSIVE usw.) übergibt, die beim Öffnen oder Erstellen des ursprünglichen Eigenschaftensatzes angegeben wurden.
Wenn die Methode fehlschlägt, sind die in rgvar[] geschriebenen Werte nicht definiert. Wenn einige Stream- oder Speicherwerteigenschaften erfolgreich geöffnet wurden, aber vor Abschluss der Ausführung ein Fehler auftritt, sollten diese freigegeben werden, bevor die Methode zurückgibt.
-
Schreibt die im rgpspec[]-Array angegebenen Eigenschaften und weist ihnen die in rgvar[] angegebenen PROPVARIANT-Tags und -Werte zu. Eigenschaften, die bereits vorhanden sind, werden die angegebenen PROPVARIANT-Werte zugewiesen. Eigenschaften, die derzeit nicht vorhanden sind, werden erstellt.
-
Löscht die in rgpspec[] angegebenen Eigenschaften.
-
Liest vorhandene Zeichenfolgennamen, die den im rgpropid[]-Array angegebenen Eigenschafts-IDs zugeordnet sind.
-
Weist im rglpwstrName-Array angegebene Zeichenfolgennamen Eigenschaften-IDs zu, die im rgpropid-Array angegeben sind.
-
Löscht Eigenschaftennamen für die im rgpropid[]-Array angegebenen Eigenschaften.
-
Legt die CLSID des Eigenschaftensatzdatenstroms fest. In der Verbunddateiimplementierung legt das Festlegen der CLSID für einen nicht einfachen Eigenschaftssatz (einer, der rechtlich Speicher- oder Streamwerteigenschaften enthalten kann, wie in IPropertySetStorage::Create beschrieben) auch die CLSID für den zugrunde liegenden Unterspeicher fest, sodass sie über einen Aufruf von IStorage::Stat abgerufen werden kann.
-
Für einfache und nicht einfache Eigenschaftensätze wird das Eigenschaftssatz-Speicherimage auf den zugrunde liegenden Speicher geleert. Darüber hinaus führt diese Methode für nicht einfache Transacted-Mode-Eigenschaftensätze einen Commit (wie in IStorage::Commit) für den Speicher aus, der den Eigenschaftensatz enthält.
-
Ruft nur bei nicht einfachen Eigenschaftensätzen die Revert-Methode des zugrunde liegenden Speichers auf, und öffnet den "contents"-Stream erneut. Bei einfachen Eigenschaftensätzen gibt diese Schnittstelle immer S_OK zurück. Nicht einfache Eigenschaftensätze wurden mit dem PROPSETFLAG_NONSIMPLE-Flag in der IPropertySetStorage::Create-Methode erstellt. Weitere Informationen finden Sie unter Speicher- und Streamobjekte für einen Eigenschaftensatz .
-
Erstellt eine instance von IEnumSTATPROPSTG, dessen Methoden aufgerufen werden können, um die STATPROPSTG-Strukturen aufzulisten, die Informationen zu den einzelnen Eigenschaften in der Gruppe bereitstellen. Diese Implementierung erstellt ein Array, in das der gesamte Eigenschaftssatz gelesen wird und das freigegeben werden kann, wenn IEnumSTATPROPSTG::Clone aufgerufen wird. Änderungen am Eigenschaftensatz werden nicht in einem geöffneten IEnumSTATPROPSTG-instance widerspiegelt. Um solche Änderungen zu sehen, muss eine neue instance dieses Enumerators erstellt werden.
-
Füllt die Member einer STATPROPSETSTG-Struktur aus, die Daten über den Eigenschaftensatz als Ganzes enthält. Gibt bei der Rückgabe einen Zeiger auf die Struktur an. Bei nicht einfachen Speichersätzen ruft diese Implementierung IStorage::Stat (oder IStream::Stat) auf, um die Zeiten aus dem zugrunde liegenden Speicher oder Stream abzurufen. Bei einfachen Speichersätzen werden keine Zeiten beibehalten.
-
Legt nur für nicht einfache Eigenschaftensätze die vom zugrunde liegenden Speicher unterstützten Zeiten fest. Die Implementierung des zusammengesetzten Dateispeichers unterstützt alle drei: Änderung, Zugriff und Erstellung. Diese Implementierung von SetTimes ruft die IStorage::SetElementTimes-Methode des zugrunde liegenden Speichers auf, um diese Zeiten abzurufen.
Zugehörige Themen