Funzione PSCoerceToCanonicalValue (propsys.h)
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 |
|---|---|
|
Funzione completata. Il valore della proprietà specificato da ppropvar è ora in formato canonico. |
|
Il valore della proprietà specificato da ppropvar è ora in una forma troncata e canonica. |
|
Il parametro ppropvar non è valido. La struttura PROPVARIANT è stata cancellata. |
|
La coercizione dal tipo del valore al tipo della descrizione della proprietà non era possibile. La struttura PROPVARIANT è stata cancellata. |
|
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:
- 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.
- 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:
- I valori di tipo VT_LPWSTR, VT_BSTR o 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 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.
- 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 |