Funzione PropVariantChangeType (propvarutil.h)

Articolo
03/15/2023

Coerces un valore archiviato come struttura PROPVARIANT a un valore equivalente di un tipo variant diverso.

Sintassi

PSSTDAPI PropVariantChangeType(
  [out] PROPVARIANT          *ppropvarDest,
  [in]  REFPROPVARIANT       propvarSrc,
  [in]  PROPVAR_CHANGE_FLAGS flags,
  [in]  VARTYPE              vt
);

Parametri

[out] ppropvarDest

Tipo: PROPVARIANT*

Puntatore a una struttura PROPVARIANT che, quando questa funzione restituisce correttamente, riceve il valore coerced e il nuovo tipo.

[in] propvarSrc

Tipo: REFPROPVARIANT

Riferimento alla struttura PROPVARIANT di origine contenente il valore espresso come tipo originale.

[in] flags

Tipo: PROPVAR_CHANGE_FLAGS

Riservato, deve essere 0.

[in] vt

Tipo: VARTYPE

Specifica il nuovo tipo per il valore. Per i nomi dei tipi riconosciuti, vedere le tabelle seguenti.

Valore restituito

Tipo: HRESULT

Restituisce S_OK se ha esito positivo o un valore di errore COM standard in caso contrario. Se la coercizione richiesta non è possibile, viene restituito un errore.

Commenti

Si noti che le strutture PROPVARIANT di origine e destinazione devono essere strutture separate. Non è possibile sovrascrivere i dati PROPVARIANT di origine con i nuovi dati di destinazione; il tentativo di eseguire questa operazione comporta un errore.

PropVariantChangeType converte i valori tra i tipi seguenti come indicato di seguito. I numeri fanno riferimento alle condizioni descritte dopo le tabelle.

	VT_LPWSTR	VT_BSTR	VT_BOOL	VT_FILETIME	VT_DATE	VT_CLSID
VT_LPWSTR	Sì	Sì	Sì	Sì (2)	Sì (2)	Sì
VT_BSTR	Sì	Sì	Sì	Sì (2)	Sì (2)	Sì
VT_BOOL	Sì	Sì	Sì	No	No	No
VT_I2	Sì	Sì	Sì	No	No	No
VT_I4	Sì	Sì	Sì	No	No	No
VT_I8	Sì	Sì	Sì	No	No	No
VT_UI2	Sì	Sì	Sì	No	No	No
VT_UI4	Sì	Sì	Sì	No	No	No
VT_UI8	Sì	Sì	Sì	No	No	No
VT_R8	Sì (3)	Sì (3)	Sì	No	No	No
VT_FILETIME	Sì (2)	Sì (2)	No	Sì	Sì	No
VT_DATE	Sì (2)	Sì (2)	No	Sì	Sì	No
VT_CLSID	Sì	Sì	No	No	No	Sì

	VT_I2	VT_I4	VT_I8	VT_UI2	VT_UI4	VT_UI8	VT_R8
VT_LPWSTR	Sì	Sì	Sì	Sì	Sì	Sì	Sì (3)
VT_BSTR	Sì	Sì	Sì	Sì	Sì	Sì	Sì (3)
VT_BOOL	Sì	Sì	Sì	Sì	Sì	Sì	Sì
VT_I2	Sì	Sì	Sì	Sì (1)	Sì (1)	Sì (1)	Sì (1)
VT_I4	Sì (1)	Sì	Sì	Sì (1)	Sì (1)	Sì (1)	Sì (1)
VT_I8	Sì (1)	Sì (1)	Sì	Sì (1)	Sì (1)	Sì (1)	Sì (1)
VT_UI2	Sì (1)	Sì	Sì	Sì	Sì	Sì	Sì (1)
VT_UI4	Sì (1)	Sì (1)	Sì	Sì (1)	Sì	Sì	Sì (1)
VT_UI8	Sì (1)	Sì (1)	Sì (1)	Sì (1)	Sì (1)	Sì	Sì (1)
VT_R8	Sì (1)	Sì (1)	Sì (1)	Sì (1)	Sì (1)	Sì (1)	Sì
VT_FILETIME	No	No	No	No	No	No	No
VT_DATE	No	No	No	No	No	No	No
VT_CLSID	No	No	No	No	No	No	No

Condizioni

Quando si converte tra tipi numerici, le conversioni out-of-range hanno esito negativo. Ad esempio, un valore negativo firmato a un tipo senza segno o un valore senza segno a 4 byte maggiore di 65535 a un tipo senza segno 2 byte.
Quando si converte tra stringhe e date, viene usato un modulo stringa canonico anziché una rappresentazione localizzata o "leggibile". Il formato è "aaaa/mm/dd:hh:mm:ss.fff" (anno, mese, data, ore, minuti, secondi, millisecondi). Si noti che questa precisione è minore di quella supportata dal tipo FILETIME , ma deve essere sufficiente per la maggior parte dei fini.
Quando si converte tra numeri a virgola mobile e stringhe, viene usato il separatore decimale delle impostazioni locali correnti. Si noti che questo potrebbe causare problemi quando questi valori vengono salvati nei file spostati tra impostazioni locali diverse.

Nota Altri tipi potrebbero essere supportati in futuro.

La conversione tra vettori (VT_VECTOR) e matrici (VT_ARRAY) è supportata in alcuni casi. Quando è supportata, il conteggio degli elementi deve essere lo stesso in ogni. Un vettore con valore singolo può essere convertito in un valore non vettoriale, ma non è possibile convertire un vettore multivalore in un tipo non vettore.

La coercizione tra i tipi viene eseguita senza rispettare le informazioni specifiche della proprietà. Le coercioni specifiche della proprietà devono essere eseguite usando PSCoerceToCanonicalValue. Inoltre, se la forma stringa di un valore è necessaria per scopi dell'interfaccia utente, PSFormatForDisplay deve essere usata per formattare il valore in base alle impostazioni locali e alle informazioni specifiche della proprietà anziché usare PropVariantChangeType per coercire il valore in una stringa.

Esempio

L'esempio di codice seguente, da includere come parte di un programma più grande, illustra come usare PropVariantChangeType per inizializzare un valore VT_FILETIME da una stringa.

PROPVARIANT propvarString = {0};
                    
HRESULT hr = InitPropVariantFromString(L"2007/01/30:12:00:00.000", &propvarString);
if (SUCCEEDED(hr))
{
    PROPVARIANT propvarFiletime = {0};

    hr = PropVariantChangeType(&propvarFiletime, propvarString, 0, VT_FILETIME);
    if (SUCCEEDED(hr))
    {
        // propvarFiletime now contains the FILETIME representation 
        // of 1/30/2007 12:00 PM
        PropVariantClear(&propvarFiletime);
    }
    PropVariantClear(&propvarString);
}

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

Condividi tramite