PropVariantToStringVectorAlloc-Funktion (propvarutil.h)

Artikel
08/25/2023

Extrahiert Daten aus einer PROPVARIANT-Struktur in eine neu zugeordnete Zeichenfolge in einem neu zugeordneten Vektor.

Syntax

PSSTDAPI PropVariantToStringVectorAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          **pprgsz,
  [out] ULONG          *pcElem
);

Parameter

[in] propvar

Typ: REFPROPVARIANT

Verweis auf eine PROPVARIANT-Quellstruktur .

[out] pprgsz

Typ: PWSTR**

Wenn diese Funktion zurückgibt, enthält einen Zeiger auf einen Vektor von Zeichenfolgen, die aus der PROPVARIANT-Quellstruktur extrahiert wurden.

[out] pcElem

Typ: ULONG*

Wenn diese Funktion zurückgibt, enthält die Anzahl der Zeichenfolgenelemente, 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.
E_INVALIDARG	PropVARIANT war nicht vom geeigneten Typ.

Hinweise

Diese Hilfsfunktion wird an Stellen verwendet, an denen die aufrufende Anwendung erwartet, dass eine PROPVARIANT einen Vektor von Zeichenfolgenwerten enthält.

Diese Hilfsfunktion funktioniert für die folgendenPROPVARIANT-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 Funktion einen Vektor von Zeichenfolgenwerten in einen neu zugeordneten Vektor neu zugeordneter Zeichenfolgen. Die aufrufende Anwendung ist für die Verwendung von CoTaskMemFree verantwortlich, um sowohl die im Ausgabevektor enthaltenen Zeichenfolgen als auch den Ausgabevektor selbst freizugeben, wenn sie nicht mehr benötigt werden.

Wenn ein BSTR in der PROPVARIANT-QuelleNULL ist, platziert diese Funktion eine neu zugeordnete Zeichenfolge, die "" enthält, in den Ausgabevektor.

Beispiele

Im folgenden Beispiel, das als Teil eines größeren Programms eingeschlossen werden soll, wird veranschaulicht, wie PropVariantToStringVectorAlloc verwendet wird, um auf einen Zeichenfolgenvektorwert in einem PROPVARIANT zuzugreifen.

// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Keywords, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Keywords is expected to produce a VT_VECTOR | VT_LPWSTR, or VT_EMPTY
         // PropVariantToStringVectorAlloc will return an error for VT_EMPTY
         LPWSTR *prgKeywords;
         ULONG cElem;
         hr = PropVariantToStringVectorAlloc (propvar, &prgKeywords, &cElem);
         if (SUCCEEDED(hr))
         {
                 // prgKeywords contains cElem strings
                 for (ULONG i = 0; i < cElem; i++)
                 {
                          CoTaskMemFree(prgKeywords[i]);
                 }
                 CoTaskMemFree(prgKeywords);
         }
         else
         {
                 // propvar either is VT_EMPTY, or contains something other than a vector of  strings
         }
         PropVariantClear(&propvar);
}

Anforderungen


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