IPropertyDescription：：CoerceToCanonicalValue 方法 (propsys.h)

根據屬性描述，強制將值強制為標準值。

語法

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

[in, out] ppropvar

在專案上，包含包含原始值的 PROPVARIANT 結構的指標。當這個方法傳回時，會包含標準值。

類型： HRESULT

如果失敗碼未INPLACE_S_TRUNCATED或E_INVALIDARG，則無法從值的型別強制轉型為屬性描述的類型，而且已清除 PROPVARIANT 結構。

可能的結果包括：

傳回碼	描述
S_OK	此函數已成功。 ppropvar 指定的屬性值現在是標準形式。
INPLACE_S_TRUNCATED	ppropvar 指定的屬性值現在採用截斷、標準形式。
E_INVALIDARG	ppropvar 參數無效。已清除 PROPVARIANT 結構。

如需詳細資訊，請參閱屬性 .propdesc 檔案中 typeInfo 元素的類型屬性。

大部分的屬性描述都會指定其值預期使用的型別。例如， System.Title 的屬性描述會指定 System.Title 值應該使用 VT_LPWSTR。這個方法會將值強制轉換為這個類型，並將結果強制成標準形式。

請務必注意，如果這個方法失敗，它已經在輸入 PROPVARIANT 結構上呼叫 PropVariantClear。只有在此方法成功時，呼叫應用程式才負責在不再需要結構時呼叫 ppropvar 上的 PropVariantClear。

此方法所執行的強制型轉也會由屬性系統在 IPropertyStore：：GetValue 和 IPropertyStore：：SetValue 呼叫期間執行。應用程式可能會相依於屬性系統來執行強制型轉，或使用這個方法來在應用程式選擇時執行強制型轉。

強制型轉會以四個步驟執行，如下所示：

下列值會 VT_EMPTY轉換成。
- 類型的 VT_NULL值。
- 類型的 VT_LPWSTR, VT_BSTR值，或 VT_LPSTR 其指標為 NULL。
- 型 VT_LPWSTR, VT_BSTR別的值，或是 VT_LPSTR 空白或完全包含空格的值。
- 午夜 1601/01/02 之前的型 VT_FILETIME 別值。
如果值不是步驟 1 之後的類型 VT_EMPTY ，則會轉換成屬性描述所指定的類型。您可以使用 IPropertyDescription：：GetPropertyType 取得屬性描述的類型。如需屬性架構如何影響屬性描述類型的資訊，請參閱 typeInfo 。轉換的執行方式如下：
- 類型的VT_LPWSTR, VT_BSTR值，或 VT_LPSTR 會使用 InitPropVariantFromStringAsVector 轉換成 VT_VECTOR | VT_LPWSTR 。
- 所有其他轉換都是使用 PropVariantChangeType 來執行

在步驟 2 和 3 之後，值會根據其類型強制轉換成標準形式。下表摘要說明標準表單。

數值類型	標準表單
`VT_EMPTY`	一律是標準。
`VT_LPWSTR`	沒有前置或尾端空格。字串為非空白。字串為非 NULL。例如： `L"Alice"` 。如果這是樹狀結構屬性 (，也就是說，如果 typeInfo 元素的屬性 `isTreeProperty` 是 TRUE) ，則它不能有前置或尾端斜線 (/) 、文字與正斜線之間不能有空格，而且不能有兩個連續的正斜線 (/) 。例如，`L"Friend/Bob"` 強制會移除不必要的字元，如果沒有任何內容，則會產生 `VT_EMPTY` 。
`VT_VECTOR \| VT_LPWSTR`	向量中的每個字串都必須遵守上述的規則 `VT_LPWSTR` 。此外，向量不能有重複專案，而且沒有 Null 指標。如果這是樹狀結構屬性，則沒有任何值可以是另一個值的上階。例如， `L"Friend"` 是 L“Friend/Bob” 的上階。如果沒有內容，強制會移除重複和上階字元，並會導致 `VT_EMPTY`。

如果適用，則會根據屬性描述類型列舉來檢查值。下列檢查適用。

列舉類型	數值類型	標準表單
離散或範圍	`VT_EMPTY`	一律標準
Discrete	`VT_LPWSTR`	字串符合屬性允許的其中一個列舉字串。比較不區分大小寫。如果沒有，請將值 `VT_EMPTY`轉換成。
Discrete	數值	數位符合屬性允許的其中一個列舉值。如果沒有，請將值 `VT_EMPTY`轉換成。
Discrete	`VT_VECTOR \| VT_LPWSTR`	向量中的每個字串都符合屬性所允許的其中一個列舉字串。比較不區分大小寫。如果沒有，請從向量中移除該字串。如果產生的向量是空的，請將值 `VT_EMPTY`轉換為。
Discrete	`VT_VECTOR \|` 數位	向量中的每個數位都符合屬性所允許的其中一個列舉值。如果沒有，請從向量中移除該數位。如果產生的向量是空的，請將值 `VT_EMPTY`轉換為。
不等	`VT_LPWSTR`	字串存在於屬性允許的範圍中。比較會區分大小寫。如果沒有，請將值 `VT_EMPTY`轉換成。
不等	數值	數位存在於屬性允許的範圍中。如果沒有，請將值轉換成 VT_EMPTY。
不等	`VT_VECTOR \| VT_LPWSTR`	向量中的每個字串都存在於屬性允許的範圍中。比較會區分大小寫。如果沒有，請從向量中移除該字串。如果產生的向量是空的，請將值 `VT_EMPTY`轉換為。
不等	`VT_VECTOR` \|數位	向量中的每個數位都存在於屬性允許的範圍中。如果沒有，請從向量中移除該數位。如果產生的向量是空的，請將值轉換為VT_EMPTY。