PROPVARIANT 結構 (propidl.h)
PROPVARIANT 結構用於 IPropertyStorage 的 ReadMultiple 和 WriteMultiple 方法中，以定義屬性集中的型別標記和屬性值。
IPropertyStore 的 GetValue 和 SetValue 方法也會使用 PROPVARIANT 結構，以取代 IPropertySetStorage 做為 Windows Vista 中程式專案屬性的主要方法。 如需詳細資訊，請參閱 屬性處理程式。
有五個成員。 第一個成員、實值型別標籤，以及屬性的值最後一個成員都是重要的。 中間三個成員會保留供日後使用。
語法
typedef struct tagPROPVARIANT {
union {
typedef struct {
VARTYPE vt;
PROPVAR_PAD1 wReserved1;
PROPVAR_PAD2 wReserved2;
PROPVAR_PAD3 wReserved3;
union {
CHAR cVal;
UCHAR bVal;
SHORT iVal;
USHORT uiVal;
LONG lVal;
ULONG ulVal;
INT intVal;
UINT uintVal;
LARGE_INTEGER hVal;
ULARGE_INTEGER uhVal;
FLOAT fltVal;
DOUBLE dblVal;
VARIANT_BOOL boolVal;
VARIANT_BOOL __OBSOLETE__VARIANT_BOOL;
SCODE scode;
CY cyVal;
DATE date;
FILETIME filetime;
CLSID *puuid;
CLIPDATA *pclipdata;
BSTR bstrVal;
BSTRBLOB bstrblobVal;
BLOB blob;
LPSTR pszVal;
LPWSTR pwszVal;
IUnknown *punkVal;
IDispatch *pdispVal;
IStream *pStream;
IStorage *pStorage;
LPVERSIONEDSTREAM pVersionedStream;
LPSAFEARRAY parray;
CAC cac;
CAUB caub;
CAI cai;
CAUI caui;
CAL cal;
CAUL caul;
CAH cah;
CAUH cauh;
CAFLT caflt;
CADBL cadbl;
CABOOL cabool;
CASCODE cascode;
CACY cacy;
CADATE cadate;
CAFILETIME cafiletime;
CACLSID cauuid;
CACLIPDATA caclipdata;
CABSTR cabstr;
CABSTRBLOB cabstrblob;
CALPSTR calpstr;
CALPWSTR calpwstr;
CAPROPVARIANT capropvar;
CHAR *pcVal;
UCHAR *pbVal;
SHORT *piVal;
USHORT *puiVal;
LONG *plVal;
ULONG *pulVal;
INT *pintVal;
UINT *puintVal;
FLOAT *pfltVal;
DOUBLE *pdblVal;
VARIANT_BOOL *pboolVal;
DECIMAL *pdecVal;
SCODE *pscode;
CY *pcyVal;
DATE *pdate;
BSTR *pbstrVal;
IUnknown **ppunkVal;
IDispatch **ppdispVal;
LPSAFEARRAY *pparray;
PROPVARIANT *pvarVal;
};
} tag_inner_PROPVARIANT, PROPVARIANT, *LPPROPVARIANT;
DECIMAL decVal;
};
} PROPVARIANT, *LPPROPVARIANT;
成員
tag_inner_PROPVARIANT
tag_inner_PROPVARIANT.vt
實值型別標記。
tag_inner_PROPVARIANT.wReserved1
保留供未來使用。
tag_inner_PROPVARIANT.wReserved2
保留供未來使用。
tag_inner_PROPVARIANT.wReserved3
保留供未來使用。
tag_inner_PROPVARIANT.cVal
VT_I1版本 1
tag_inner_PROPVARIANT.bVal
VT_UI1
tag_inner_PROPVARIANT.iVal
VT_I2
tag_inner_PROPVARIANT.uiVal
VT_UI2
tag_inner_PROPVARIANT.lVal
VT_I4
tag_inner_PROPVARIANT.ulVal
VT_UI4
tag_inner_PROPVARIANT.intVal
VT_INT版本 1
tag_inner_PROPVARIANT.uintVal
VT_UINT版本 1
tag_inner_PROPVARIANT.hVal
VT_I8
tag_inner_PROPVARIANT.uhVal
VT_UI8
tag_inner_PROPVARIANT.fltVal
VT_R4
tag_inner_PROPVARIANT.dblVal
VT_R8
tag_inner_PROPVARIANT.boolVal
VT_BOOL
tag_inner_PROPVARIANT.__OBSOLETE__VARIANT_BOOL
tag_inner_PROPVARIANT.scode
VT_ERROR
tag_inner_PROPVARIANT.cyVal
VT_CY
tag_inner_PROPVARIANT.date
VT_DATE
tag_inner_PROPVARIANT.filetime
VT_FILETIME
tag_inner_PROPVARIANT.puuid
VT_CLSID
tag_inner_PROPVARIANT.pclipdata
VT_CF
tag_inner_PROPVARIANT.bstrVal
VT_BSTR
tag_inner_PROPVARIANT.bstrblobVal
VT_BSTR_BLOB
tag_inner_PROPVARIANT.blob
VT_BLOB、 VT_BLOBOBJECT
tag_inner_PROPVARIANT.pszVal
VT_LPSTR
tag_inner_PROPVARIANT.pwszVal
VT_LPWSTR
tag_inner_PROPVARIANT.punkVal
VT_UNKNOWN
tag_inner_PROPVARIANT.pdispVal
VT_DISPATCH版本 1
tag_inner_PROPVARIANT.pStream
VT_STREAM，VT_STREAMED_OBJECT
tag_inner_PROPVARIANT.pStorage
VT_STORAGE、 VT_STORED_OBJECT
tag_inner_PROPVARIANT.pVersionedStream
VT_VERSIONED_STREAM
tag_inner_PROPVARIANT.parray
VT_ARRAY | VT_*，版本 1
tag_inner_PROPVARIANT.cac
VT_VECTOR | VT_I1版本 1
tag_inner_PROPVARIANT.caub
VT_VECTOR | VT_UI1
tag_inner_PROPVARIANT.cai
VT_VECTOR | VT_I2
tag_inner_PROPVARIANT.caui
VT_VECTOR | VT_UI2
tag_inner_PROPVARIANT.cal
VT_VECTOR | VT_I4
tag_inner_PROPVARIANT.caul
VT_VECTOR | VT_UI4
tag_inner_PROPVARIANT.cah
VT_VECTOR | VT_I8
tag_inner_PROPVARIANT.cauh
VT_VECTOR | VT_UI8
tag_inner_PROPVARIANT.caflt
VT_VECTOR | VT_R4
tag_inner_PROPVARIANT.cadbl
VT_VECTOR | VT_R8
tag_inner_PROPVARIANT.cabool
VT_VECTOR | VT_BOOL
tag_inner_PROPVARIANT.cascode
VT_VECTOR | VT_ERROR
tag_inner_PROPVARIANT.cacy
VT_VECTOR | VT_CY
tag_inner_PROPVARIANT.cadate
VT_VECTOR | VT_DATE
tag_inner_PROPVARIANT.cafiletime
VT_VECTOR | VT_FILETIME
tag_inner_PROPVARIANT.cauuid
VT_VECTOR | VT_CLSID
tag_inner_PROPVARIANT.caclipdata
VT_VECTOR | VT_CF
tag_inner_PROPVARIANT.cabstr
VT_VECTOR | VT_BSTR
tag_inner_PROPVARIANT.cabstrblob
VT_VECTOR | VT_BSTR
tag_inner_PROPVARIANT.calpstr
VT_VECTOR | VT_LPSTR
tag_inner_PROPVARIANT.calpwstr
VT_VECTOR | VT_LPWSTR
tag_inner_PROPVARIANT.capropvar
VT_VECTOR | VT_VARIANT
tag_inner_PROPVARIANT.pcVal
| VT_BYREFVT_I1版本 1
tag_inner_PROPVARIANT.pbVal
| VT_BYREFVT_UI1版本 1
tag_inner_PROPVARIANT.piVal
| VT_BYREFVT_I2版本 1
tag_inner_PROPVARIANT.puiVal
| VT_BYREFVT_UI2版本 1
tag_inner_PROPVARIANT.plVal
| VT_BYREFVT_I4版本 1
tag_inner_PROPVARIANT.pulVal
| VT_BYREFVT_UI4版本 1
tag_inner_PROPVARIANT.pintVal
| VT_BYREFVT_INT版本 1
tag_inner_PROPVARIANT.puintVal
| VT_BYREFVT_UINT版本 1
tag_inner_PROPVARIANT.pfltVal
| VT_BYREFVT_R4版本 1
tag_inner_PROPVARIANT.pdblVal
| VT_BYREFVT_R8版本 1
tag_inner_PROPVARIANT.pboolVal
| VT_BYREFVT_R8版本 1
tag_inner_PROPVARIANT.pdecVal
| VT_BYREFVT_DECIMAL版本 1
tag_inner_PROPVARIANT.pscode
| VT_BYREFVT_ERROR版本 1
tag_inner_PROPVARIANT.pcyVal
| VT_BYREFVT_CY版本 1
tag_inner_PROPVARIANT.pdate
| VT_BYREFVT_DATE版本 1
tag_inner_PROPVARIANT.pbstrVal
| VT_BYREFVT_BSTR版本 1
tag_inner_PROPVARIANT.ppunkVal
| VT_BYREFVT_UNKNOWN版本 1
tag_inner_PROPVARIANT.ppdispVal
| VT_BYREFVT_DISPATCH版本 1
tag_inner_PROPVARIANT.pparray
| VT_BYREFVT_DISPATCH版本 1
tag_inner_PROPVARIANT.pvarVal
| VT_BYREFVT_VARIANT版本 1
decVal
| VT_BYREFVT_DECIMAL版本 1
備註
PROPVARIANT 結構也可以保存值VT_DECIMAL：
DECIMAL decVal; //VT_DECIMAL
不過， DECIMAL 結構的值需要特殊處理。 DECIMAL 結構的大小與整個 PROPVARIANT 結構相同，而且不符合保留所有其他值類型的等位。 相反地， DECIMAL 結構的值會佔用整個 PROPVARIANT 結構，包括保留的欄位和 vt 成員。 不過，不會使用 DECIMAL 結構的第一個成員，而且大小等於 PROPVARIANT 結構的 vt 成員。 因此，Win32 之 Propidl.h 頭檔中的 PROPVARIANT 結構宣告會以對應至 PROPVARIANT 結構的開頭的方式定義 decVal 成員。 因此，若要將 DECIMAL 結構的值放入 PROPVARIANT 結構中，值必須載入 decVal 成員，且 vt 成員設定為 VT_DECIMAL，就如同任何其他值一樣。
PROPVARIANT 是透過 IPropertyStorage 介面讀取和寫入屬性值的基本數據類型。
數據類型 PROPVARIANT 與在 OLE2 中定義為自動化一部分的數據類型 VARIANT 相關。 從自動化重複使用數個定義，如下所示：
typedef struct tagCY {
unsigned long Lo;
long Hi;
} CY;
typedef struct tagDEC {
USHORT wReserved;
BYTE scale;
BYTE sign;
ULONG Hi32;
ULONGLONG Lo64;
} DECIMAL;
typedef struct tagSAFEARRAYBOUND {
ULONG cElements;
LONG lLbound;
} SAFEARRAYBOUND;
typedef struct tagSAFEARRAY {
USHORT cDims;
USHORT fFeatures;
ULONG cbElements;
ULONG cLocks;
PVOID pvData;
SAFEARRAYBOUND rgsabound [ * ];
} SAFEARRAY;
typedef CY CURRENCY;
typedef short VARIANT_BOOL;
typedef unsigned short VARTYPE;
typedef double DATE;
typedef OLECHAR* BSTR;
此外，某些類型對 PROPVARIANT 結構而言是唯一的：
typedef struct tagCLIPDATA {
// cbSize is the size of the buffer pointed to
// by pClipData, plus sizeof(ulClipFmt)
ULONG cbSize;
long ulClipFmt;
BYTE* pClipData;
} CLIPDATA;
唯一 的 PROPVARIANT 類型有數種數據類型，可定義其他數據類型的計數數位。 所有計算數位的數據類型都是以字母 CA 開頭，例如 CAUB，並且具有 OR 運算符 vt 值， (元素的 VarType 以及具有 VT_VECTOR) 的 OR 運算符。 計算數位結構的格式如下 (，其中 name 是計算數位的特定名稱) 。
#define TYPEDEF_CA(type, name)
typedef struct tag ## name {\
ULONG cElems;\
type *pElems;\
} name
| Propvariant 類型 | 程式碼 | Propvariant 成員 | 值表示法 |
|---|---|---|---|
| VT_EMPTY | 0 | 無 | 具有 類型指標VT_EMPTY 的屬性沒有與其相關聯的數據;也就是說，值的大小為零。 |
| VT_NULL | 1 | 無 | 這就像是 NULL 的指標。 |
| VT_I1 | 16 | cVal | 1 位元組帶正負號的整數。 |
| VT_UI1 | 17 | bVal | 1 位元組無符號整數。 |
| VT_I2 | 2 | iVal | 兩個字節，表示 2 位元組帶正負號的整數值。 |
| VT_UI2 | 18 | uiVal | 2 位元組無符號整數。 |
| VT_I4 | 3 | lVal | 4 位元組帶正負號的整數值。 |
| VT_UI4 | 19 | ulVal | 4 位元組無符號整數。 |
| VT_INT | 22 | intVal | 4 位元組帶正負號的整數值 (等於 VT_I4) 。 |
| VT_UINT | 23 | uintVal | 4 位元組無符號整數 (相當於 VT_UI4) 。 |
| VT_I8 | 20 | hVal | 8 位元組帶正負號的整數。 |
| VT_UI8 | 21 | uhVal | 8 位元組無符號整數。 |
| VT_R4 | 4 | fltVal | 32 位 IEEE 浮點值。 |
| VT_R8 | 5 | dblVal | 64 位 IEEE 浮點值。 |
| VT_BOOL | 11 | boolVal (舊版設計 中的bool) | 布爾值，包含 0 (FALSE) 或 -1 (TRUE) 的 WORD。 |
| VT_ERROR | 10 | scode | 包含狀態代碼的 DWORD 。 |
| VT_CY | 6 | cyVal | 8 位元組二的補碼整數 (縮放為10,000) 。 此類型通常用於貨幣金額。 |
| VT_DATE | 7 | date | 64 位浮點數，代表自 1899 年 12 月 31 日起， (不是秒數) 的天數。 例如，1900 年 1 月 1 日是 2.0、1900 年 1 月 2 日、3.0，依此類) 。 這會儲存在 與VT_R8相同的表示法中。 |
| VT_FILETIME | 64 | filetime | Win32 所定義的 64 位 FILETIME 結構。 建議所有時間都儲存在通用座標時間 (UTC) 。 |
| VT_CLSID | 72 | puuid | CLSID) (或其他全域唯一標識碼 (GUID) ) 的類別標識碼指標 (。 |
| VT_CF | 71 | pclipdata | 上述 CLIPDATA 結構的指標。 |
| VT_BSTR | 8 | bstrVal | Null 終止 Unicode 字串的指標。 字串緊接在代表位元組計數的 DWORD 前面，但 bstrVal 會將這個 DWORD 指向字串的第一個字元。 BSTR必須使用 Automation SysAllocString 和 SysFreeString 呼叫來配置和釋放。 |
| VT_BSTR_BLOB | 0xfff | bstrblobVal | 僅供系統使用。 |
| VT_BLOB | 65 | Blob | 位元組的 DWORD 計數，後面接著該多位元組的數據。 位元組計數不包含計數本身長度的四個字節;空 的 Blob 成員計數為零，後面接著零個字節。 這類似於 值VT_BSTR，但不保證數據結尾的 null 位元組。 |
| VT_BLOBOBJECT | 70 | Blob |
Blob 成員，包含相同表示法中出現的串行化物件VT_STREAMED_OBJECT。 也就是說， DWORD 位元組計數 (其中位元組計數不包含本身的大小) 其格式為類別標識符，後面接著該類別的初始化數據。
VT_BLOB_OBJECT與VT_STREAMED_OBJECT之間的唯一顯著差異在於，前者沒有後者會有的系統層級儲存額外負荷，因此更適合涉及小型物件的案例。 |
| VT_LPSTR | 30 | pszVal | 系統預設代碼頁中 Null 終止 ANSI 字串的指標。 |
| VT_LPWSTR | 31 | pwszVal | 用戶預設地區設定中 Null 終止 Unicode 字串的指標。 |
| VT_UNKNOWN | 13 | punkVal | 新增。 |
| VT_DISPATCH | 9 | pdispVal | 新增。 |
| VT_STREAM | 66 | pStream | IStream 介面的指標，代表與「內容」數據流同層級的數據流。 |
| VT_STREAMED_OBJECT | 68 | pStream | 如同 VT_STREAM，但表示數據流包含串行化物件，也就是CLSID，後面接著類別的初始化數據。 數據流是包含屬性集之「內容」數據流的同層級數據流。 |
| VT_STORAGE | 67 | pStorage | IStorage 介面的指標，代表與「內容」數據流同層級的記憶體物件。 |
| VT_STORED_OBJECT | 69 | pStorage | 如同 VT_STORAGE，但表示指定的 IStorage 包含可載入的物件。 |
| VT_VERSIONED_STREAM | 73 | pVersionedStream | 具有 GUID 版本的數據流。 |
| VT_DECIMAL | 14 | decVal | DECIMAL 結構。 |
| VT_VECTOR | 0x1000 | 約* | 如果使用 OR 運算符將類型指標與VT_VECTOR結合，則值為其中一個計算數位值。 這會建立 專案的 DWORD 計數，後面接著值的指定重複項目指標。
例如，VT_LPSTR VT_VECTOR|的類型指標具有 DWORD 元素計數，後面接著 LPSTR 元素陣列的指標。 VT_VECTOR可由 OR 運算符與下列類型結合：VT_I1， VT_UI1、VT_I2、VT_UI2、VT_BOOL、VT_I4、VT_UI4、VT_R4、VT_R8、VT_ERROR VT_I8、VT_UI8、VT_CY、VT_DATE、VT_FILETIME、VT_CLSID、VT_CF、VT_BSTR、VT_LPSTR、VT_LPWSTR和VT_VARIANT。 VT_VECTOR 也可以透過 OR 作業與 VT_BSTR_BLOB合併，不過僅供系統使用。 |
| VT_ARRAY | 0x2000 | Parray | 如果類型指標與 OR 運算子VT_ARRAY結合，則值為 SAFEARRAY 的指標。 VT_ARRAY可以搭配下列數據類型使用 OR：VT_I1、VT_UI1、VT_I2、VT_UI2、VT_I4、VT_UI4、VT_INT、VT_UINT、VT_R4、VT_R8、VT_BOOL、VT_DECIMAL、VT_ERROR、VT_CY、VT_DATE、VT_BSTR、VT_DISPATCH、VT_UNKNOWN和VT_VARIANT。 VT_ARRAY無法搭配VT_VECTOR使用 OR。 |
| VT_BYREF | 0x4000 | P* | 如果類型指標與 OR 運算子VT_BYREF結合，則值為參考。 參考型別會解譯為數據的參考，類似於 C++ 中的參考型別 (例如“int&”) 。
VT_BYREF可以搭配下列類型使用 OR：VT_I1、VT_UI1、VT_I2、VT_UI2、VT_I4、VT_UI4、VT_INT、VT_UINT、VT_R4、VT_R8、VT_BOOL、VT_DECIMAL、VT_ERROR、VT_CY、VT_DATE、VT_BSTR、VT_UNKNOWN、VT_DISPATCH、VT_ARRAY和VT_VARIANT。 |
| VT_VARIANT | 12 | capropvar | DWORD 類型指標，後面接著對應的值。 VT_VARIANT 只能與 VT_VECTOR 或 VT_BYREF搭配使用。 |
| VT_TYPEMASK | 0xFFF | 用來作為 VT_VECTOR 和其他修飾詞的遮罩，以擷取原始 VT 值。 |
剪貼簿格式識別碼，以標記VT_CF儲存，使用五個表示法之一，使用 PClipData 指標識別於 CLIPDATA 結構的 ulClipFmt 成員中，使用特定數據類型的 pClipData 指標。
| ulClipFmt 值 | pClipData 值 |
|---|---|
| -1L | 包含內建 Windows 剪貼簿格式值的 DWORD 。 |
| -2L | 包含 Macintosh 剪貼簿格式值的 DWORD 。 |
| -3L | 包含格式識別碼的 GUID (FMTID) 。 這很少使用。 |
| 任何正值 | 包含 Windows 剪貼簿格式名稱的 Null 終止字串，適合傳遞至 RegisterClipboardFormat 函式。 此函式會註冊新的剪貼簿格式。 如果已存在具有指定名稱的已註冊格式，則不會註冊新的格式，且傳回值會識別現有的格式。 這可讓多個應用程式使用相同的已註冊剪貼簿格式來複製和貼上數據。 格式名稱比較不區分大小寫，而且是由範圍中的值從 0xC000 到 0xFFFF 所識別。 字串中用於字元的代碼頁是根據代碼頁指標。 這裡的「正值」是字串長度，包括結尾的 Null 位元組。 當註冊剪貼簿格式放在剪貼簿上或從剪貼簿擷取時，它們必須以 HGLOBAL 數據類型值的形式提供物件的句柄。 |
| 0L | 很少使用任何數據 () 。 |
如果 ulClipFmt 成員的值是 -1，則數據會採用內建 Windows 格式的格式。 在此情況下，pClipData 所指向緩衝區的第一個 DWORD 是剪貼簿格式識別碼，例如CF_METAFILEPICT。 在CF_METAFILEPCT的情況下，以下是 METAFILEPICT 結構的變化， (它使用 WORD，而不是 使用 DWORD 資料類型) 。 也就是說，此數據的格式如下：
struct PACKEDMETA
{
WORD mm;
WORD xExt;
WORD yExt
WORD reserved;
};
在METAFILEPICT結構為元文件數據之後，適合傳遞至SetMetaFileBitsEx函式。 此函式會從提供的數據建立以記憶體為基礎的 Windows 格式元檔。 提供此函式以與16位版本的Windows相容。 以 Win32 為基礎的應用程式應該使用 SetEnhMetaFileBits 函式 。 此函式會擷取指定之增強格式元檔的內容，並將其複製到緩衝區。 如果函式成功且緩衝區指標為 NULL，則傳回值會是以位元組為單位的增強元檔大小。 如果函式成功，而且緩衝區指標是有效的指標，則傳回值會是複製到緩衝區的位元組數目。 如果此函式失敗，則傳回值為零。
當註冊剪貼簿格式放在剪貼簿上或從剪貼簿擷取時，它們的格式必須是 HGLOBAL 值。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [傳統型應用程式 |UWP 應用程式] |
| 標頭 | propidl.h (包含 Propidl.h) |