PropVariantGetStringElem-Funktion (propvarutil.h)

  • Artikel

Extrahiert ein einzelnes Unicode-Zeichenfolgenelement aus einer PROPVARIANT-Struktur vom Typ VT_LPWSTR, VT_BSTR, VT_VECTOR | VT_LPWSTR, VT_VECTOR | VT_BSTR oder VT_ARRAY | VT_BSTR.

Syntax

PSSTDAPI PropVariantGetStringElem(
  [in]  REFPROPVARIANT propvar,
  [in]  ULONG          iElem,
  [out] PWSTR          *ppszVal
);

Parameter

[in] propvar

Typ: REFPROPVARIANT

Verweis auf eine PROPVARIANT-Quellstruktur .

[in] iElem

Typ: ULONG

Der Vektor- oder Arrayindex; Andernfalls muss iElem 0 sein.

[out] ppszVal

Typ: PWSTR*

Wenn diese Funktion zurückgibt, enthält den extrahierten Zeichenfolgenwert. Die aufrufende Anwendung ist für das Freigeben dieser Zeichenfolge verantwortlich, indem Sie CoTaskMemFree aufruft, wenn sie nicht mehr benötigt wird.

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 funktioniert für PROPVARIANT-Strukturen der folgenden Typen:

  • VT_LPWSTR
  • VT_BSTR
  • VT_VECTOR | VT_LPWSTR
  • VT_VECTOR | VT_BSTR
  • VT_ARRAY | VT_BSTR
Wenn die Propvariant-Quelle den Typ VT_LPWSTR oder VT_BSTR hat, muss iElem 0 sein. Andernfalls muss iElem kleiner als die Anzahl der Elemente im Vektor oder Array sein. Sie können PropVariantGetElementCount verwenden, um die Anzahl der Elemente im Vektor oder Array abzurufen.

Wenn ein BSTR-Element über einen NULL-Zeiger verfügt, weist diese Funktion eine leere Zeichenfolge zu.

Beispiele

Im folgenden Codebeispiel, das als Teil eines größeren Programms eingeschlossen werden soll, wird veranschaulicht, wie PropVariantGetStringElem mit einer Iterationsanweisung verwendet wird, um auf die Werte in einem PROPVARIANT zuzugreifen.

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

if ((propvar.vt & VT_TYPEMASK) == VT_LPWSTR || (propvar.vt & VT_TYPEMASK) == VT_BSTR)
{
    UINT cElem = PropVariantGetElementCount(propvar);
    HRESULT hr = <mark type="const">S_OK</mark>;

    for (UINT iElem = 0; SUCCEEDED(hr) && iElem < cElem; iElem ++)
    {
        PWSTR pszValue;
        hr = PropVariantGetStringElem(propvar, iElem, &pszValue);

        if (SUCCEEDED(hr))
        {
            // pszValue is valid now
            CoTaskMemFree(pszValue);
        }
    }
}

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

PropVariantGetElem