PROPVARIANT 結構 (propidlbase.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
tag_inner_PROPVARIANT.bVal
tag_inner_PROPVARIANT.iVal
tag_inner_PROPVARIANT.uiVal
tag_inner_PROPVARIANT.lVal
tag_inner_PROPVARIANT.ulVal
tag_inner_PROPVARIANT.intVal
tag_inner_PROPVARIANT.uintVal
tag_inner_PROPVARIANT.hVal
tag_inner_PROPVARIANT.uhVal
tag_inner_PROPVARIANT.fltVal
tag_inner_PROPVARIANT.dblVal
tag_inner_PROPVARIANT.boolVal
tag_inner_PROPVARIANT.__OBSOLETE__VARIANT_BOOL
tag_inner_PROPVARIANT.scode
tag_inner_PROPVARIANT.cyVal
tag_inner_PROPVARIANT.date
tag_inner_PROPVARIANT.filetime
tag_inner_PROPVARIANT.puuid
tag_inner_PROPVARIANT.pclipdata
tag_inner_PROPVARIANT.bstrVal
tag_inner_PROPVARIANT.bstrblobVal
tag_inner_PROPVARIANT.blob
tag_inner_PROPVARIANT.pszVal
tag_inner_PROPVARIANT.pwszVal
tag_inner_PROPVARIANT.punkVal
tag_inner_PROPVARIANT.pdispVal
tag_inner_PROPVARIANT.pStream
tag_inner_PROPVARIANT.pStorage
tag_inner_PROPVARIANT.pVersionedStream
tag_inner_PROPVARIANT.parray
tag_inner_PROPVARIANT.cac
tag_inner_PROPVARIANT.caub
tag_inner_PROPVARIANT.cai
tag_inner_PROPVARIANT.caui
tag_inner_PROPVARIANT.cal
tag_inner_PROPVARIANT.caul
tag_inner_PROPVARIANT.cah
tag_inner_PROPVARIANT.cauh
tag_inner_PROPVARIANT.caflt
tag_inner_PROPVARIANT.cadbl
tag_inner_PROPVARIANT.cabool
tag_inner_PROPVARIANT.cascode
tag_inner_PROPVARIANT.cacy
tag_inner_PROPVARIANT.cadate
tag_inner_PROPVARIANT.cafiletime
tag_inner_PROPVARIANT.cauuid
tag_inner_PROPVARIANT.caclipdata
tag_inner_PROPVARIANT.cabstr
tag_inner_PROPVARIANT.cabstrblob
tag_inner_PROPVARIANT.calpstr
tag_inner_PROPVARIANT.calpwstr
tag_inner_PROPVARIANT.capropvar
tag_inner_PROPVARIANT.pcVal
tag_inner_PROPVARIANT.pbVal
tag_inner_PROPVARIANT.piVal
tag_inner_PROPVARIANT.puiVal
tag_inner_PROPVARIANT.plVal
tag_inner_PROPVARIANT.pulVal
tag_inner_PROPVARIANT.pintVal
tag_inner_PROPVARIANT.puintVal
tag_inner_PROPVARIANT.pfltVal
tag_inner_PROPVARIANT.pdblVal
tag_inner_PROPVARIANT.pboolVal
tag_inner_PROPVARIANT.pdecVal
tag_inner_PROPVARIANT.pscode
tag_inner_PROPVARIANT.pcyVal
tag_inner_PROPVARIANT.pdate
tag_inner_PROPVARIANT.pbstrVal
tag_inner_PROPVARIANT.ppunkVal
tag_inner_PROPVARIANT.ppdispVal
tag_inner_PROPVARIANT.pparray
tag_inner_PROPVARIANT.pvarVal
decVal
備註
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) | 布爾值，此 WORD 包含 0 (FALSE) 或 -1 (TRUE) 。 |
| 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 指向字串的第一個字元。 必須使用 Automation SysAllocString 和 SysFreeString 呼叫來配置和釋放 BSTRs。 |
| 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 介面的指標，代表與“Contents” 數據流同層級的記憶體物件。 |
| 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 應用程式] |
| 標頭 | propidlbase.h (包含 Propidl.h) |
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應