共用方式為


IPropertyDescription::CoerceToCanonicalValue 方法 (propsys.h)

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

語法

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

參數

[in, out] ppropvar

類型: PROPVARIANT*

在專案上,包含包含原始值的 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::GetValueIPropertyStore::SetValue 呼叫期間執行。 應用程式可能會相依於屬性系統來執行強制型轉,或使用這個方法來在應用程式選擇時執行強制型轉。

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

  1. 下列值會 VT_EMPTY轉換成 。
    • 類型的 VT_NULL值。
    • 類型的 VT_LPWSTR, VT_BSTR值,或 VT_LPSTR 其指標為 NULL
    • VT_LPWSTR, VT_BSTR別 的值,或是 VT_LPSTR 空白或完全包含空格的值。
    • 午夜 1601/01/02 之前的型 VT_FILETIME 別值。
  2. 如果值不是步驟 1 之後的類型 VT_EMPTY ,則會轉換成屬性描述所指定的類型。 您可以使用 IPropertyDescription::GetPropertyType 取得屬性描述的類型。 如需屬性架構如何影響屬性描述類型的資訊,請參閱 typeInfo 。 轉換的執行方式如下:
  3. 在步驟 2 和 3 之後,值會根據其類型強制轉換成標準形式。 下表摘要說明標準表單。
    數值類型 標準表單
    VT_EMPTY 一律是標準。
    VT_LPWSTR
    • 沒有前置或尾端空格。 字串為非空白。 字串為非 NULL。 例如: L"Alice"
    • 如果這是樹狀結構屬性 (,也就是說,如果 typeInfo 元素的屬性 isTreePropertyTRUE) ,則它不能有前置或尾端斜線 (/) 、文字與正斜線之間不能有空格,而且不能有兩個連續的正斜線 (/) 。 例如,L"Friend/Bob"
    • 強制會移除不必要的字元,如果沒有任何內容,則會產生 VT_EMPTY
    VT_VECTOR | VT_LPWSTR
    • 向量中的每個字串都必須遵守上述的規則 VT_LPWSTR 。 此外,向量不能有重複專案,而且沒有 Null 指標。
    • 如果這是樹狀結構屬性,則沒有任何值可以是另一個值的上階。 例如, L"Friend" 是 L“Friend/Bob” 的上階。
    • 如果沒有內容,強制會移除重複和上階字元,並會導致 VT_EMPTY
     
  4. 如果適用,則會根據屬性描述類型列舉來檢查值。 下列檢查適用。
    列舉類型 數值類型 標準表單
    離散或範圍 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。
     

規格需求

需求
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 propsys.h

另請參閱

IPropertyDescription

屬性描述架構