PropVariantToString-Funktion (propvarutil.h)

Artikel
08/25/2023

Extrahiert einen Zeichenfolgenwert aus einer PROPVARIANT-Struktur .

Syntax

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

Parameter

[in] propvar

Typ: REFPROPVARIANT

Verweis auf eine PROPVARIANT-Quellstruktur .

[out] psz

Typ: PWSTR

Verweist auf einen Zeichenfolgenpuffer. Wenn diese Funktion zurückgibt, wird der Puffer mit einem WERT für eine beendete Unicode-Zeichenfolge mit NULL initialisiert.

[in] cch

Typ: UINT

Größe des Puffers, auf den psz in Zeichen verweist.

Rückgabewert

Typ: HRESULT

Diese Funktion kann einen dieser Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Der Wert wurde extrahiert, und der Ergebnispuffer wurde NULL beendet.
STRSAFE_E_INSUFFICIENT_BUFFER	Fehler beim Kopiervorgang aufgrund unzureichenden Pufferspeicherplatzes. Der Zielpuffer enthält eine abgeschnittene, mit NULL beendete Version des beabsichtigten Ergebnisses. In Situationen, in denen das Abschneiden akzeptabel ist, kann dies nicht unbedingt als Fehlerbedingung angesehen werden.
Ein anderer Fehlerwert	Die Extraktion ist aus einem anderen Grund fehlgeschlagen.

Hinweise

Diese Hilfsfunktion wird an Stellen verwendet, an denen die aufrufende Anwendung erwartet, dass ein PROPVARIANT einen Zeichenfolgenwert enthält. Für instance kann eine Anwendung, die Werte aus einem Eigenschaftenspeicher erhält, dies verwenden, um einen Zeichenfolgenwert für Zeichenfolgeneigenschaften sicher zu extrahieren.

Wenn die PROPVARIANT-Quelle den Typ VT_LPWSTR oder VT_BSTR aufweist, extrahiert diese Funktion die Zeichenfolge und platziert sie im bereitgestellten Puffer. Andernfalls wird versucht, den Wert in der PROPVARIANT-Struktur in eine Zeichenfolge zu konvertieren. Wenn eine Konvertierung nicht möglich ist, gibt PropVariantToString einen Fehlercode zurück und legt psz auf "\0" fest. Eine Liste der möglichen Konvertierungen finden Sie unter PropVariantChangeType . Beachten Sie, dass VT_EMPTY erfolgreich in "" konvertiert wurde.

Zusätzlich zum beendenden NULL-Wert werden höchstens cch-1-Zeichen in den Puffer geschrieben, auf den psz verweist. Wenn der Wert in der PROPVARIANT-Quelle länger ist, als in den Puffer passt, wird eine abgeschnittene null terminated-Kopie der Zeichenfolge in den Puffer geschrieben, und diese Funktion gibt STRSAFE_E_INSUFFICIENT_BUFFER zurück. Die resultierende Zeichenfolge wird immer NULL beendet.

Zusätzlich zu den von PropVariantChangeType bereitgestellten Konvertierungen gelten die folgenden Sonderfälle für PropVariantToString.

PROPVARIANTmit Vektorwerten werden in Zeichenfolgen konvertiert, indem jedes Element durch "; " getrennt wird. Beispielsweise konvertiert PropVariantToString einen Vektor von drei ganzen Zahlen( {3, 1, 4}) in die Zeichenfolge "3; 1; 4". Das Semikolon ist unabhängig vom aktuellen Gebietsschema.
VT_BLOB-, VT_STREAM-, VT_STREAMED_OBJECT- und VT_UNKNOWN-Werte werden mithilfe einer nicht unterstützten Codierung in Zeichenfolgen konvertiert. Es ist nicht möglich, auf diese Weise erstellte Zeichenfolgen zu decodieren, und das Format kann sich in Zukunft ändern.

Beispiele

Im folgenden Beispiel, das als Teil eines größeren Programms eingeschlossen werden soll, wird veranschaulicht, wie PropVariantToString verwendet wird, um auf einen Zeichenfolgenwert in einem PROPVARIANT zuzugreifen.

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_Title, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    else

    {

        // the extraction failed

    }

    PropVariantClear(&propvar);

}

Anforderungen


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	propvarutil.h
Bibliothek	Propsys.lib
DLL	Propsys.dll (Version 6.0 oder höher)
Verteilbare Komponente	Windows Desktop Search (WDS) 3.0