共用方式為

PSCoerceToCanonicalValue 函式 (propsys.h)

  • 發行項

根據屬性描述，將屬性的值轉換為標準值。

語法

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

參數

[in] key

類型： REFPROPERTYKEY

PROPERTYKEY 結構的參考，這個結構會識別其值要強制轉型的屬性。

[in, out] ppropvar

類型： PROPVARIANT*

在專案上，包含包含原始值的 PROPVARIANT 結構的指標。 當此函式成功傳回時，會包含標準值。

傳回值

類型： HRESULT

可能的傳回值包括下列各項：

傳回碼 描述
S_OK
 此函數已成功。 ppropvar 指定的屬性值現在為標準格式。
INPLACE_S_TRUNCATED
 ppropvar 指定的屬性值現在是截斷的正式格式。
E_INVALIDARG
 ppropvar 參數無效。 已清除 PROPVARIANT 結構。
TYPE_E_TYPEMISMATCH
 無法從值的型別強制型別到屬性描述的類型。 已清除 PROPVARIANT 結構。
任何其他失敗碼
 無法從值的型別強制型別到屬性描述的類型。 已清除 PROPVARIANT 結構。

備註

此函式是系統 實作 IPropertyDescription：：CoerceToCanonicalValue 的包裝函式。

大部分的屬性描述都會指定預期使用其值的類型。 例如，System.Title 的屬性描述會指定 System.Title 值的類型應為 VT_LPWSTR。 此函式會將值強制轉換為此類型，然後將結果強制轉型為標準形式。

請務必注意，如果此函式失敗，則其已在輸入 PROPVARIANT 結構上呼叫 PropVariantClear。 只有當此函式成功時，才負責在不再需要結構時於 ppropvar 上呼叫 PropVariantClear 的呼叫應用程式。

呼叫 IPropertyStore：：GetValue 和 IPropertyStore：：SetValue 時，屬性系統也會執行此函式所執行的強制型轉。 應用程式可以相依於屬性系統來執行強制型轉，或使用此函式在應用程式選擇時執行強制型轉。

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

  1. 下列值會轉換成 VT_EMPTY。
    • 類型為 VT_NULL的值。
    • 類型為 NULL VT_LPWSTR、VT_BSTR或VT_LPSTR的值。
    • VT_LPWSTR、VT_BSTR或空白或完全由空格組成的VT_LPSTR類型的值。
    • VT_FILETIME午夜 1601/01/02 之前的類型值。
  2. 如果值的類型不是步驟 1 之後VT_EMPTY，則會轉換成屬性描述所指定的類型。 您可以呼叫 IPropertyDescription：：GetPropertyType 來取得屬性描述的類型。 如需屬性架構如何影響屬性描述類型的資訊，請參閱 typeInfo。 轉換的執行方式如下：
  3. 在步驟 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。
     
  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。
     

範例

下列範例要包含在較大的程式中，示範如何使用 PSCoerceToCanonicalValue 將值強制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.
}

規格需求

需求 值
最低支援的用戶端 Windows XP 搭配 SP2、Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 SP1 [僅限傳統型應用程式]
目標平台 Windows
標頭 propsys.h
程式庫 Propsys.lib
Dll Propsys.dll (6.0 版或更新版本)
可轉散發套件 Windows 桌面搜尋 (WDS) 3.0

另請參閱

IPropertyDescription

IShellItem2：：GetPropertyStore

PropVariantChangeType

屬性描述架構

typeInfo