Funzione PropVariantToStringVectorAlloc (propvarutil.h)

Articolo
08/25/2023

Estrae i dati da una struttura PROPVARIANT in una nuova stringa allocata in un vettore appena allocato.

Sintassi

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

Parametri

[in] propvar

Tipo: REFPROPVARIANT

Riferimento a una struttura PROPVARIANT di origine.

[out] pprgsz

Tipo: PWSTR**

Quando questa funzione restituisce, contiene un puntatore a un vettore di stringhe estratte dalla struttura PROPVARIANT di origine.

[out] pcElem

Tipo: ULONG*

Quando questa funzione restituisce, contiene il conteggio degli elementi stringa estratti dalla struttura PROPVARIANT di origine.

Valore restituito

Tipo: HRESULT

Questa funzione può restituire uno di questi valori.

Codice restituito	Descrizione
S_OK	Restituisce S_OK se ha esito positivo o un valore di errore in caso contrario.
E_INVALIDARG	PropVARIANT non era del tipo appropriato.

Commenti

Questa funzione helper viene usata nelle posizioni in cui l'applicazione chiamante prevede che un PROPVARIANT contenga un vettore di valori stringa.

Questa funzione helper funziona per i tipiPROPVARIANT seguenti:

VT_VECTOR | VT_LPWSTR
VT_VECTOR | VT_BSTR
VT_ARRAY | VT_BSTR

Se l'origine PROPVARIANT ha un tipo supportato, questa funzione estrae un vettore di valori stringa in un vettore appena allocato di stringhe appena allocate. L'applicazione chiamante è responsabile dell'uso di CoTaskMemFree per rilasciare entrambe le stringhe contenute nel vettore di output e il vettore di output stesso, quando non sono più necessari.

Se un BSTR nell'origine PROPVARIANT è NULL, questa funzione inserisce una stringa appena allocata contenente "" nel vettore di output.

Esempio

Nell'esempio seguente, da includere come parte di un programma più ampio, viene illustrato come usare PropVariantToStringVectorAlloc per accedere a un valore vettore stringa in un PROPVARIANT.

// 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);
}

Requisiti


Client minimo supportato	Windows XP con SP2, Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2003 con SP1 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	propvarutil.h
Libreria	Propsys.lib
DLL	Propsys.dll (versione 6.0 o successiva)
Componente ridistribuibile	Windows Desktop Search (WDS) 3.0