Metodo IPropertyDescription::CoerceToCanonicalValue (propsys.h)

Articolo
03/05/2024

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:

Codice restituito	Descrizione
S_OK	Funzione completata. Il valore della proprietà specificato da ppropvar è ora in formato canonico.
INPLACE_S_TRUNCATED	Il valore della proprietà specificato da ppropvar è ora in formato canonico troncato.
E_INVALIDARG	Il parametro ppropvar non è valido. La struttura PROPVARIANT è stata cancellata.

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:

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.
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

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`.

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

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	propsys.h

Vedi anche

IPropertyDescription

Schema Descrizione proprietà

Condividi tramite