PropVariantToStringVector-Funktion (propvarutil.h)

Artikel
03/01/2024

Extrahiert einen Vektor von Zeichenfolgen aus einer PROPVARIANT-Struktur .

Syntax

PSSTDAPI PropVariantToStringVector(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          *prgsz,
  [in]  ULONG          crgsz,
  [out] ULONG          *pcElem
);

Parameter

[in] propvar

Typ: REFPROPVARIANT

Verweis auf eine PROPVARIANT-Quellstruktur .

[out] prgsz

Typ: PWSTR*

Zeiger auf einen Vektor von Zeichenfolgenzeigern. Wenn diese Funktion zurückgibt, wurde der Puffer mit pcElem-Elementen initialisiert, die auf neu zugeordnete Zeichenfolgen zeigen, die die aus der PROPVARIANT-Quelle extrahierten Daten enthalten.

[in] crgsz

Typ: ULONG

Größe des Puffers, auf den prgsz in -Elementen verweist.

[out] pcElem

Typ: ULONG*

Wenn diese Funktion zurückgibt, enthält die Anzahl der Zeichenfolgen, die aus der PROPVARIANT-Quellstruktur extrahiert wurden.

Rückgabewert

Typ: HRESULT

Diese Funktion kann einen dieser Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Gibt bei erfolgreicher Ausführung S_OK oder andernfalls einen Fehlerwert zurück.
TYPE_E_BUFFERTOOSMALL	DiePROPVARIANT-Quelle enthielt mehr als crgsz-Werte . Der Puffer, auf den prgsz verweist.
E_INVALIDARG	PropVARIANT war nicht vom geeigneten Typ.

Hinweise

Diese Hilfsfunktion wird an Stellen verwendet, an denen die aufrufende Anwendung erwartet, dass propVARIANT einen Vektor von Zeichenfolgenwerten mit einer festen Anzahl von Elementen enthält.

Diese Funktion funktioniert für die folgenden PROPVARIANT-Typen :

VT_VECTOR | VT_LPWSTR
VT_VECTOR | VT_BSTR
VT_ARRAY | VT_BSTR

Wenn der Propvariant-Quelltyp über einen unterstützten Typ verfügt, extrahiert diese Hilfsfunktion bis zu crgsz-Zeichenfolgenwerte und platziert eine zugeordnete Kopie von beiden in den Puffer, auf den prgsz verweist. Wenn PROPVARIANT mehr Elemente enthält, als in den prgsz-Puffer passen, gibt diese Funktion einen Fehler zurück und legt pcElem auf 0 fest.

Da jede Zeichenfolge in, auf die vom Ausgabepuffer verwiesen wird, neu zugeordnet wurde, ist die aufrufende Anwendung für die Verwendung von CoTaskMemFree verantwortlich, um jede Zeichenfolge im Ausgabepuffer freizugeben, wenn sie nicht mehr benötigt werden.

Wenn ein BSTR in der PROPVARIANT-QuelleNULL ist, wird er in eine neu zugeordnete Zeichenfolge konvertiert, die "" in der Ausgabe enthält.

Beispiele

// PROPVARIANT propvar;
// Assume the variable propvar is initialized and valid
LPWSTR rgszStrings; // The application is expecting propvar to hold 4 strings in a vector
ULONG cElems;
HRESULT hr = PropVariantToStringVector(propvar, rgszStrings, ARRAYSIZE(rgszStrings), &cElems);
if (SUCCEEDED(hr))
{
     if (cElems == ARRAYSIZE(rgszStrings))
     {
         // The application got 4 string which are now stored in rgszStrings
     }
     else
     {
         // The application got cElems which are stored in the first cElems elements of rgLongs
     }
 
    // Free the cElems strings that PropVariantToStringVector allocated
    for (ULONG i = 0; i < cElems; i++)
    {
        CoTaskMemFree(rgszStrings[i]);
    }
}

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