PropVariantToStringAlloc-Funktion (propvarutil.h)

Artikel
03/01/2024

Extrahiert einen Zeichenfolgeneigenschaftswert aus einer PROPVARIANT-Struktur .

Syntax

PSSTDAPI PropVariantToStringAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          *ppszOut
);

Parameter

[in] propvar

Typ: REFPROPVARIANT

Verweis auf eine PROPVARIANT-Quellstruktur .

[out] ppszOut

Typ: PWSTR*

Wenn diese Funktion zurückgibt, enthält einen Zeiger auf den extrahierten Eigenschaftswert, sofern vorhanden.

Rückgabewert

Typ: HRESULT

Wenn diese Funktion erfolgreich ist, gibt sie S_OK zurück. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Diese Hilfsfunktion wird an Stellen verwendet, an denen die aufrufende Anwendung erwartet, dass ein PROPVARIANT einen Zeichenfolgenwert enthält.

Wenn die Propvariant-Quelle den Typ VT_LPWSTR oder VT_BSTR aufweist, extrahiert diese Funktion die Zeichenfolge in einen neu zugewiesenen Puffer. Andernfalls wird versucht, den Wert in der PROPVARIANT-Struktur in eine Zeichenfolge zu konvertieren. Wenn eine Konvertierung nicht möglich ist, gibt PropVariantToStringAlloc einen Fehlercode zurück und legt ppszOut auf NULL fest. Eine Liste möglicher Konvertierungen finden Sie unter PropVariantChangeType . Beachten Sie, dass VT_EMPTY erfolgreich in einen zugeordneten Puffer konvertiert wurde, der "" enthält.

Die aufrufende Anwendung ist für die Verwendung von CoTaskMemFree verantwortlich, um die von ppszOut angezeigte Zeichenfolge freizugeben, wenn sie nicht mehr benötigt wird.

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

Vektorwert-PROPVARIANTs werden in Zeichenfolgen konvertiert, indem jedes Element mit "; " getrennt wird. PropVariantToStringAlloc konvertiert beispielsweise einen Vektor von 3 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

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

    // PropVariantToStringAlloc will convert VT_EMPTY to "".

    LPWSTR pszTitle;

    hr = PropVariantToString(propvar, &pszTitle);

    if (SUCCEEDED(hr))

    {

        // pszTitle is now valid

    }

    else

    {

        // pszTitle is always NULL

    }

    PropVariantClear(&propvar);

}

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