IPropertyStorage::WriteMultiple-Methode (propidl.h)

Artikel
03/01/2024

Die WriteMultiple-Methode schreibt eine angegebene Gruppe von Eigenschaften in den aktuellen Eigenschaftensatz. Wenn eine Eigenschaft mit einem angegebenen Namen oder Eigenschaftenbezeichner bereits vorhanden ist, wird sie ersetzt, auch wenn sich der alte und der neue Typ für den Eigenschaftswert unterscheiden. Wenn eine Eigenschaft eines angegebenen Namens oder einer Eigenschaften-ID nicht vorhanden ist, wird sie erstellt.

Syntax

HRESULT WriteMultiple(
  [in] ULONG                cpspec,
  [in] const PROPSPEC []    rgpspec,
  [in] const PROPVARIANT [] rgpropvar,
  [in] PROPID               propidNameFirst
);

Parameter

[in] cpspec

Die Anzahl der festgelegten Eigenschaften. Der Wert dieses Parameters kann auf 0 (null) festgelegt werden. Dies verfehlt jedoch den Zweck der -Methode, da dann keine Eigenschaften geschrieben werden.

[in] rgpspec

Ein Array der Eigenschaften-IDs (PROPSPEC), auf die Eigenschaften festgelegt sind. Diese müssen keine bestimmte Reihenfolge aufweisen und können Duplikate enthalten, aber die zuletzt angegebene Eigenschafts-ID wird wirksam. Eine Mischung aus Eigenschafts-IDs und Zeichenfolgennamen ist zulässig.

[in] rgpropvar

Ein Array (mit der Größe cpspec) von PROPVARIANT-Strukturen , die die zu schreibenden Eigenschaftswerte enthalten. Das Array muss die von cpspec angegebene Größe aufweisen.

[in] propidNameFirst

Der Mindestwert für die Eigenschaften-IDs, die die Methode zuweisen muss, wenn der rgpspec-Parameter eigenschaften mit Zeichenfolgennamen angibt, für die derzeit keine Eigenschaften-IDs vorhanden sind. Wenn alle mit Zeichenfolgennamen angegebenen Eigenschaften bereits in diesem Satz vorhanden sind und daher bereits Über Eigenschaften-IDs verfügen, wird dieser Wert ignoriert. Wenn er nicht ignoriert wird, muss dieser Wert größer als oder gleich zwei und kleiner als 0x80000000 sein. Die Eigenschaften-IDs 0 und 1 und größer als 0x80000000 sind für besondere Zwecke reserviert.

Rückgabewert

Diese Methode unterstützt zusätzlich zu Folgendem den Standardrückgabewert E_UNEXPECTED:

Diese Funktion kann auch Dateisystemfehler oder Win32-Fehler zurückgeben, die in einen HRESULT-Datentyp umschlossen sind. Weitere Informationen finden Sie unter Strategien zur Fehlerbehandlung.

Hinweise

Wenn eine angegebene Eigenschaft bereits vorhanden ist, wird deren Wert durch den in rgpspec angegebenen ersetzt, auch wenn sich die alten und neuen Typen für den Eigenschaftswert unterscheiden. Wenn die angegebene Eigenschaft noch nicht vorhanden ist, wird diese Eigenschaft erstellt. Die Änderungen werden erst dann im zugrunde liegenden Speicher gespeichert, wenn IPropertyStorage::Commit aufgerufen wurde.

Eigenschaftennamen werden in einem speziellen Wörterbuchabschnitt des Eigenschaftensatzes gespeichert, der solche Namen Eigenschaften-IDs zuordnet. Alle Eigenschaften verfügen über eine ID, aber Namen sind optional. Ein Zeichenfolgenname wird bereitgestellt, indem PRSPEC_LPWSTR im ulKind-Member der PROPSPEC-Struktur angegeben wird. Wenn ein Zeichenfolgenname für eine Eigenschaft angegeben wird und der Name noch nicht im Wörterbuch vorhanden ist, weist die Methode eine Eigenschafts-ID zu und fügt dem Wörterbuch die Eigenschafts-ID und den Namen hinzu. Die Eigenschafts-ID wird so zugeordnet, dass sie nicht mit anderen IDs im Eigenschaftensatz in Konflikt steht. Der Wert der Eigenschafts-ID ist ebenfalls nicht kleiner als der vom propidNameFirst-Parameter angegebene Wert. Wenn der Parameter rgpspec Eigenschaften mit Zeichenfolgennamen angibt, für die derzeit keine Eigenschaften-IDs vorhanden sind, gibt der parameter propidNameFirst den Mindestwert für die Eigenschaften-IDs an, die die WriteMultiple-Methode zuweisen muss.

Wenn ein neuer Eigenschaftssatz erstellt wird, werden die speziellen Codepageeigenschaften (Eigenschafts-ID 1) und Gebietsschema-ID (Eigenschafts-ID 0x80000000) automatisch in den Eigenschaftensatz geschrieben. Diese Eigenschaften können anschließend mithilfe der IPropertyStorage::ReadMultiple-Methode gelesen werden, indem Eigenschaften-IDs mit den vom Header definierten PID_CODEPAGE bzw. PID_LOCALE-Werten angegeben werden. Wenn ein Eigenschaftensatz nicht leer ist – zusätzlich zu den Eigenschaften Codepage und Gebietsschema-ID über eine oder mehrere Eigenschaften verfügt oder einen oder mehrere Namen im Wörterbuch enthält – können die eigenschaften der speziellen Codepage und der Gebietsschema-ID nicht durch Aufrufen von IPropertyStorage::WriteMultiple geändert werden. Wenn der Eigenschaftensatz jedoch leer ist, können eine oder beide dieser speziellen Eigenschaften geändert werden.

Wenn ein Element im rgspec-Array mit dem PRSPEC_PROPID Wert 0xffffffff (PID_ILLEGAL) festgelegt wird, wird der entsprechende Wert im rgvar-Array von IPropertyStorage::WriteMultiple ignoriert. Wenn diese Methode beispielsweise aufgerufen wird, wobei der cspec-Parameter auf 3 festgelegt ist, aber rgpspec[1].prspec auf PRSPEC_PROPID und rgpspec[1].propid auf PID_ILLEGAL festgelegt ist, werden nur zwei Eigenschaften geschrieben. Das rgpropvar[1]- Element wird ignoriert.

Verwenden Sie das PropVariantInit-Makro , um PROPVARIANT-Strukturen zu initialisieren.

Eigenschaftensätze, die die Daten für nicht einfache Eigenschaften nicht einschließen, sind für Windows NT 4.0 und früher auf 256 KB beschränkt. Für Windows 2000, Windows XP und Windows Server 2003 sind OLE-Eigenschaftensätze auf 1 MB beschränkt. Wenn diese Grenzwerte überschritten werden, schlägt der Vorgang fehl, und der Aufrufer erhält eine Fehlermeldung. Es besteht keine Möglichkeit eines Speicherverlusts oder -überlaufs. Weitere Informationen finden Sie unter Verwalten von Eigenschaftensätzen.

Es sei denn, PROPSETFLAG_CASE_SENSITIVE an IPropertySetStorage::Create übergeben wird, wird bei Eigenschaftensatznamen die Groß-/Kleinschreibung nicht beachtet. Das Angeben einer Eigenschaft anhand ihres Namens in IPropertyStorage::WriteMultiple führt zu einer Suche der Namen im Eigenschaftensatz ohne Berücksichtigung der Groß-/Kleinschreibung. Um Zeichenfolgen ohne Beachtung der Groß-/Kleinschreibung zu vergleichen, muss das Gebietsschema der Zeichenfolgen bekannt sein. Weitere Informationen finden Sie unter IPropertyStorage::WritePropertyNames.

Weitere Informationen finden Sie unter Überlegungen zur Eigenschaftsspeicherung.

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	propidl.h (include Objbase.h, Propidlbase.h)
Bibliothek	Uuid.lib
DLL	Ole32.dll