IPropertyDescription::CoerceToCanonicalValue-Methode (propsys.h)

  • Artikel

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:

Rückgabecode BESCHREIBUNG
S_OK
 Die Funktion wurde erfolgreich ausgeführt. Der von ppropvar angegebene Eigenschaftswert befindet sich jetzt in einer kanonischen Form.
INPLACE_S_TRUNCATED
 Der von ppropvar angegebene Eigenschaftswert befindet sich jetzt in einer abgeschnittenen kanonischen Form.
E_INVALIDARG
 Der ppropvar-Parameter ist ungültig. Die PROPVARIANT-Struktur wurde gelöscht.

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:
  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

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile propsys.h

Weitere Informationen

IPropertyDescription

Eigenschaftenbeschreibungsschema