Funzione PropVariantGetStringElem (propvarutil.h)

Articolo
03/09/2024

Estrae un singolo elemento stringa Unicode da una struttura PROPVARIANT di tipo VT_LPWSTR, VT_BSTR, VT_VECTOR | VT_LPWSTR, VT_VECTOR | VT_BSTR o VT_ARRAY | VT_BSTR.

Sintassi

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

Parametri

[in] propvar

Tipo: REFPROPVARIANT

Riferimento a una struttura PROPVARIANT di origine.

[in] iElem

Tipo: ULONG

Vettore o indice matrice; in caso contrario, iElem deve essere 0.

[out] ppszVal

Tipo: PWSTR*

Quando questa funzione viene restituita, contiene il valore stringa estratto. L'applicazione chiamante è responsabile della liberazione di questa stringa chiamando CoTaskMemFree quando non è più necessaria.

Valore restituito

Tipo: HRESULT

Se questa funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

Questa funzione helper funziona per le strutture PROPVARIANT dei tipi seguenti:

VT_LPWSTR
VT_BSTR
VT_VECTOR | VT_LPWSTR
VT_VECTOR | VT_BSTR
VT_ARRAY | VT_BSTR

Se l'origine PROPVARIANT ha tipo VT_LPWSTR o VT_BSTR, iElem deve essere 0. In caso contrario , iElem deve essere minore del numero di elementi nel vettore o nella matrice. È possibile usare PropVariantGetElementCount per ottenere il numero di elementi nel vettore o nella matrice.

Se un elemento BSTR ha un puntatore NULL , questa funzione alloca una stringa vuota.

Esempio

Nell'esempio di codice seguente, da includere come parte di un programma più ampio, viene illustrato come usare PropVariantGetStringElem con un'istruzione di iterazione per accedere ai valori in un PROPVARIANT.

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

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

Vedi anche

PropVariantGetElem

Condividi tramite