Funzione PropVariantChangeType (propvarutil.h)

  • Articolo

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

  1. 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.
  2. 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.
  3. 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