PropVariantToBSTR-Funktion (propvarutil.h)

Extrahiert den BSTR-Eigenschaftswert einer PROPVARIANT-Struktur .

Syntax

PSSTDAPI PropVariantToBSTR(
  [in]  REFPROPVARIANT propvar,
  [out] BSTR           *pbstrOut
);

Parameter

[in] propvar

Typ: REFPROPVARIANT

Verweis auf eine PROPVARIANT-Quellstruktur .

[out] pbstrOut

Typ: BSTR*

Zeiger auf den extrahierten Eigenschaftswert, sofern vorhanden; enthält andernfalls eine leere Zeichenfolge.

Rückgabewert

Typ: HRESULT

Wenn diese Funktion erfolgreich ist, wird S_OK zurückgegeben. 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_BSTR oder VT_LPWSTR aufweist, extrahiert diese Funktion die Zeichenfolge als BSTR-Wert . Andernfalls wird versucht, den Wert in der PROPVARIANT-Struktur in eine Zeichenfolge zu konvertieren. Wenn eine Konvertierung nicht möglich ist, gibt PropVariantToBSTR einen Fehlercode zurück und legt pbstrOut auf NULL fest. Eine Liste der möglichen Konvertierungen finden Sie unter PropVariantChangeType .

VT_EMPTY wurde erfolgreich in einen zugeordneten BSTR konvertiert, der "" enthält.

Die aufrufende Anwendung ist für die Verwendung von SysFreeString verantwortlich, um den BSTR freizugeben, auf den pbstrOut verweist, wenn es nicht mehr benötigt wird.

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

• Vektorwert-PROPVARIANTs werden in Zeichenfolgen konvertiert, indem jedes Element durch "; " getrennt wird. Beispielsweise konvertiert PropVariantToBSTR 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 über eine nicht unterstützte 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 PropVariantToBSTR für den Zugriff auf einen Zeichenfolgenwert in einem PROPVARIANT verwendet wird.

// IPropertyStore *ppropstore;
// Assume the 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.
    // PropVariantToBSTR will convert VT_EMPTY to "".
    BSTR bstrTitle;
    
    hr = PropVariantToBSTR(propvar, &bstrTitle);
    
    if (SUCCEEDED(hr))
    {
        // bstrTitle is now valid.
    }
    else
    {
        // bstrTitle 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

Weitere Informationen

InitPropVariantFromString

PropVariantGetStringElem

PropVariantToString

PropVariantToStringWithDefault