Share via


PROPVARIANT (Compact 2013)

3/26/2014

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.

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.
  • wReserved2
    Reserved.
  • wReserved3
    Reserved.
  • 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

See Also

Reference

Automation Structures
IStream
IStorage
FreePropVariantArray
PropVariantClear
PropVariantCopy

Other Resources

FILETIME
RegisterClipboardFormat