PROPVARIANT structure

The PROPVARIANT structure is used in the ReadMultiple and WriteMultiple methods of IPropertyStorage to define the type tag and the value of a property in a property set.

The PROPVARIANT structure is also used by the GetValue and SetValue methods of IPropertyStore, which replaces IPropertySetStorage as the primary way to program item properties in Windows Vista. For more information, see Property Handlers.

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. For more information, see Property Set Serialization.

The PROPVARIANT structure is defined as follows:

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;

Members

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 of Win32 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.

PROPVARIANT is the fundamental data type by which property values are read and written through the IPropertyStorage interface.

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 typeCodePropvariant memberValue representation
VT_EMPTY0NoneA property with a type indicator of VT_EMPTY has no data associated with it; that is, the size of the value is zero.
VT_NULL1NoneThis is like a pointer to NULL.
VT_I116cVal1-byte signed integer.
VT_UI117bVal1-byte unsigned integer.
VT_I22iValTwo bytes representing a 2-byte signed integer value.
VT_UI218uiVal2-byte unsigned integer.
VT_I43lVal4-byte signed integer value.
VT_UI419ulVal4-byte unsigned integer.
VT_INT22intVal4-byte signed integer value (equivalent to VT_I4).
VT_UINT23uintVal4-byte unsigned integer (equivalent to VT_UI4).
VT_I820hVal8-byte signed integer.
VT_UI821uhVal8-byte unsigned integer.
VT_R44fltVal32-bit IEEE floating point value.
VT_R85dblVal64-bit IEEE floating point value.
VT_BOOL11boolVal (bool in earlier designs)Boolean value, a WORD that contains 0 (FALSE) or -1 (TRUE).
VT_ERROR10scodeA DWORD that contains a status code.
VT_CY6cyVal8-byte two's complement integer (scaled by 10,000). This type is commonly used for currency amounts.
VT_DATE7dateA 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_FILETIME64filetime64-bit FILETIME structure as defined by Win32. It is recommended that all times be stored in Universal Coordinate Time (UTC).
VT_CLSID72puuidPointer to a class identifier (CLSID) (or other globally unique identifier (GUID)).
VT_CF71pclipdataPointer to a CLIPDATA structure, described above.
VT_BSTR8bstrValPointer 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_BLOB0xfffbstrblobValFor system use only.
VT_BLOB65blobDWORD 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_BLOBOBJECT70blobA blob member that contains 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_LPSTR30pszValA pointer to a null-terminated ANSI string in the system default code page.
VT_LPWSTR31pwszValA pointer to a null-terminated Unicode string in the user default locale.
VT_UNKNOWN13punkValNew.
VT_DISPATCH9pdispValNew.
VT_STREAM66pStreamA pointer to an IStream interface that represents a stream which is a sibling to the "Contents" stream.
VT_STREAMED_OBJECT68pStreamAs 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_STORAGE67pStorageA pointer to an IStorage interface, representing a storage object that is a sibling to the "Contents" stream.
VT_STORED_OBJECT69pStorageAs in VT_STORAGE, but indicates that the designated IStorage contains a loadable object.
VT_VERSIONED_STREAM73pVersionedStreamA stream with a GUID version.
VT_DECIMAL14decValA DECIMAL structure.
VT_VECTOR0x1000ca*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_ARRAY0x2000ParrayIf 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_BYREF0x4000p*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_VARIANT12capropvarA DWORD type indicator followed by the corresponding value. VT_VARIANT can be used only with VT_VECTOR or VT_BYREF.
VT_TYPEMASK0xFFF Used as a mask for VT_VECTOR and other modifiers to extract the raw VT value.

 

Clipboard format identifiers, stored with the tag VT_CF, use one of five representations, identified in the ulClipFmt member of the CLIPDATA structure using the pClipData pointer to the particular data type.

ulClipFmt valuepClipData value
-1LA DWORD that contains a built-in Windows clipboard format value.
-2LA DWORD that contains a Macintosh clipboard format value.
-3LA GUID that contains a format identifier (FMTID). This is rarely used.
any positive valueA null-terminated string that contains a Windows clipboard format name, one suitable for passing to the RegisterClipboardFormat function. This function registers a new clipboard format. If a registered format with the specified name already exists, a new format is not registered and the return value identifies the existing format. This enables more than one application to copy and paste data using the same registered clipboard format. The format name comparison is case insensitive and is identified by values in the range from 0xC000 through 0xFFFF. The code page used for characters in the string is according to the code-page indicator. The "positive value" here is the string length, including the null byte at the end. When register clipboard formats are placed on or retrieved from the clipboard, they must be in the form of an HGLOBAL data-type value, which provides the handle to the object.
0LNo data (rarely used).

 

If the value of the ulClipFmt member is -1, the data is in the form of a built-in Windows format. In this case, the first DWORD of the buffer pointed to by pClipData is the clipboard format identifier, for example CF_METAFILEPICT. In the case of CF_METAFILEPCT, what follows is a variation on the METAFILEPICT structure (it uses WORD, rather than DWORD data types). That is, this data is in the following form:

struct PACKEDMETA
{
    WORD mm;
    WORD xExt;
    WORD yExt
    WORD reserved;
};

After the METAFILEPICT structure is the metafile data, suitable to be passed to the SetMetaFileBitsEx function. This function creates a memory-based, Windows-format metafile from the supplied data. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the SetEnhMetaFileBits function. This function retrieves the contents of the specified enhanced-format metafile and copies them into a buffer. If the function succeeds and the buffer pointer is NULL, the return value is the size of the enhanced metafile in bytes. If the function succeeds and the buffer pointer is a valid pointer, the return value is the number of bytes copied to the buffer. If the function fails, the return value is zero.

When register clipboard formats are placed on or retrieved from the clipboard, they must be in the form of an HGLOBAL value.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

Header

Propidl.h

 

 

Community Additions

ADD
Show:
© 2014 Microsoft