PSCoerceToCanonicalValue-Funktion (propsys.h)

Artikel
03/06/2024

Konvertiert den Wert einer Eigenschaft gemäß der Eigenschaftenbeschreibung in den kanonischen Wert.

Syntax

PSSTDAPI PSCoerceToCanonicalValue(
  [in]      REFPROPERTYKEY key,
  [in, out] PROPVARIANT    *ppropvar
);

Parameter

[in] key

Typ: REFPROPERTYKEY

Verweis auf eine PROPERTYKEY-Struktur , die die Eigenschaft identifiziert, deren Wert umgewandelt werden soll.

[in, out] ppropvar

Typ: PROPVARIANT*

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

Rückgabewert

Typ: HRESULT

Folgende Rückgabewerte 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.
TYPE_E_TYPEMISMATCH	Die Umwandlung vom Typ des Werts zum Typ der Eigenschaftsbeschreibung war nicht möglich. Die PROPVARIANT-Struktur wurde gelöscht.
Beliebiger anderer Fehlercode	Die Umwandlung vom Typ des Werts zum Typ der Eigenschaftsbeschreibung war nicht möglich. Die PROPVARIANT-Struktur wurde gelöscht.

Hinweise

Diese Funktion ist ein Wrapper für die Systemimplementierung von IPropertyDescription::CoerceToCanonicalValue.

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 vom Typ VT_LPWSTR sein sollen. Diese Funktion wandelt Werte in diesen Typ um und wandelt das Ergebnis dann in eine kanonische Form um.

Es ist wichtig zu beachten, dass diese Funktion, wenn diese Funktion fehlschlägt, bereits PropVariantClear für die PROPVARIANT-Eingabestruktur aufgerufen hat. Nur wenn diese Funktion erfolgreich ist, ist die aufrufende Anwendung für den Aufruf von PropVariantClear auf ppropvar verantwortlich, wenn die Struktur nicht mehr benötigt wird.

Die von dieser Funktion ausgeführte Koersion wird auch vom Eigenschaftensystem während aufrufen von IPropertyStore::GetValue und IPropertyStore::SetValue ausgeführt. Anwendungen können entweder vom Eigenschaftensystem abhängig sein, um die Zwingungen auszuführen, oder sie können diese Funktion 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:

Die folgenden Werte werden in VT_EMPTY konvertiert.
- Werte vom Typ VT_NULL.
- Werte vom Typ VT_LPWSTR, VT_BSTR oder VT_LPSTR deren Zeiger NULL ist.
- Werte vom Typ VT_LPWSTR, VT_BSTR oder VT_LPSTR, die leer sind oder vollständig aus Leerzeichen bestehen.
- Werte vom Typ VT_FILETIME vor Mitternacht 1601/01/02.
Wenn der Wert nach Schritt 1 nicht vom Typ VT_EMPTY ist, wird er in den typ konvertiert, der in der Eigenschaftenbeschreibung angegeben ist. Der Typ einer Eigenschaftenbeschreibung kann durch Aufrufen von 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_BSTR oder VT_LPSTR werden in VT_VECTOR | VT_LPWSTR mit InitPropVariantFromStringAsVector.
- Alle anderen Konvertierungen werden mit PropVariantChangeType ausgeführt.

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 und nicht NULL. Beispiel: L"Alice". Wenn es sich um eine Struktureigenschaft handelt (das heißt, wenn das isTreeProperty-Attribut des typeInfo-ElementsTRUE ist), darf sie keine führenden oder nachgestellten Schrägstriche (/) aufweisen, darf keine Leerzeichen zwischen dem Text und den Schrägstrichen aufweisen und darf nicht über zwei aufeinander folgende Schrägstriche(/) verfügen. Beispiel: L"Friend/Bob". Die Erzwungenheit entfernt unnötige Zeichen und führt zu VT_EMPTY, wenn kein Inhalt vorhanden ist.
VT_VECTOR \| VT_LPWSTR	Jede Zeichenfolge im Vektor muss den oben aufgeführten Regeln für 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 ist L"Friend" ein Vorfahre von L"Friend/Bob". Wenn kein Inhalt vorhanden ist, entfernt die Nötigung doppelte Und Vorgängerzeichen und führt zu VT_EMPTY.

Falls zutreffend, wird der Wert anhand der Eigenschaftsbeschreibungstypenumeration überprüft. Die Überprüfungen in der folgenden Tabelle gelten.

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 im 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.

Beispiele

Im folgenden Beispiel, das als Teil eines größeren Programms eingeschlossen werden soll, wird veranschaulicht, wie SIE PSCoerceToCanonicalValue verwenden, um einen Wert in den für PKEY_Keywords erforderlichen Typ zu überzuverwenden.

// PROPVARIANT propvar;
// Assume variable propvar is initialized and valid.

HRESULT hr = PSCoerceToCanonicalValue(PKEY_Keywords, &propvar);

if (SUCCEEDED(hr))
{
    // The conversion succeeded and propvar now is of the correct type for 
    // PKEY_Keywords, or VT_EMPTY.
    PropVariantClear(&propvar);
}
else
{
    // The conversion failed and propvar is now VT_EMPTY.
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP mit SP2, Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 mit SP1 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	propsys.h
Bibliothek	Propsys.lib
DLL	Propsys.dll (Version 6.0 oder höher)
Verteilbare Komponente	Windows Desktop Search (WDS) 3.0