propVariantChangeType 函式 (propvarutil.h)
將儲存為 PROPVARIANT 結構的值強制轉換為不同變體類型的對等值。
語法
PSSTDAPI PropVariantChangeType(
[out] PROPVARIANT *ppropvarDest,
[in] REFPROPVARIANT propvarSrc,
[in] PROPVAR_CHANGE_FLAGS flags,
[in] VARTYPE vt
);
參數
[out] ppropvarDest
類型： PROPVARIANT*
PROPVARIANT 結構的指標，當此函式成功傳回時，會收到強制型別和其新型別。
[in] propvarSrc
類型： REFPROPVARIANT
來源 PROPVARIANT 結構的參考，其中包含以原始類型表示的值。
[in] flags
類型： PROPVAR_CHANGE_FLAGS
保留的 必須是 0。
[in] vt
類型： VARTYPE
指定 值的新型別。 如需辨識的類型名稱，請參閱下表。
傳回值
類型： HRESULT
如果成功，則傳回 S_OK ，否則傳回標準 COM 錯誤值。 如果無法要求強制型轉，則會傳回錯誤。
備註
請注意，來源和目的地 PROPVARIANT 結構必須是個別的結構。 您無法以新的目的地數據覆寫來源 PROPVARIANT 數據;嘗試這樣做會導致錯誤。
PropVariantChangeType 會轉換下列類型之間的值，如下所示。 數位是指數據表之後說明的條件。
| VT_LPWSTR | VT_BSTR | VT_BOOL | VT_FILETIME | VT_DATE | VT_CLSID | |
|---|---|---|---|---|---|---|
| VT_LPWSTR | Yes | Yes | Yes | 是 (2) | 是 (2) | Yes |
| VT_BSTR | Yes | Yes | Yes | 是 (2) | 是 (2) | Yes |
| VT_BOOL | Yes | Yes | 是 | No | No | No |
| VT_I2 | Yes | Yes | 是 | No | No | No |
| VT_I4 | Yes | Yes | 是 | No | No | No |
| VT_I8 | Yes | Yes | 是 | No | No | No |
| VT_UI2 | Yes | Yes | 是 | No | No | No |
| VT_UI4 | Yes | Yes | 是 | No | No | No |
| VT_UI8 | Yes | Yes | 是 | No | No | No |
| VT_R8 | 是 (3) | 是 (3) | 是 | No | No | No |
| VT_FILETIME | 是 (2) | 是 (2) | No | Yes | 是 | No |
| VT_DATE | 是 (2) | 是 (2) | No | Yes | 是 | No |
| VT_CLSID | Yes | 是 | No | No | No | Yes |
| VT_I2 | VT_I4 | VT_I8 | VT_UI2 | VT_UI4 | VT_UI8 | VT_R8 | |
|---|---|---|---|---|---|---|---|
| VT_LPWSTR | Yes | Yes | Yes | Yes | Yes | Yes | 是 (3) |
| VT_BSTR | Yes | Yes | Yes | Yes | Yes | Yes | 是 (3) |
| VT_BOOL | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| VT_I2 | Yes | Yes | Yes | 是 (1) | 是 (1) | 是 (1) | 是 (1) |
| VT_I4 | 是 (1) | Yes | Yes | 是 (1) | 是 (1) | 是 (1) | 是 (1) |
| VT_I8 | 是 (1) | 是 (1) | Yes | 是 (1) | 是 (1) | 是 (1) | 是 (1) |
| VT_UI2 | 是 (1) | Yes | Yes | Yes | Yes | Yes | 是 (1) |
| VT_UI4 | 是 (1) | 是 (1) | Yes | 是 (1) | Yes | Yes | 是 (1) |
| VT_UI8 | 是 (1) | 是 (1) | 是 (1) | 是 (1) | 是 (1) | Yes | 是 (1) |
| VT_R8 | 是 (1) | 是 (1) | 是 (1) | 是 (1) | 是 (1) | 是 (1) | Yes |
| VT_FILETIME | No | No | No | No | No | No | No |
| VT_DATE | No | No | No | No | No | No | No |
| VT_CLSID | No | No | No | No | No | No | No |
條件
- 在數值類型之間轉換時，超出範圍轉換會失敗。 例如，負數帶正負號值到不帶正負號的類型，或大於 65535 的 4 位元組不帶正負號值到 2 位元節不帶正負號的類型。
- 在字串和日期之間轉換時，會使用標準字串窗體，而不是當地語系化或「人類可讀」表示法。 格式為 「yyyy/mm/dd：hh：mm：ss.fff」 (年、月、日期、小時、分鐘、秒、毫秒) 。 請注意，這比 FILETIME 類型所支援的有效位數還低，但它應該足以用於大部分用途。
- 在浮點數與字串之間轉換時，會使用目前的地區設定小數分隔符。 請注意，當這些值儲存在不同的地區設定之間移動的檔案中時，這可能會造成問題。
注意 未來可能支援其他類型。
在型別之間執行強制轉換，而不需遵守屬性特定資訊。 應該使用 PSCoerceToCanonicalValue 來執行屬性特定的強制。 此外，如果UI用途需要值的字串格式， PSFormatForDisplay 應該用來根據地區設定和屬性特定資訊來格式化值，而不是使用 PropVariantChangeType 將值強制轉換成字元串。
範例
下列程式代碼範例會示範如何使用 PropVariantChangeType ，從字串初始化 VT_FILETIME 值。
PROPVARIANT propvarString = {0};
HRESULT hr = InitPropVariantFromString(L"2007/01/30:12:00:00.000", &propvarString);
if (SUCCEEDED(hr))
{
PROPVARIANT propvarFiletime = {0};
hr = PropVariantChangeType(&propvarFiletime, propvarString, 0, VT_FILETIME);
if (SUCCEEDED(hr))
{
// propvarFiletime now contains the FILETIME representation
// of 1/30/2007 12:00 PM
PropVariantClear(&propvarFiletime);
}
PropVariantClear(&propvarString);
}
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP 搭配 SP2、Windows Vista [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 SP1 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | propvarutil.h |
| 程式庫 | Propsys.lib |
| Dll | Propsys.dll (6.0 版或更新版本) |
| 可轉散發套件 | Windows 桌面搜尋 (WDS) 3.0 |