PropVariantToStrRet-Funktion (propvarutil.h)

Artikel
03/01/2024

Extrahiert eine Zeichenfolge aus einer PROPVARIANT-Struktur und platziert sie in einer STRRET-Struktur .

Syntax

PSSTDAPI PropVariantToStrRet(
  [in]  REFPROPVARIANT propvar,
  [out] STRRET         *pstrret
);

Parameter

[in] propvar

Typ: REFPROPVARIANT

Verweis auf eine PROPVARIANT-Quellstruktur .

[out] pstrret

Typ: STRRET*

Zeigt auf die STRRET-Struktur . Wenn diese Funktion zurückgibt, wurde die Struktur initialisiert, um eine Kopie der extrahierten Zeichenfolge zu enthalten.

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 in Anwendungen verwendet, die einen Zeichenfolgenwert in einer PROPVARIANT-Struktur in eine STRRET-Struktur konvertieren möchten. Für instance kann eine Anwendung, die IShellFolder::GetDisplayNameOf implementiert, diese Funktion nützlich finden.

Wenn die Propvariant-Quelle den Typ VT_LPWSTR oder VT_BSTR hat, extrahiert diese Funktion die Zeichenfolge und platziert sie in der STRRET-Struktur . 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. Eine Liste möglicher Konvertierungen finden Sie unter PropVariantChangeType . Beachten Sie, dass VT_EMPTY erfolgreich in "" konvertiert wurde.

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

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

Wenn die Extraktion erfolgreich ist, initialisiert die Funktion das uType-Element der STRRET-Struktur mit STRRET_WSTR und legt das pOleStr-Element dieser Struktur so fest, dass er auf eine zugeordnete Kopie der Zeichenfolge verweist. Die aufrufende Anwendung ist für die Verwendung von CoTaskMemFree oder StrRetToStr verantwortlich, um diese Zeichenfolge frei zu geben, wenn sie nicht mehr benötigt wird.

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_FileName, &propvar);

if (SUCCEEDED(hr))

{

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

    // PropVariantToStrRet will convert VT_EMPTY to "".

    // If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET

    STRRET strName;

    hr = PropVariantToStrRet(propvar, &strName);

    if (SUCCEEDED(hr))

    {

        // strName is now valid

 

        if (strName.uType == STRRET_WSTR)

        {

            CoTaskMemFree(strName.pOleStr);

        }

    }

    else

    {

        // the extraction failed

    }

    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