Funzione PSCoerceToCanonicalValue (propsys.h)

  • Articolo

Converte il valore di una proprietà nel valore canonico, in base alla descrizione della proprietà.

Sintassi

PSSTDAPI PSCoerceToCanonicalValue(
  [in]      REFPROPERTYKEY key,
  [in, out] PROPVARIANT    *ppropvar
);

Parametri

[in] key

Tipo: REFPROPERTYKEY

Riferimento a una struttura PROPERTYKEY che identifica la proprietà il cui valore deve essere coercito.

[in, out] ppropvar

Tipo: PROPVARIANT*

Nella voce contiene un puntatore a una struttura PROPVARIANT contenente il valore originale. Quando questa funzione restituisce correttamente, contiene il valore canonico.

Valore restituito

Tipo: HRESULT

I valori restituiti 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 una forma troncata e canonica.
E_INVALIDARG
 Il parametro ppropvar non è valido. La struttura PROPVARIANT è stata cancellata.
TYPE_E_TYPEMISMATCH
 La coercizione dal tipo del valore al tipo della descrizione della proprietà non era possibile. La struttura PROPVARIANT è stata cancellata.
Qualsiasi altro codice di errore
 La coercizione dal tipo del valore al tipo della descrizione della proprietà non era possibile. La struttura PROPVARIANT è stata cancellata.

Commenti

Questa funzione è un wrapper intorno all'implementazione del sistema di IPropertyDescription::CoerceToCanonicalValue.

La maggior parte delle descrizioni delle proprietà specifica il tipo previsto per l'uso dei valori. Ad esempio, la descrizione della proprietà per System.Title specifica che i valori System.Title devono essere di tipo VT_LPWSTR. Questa funzione coerce i valori di questo tipo e quindi coerce il risultato in una forma canonica.

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

La coercizione eseguita da questa funzione viene eseguita anche dal sistema delle proprietà durante le chiamate a IPropertyStore::GetValue e IPropertyStore::SetValue. Le applicazioni possono dipendere dal sistema delle proprietà per eseguire le coercioni o possono usare questa funzione per eseguire la coercizione alla volta della scelta dell'applicazione.

La coercizione viene eseguita in quattro passaggi, come segue:

  1. I valori seguenti vengono convertiti in VT_EMPTY.
    • Valori di tipo VT_NULL.
    • Valori di tipo VT_LPWSTR, VT_BSTR o VT_LPSTR il cui puntatore è NULL.
    • Valori di tipo VT_LPWSTR, VT_BSTR o VT_LPSTR vuoti o costituiti interamente da spazi.
    • Valori di tipo VT_FILETIME prima della 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 una descrizione della proprietà può essere ottenuto chiamando IPropertyDescription::GetPropertyType. Per informazioni su come lo schema delle proprietà influisce sul tipo di una descrizione della proprietà, vedere typeInfo. Le conversioni vengono eseguite come segue:
  3. Dopo i passaggi 2 e 3, il valore viene coercito in una forma canonica in base al relativo tipo. I moduli canonici sono riepilogati nella tabella seguente.
    Tipo di valore Modulo canonico
    VT_EMPTY Sempre canonica.
    VT_LPWSTR
    • Nessuna spazi iniziale o finale. La stringa non è vuota e non NULL. Ad esempio, L"Alice".
    • Se si tratta di una proprietà ad albero, ovvero se l'attributo isTreeProperty dell'elemento typeInfo è TRUE, non deve avere barre iniziali o finali (/), non deve avere spazi tra il testo e le barre in avanti e non deve avere due barre in avanti consecutive(/). Ad esempio, L"Friend/Bob".
    • La coercizione rimuove i caratteri non necessari e genera VT_EMPTY se non c'era contenuto.
    VT_VECTOR | VT_LPWSTR
    • Ogni stringa nel vettore deve rispettare le regole per VT_LPWSTR elencate sopra. Inoltre, il vettore non deve avere duplicati e non ha puntatori Null.
    • Se si tratta di una proprietà ad albero, nessun valore può essere il predecessore di un altro valore. Ad esempio, L"Friend" è un predecessore di L"Friend/Bob".
    • Se non c'è contenuto, la coercizione rimuove caratteri duplicati e predecessori e genera VT_EMPTY.
     
  4. Se applicabile, il valore viene controllato rispetto all'enumerazione del tipo di descrizione della proprietà. I controlli nella tabella seguente si applicano.
    Tipo di enumerazione Tipo di valore Modulo canonico
    Discreti o ranged VT_EMPTY Sempre canonico
    Discrete VT_LPWSTR La stringa corrisponde a una delle stringhe enumerate consentite per la proprietà. I confronti sono senza 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 sono senza 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.
     

Esempio

Nell'esempio seguente, da includere come parte di un programma più ampio, viene illustrato come usare PSCoerceToCanonicalValue per associare un valore al tipo richiesto per PKEY_Keywords.

// PROPVARIANT propvar;
// Assume variable propvar is initialized and valid.

HRESULT hr = PSCoerceToCanonicalValue(PKEY_Keywords, &propvar);

if (SUCCEEDED(hr))
{
    // The conversion succeeded and propvar now is of the correct type for 
    // PKEY_Keywords, or VT_EMPTY.
    PropVariantClear(&propvar);
}
else
{
    // The conversion failed and propvar is now VT_EMPTY.
}

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 propsys.h
Libreria Propsys.lib
DLL Propsys.dll (versione 6.0 o successiva)
Componente ridistribuibile Windows Desktop Search (WDS) 3.0

Vedi anche

IPropertyDescription

IShellItem2::GetPropertyStore

PropVariantChangeType

Schema Descrizione proprietà

Typeinfo