PROPVARIANT
A version of this page is also available for
4/8/2010
This structure is used to define the type tag and the value of a property in a property set. There are five members. The first member, the value-type tag, and the last member, the value of the property, are significant. The middle three members are reserved for future use.
Note
The bool member in previous definitions of this structure has been renamed to boolVal, because some compilers now recognize bool as a keyword.
Note
The PROPVARIANT structure, defined below, includes types that can be serialized in the version 1 property set serialization format. The version 1 format supports all types allowed in the version 0 format plus some additional types. The added types include "Version 1" in the comment field below. Use these types only if a version 1 property set is intended.
Syntax
typedef struct PROPVARIANT {
VARTYPE vt;
WORD wReserved1;
WORD wReserved2;
WORD 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;
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;
};
} PROPVARIANT;
Parameters
- vt
Value type tag.
- wReserved1
Reserved for future use.
- wReserved2
Reserved for future use.
- wReserved3
Reserved for future use.
- cVal
VT_I1, Version 1
- bVal
VT_UI1
- iVal
VT_I2
- uiVal
VT_UI2
- lVal
VT_I4
- ulVal
VT_UI4
- intVal
VT_INT, Version 1
- uintVal
VT_UINT, Version 1
- hVal
VT_I8
- uhVal
VT_UI8
- fltVal
VT_R4
- dblVal
VT_R8
- boolVal
VT_BOOL
- scode
VT_ERROR
- cyVal
VT_CY
- date
VT_DATE
- filetime
VT_FILETIME
- puuid
VT_CLSID
- pclipdata
VT_CF
- bstrVal
VT_BSTR
- bstrblobVal
VT_BSTR_BLOB
- blob
VT_BLOB, VT_BLOBOBJECT
- pszVal
VT_LPSTR
- pwszVal
VT_LPWSTR
- punkVal
VT_UNKNOWN
- pdispVal
VT_DISPATCH
- pStream
VT_STREAM, VT_STREAMED_OBJECT
- pStorage
VT_STORAGE, VT_STORED_OBJECT
- pVersionedStream
VT_VERSIONED_STREAM
- parray
VT_ARRAY | VT_*, Version 1
- cac
VT_VECTOR | VT_I1, Version 1
- caub
VT_VECTOR | VT_UI1
- cai
VT_VECTOR | VT_I2
- caui
VT_VECTOR | VT_UI2
- cal
VT_VECTOR | VT_I4
- caul
VT_VECTOR | VT_UI4
- cah
VT_VECTOR | VT_I8
- cauh
VT_VECTOR | VT_UI8
- caflt
VT_VECTOR | VT_R4
- cadbl
VT_VECTOR | VT_R8
- cabool
VT_VECTOR | VT_BOOL
- cascode
VT_VECTOR | VT_ERROR
- cacy
VT_VECTOR | VT_CY
- cadate
VT_VECTOR | VT_DATE
- cafiletime
VT_VECTOR | VT_FILETIME
- cauuid
VT_VECTOR | VT_CLSID
- caclipdata
VT_VECTOR | VT_CF
- cabstr
VT_VECTOR | VT_BSTR
- cabstrblob
VT_VECTOR | VT_BSTR_BLOB
- calpstr
VT_VECTOR | VT_LPSTR
- calpwstr
VT_VECTOR | VT_LPWSTR
- capropvar
VT_VECTOR | VT_VARIANT
- pcVal
VT_BYREF | VT_I1, Version 1
- pbVal
VT_BYREF | VT_UI1, Version 1
- piVal
VT_BYREF | VT_I2, Version 1
- puiVal
VT_BYREF | VT_UI2, Version 1
- plVal
VT_BYREF | VT_I4, Version 1
- pulVal
VT_BYREF | VT_UI4, Version 1
- pintVal
VT_BYREF | VT_INT, Version 1
- puintVal
VT_BYREF | VT_UINT, Version 1
- pfltVal
VT_BYREF | VT_R4, Version 1
- pdblVal
VT_BYREF | VT_R8, Version 1
- pboolVal
VT_BYREF | VT_BOOL, Version 1
- pdecVal
VT_BYREF | VT_DECIMAL, Version 1
- pscode
VT_BYREF | VT_ERROR, Version 1
- pcyVal
VT_BYREF | VT_CY, Version 1
- pdate
VT_BYREF | VT_DATE, Version 1
- pbstrVal
VT_BYREF | VT_BSTR, Version 1
- ppunkVal
VT_BYREF | VT_UNKNOWN, Version 1
- ppdispVal
VT_BYREF | VT_DISPATCH, Version 1
- pparray
VT_BYREF | VT_ARRAY, Version 1
- pvarVal
VT_BYREF | VT_VARIANT, Version 1
Remarks
The PROPVARIANT structure can also hold a value of VT_DECIMAL:
DECIMAL decVal; //VT_DECIMAL
However, the value of the DECIMAL structure requires special handling. The DECIMAL structure is the same size as an entire PROPVARIANT structure and does not fit into the union that holds all other types of values. Instead, the value of the DECIMAL structure occupies the entire PROPVARIANT structure, including the reserved fields and the vt member. However, the first member of the DECIMAL structure is not used and is equal in size to the vt member of the PROPVARIANT structure. Therefore, the PROPVARIANT structure declaration in the propidl.h header file defines the decVal member in such a way that it corresponds to the beginning of the PROPVARIANT structure. Therefore, to put the value of the DECIMAL structure into a PROPVARIANT structure, the value must be loaded into the decVal member and the vt member is set to VT_DECIMAL, just as for any other value.
The data type PROPVARIANT is related to the data type VARIANT, defined as part of Automation in OLE2. Several definitions are reused from Automation, as follows:
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;
In addition, some types are unique to the PROPVARIANT structure:
typedef struct tagCLIPDATA {
// cbSize is the size of the buffer pointed to
// by pClipData, plus sizeof(ulClipFmt)
ULONG cbSize;
long ulClipFmt;
BYTE* pClipData;
} CLIPDATA;
Among the unique PROPVARIANT types are several data types that define counted arrays of other data types. The data types of all counted arrays begin with the letters CA, for example CAUB, and have an OR operator vt value (the VarType of the element and an OR operator with VT_VECTOR). The counted array structure has the following form (where name is the specific name of the counted array).
#define TYPEDEF_CA(type, name)
typedef struct tag ## name {\
ULONG cElems;\
type *pElems;\
} name
| Propvariant type | Code | PROPVARIANT Member | Value Representation |
|---|---|---|---|
VT_EMPTY |
0 |
None |
A property with a type indicator of VT_EMPTY has no data associated with it; that is, the size of the value is zero. |
VT_NULL |
1 |
None |
This is like a pointer to NULL. |
VT_I1 |
16 |
cVal |
1-byte signed integer. |
VT_UI1 |
17 |
bVal |
1-byte unsigned integer. |
VT_I2 |
2 |
iVal |
Two bytes representing a 2-byte signed integer value. |
VT_UI2 |
18 |
uiVal |
2-byte unsigned integer. |
VT_I4 |
3 |
lVal |
4-byte signed integer value. |
VT_UI4 |
19 |
ulVal |
4-byte unsigned integer. |
VT_INT |
22 |
intVal |
4-byte signed integer value (equivalent to VT_I4). |
VT_UINT |
23 |
uintVal |
4-byte unsigned integer (equivalent to VT_UI4). |
VT_I8 |
20 |
hVal |
8-byte signed integer. |
VT_UI8 |
21 |
uhVal |
8-byte unsigned integer. |
VT_R4 |
4 |
fltVal |
32-bit IEEE floating point value. |
VT_R8 |
5 |
dblVal |
64-bit IEEE floating point value. |
VT_BOOL |
11 |
boolVal (bool in earlier designs) |
Boolean value, a WORD containing 0 (FALSE) or -1 (TRUE). |
VT_ERROR |
10 |
scode |
A DWORD containing a status code. |
VT_CY |
6 |
cyVal |
8-byte two's complement integer (scaled by 10,000). This type is commonly used for currency amounts. |
VT_DATE |
7 |
date |
A 64-bit floating point number representing the number of days (not seconds) since December 31, 1899. For example, January 1, 1900, is 2.0, January 2, 1900, is 3.0, and so on). This is stored in the same representation as VT_R8. |
VT_FILETIME |
64 |
filetime |
64-bit FILETIME structure. It is recommended that all times be stored in Universal Coordinate Time (UTC). |
VT_CLSID |
72 |
puuid |
Pointer to a class identifier (CLSID) (or other globally unique identifier (GUID)). |
VT_CF |
71 |
pclipdata |
Pointer to a CLIPDATA structure, described above. |
VT_BSTR |
8 |
bstrVal |
Pointer to a null-terminated Unicode string. The string is immediately preceded by a DWORD representing the byte count, but bstrVal points past this DWORD to the first character of the string. BSTRs must be allocated and freed using the Automation SysAllocString and SysFreeString calls. |
VT_BSTR_BLOB |
0xfff |
bstrblobVal |
For system use only. |
VT_BLOB |
65 |
blob |
DWORD count of bytes, followed by that many bytes of data. The byte count does not include the four bytes for the length of the count itself; an empty blob member would have a count of zero, followed by zero bytes. This is similar to the value VT_BSTR, but does not guarantee a null byte at the end of the data. |
VT_BLOBOBJECT |
70 |
blob |
A blob member containing a serialized object in the same representation that would appear in VT_STREAMED_OBJECT. That is, a DWORD byte count (where the byte count does not include the size of itself) which is in the format of a class identifier followed by initialization data for that class. |
|
|
|
The only significant difference between VT_BLOB_OBJECT and VT_STREAMED_OBJECT is that the former does not have the system-level storage overhead that the latter would have, and is therefore more suitable for scenarios involving numbers of small objects. |
VT_LPSTR |
30 |
pszVal |
Pointer to a null-terminated ANSI string in the system default code page. |
VT_LPWSTR |
31 |
pwszVal |
Pointer to a null-terminated Unicode string in the user's default locale. |
VT_UNKNOWN |
13 |
punkVal |
New |
VT_DISPATCH |
9 |
pdispVal |
New |
VT_STREAM |
66 |
pStream |
Pointer to an IStream interface, representing a stream which is a sibling to the "Contents" stream. |
VT_STREAMED_OBJECT |
68 |
pStream |
As in VT_STREAM, but indicates that the stream contains a serialized object, which is a CLSID followed by initialization data for the class. The stream is a sibling to the "Contents" stream that contains the property set. |
VT_STORAGE |
67 |
pStorage |
Pointer to an IStorage interface, representing a storage object that is a sibling to the "Contents" stream. |
VT_STORED_OBJECT |
69 |
pStorage |
As in VT_STORAGE, but indicates that the designated IStorage contains a loadable object. |
VT_VERSIONED_STREAM |
73 |
pVersionedStream |
A stream with a GUID version. |
VT_DECIMAL |
14 |
decVal |
A DECIMAL structure. |
VT_VECTOR |
0x1000 |
ca* |
If the type indicator is combined with VT_VECTOR by using an OR operator, the value is one of the counted array values. This creates a DWORD count of elements, followed by a pointer to the specified repetitions of the value. |
|
|
|
For example, a type indicator of VT_LPSTR|VT_VECTOR has a DWORD element count, followed by a pointer to an array of LPSTR elements. |
|
|
|
VT_VECTOR can be combined by an OR operator with the following types: 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, and VT_VARIANT. VT_VECTOR can also be combined by an OR operation with VT_BSTR_BLOB, however it is for system use only. |
VT_ARRAY |
0x2000 |
Parray |
If the type indicator is combined with VT_ARRAY by an OR operator, the value is a pointer to a SAFEARRAY. VT_ARRAY can use the OR with the following data types: 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, and VT_VARIANT. VT_ARRAY cannot use OR with VT_VECTOR. |
VT_BYREF |
0x4000 |
p* |
If the type indicator is combined with VT_BYREF by an OR operator, the value is a reference. Reference types are interpreted as a reference to data, similar to the reference type in C++ (for example, "int&"). |
|
|
|
VT_BYREF can use OR with the following types: 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, and VT_VARIANT. |
VT_VARIANT |
12 |
capropvar |
A DWORD type indicator followed by the corresponding value. VT_VARIANT can be used only with VT_VECTOR or VT_BYREF. |
VT_TYPEMASK |
0xFFF |
|
Used as a mask for VT_VECTOR and other modifiers to extract the raw VT value. |
Requirements
| Header | oaidl.h |
| Windows Embedded CE | Windows CE 2.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
Automation Structures
IStream
IStorage
FreePropVariantArray
PropVariantClear
PropVariantCopy