Metodo IPropertyDescription::CoerceToCanonicalValue (propsys.h)

  • Articolo

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:

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

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à