IPropertyDescription::CoerceToCanonicalValue-Methode (propsys.h)

Wandelt den Wert gemäß der Eigenschaftenbeschreibung in den kanonischen Wert um.

Syntax

HRESULT CoerceToCanonicalValue(
  [in, out] PROPVARIANT *ppropvar
);

Parameter

[in, out] ppropvar

Typ: PROPVARIANT*

Enthält bei eintrag einen Zeiger auf eine PROPVARIANT-Struktur , die den ursprünglichen Wert enthält. Wenn diese Methode zurückgibt, enthält den kanonischen Wert.

Rückgabewert

Typ: HRESULT

Wenn der Fehlercode nicht INPLACE_S_TRUNCATED oder E_INVALIDARG ist, war die Umwandlung vom Typ des Werts zum Typ der Eigenschaftenbeschreibung nicht möglich, und die PROPVARIANT-Struktur wurde gelöscht.

Folgende Ergebnisse sind möglich:

Hinweise

Weitere Informationen finden Sie im Type-Attribut des typeInfo-Elements in der PROPDESC-Datei der Eigenschaft.

Die meisten Eigenschaftenbeschreibungen geben den Typ an, den ihre Werte verwenden sollen. Beispielsweise gibt die Eigenschaftenbeschreibung für System.Title an, dass System.Title-Werte verwenden VT_LPWSTRsollen. Mit dieser Methode werden Werte in diesen Typ umgewandelt und das Ergebnis in eine kanonische Form umgewandelt.

Es ist wichtig zu beachten, dass bei einem Fehlschlagen dieser Methode bereits propVariantClear für die PROPVARIANT-Eingabestruktur aufgerufen wurde. Nur wenn diese Methode erfolgreich ist, ist die aufrufende Anwendung für den Aufruf von PropVariantClear für ppropvar verantwortlich, wenn die Struktur nicht mehr benötigt wird.

Die von dieser Methode ausgeführte Coercion wird auch vom Eigenschaftensystem während IPropertyStore::GetValue - und IPropertyStore::SetValue-Aufrufen ausgeführt. Anwendungen können vom Eigenschaftensystem abhängig sein, um die Coercions auszuführen, oder sie können diese Methode verwenden, um die Koersion zu einem Zeitpunkt auszuführen, zu dem die Anwendung ausgewählt ist.

Die Nötigung erfolgt wie folgt in vier Schritten:

1. Die folgenden Werte werden in VT_EMPTYkonvertiert.
   • Werte vom Typ VT_NULL.
   • Werte vom Typ VT_LPWSTR, VT_BSTRoder VT_LPSTR deren Zeiger NULL ist.
   • Werte vom Typ VT_LPWSTR, VT_BSTR, die VT_LPSTR leer sind oder vollständig aus Leerzeichen bestehen.
   • Werte vom Typ VT_FILETIME vor Mitternacht 1601/01/02.
2. Wenn der Wert nach Schritt 1 nicht vom Typ VT_EMPTY ist, wird er in den in der Eigenschaftenbeschreibung angegebenen Typ konvertiert. Der Typ einer Eigenschaftenbeschreibung kann mit IPropertyDescription::GetPropertyType abgerufen werden. Informationen dazu, wie das Eigenschaftenschema den Typ einer Eigenschaftenbeschreibung beeinflusst, finden Sie unter typeInfo . Konvertierungen werden wie folgt ausgeführt:
   • Werte vom Typ VT_LPWSTR, VT_BSTRoder VT_LPSTR werden mithilfe von InitPropVariantFromStringAsVector in konvertiertVT_VECTOR | VT_LPWSTR.
   • Alle anderen Konvertierungen werden mit PropVariantChangeType ausgeführt.
3. Nach den Schritten 2 und 3 wird der Wert basierend auf seinem Typ in eine kanonische Form umgewandelt. Die kanonischen Formen sind in der folgenden Tabelle zusammengefasst.

   Werttyp	Kanonische Form
   VT_EMPTY	Immer kanonisch.
   VT_LPWSTR	Keine führenden oder nachgestellten Leerzeichen. Die Zeichenfolge ist nicht leer. Die Zeichenfolge ist nicht NULL. Beispiel: L"Alice". Wenn es sich um eine Struktureigenschaft handelt (das heißt, wenn das Attribut des isTreeProperty typeInfo-Elements TRUE ist), darf sie keine führenden oder nachgestellten Schrägstriche (/) aufweisen, darf keine Leerzeichen zwischen dem Text und den Schrägstrichen aufweisen und darf keine zwei aufeinander folgenden Schrägstriche(/) aufweisen. Zum Beispiel, L"Friend/Bob" Die Erzwungenheit entfernt unnötige Zeichen und führt dazu VT_EMPTY , wenn kein Inhalt vorhanden ist.
   VT_VECTOR | VT_LPWSTR	Jede Zeichenfolge im Vektor muss den oben aufgeführten Regeln VT_LPWSTR entsprechen. Darüber hinaus darf der Vektor keine Duplikate und keine NULL-Zeiger aufweisen. Wenn dies eine Struktureigenschaft ist, kann kein Wert der Vorgänger eines anderen Werts sein. Beispielsweise L"Friend" ist ein Vorfahre von L"Friend/Bob". Wenn kein Inhalt vorhanden ist, entfernt die Koersion Doppelte und Vorgängerzeichen und führt zu VT_EMPTY.

    
4. Falls zutreffend, wird der Wert anhand der Eigenschaftsbeschreibungstypenumeration überprüft. Es gelten die folgenden Überprüfungen.

   Enumerationstyp	Werttyp	Kanonische Form
   Diskret oder Ranged	VT_EMPTY	Immer kanonisch
   Discrete	VT_LPWSTR	Die Zeichenfolge entspricht einer der für die -Eigenschaft zulässigen enumerierten Zeichenfolgen. Bei den Vergleichen wird die Groß-/Kleinschreibung nicht beachtet. Wenn nicht, konvertieren Sie den Wert in VT_EMPTY.
   Discrete	Numeric	Die Zahl entspricht einem der für die -Eigenschaft zulässigen Enumerationswerte. Wenn nicht, konvertieren Sie den Wert in VT_EMPTY.
   Discrete	VT_VECTOR | VT_LPWSTR	Jede Zeichenfolge im Vektor entspricht einer der aufgelisteten Zeichenfolgen, die für die -Eigenschaft zulässig sind. Bei den Vergleichen wird die Groß-/Kleinschreibung nicht beachtet. Wenn nicht, entfernen Sie diese Zeichenfolge aus dem Vektor. Wenn der resultierende Vektor leer ist, konvertieren Sie den Wert in VT_EMPTY.
   Discrete	VT_VECTOR | Numerischen	Jede Zahl im Vektor entspricht einem der für die -Eigenschaft zulässigen Enumerationswerte. Wenn nicht, entfernen Sie diese Zahl aus dem Vektor. Wenn der resultierende Vektor leer ist, konvertieren Sie den Wert in VT_EMPTY.
   Reichten	VT_LPWSTR	Die Zeichenfolge befindet sich in dem bereich, der für die -Eigenschaft zulässig ist. Bei Vergleichen wird die Groß-/Kleinschreibung berücksichtigt. Wenn nicht, konvertieren Sie den Wert in VT_EMPTY.
   Reichten	Numeric	Die Zahl befindet sich in dem bereich, der für die -Eigenschaft zulässig ist. Wenn nicht, konvertieren Sie den Wert in VT_EMPTY.
   Reichten	VT_VECTOR | VT_LPWSTR	Jede Zeichenfolge im Vektor befindet sich in dem bereich, der für die -Eigenschaft zulässig ist. Bei Vergleichen wird die Groß-/Kleinschreibung berücksichtigt. Wenn nicht, entfernen Sie diese Zeichenfolge aus dem Vektor. Wenn der resultierende Vektor leer ist, konvertieren Sie den Wert in VT_EMPTY.
   Reichten	VT_VECTOR | Numerischen	Jede Zahl im Vektor befindet sich in dem Bereich, der für die -Eigenschaft zulässig ist. Wenn nicht, entfernen Sie diese Zahl aus dem Vektor. Wenn der resultierende Vektor leer ist, konvertieren Sie den Wert in VT_EMPTY.

    

Anforderungen

Weitere Informationen

IPropertyDescription

Eigenschaftenbeschreibungsschema