IPropertyStorage-Compound Dateiimplementierung
Die COM-Implementierung der Strukturierten Speicherarchitektur wird zusammengesetzten Dateienbezeichnet. Speicherobjekte, die in Verbunddateien implementiert werden, umfassen eine Implementierung von IPropertyStorage, der Schnittstelle, die einen einzelnen beständigen Eigenschaftensatz verwaltet, und IPropertySetStorage, der Schnittstelle, die Gruppen persistenter Eigenschaftensätze verwaltet. Weitere Informationen zur IPropertyStorage Schnittstelle finden Sie unter IPropertyStorage und Überlegungen zum Eigenschaftenspeicher.
Um einen Zeiger auf die Verbunddateiimplementierung von IPropertyStorageabzurufen, rufen Sie StgCreateStorageEx auf, um ein neues verbunddateiobjekt zu erstellen, oder StgOpenStorageEx, um ein zuvor erstelltes Verbunddateiobjekt zu öffnen. Im Fall von StgCreateStorageExsollte der stgfmt Parameter auf STGFMT_STORAGE festgelegt werden. Im Fall von StgOpenStorageExsollte der stgfmt Parameter auf STGFMT_STORAGE oder STGFMT_ANY festgelegt werden. In beiden Fällen sollte der Parameter auf IID_IPropertySetStorage festgelegt werden. Beide Funktionen stellen einen Zeiger auf das Objekt IPropertySetStorage Schnittstelle bereit. Durch Aufrufen der Create oder Open-Methode dieser Schnittstelle erhalten Sie einen Zeiger auf die IPropertyStorage- Schnittstelle, die Sie zum Aufrufen einer der Methoden verwenden können.
Eine alternative Möglichkeit zum Abrufen eines Zeigers zur zusammengesetzten Dateiimplementierung von IPropertySetStorage- besteht darin, die älteren StgCreateDocfile- und StgOpenStorage--Funktionen aufzurufen, oder um einen riid Parameter von IID_IStorage an 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 headerdefinierten Namen für die IID_IPropertySetStorage der Schnittstellenbezeichner (IID) an.
Wann verwendet werden soll
Verwenden Sie IPropertyStorage-, um Eigenschaften innerhalb eines einzelnen Eigenschaftensatzes zu verwalten. Die Methoden unterstützen das Lesen, Schreiben und Löschen von Eigenschaften sowie die optionalen Zeichenfolgennamen, die Eigenschaftenbezeichnern zugeordnet werden können. Andere Methoden unterstützen den Standardmäßigen Commit und Wiederherstellen von Speichervorgängen. 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. Durch Aufrufen der Enum--Methode wird ein Zeiger auf die zusammengesetzte Dateiimplementierung von IEnumSTATPROPSTGangegeben, wodurch Sie die Eigenschaften im Satz aufzählen können.
Anmerkung
Wenn Sie einen Zeiger auf IPropertyStorage abrufen, indem Sie StgCreateDocfile-, StgCreateStorageEx, StgOpenStorage oder StgOpenStorageEx für einen Speicher für Eigenschaftensätze mit einfachem Modus aufrufen, die IPropertyStorage Methoden den Regeln von Datenströmen im einfachen Modus entsprechen. Der Eigenschaftensatzspeicher ist ein einfacher Modus, wenn er für eine Datei abgerufen wurde, die mit dem STGM_SIMPLE Flag erstellt oder geöffnet wurde. In diesem Fall ist es nicht immer möglich, den zugrunde liegenden Datenstrom zu vergrößern, und es ist nicht möglich, vorhandene Eigenschaften durch größere Eigenschaften zu ersetzen. Weitere Informationen finden Sie unter IPropertySetStorage-Compound Dateiimplementierung.
IPropertyStorage und Caching
Die zusammengesetzte Dateiimplementierung von IPropertyStorage zwischenspeichert offene Eigenschaftensätze im Arbeitsspeicher, um die Leistung zu verbessern. Daher werden Änderungen an einem Eigenschaftensatz erst in die Verbunddatei geschrieben, wenn die Methoden Commit oder Release (letzte Referenz) aufgerufen werden.
Simple Mode-Eigenschaftensätze
Ein Eigenschaftsspeicherobjekt befindet sich im einfachen Modus, wenn es aus einem Speicherobjekt für eigenschaftensätze im einfachen Modus erstellt wird. Ein Property Set-Speicherobjekt würde sich beispielsweise im einfachen Modus befinden, wenn es aus der StgOpenStorageEx--Funktion abgerufen wurde, wobei das im grfMode Parameter festgelegte STGM_SIMPLE Flag festgelegt ist. Beachten Sie, dass "einfacher Modus" nicht mit "einfachen Eigenschaftensätzen" verknüpft ist. Ein Eigenschaftensatz 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 unimplenten Eigenschaftensätzen finden Sie unter Storage- und Stream Objects for a Property Set.
Wenn ein Objekt für einfache Modus-Eigenschaftsspeicher erstellt wird, gibt es keine Einschränkungen für die Verwendung. Wenn ein vorhandenes Speicherobjekt für einfachen Modus-Eigenschaften geöffnet wird, kann das zugrunde liegende Datenstromobjekt, 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 Datenstrom erfordert.
Eigenschaftensatzformate
Die zusammengesetzte Dateiimplementierung von IPropertyStorage unterstützt sowohl die Serialisierungsformate der Version 0 als auch die Serialisierungsformate der Version 1. Das Format der Version 1 wird auf Computern unter Windows 2000 unterstützt. Weitere Informationen finden Sie unter Property Set Serialization. Eigenschaftensätze werden im Version 0-Format 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 PROPSETFLAG_DEFAULT-Flag erstellt wird, ist das Format Version 0. Solange Eigenschaftentypen, die dem Format der Version 0 entsprechen, in diesen Eigenschaftensatz geschrieben und gelesen werden, verbleibt der Eigenschaftensatz im Version 0-Format. Wenn ein Eigenschaftstyp der Version 1 in den Eigenschaftensatz geschrieben wird, wird der Eigenschaftensatz automatisch auf Version 1 aktualisiert. Anschließend kann dieser Eigenschaftensatz nicht mehr von Implementierungen gelesen werden, die nur Version 0 erkennen.
IPropertyStorage- und Variant-Typen
Die zusammengesetzte Dateiimplementierung 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. d. h. diese Werte können mit VT_ARRAY im vt Member der PROPVARIANT Struktur kombiniert werden.
Variant-Typen, die in SafeArray durch zusammengesetzte Dateiimplementierung 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 das 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 keine VT_VECTOR, VT_ARRAY oder VT_BYREF Indikatoren enthalten.
IPropertyStorage-Methoden
Die zusammengesetzte Dateiimplementierung 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 Eigenschaftsbezeichner, 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 zum Freigeben von Öffnungsvorgängen ab. Da in einer zusammengesetzten Datei STGM_SHARE_EXCLUSIVE erzwungen wird, schlagen mehrere geöffnete Versuche fehl. Das Öffnen desselben Speicherobjekts aus demselben übergeordneten Speicher wird nicht unterstützt. Das STGM_SHARE_EXCLUSIVE Flag muss angegeben werden.
Um einen threadsicheren Vorgang sicherzustellen, wenn dieselbe Stream- oder Speicherwerteigenschaft mehrmals über denselben IPropertyStorage Zeiger in der COM-Verbunddateiimplementierung angefordert wird, wird der Öffnenvorgang erfolgreich ausgeführt oder fehlschlagen, je nachdem, ob die Eigenschaft bereits geöffnet ist und ob das zugrunde liegende Dateisystem mehrere Öffnungen eines Datenstroms oder Speichers verarbeitet. Die ReadMultiple--Operation für eine Stream- oder Speicherwerteigenschaft führt daher immer zu einem Aufruf von IStorage::OpenStreamoder IStorage::OpenStorage, die den Zugriff (STGM_READWRITE usw.) übergibt und Flags (STGM_SHARE_EXCLUSIVE usw.) teilt, die angegeben wurden, wenn der ursprüngliche Eigenschaftensatz geöffnet oder erstellt wurde.
Wenn die Methode fehlschlägt, sind die Werte, die in rgvar-[] geschrieben wurden, nicht definiert. Wenn einige Datenstrom- oder Speicherwerteigenschaften erfolgreich geöffnet werden, aber ein Fehler auftritt, bevor die Ausführung abgeschlossen ist, sollten diese freigegeben werden, bevor die Methode zurückgegeben wird.
-
Schreibt die eigenschaften, die im rgpspec[] array angegeben sind, und weist ihnen die PROPVARIANT Tags und Werte zu, die in rgvar[] angegeben sind. Eigenschaften, die bereits vorhanden sind, werden den angegebenen PROPVARIANT- Werten zugewiesen. Eigenschaften, die derzeit nicht vorhanden sind, werden erstellt.
-
Löscht die in der rgpspec[].
-
Liest vorhandene Zeichenfolgennamen, die den Eigenschaften-IDs zugeordnet sind, die im rgpropid[] Array angegeben sind.
-
Weist Zeichenfolgennamen zu, die im rglpwstrName Array angegeben sind, eigenschaften-IDs, die im rgpropid Array angegeben sind.
-
Löscht Eigenschaftsnamen für die eigenschaften, die im rgpropid[] Array angegeben sind.
-
Legt die CLSID- des Eigenschaftensatzdatenstroms fest. In der Verbunddateiimplementierung legt das Festlegen der CLSID für einen nichtimplenten Eigenschaftensatz (eine, die rechtlich Speicher- oder Streamwerteigenschaften enthalten kann, wie in IPropertySetStorage::Create) auch die CLSID für den zugrunde liegenden Unterspeicher festgelegt, sodass sie über einen Aufruf von IStorage::Statabgerufen werden kann.
-
Leeren Sie für einfache und nicht einfache Eigenschaftensätze das Speicherbild für den Eigenschaftensatz auf den zugrunde liegenden Speicher. Darüber hinaus führt diese Methode für nicht implementierte Transacted-Mode-Eigenschaftensätze einen Commit (wie in IStorage::Commit) für den Speicher aus, der den Eigenschaftensatz enthält.
-
Ruft nur bei Nichtimple-Eigenschaftssätzen die Revert Methode des zugrunde liegenden Speichers auf und öffnet den "contents"-Datenstrom erneut. Bei einfachen Eigenschaftensätzen gibt diese Schnittstelle immer S_OK zurück. Nichtimple-Eigenschaftensätze sind solche, die mithilfe des PROPSETFLAG_NONSIMPLE Flags in der IPropertySetStorage::Create-Methode erstellt wurden. Weitere Informationen finden Sie unter Storage and Stream Objects for a Property Set .
-
Erstellt eine Instanz von IEnumSTATPROPSTG, deren Methoden aufgerufen werden können, um die STATPROPSTG- Strukturen auflisten, die Informationen zu den einzelnen Eigenschaften in der Gruppe bereitstellen. Diese Implementierung erstellt ein Array, in das der gesamte Eigenschaftensatz gelesen wird und freigegeben werden kann, wenn IEnumSTATPROPSTG::Clone aufgerufen wird. Änderungen am Eigenschaftensatz werden nicht in einer geöffneten IEnumSTATPROPSTG Instanz widerzuspiegeln. Um solche Änderungen anzuzeigen, muss eine neue Instanz dieses Enumerators erstellt werden.
-
Füllt die Elemente einer STATPROPSETSTG- Struktur aus, die Daten über den gesamten Eigenschaftensatz enthält. Gibt zurück einen Zeiger auf die Struktur an. Bei Nichtimple-Speichersätzen ruft diese Implementierung IStorage::Stat (oder IStream::Stat) auf, um die Zeiten aus dem zugrunde liegenden Speicher oder Datenstrom abzurufen. Für einfache Speichersätze werden keine Zeiten beibehalten.
-
Bei Nichtimple-Eigenschaftssätzen werden nur die vom zugrunde liegenden Speicher unterstützten Zeiten festgelegt. Die Zusammengesetzte Dateispeicherimplementierung 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.
Verwandte Themen