Funzione PropVariantToStringVector (propvarutil.h)

Articolo
03/05/2024

Estrae un vettore di stringhe da una struttura PROPVARIANT .

Sintassi

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

Parametri

[in] propvar

Tipo: REFPROPVARIANT

Riferimento a una struttura PROPVARIANT di origine.

[out] prgsz

Tipo: PWSTR*

Puntatore a un vettore di puntatori di stringa. Quando questa funzione restituisce, il buffer è stato inizializzato con elementi pcElem che puntano a stringhe appena allocate contenenti i dati estratti dall'origine PROPVARIANT.

[in] crgsz

Tipo: ULONG

Dimensioni del buffer puntate da prgsz, negli elementi.

[out] pcElem

Tipo: ULONG*

Quando questa funzione restituisce, contiene il conteggio delle stringhe estratte 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.
TYPE_E_BUFFERTOOSMALL	L'originePROPVARIANT contiene più dei valori crgsz . Buffer a cui punta il prgsz.
E_INVALIDARG	PropVARIANT non era del tipo appropriato.

Commenti

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

Questa funzione funziona per i tipi PROPVARIANT seguenti:

VT_VECTOR | VT_LPWSTR
VT_VECTOR | VT_BSTR
VT_ARRAY | VT_BSTR

Se l'origine PROPVARIANT ha un tipo supportato, questa funzione helper estrae fino a valori di stringa crgsz e inserisce una copia allocata di ognuno nel buffer a cui punta da prgsz . Se PROPVARIANT contiene più elementi che si adattano al buffer prgsz , questa funzione restituisce un errore e imposta pcElem su 0.

Poiché ogni stringa indicata dal buffer di output è stata appena allocata, l'applicazione chiamante è responsabile dell'uso di CoTaskMemFree per liberare ogni stringa nel buffer di output quando non sono più necessari.

Se un BSTR nell'origine PROPVARIANT è NULL, viene convertito in una stringa appena allocata contenente "" nell'output.

Esempio

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

Requisiti

Requisito	Valore
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