Metodo IPropertyDescription::CoerceToCanonicalValue (propsys.h)

Imposta il valore sul valore canonico, in base alla descrizione della proprietà.

Sintassi

HRESULT CoerceToCanonicalValue(
  [in, out] PROPVARIANT *ppropvar
);

Parametri

[in, out] ppropvar

Tipo: PROPVARIANT*

Nella voce contiene un puntatore a una struttura PROPVARIANT che contiene il valore originale. Quando termina, questo metodo contiene il valore canonico.

Valore restituito

Tipo: HRESULT

Se il codice di errore non è INPLACE_S_TRUNCATED o E_INVALIDARG, la coercizione dal tipo del valore al tipo della descrizione della proprietà non è stata possibile e la struttura PROPVARIANT è stata cancellata.

I risultati possibili includono quanto segue:

Commenti

Per altre informazioni, vedere l'attributo type dell'elemento typeInfo nel file propdesc della proprietà.

La maggior parte delle descrizioni delle proprietà specifica il tipo che i valori devono usare. Ad esempio, la descrizione della proprietà per System.Title specifica che i valori System.Title devono usare VT_LPWSTR. Questo metodo impone valori a questo tipo e imposta il risultato in una forma canonica.

È importante notare che se questo metodo ha esito negativo, avrà già chiamato PropVariantClear sulla struttura PROPVARIANT di input. Solo se questo metodo ha esito positivo è l'applicazione chiamante responsabile della chiamata di PropVariantClear su ppropvar quando la struttura non è più necessaria.

La coercizione eseguita da questo metodo viene eseguita anche dal sistema di proprietà durante le chiamate IPropertyStore::GetValue e IPropertyStore::SetValue . Le applicazioni possono dipendere dal sistema di proprietà per eseguire le coercizioni o possono usare questo metodo per eseguire la coercizione al momento della scelta dell'applicazione.

La coercizione viene eseguita in quattro passaggi, come indicato di seguito:

1. I valori seguenti vengono convertiti in VT_EMPTY.
   • Valori di tipo VT_NULL.
   • Valori di tipo VT_LPWSTR, VT_BSTRo VT_LPSTR il cui puntatore è NULL.
   • Valori di tipo VT_LPWSTR, VT_BSTRo VT_LPSTR vuoti o costituiti interamente da spazi.
   • Valori di tipo VT_FILETIME precedenti alla mezzanotte 1601/01/02.
2. Se il valore non è di tipo VT_EMPTY dopo il passaggio 1, viene convertito nel tipo specificato dalla descrizione della proprietà. Il tipo di descrizione di una proprietà può essere ottenuto usando IPropertyDescription::GetPropertyType. Per informazioni su come lo schema delle proprietà influisce sul tipo di descrizione di una proprietà, vedere typeInfo . Le conversioni vengono eseguite come segue:
   • I valori di tipo VT_LPWSTR, VT_BSTRo VT_LPSTR vengono convertiti in VT_VECTOR | VT_LPWSTR usando InitPropVariantFromStringAsVector.
   • Tutte le altre conversioni vengono eseguite usando PropVariantChangeType
3. Dopo i passaggi 2 e 3, il valore viene predefinito in una forma canonica in base al tipo. I moduli canonici sono riepilogati nella tabella seguente.

   Tipo di valore	Formato canonico
   VT_EMPTY	Sempre canonico.
   VT_LPWSTR	Nessuna spazi iniziale o finale. La stringa non è vuota. La stringa è non NULL. Ad esempio: L"Alice". Se si tratta di una proprietà dell'albero, ovvero se l'attributo dell'elemento isTreeProperty typeInfo è TRUE, non deve avere barre iniziali o finali (/), non deve avere spazi tra il testo e le barre e non deve avere due barre consecutive. Ad esempio: L"Friend/Bob" La coercizione rimuove i caratteri non necessari e genererà VT_EMPTY se non è presente alcun contenuto.
   VT_VECTOR | VT_LPWSTR	Ogni stringa nel vettore deve rispettare le regole elencate VT_LPWSTR in precedenza. Inoltre, il vettore non deve avere duplicati e non ha puntatori Null. Se si tratta di una proprietà albero, nessun valore può essere il predecessore di un altro valore. Ad esempio, L"Friend" è un predecessore di L"Friend/Bob". Se non è presente alcun contenuto, la coercizione rimuove i caratteri duplicati e predecessori e genererà VT_EMPTY.

    
4. Se applicabile, il valore viene controllato rispetto all'enumerazione del tipo di descrizione della proprietà. Si applicano i controlli seguenti.

   Tipo di enumerazione	Tipo di valore	Formato canonico
   Discreti o con intervallo	VT_EMPTY	Sempre canonico
   Discrete	VT_LPWSTR	La stringa corrisponde a una delle stringhe enumerate consentite per la proprietà . I confronti non fanno distinzione tra maiuscole e minuscole. In caso contrario, convertire il valore in VT_EMPTY.
   Discrete	Numeric	Il numero corrisponde a uno dei valori enumerati consentiti per la proprietà . In caso contrario, convertire il valore in VT_EMPTY.
   Discrete	VT_VECTOR | VT_LPWSTR	Ogni stringa nel vettore corrisponde a una delle stringhe enumerate consentite per la proprietà . I confronti non fanno distinzione tra maiuscole e minuscole. In caso contrario, rimuovere tale stringa dal vettore. Se il vettore risultante è vuoto, convertire il valore in VT_EMPTY.
   Discrete	VT_VECTOR | Numerico	Ogni numero nel vettore corrisponde a uno dei valori enumerati consentiti per la proprietà . In caso contrario, rimuovere tale numero dal vettore. Se il vettore risultante è vuoto, convertire il valore in VT_EMPTY.
   Variava	VT_LPWSTR	La stringa esiste nell'intervallo consentito per la proprietà . Nei confronti viene fatta distinzione tra maiuscole e minuscole. In caso contrario, convertire il valore in VT_EMPTY.
   Variava	Numeric	Il numero esiste nell'intervallo consentito per la proprietà . In caso contrario, convertire il valore in VT_EMPTY.
   Variava	VT_VECTOR | VT_LPWSTR	Ogni stringa nel vettore esiste nell'intervallo consentito per la proprietà . Nei confronti viene fatta distinzione tra maiuscole e minuscole. In caso contrario, rimuovere tale stringa dal vettore. Se il vettore risultante è vuoto, convertire il valore in VT_EMPTY.
   Variava	VT_VECTOR | Numerico	Ogni numero nel vettore esiste nell'intervallo consentito per la proprietà . In caso contrario, rimuovere tale numero dal vettore. Se il vettore risultante è vuoto, convertire il valore in VT_EMPTY.

    

Requisiti

Vedi anche

IPropertyDescription

Schema Descrizione proprietà